acme

Documentation

Index

• Constants
• type AcmeFS
  • func NewAcmeFS(config Config) *AcmeFS
  • func (acm *AcmeFS) All() ([]tlsfs.DomainAccount, error)
  • func (acm *AcmeFS) Create(acct tlsfs.NewDomain, tos tlsfs.TOSAction) (tlsfs.TLSDomainCertificate, tlsfs.Status, error)
  • func (acm *AcmeFS) CreateCA(acct tlsfs.NewDomain, tos tlsfs.TOSAction) (tlsfs.TLSDomainCertificate, tlsfs.Status, error)
  • func (acm *AcmeFS) CreateWithCSR(req x509.CertificateRequest, tos tlsfs.TOSAction) (tlsfs.TLSDomainCertificate, tlsfs.Status, error)
  • func (acm *AcmeFS) Get(email string, domain string) (tlsfs.TLSDomainCertificate, tlsfs.Status, error)
  • func (acm *AcmeFS) GetCertificate(email string) tlsfs.CertificateFunc
  • func (acm *AcmeFS) GetUser(email string) (tlsfs.Account, error)
  • func (acm *AcmeFS) Renew(email string, domain string) (tlsfs.TLSDomainCertificate, tlsfs.Status, error)
  • func (acm *AcmeFS) Revoke(email string, domain string) error
  • func (acm *AcmeFS) Serve(def http.Handler) http.Handler
• type Config

Constants

const (
	TLSSNI = string(acme.TLSSNI01)
	HTTP01 = string(acme.HTTP01)
)

constants of supported challenge types.

Types

type AcmeFS

type AcmeFS struct {
	// contains filtered or unexported fields
}

AcmeFS implements the tlsfs.TlsFS interface, providing a tls certificate acquisition, renewal and management implementation for working with Let's Encrypt CA based certificates.

func NewAcmeFS

func NewAcmeFS(config Config) *AcmeFS

NewAcmeFS returns a new instance of the AcmeFS.

func (*AcmeFS) All

func (acm *AcmeFS) All() ([]tlsfs.DomainAccount, error)

All returns all existing certificates within the AcmeFS regardless of renewal status allowing all state preserved to caller.

func (*AcmeFS) Create

func (acm *AcmeFS) Create(acct tlsfs.NewDomain, tos tlsfs.TOSAction) (tlsfs.TLSDomainCertificate, tlsfs.Status, error)

Create attempts to create a given TLSDomainCertificate for the giving account. If a certificate already exists for the giving accounts.Domain, then the old TLSDomainCertificate is returned if its has not pass the accepted expiration time yet of 30 days. If it has then a renewal is initiated for the certificate and if successfully will return the new TLSDomainCertificate after replacing the old one. If a renewal failed and the certificate is less than two weeks to expiry or within the 30-days expiration, then the certificate is returned with an appropriate status to indicate non-critical but important reason of failure. NOTE: With Lets Encrypt, we do not have control over the value of the common name passed to the certificate request on the CA side, so the tlsfs.NewDomian.CommonName and tlsfs.NewDomian.DNSNames is ignored.

func (*AcmeFS) CreateCA

func (acm *AcmeFS) CreateCA(acct tlsfs.NewDomain, tos tlsfs.TOSAction) (tlsfs.TLSDomainCertificate, tlsfs.Status, error)

CreateCA is not supported by this acme implementation. It's purpose is to allowing signing certificate requests for sub-CAs.

func (*AcmeFS) CreateWithCSR

func (acm *AcmeFS) CreateWithCSR(req x509.CertificateRequest, tos tlsfs.TOSAction) (tlsfs.TLSDomainCertificate, tlsfs.Status, error)

CreateWithCSR attempts to returns a new tlsfs.TLSDOmainCertificate for giving certificate request. It creates a temporary user without a private key and uses this user to create a acme client to serve said certificate requests.

func (*AcmeFS) Get

func (acm *AcmeFS) Get(email string, domain string) (tlsfs.TLSDomainCertificate, tlsfs.Status, error)

Get attempts to retrieve a existing certificate from the underline store, if such certificate is requiring renewal then the renewal process is called for the certificate with appropriate response returned as stated for the AcmeFS.Renew method. It returns a status appropriate for the certificate returned to indicate to the caller the state and needed action if any to be done.

func (*AcmeFS) GetCertificate

func (acm *AcmeFS) GetCertificate(email string) tlsfs.CertificateFunc

GetCertificate returns a tlsfs.GetCertificateFunc which should be assigned to a tls.Config.GetCertificate field to handle automatic loading and retrieval of tls.Certificates through this filesystem. NOTE: Your are required to provide an email which will reference the account/user who signs for these certificates generated by the returned function.

