Documentation ¶
Overview ¶
Package acme implements the ACME protocol for Let's Encrypt and other conforming providers.
Index ¶
- Constants
- Variables
- func ClearFqdnCache()
- func DNS01Record(domain, keyAuth string) (fqdn string, value string, ttl int)
- func FindZoneByFqdn(fqdn string, nameservers []string) (string, error)
- func GetOCSPForCert(bundle []byte) ([]byte, *ocsp.Response, error)
- func GetPEMCertExpiration(cert []byte) (time.Time, error)
- func HTTP01ChallengePath(token string) string
- func TLSALPNChallengeBlocks(domain, keyAuth string) ([]byte, []byte, error)
- func TLSALPNChallengeCert(domain, keyAuth string) (*tls.Certificate, error)
- func ToFqdn(name string) string
- func UnFqdn(name string) string
- func WaitFor(timeout, interval time.Duration, f func() (bool, error)) error
- type CertificateResource
- type Challenge
- type ChallengeProvider
- type ChallengeProviderTimeout
- type Client
- func (c *Client) DeleteRegistration() error
- func (c *Client) ExcludeChallenges(challenges []Challenge)
- func (c *Client) GetExternalAccountRequired() bool
- func (c *Client) GetToSURL() string
- func (c *Client) ObtainCertificate(domains []string, bundle bool, privKey crypto.PrivateKey, mustStaple bool) (*CertificateResource, error)
- func (c *Client) ObtainCertificateForCSR(csr x509.CertificateRequest, bundle bool) (*CertificateResource, error)
- func (c *Client) QueryRegistration() (*RegistrationResource, error)
- func (c *Client) Register(tosAgreed bool) (*RegistrationResource, error)
- func (c *Client) RegisterWithExternalAccountBinding(tosAgreed bool, kid string, hmacEncoded string) (*RegistrationResource, error)
- func (c *Client) RenewCertificate(cert CertificateResource, bundle, mustStaple bool) (*CertificateResource, error)
- func (c *Client) ResolveAccountByKey() (*RegistrationResource, error)
- func (c *Client) RevokeCertificate(certificate []byte) error
- func (c *Client) SetChallengeProvider(challenge Challenge, p ChallengeProvider) error
- func (c *Client) SetHTTPAddress(iface string) error
- func (c *Client) SetTLSAddress(iface string) error
- type DNSProviderManual
- type HTTPProviderServer
- type KeyType
- type NonceError
- type ObtainError
- type RegistrationResource
- type RemoteError
- type TLSALPNProviderServer
- type TOSError
- type User
Constants ¶
const ( // HTTP01 is the "http-01" ACME challenge https://github.com/ietf-wg-acme/acme/blob/master/draft-ietf-acme-acme.md#http // Note: HTTP01ChallengePath returns the URL path to fulfill this challenge HTTP01 = Challenge("http-01") // DNS01 is the "dns-01" ACME challenge https://github.com/ietf-wg-acme/acme/blob/master/draft-ietf-acme-acme.md#dns // Note: DNS01Record returns a DNS record which will fulfill this challenge DNS01 = Challenge("dns-01") // TLSALPN01 is the "tls-alpn-01" ACME challenge https://tools.ietf.org/html/draft-ietf-acme-tls-alpn-01 TLSALPN01 = Challenge("tls-alpn-01") )
const ( EC256 = KeyType("P256") EC384 = KeyType("P384") RSA2048 = KeyType("2048") RSA4096 = KeyType("4096") RSA8192 = KeyType("8192") )
Constants for all key types we support.
const ( // OCSPGood means that the certificate is valid. OCSPGood = ocsp.Good // OCSPRevoked means that the certificate has been deliberately revoked. OCSPRevoked = ocsp.Revoked // OCSPUnknown means that the OCSP responder doesn't know about the certificate. OCSPUnknown = ocsp.Unknown // OCSPServerFailed means that the OCSP responder failed to process the request. OCSPServerFailed = ocsp.ServerFailed )
const ( // DefaultPropagationTimeout default propagation timeout DefaultPropagationTimeout = 60 * time.Second // DefaultPollingInterval default polling interval DefaultPollingInterval = 2 * time.Second // DefaultTTL default TTL DefaultTTL = 120 )
const (
// ACMETLS1Protocol is the ALPN Protocol ID for the ACME-TLS/1 Protocol.
ACMETLS1Protocol = "acme-tls/1"
)
Variables ¶
var ( // UserAgent (if non-empty) will be tacked onto the User-Agent string in requests. UserAgent string // HTTPClient is an HTTP client with a reasonable timeout value and // potentially a custom *x509.CertPool based on the caCertificatesEnvVar // environment variable (see the `initCertPool` function) HTTPClient = http.Client{ Transport: &http.Transport{ Proxy: http.ProxyFromEnvironment, DialContext: (&net.Dialer{ Timeout: 30 * time.Second, KeepAlive: 30 * time.Second, }).DialContext, TLSHandshakeTimeout: 15 * time.Second, ResponseHeaderTimeout: 15 * time.Second, ExpectContinueTimeout: 1 * time.Second, TLSClientConfig: &tls.Config{ ServerName: os.Getenv(caServerNameEnvVar), RootCAs: initCertPool(), }, }, } )
var DNSTimeout = 10 * time.Second
DNSTimeout is used to override the default DNS timeout of 10 seconds.
var ( // PreCheckDNS checks DNS propagation before notifying ACME that // the DNS challenge is ready. PreCheckDNS preCheckDNSFunc = checkDNSPropagation )
var RecursiveNameservers = getNameservers(defaultResolvConf, defaultNameservers)
RecursiveNameservers are used to pre-check DNS propagation
Functions ¶
func ClearFqdnCache ¶ added in v0.3.0
func ClearFqdnCache()
ClearFqdnCache clears the cache of fqdn to zone mappings. Primarily used in testing.
func DNS01Record ¶ added in v0.3.0
DNS01Record returns a DNS record which will fulfill the `dns-01` challenge
func FindZoneByFqdn ¶ added in v0.3.0
FindZoneByFqdn determines the zone apex for the given fqdn by recursing up the domain labels until the nameserver returns a SOA record in the answer section.
func GetOCSPForCert ¶
GetOCSPForCert takes a PEM encoded cert or cert bundle returning the raw OCSP response, the parsed response, and an error, if any. The returned []byte can be passed directly into the OCSPStaple property of a tls.Certificate. If the bundle only contains the issued certificate, this function will try to get the issuer certificate from the IssuingCertificateURL in the certificate. If the []byte and/or ocsp.Response return values are nil, the OCSP status may be assumed OCSPUnknown.
func GetPEMCertExpiration ¶
GetPEMCertExpiration returns the "NotAfter" date of a PEM encoded certificate. The certificate has to be PEM encoded. Any other encodings like DER will fail.
func HTTP01ChallengePath ¶ added in v0.3.0
HTTP01ChallengePath returns the URL path for the `http-01` challenge
func TLSALPNChallengeBlocks ¶ added in v1.1.0
TLSALPNChallengeBlocks returns PEM blocks (certPEMBlock, keyPEMBlock) with the acmeValidation-v1 extension and domain name for the `tls-alpn-01` challenge.
func TLSALPNChallengeCert ¶ added in v1.1.0
func TLSALPNChallengeCert(domain, keyAuth string) (*tls.Certificate, error)
TLSALPNChallengeCert returns a certificate with the acmeValidation-v1 extension and domain name for the `tls-alpn-01` challenge.
Types ¶
type CertificateResource ¶
type CertificateResource struct { Domain string `json:"domain"` CertURL string `json:"certUrl"` CertStableURL string `json:"certStableUrl"` AccountRef string `json:"accountRef,omitempty"` PrivateKey []byte `json:"-"` Certificate []byte `json:"-"` IssuerCertificate []byte `json:"-"` CSR []byte `json:"-"` }
CertificateResource represents a CA issued certificate. PrivateKey, Certificate and IssuerCertificate are all already PEM encoded and can be directly written to disk. Certificate may be a certificate bundle, depending on the options supplied to create it.
type Challenge ¶ added in v0.3.0
type Challenge string
Challenge is a string that identifies a particular type and version of ACME challenge.
type ChallengeProvider ¶ added in v0.3.0
type ChallengeProvider interface { Present(domain, token, keyAuth string) error CleanUp(domain, token, keyAuth string) error }
ChallengeProvider enables implementing a custom challenge provider. Present presents the solution to a challenge available to be solved. CleanUp will be called by the challenge if Present ends in a non-error state.
type ChallengeProviderTimeout ¶ added in v0.3.0
type ChallengeProviderTimeout interface { ChallengeProvider Timeout() (timeout, interval time.Duration) }
ChallengeProviderTimeout allows for implementing a ChallengeProvider where an unusually long timeout is required when waiting for an ACME challenge to be satisfied, such as when checking for DNS record progagation. If an implementor of a ChallengeProvider provides a Timeout method, then the return values of the Timeout method will be used when appropriate by the acme package. The interval value is the time between checks.
The default values used for timeout and interval are 60 seconds and 2 seconds respectively. These are used when no Timeout method is defined for the ChallengeProvider.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is the user-friendy way to ACME
func NewClient ¶
NewClient creates a new ACME client on behalf of the user. The client will depend on the ACME directory located at caDirURL for the rest of its actions. A private key of type keyType (see KeyType contants) will be generated when requesting a new certificate if one isn't provided.
func (*Client) DeleteRegistration ¶ added in v0.4.0
DeleteRegistration deletes the client's user registration from the ACME server.
func (*Client) ExcludeChallenges ¶ added in v0.2.0
ExcludeChallenges explicitly removes challenges from the pool for solving.
func (*Client) GetExternalAccountRequired ¶ added in v1.0.0
GetExternalAccountRequired returns the External Account Binding requirement of the Directory
func (*Client) ObtainCertificate ¶ added in v0.2.0
func (c *Client) ObtainCertificate(domains []string, bundle bool, privKey crypto.PrivateKey, mustStaple bool) (*CertificateResource, error)
ObtainCertificate tries to obtain a single certificate using all domains passed into it. The first domain in domains is used for the CommonName field of the certificate, all other domains are added using the Subject Alternate Names extension. A new private key is generated for every invocation of this function. If you do not want that you can supply your own private key in the privKey parameter. If this parameter is non-nil it will be used instead of generating a new one. If bundle is true, the []byte contains both the issuer certificate and your issued certificate as a bundle. This function will never return a partial certificate. If one domain in the list fails, the whole certificate will fail.
func (*Client) ObtainCertificateForCSR ¶ added in v0.4.0
func (c *Client) ObtainCertificateForCSR(csr x509.CertificateRequest, bundle bool) (*CertificateResource, error)
ObtainCertificateForCSR tries to obtain a certificate matching the CSR passed into it. The domains are inferred from the CommonName and SubjectAltNames, if any. The private key for this CSR is not required. If bundle is true, the []byte contains both the issuer certificate and your issued certificate as a bundle. This function will never return a partial certificate. If one domain in the list fails, the whole certificate will fail.
func (*Client) QueryRegistration ¶ added in v0.4.0
func (c *Client) QueryRegistration() (*RegistrationResource, error)
QueryRegistration runs a POST request on the client's registration and returns the result.
This is similar to the Register function, but acting on an existing registration link and resource.
func (*Client) Register ¶
func (c *Client) Register(tosAgreed bool) (*RegistrationResource, error)
Register the current account to the ACME server.
func (*Client) RegisterWithExternalAccountBinding ¶ added in v1.0.0
func (c *Client) RegisterWithExternalAccountBinding(tosAgreed bool, kid string, hmacEncoded string) (*RegistrationResource, error)
RegisterWithExternalAccountBinding Register the current account to the ACME server.
func (*Client) RenewCertificate ¶
func (c *Client) RenewCertificate(cert CertificateResource, bundle, mustStaple bool) (*CertificateResource, error)
RenewCertificate takes a CertificateResource and tries to renew the certificate. If the renewal process succeeds, the new certificate will ge returned in a new CertResource. Please be aware that this function will return a new certificate in ANY case that is not an error. If the server does not provide us with a new cert on a GET request to the CertURL this function will start a new-cert flow where a new certificate gets generated. If bundle is true, the []byte contains both the issuer certificate and your issued certificate as a bundle. For private key reuse the PrivateKey property of the passed in CertificateResource should be non-nil.
func (*Client) ResolveAccountByKey ¶ added in v1.0.0
func (c *Client) ResolveAccountByKey() (*RegistrationResource, error)
ResolveAccountByKey will attempt to look up an account using the given account key and return its registration resource.
func (*Client) RevokeCertificate ¶
RevokeCertificate takes a PEM encoded certificate or bundle and tries to revoke it at the CA.
func (*Client) SetChallengeProvider ¶ added in v0.3.0
func (c *Client) SetChallengeProvider(challenge Challenge, p ChallengeProvider) error
SetChallengeProvider specifies a custom provider p that can solve the given challenge type.
func (*Client) SetHTTPAddress ¶ added in v0.2.0
SetHTTPAddress specifies a custom interface:port to be used for HTTP based challenges. If this option is not used, the default port 80 and all interfaces will be used. To only specify a port and no interface use the ":port" notation.
NOTE: This REPLACES any custom HTTP provider previously set by calling c.SetChallengeProvider with the default HTTP challenge provider.
func (*Client) SetTLSAddress ¶ added in v0.2.0
SetTLSAddress specifies a custom interface:port to be used for TLS based challenges. If this option is not used, the default port 443 and all interfaces will be used. To only specify a port and no interface use the ":port" notation.
NOTE: This REPLACES any custom TLS-ALPN provider previously set by calling c.SetChallengeProvider with the default TLS-ALPN challenge provider.
type DNSProviderManual ¶ added in v0.3.0
type DNSProviderManual struct{}
DNSProviderManual is an implementation of the ChallengeProvider interface
func NewDNSProviderManual ¶ added in v0.3.0
func NewDNSProviderManual() (*DNSProviderManual, error)
NewDNSProviderManual returns a DNSProviderManual instance.
func (*DNSProviderManual) CleanUp ¶ added in v0.3.0
func (*DNSProviderManual) CleanUp(domain, token, keyAuth string) error
CleanUp prints instructions for manually removing the TXT record
func (*DNSProviderManual) Present ¶ added in v0.3.0
func (*DNSProviderManual) Present(domain, token, keyAuth string) error
Present prints instructions for manually creating the TXT record
type HTTPProviderServer ¶ added in v0.3.0
type HTTPProviderServer struct {
// contains filtered or unexported fields
}
HTTPProviderServer implements ChallengeProvider for `http-01` challenge It may be instantiated without using the NewHTTPProviderServer function if you want only to use the default values.
func NewHTTPProviderServer ¶ added in v0.3.0
func NewHTTPProviderServer(iface, port string) *HTTPProviderServer
NewHTTPProviderServer creates a new HTTPProviderServer on the selected interface and port. Setting iface and / or port to an empty string will make the server fall back to the "any" interface and port 80 respectively.
func (*HTTPProviderServer) CleanUp ¶ added in v0.3.0
func (s *HTTPProviderServer) CleanUp(domain, token, keyAuth string) error
CleanUp closes the HTTP server and removes the token from `HTTP01ChallengePath(token)`
func (*HTTPProviderServer) Present ¶ added in v0.3.0
func (s *HTTPProviderServer) Present(domain, token, keyAuth string) error
Present starts a web server and makes the token available at `HTTP01ChallengePath(token)` for web requests.
type KeyType ¶ added in v0.3.0
type KeyType string
KeyType represents the key algo as well as the key size or curve to use.
type NonceError ¶ added in v0.4.0
type NonceError struct {
RemoteError
}
NonceError represents the error which is returned if the nonce sent by the client was not accepted by the server.
type ObtainError ¶ added in v1.0.0
ObtainError is returned when there are specific errors available per domain. For example in ObtainCertificate
func (ObtainError) Error ¶ added in v1.0.0
func (e ObtainError) Error() string
type RegistrationResource ¶
type RegistrationResource struct { Body accountMessage `json:"body,omitempty"` URI string `json:"uri,omitempty"` }
RegistrationResource represents all important informations about a registration of which the client needs to keep track itself.
type RemoteError ¶
type RemoteError struct { StatusCode int `json:"status,omitempty"` Type string `json:"type"` Detail string `json:"detail"` }
RemoteError is the base type for all errors specific to the ACME protocol.
func (RemoteError) Error ¶
func (e RemoteError) Error() string
type TLSALPNProviderServer ¶ added in v1.1.0
type TLSALPNProviderServer struct {
// contains filtered or unexported fields
}
TLSALPNProviderServer implements ChallengeProvider for `TLS-ALPN-01` challenge. It may be instantiated without using the NewTLSALPNProviderServer if you want only to use the default values.
func NewTLSALPNProviderServer ¶ added in v1.1.0
func NewTLSALPNProviderServer(iface, port string) *TLSALPNProviderServer
NewTLSALPNProviderServer creates a new TLSALPNProviderServer on the selected interface and port. Setting iface and / or port to an empty string will make the server fall back to the "any" interface and port 443 respectively.
func (*TLSALPNProviderServer) CleanUp ¶ added in v1.1.0
func (t *TLSALPNProviderServer) CleanUp(domain, token, keyAuth string) error
CleanUp closes the HTTPS server.
func (*TLSALPNProviderServer) Present ¶ added in v1.1.0
func (t *TLSALPNProviderServer) Present(domain, token, keyAuth string) error
Present generates a certificate with a SHA-256 digest of the keyAuth provided as the acmeValidation-v1 extension value to conform to the ACME-TLS-ALPN spec.
type TOSError ¶
type TOSError struct {
RemoteError
}
TOSError represents the error which is returned if the user needs to accept the TOS. TODO: include the new TOS url if we can somehow obtain it.
type User ¶
type User interface { GetEmail() string GetRegistration() *RegistrationResource GetPrivateKey() crypto.PrivateKey }
User interface is to be implemented by users of this library. It is used by the client type to get user specific information.