func (*AcmeFS) GetUser

func (acm *AcmeFS) GetUser(email string) (tlsfs.Account, error)

GetUser returns an existing user account asocited with the provided email.

func (*AcmeFS) Renew

func (acm *AcmeFS) Renew(email string, domain string) (tlsfs.TLSDomainCertificate, tlsfs.Status, error)

Renew attempts to renew a existing TLSDomainCertificate for the giving domain. If a certificate does not exists exists then the operation is returned with an error. A TLSDomainCertificate is returned if its has not pass the accepted expiration time yet of 30 days. If it has then the renewal is initiated for the certificate and if successfully will return the new TLSDomainCertificate after replacing the old one. If a renewal failed and the certificate is less than two weeks to expiry or within the 30-days expiration, then the certificate is returned with an appropriate status to indicate non-critical but important reason of failure.

func (*AcmeFS) Revoke

func (acm *AcmeFS) Revoke(email string, domain string) error

Revoke attempts to revoke the existing certificate associated with the user's email and domain. If certificate is pending renewal then it will wait until the end of the renewal before making an attempt to revoke certificate. Once revoked, then certificate is deleted. If revokation fails, the certificate is kept in the filesystem, till a revoke is successfully through the CA.

func (*AcmeFS) Serve

func (acm *AcmeFS) Serve(def http.Handler) http.Handler

Serve returns a http.Handler which will cater for requests targeting the `/.well-known/acme-challenge/` which responds to acme challenges for http-01, else passes the request to be handled by provided handler. Serve will proxy all requests for the acme challenge to the ip address and port provided in the Config.ListenAddr and Config.HTTPChallengePort.

type Config

type Config struct {
	// CAURL to set the CA url to be used to register and generate
	// certificates from a valid acme Certificate Authority.
	// Defaults to Lets Encrypt's CA.
	CAURL string

	// ListenerAddr sets the preferred address, only the hostname/ip
	// no port, which will be used for working out the HTTP/TLS-SNI
	// challenges.
	ListenerAddr string

	// MustStable sets the requirement that all acme clients must
	// run stable checks against retrieved certificates to ensure
	// validity and correctness.
	MustStaple bool

	// HTTPChallengePort sets the alternate port, only port and not
	// hostname/ip and port. Which should be used for HTTP challenge
	// instead of port 80. Defaults to 80 if non is provided.
	HTTPChallengePort int

	// TLSSNIChallengePort sets the alternate port, only port and not
	// hostname/ip and port. Which should be used for TLS-SNI challenge
	// instead of port 443. Defaults to 443 if non is provided.
	TLSSNIChallengePort int

	// EnableHTTP01Challenge enables the usage of the HTTP01 challenge for
	// handling acme challenge solving process. Set this to add HTTP01 has
	// a possible means to solve the acme challenge.
	// Enabling any other challenge won't disable this challenge has it
	// allows us test all challenges if another failed before returning
	// failure if all failed.
	EnableHTTP01Challenge bool

	// EnableTLSSNI01Challenge enables the usage of the TLS-SNI01 challenge for
	// handling acme challenge solving process. Set this to add TLS-SNI01 has
	// a possible means to solve the acme challenge.
	// Enabling any other challenge won't disable this challenge has it
	// allows us test all challenges if another failed before returning
	// failure if all failed.
	EnableTLSSNI01Challenge bool

	// EnableDNS01Challenge enables the usage of the DNS-01 challenge for
	// handling acme challenge solving process. Set this to add DNS-01 has
	// a possible means to solve the acme challenge. But the DNS-01 will
	// require the setting of the DNSChallengeProvider field to power up
	// the usage of the given challenge.
	// Enabling any other challenge won't disable this challenge has it
	// allows us test all challenges if another failed before returning
	// failure if all failed.
	EnableDNS01Challenge bool

	// DNSProvider accompanies the EnableDNS01Challenge field which must
	// exists to allow the usage of dns has a means of resolving the acme
	// certificate challenge. If this is not set then the DNS challenge will
	// be disabled.
	DNSProvider acme.ChallengeProvider

	// TLSCertCache holds certificates cache retrieved through tls-sni-01
	// challenges, it caches them till removal.
	TLSCertCache tlsfs.CertCache

	// CertificatesFileSystem is the filesystem to use for storing certificate zap files
	// for given domain and users. It must be different from the file system for storing
	// user data.
	CertificatesFileSystem tlsfs.ZapFS

	// UsersFileSystem is the filesystem to use for storing user records zap files
	// for registered users. It must be different from the file system for storing
	// user data.
	UsersFileSystem tlsfs.ZapFS
	// contains filtered or unexported fields
}

Config defines a configuration used for AcmeFS.