Documentation
¶
Overview ¶
Package acme implements the ACME protocol for Let's Encrypt and other conforming providers.
Index ¶
- Constants
- Variables
- func DNS01Record(domain, keyAuth string) (fqdn string, value string, ttl int)
- func GetOCSPForCert(bundle []byte) ([]byte, *ocsp.Response, error)
- func GetPEMCertExpiration(cert []byte) (time.Time, error)
- func HTTP01ChallengePath(token string) string
- func TLSSNI01ChallengeCert(keyAuth string) (tls.Certificate, error)
- type CertificateResource
- type Challenge
- type ChallengeProvider
- type Client
- func (c *Client) AgreeToTOS() error
- func (c *Client) ExcludeChallenges(challenges []Challenge)
- func (c *Client) ObtainCertificate(domains []string, bundle bool, privKey crypto.PrivateKey) (CertificateResource, map[string]error)
- func (c *Client) Register() (*RegistrationResource, error)
- func (c *Client) RenewCertificate(cert CertificateResource, bundle bool) (CertificateResource, 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 DNSProviderCloudFlare
- type DNSProviderDNSimple
- type DNSProviderDigitalOcean
- type DNSProviderManual
- type DNSProviderRFC2136
- type DNSProviderRoute53
- type HTTPProviderServer
- type KeyType
- type Registration
- type RegistrationResource
- type RemoteError
- type TLSProviderServer
- 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") // TLSSNI01 is the "tls-sni-01" ACME challenge https://github.com/ietf-wg-acme/acme/blob/master/draft-ietf-acme-acme.md#tls-with-server-name-indication-tls-sni // Note: TLSSNI01ChallengeCert returns a certificate to fulfill this challenge TLSSNI01 = Challenge("tls-sni-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") )
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 CloudFlareAPIURL = "https://api.cloudflare.com/client/v4"
CloudFlareAPIURL represents the API endpoint to call. TODO: Unexport?
Variables ¶
var ( // Logger is an optional custom logger. Logger *log.Logger )
var UserAgent string
UserAgent (if non-empty) will be tacked onto the User-Agent string in requests.
Functions ¶
func DNS01Record ¶
DNS01Record returns a DNS record which will fulfill the `dns-01` challenge
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 ¶
HTTP01ChallengePath returns the URL path for the `http-01` challenge
func TLSSNI01ChallengeCert ¶
func TLSSNI01ChallengeCert(keyAuth string) (tls.Certificate, error)
TLSSNI01ChallengeCert returns a certificate for the `tls-sni-01` challenge
Types ¶
type CertificateResource ¶
type CertificateResource struct { Domain string `json:"domain"` CertURL string `json:"certUrl"` CertStableURL string `json:"certStableUrl"` PrivateKey []byte `json:"-"` Certificate []byte `json:"-"` }
CertificateResource represents a CA issued certificate. PrivateKey and Certificate are both 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 ¶
type Challenge string
Challenge is a string that identifies a particular type and version of ACME challenge.
type ChallengeProvider ¶
type ChallengeProvider interface { Present(domain, token, keyAuth string) error CleanUp(domain, token, keyAuth string) error }
ChallengeProvider 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 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. It will generate private keys for certificates of size keyBits.
func (*Client) AgreeToTOS ¶
AgreeToTOS updates the Client registration and sends the agreement to the server.
func (*Client) ExcludeChallenges ¶
ExcludeChallenges explicitly removes challenges from the pool for solving.
func (*Client) ObtainCertificate ¶
func (c *Client) ObtainCertificate(domains []string, bundle bool, privKey crypto.PrivateKey) (CertificateResource, map[string]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) Register ¶
func (c *Client) Register() (*RegistrationResource, error)
Register the current account to the ACME server.
func (*Client) RenewCertificate ¶
func (c *Client) RenewCertificate(cert CertificateResource, bundle 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) RevokeCertificate ¶
RevokeCertificate takes a PEM encoded certificate or bundle and tries to revoke it at the CA.
func (*Client) SetChallengeProvider ¶
func (c *Client) SetChallengeProvider(challenge Challenge, p ChallengeProvider) error
SetChallengeProvider specifies a custom provider that will make the solution available
func (*Client) SetHTTPAddress ¶
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.
func (*Client) SetTLSAddress ¶
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.
type DNSProviderCloudFlare ¶
type DNSProviderCloudFlare struct {
// contains filtered or unexported fields
}
DNSProviderCloudFlare is an implementation of the DNSProvider interface
func NewDNSProviderCloudFlare ¶
func NewDNSProviderCloudFlare(cloudflareEmail, cloudflareKey string) (*DNSProviderCloudFlare, error)
NewDNSProviderCloudFlare returns a DNSProviderCloudFlare instance with a configured cloudflare client. Credentials can either be passed as arguments or through CLOUDFLARE_EMAIL and CLOUDFLARE_API_KEY env vars.
func (*DNSProviderCloudFlare) CleanUp ¶
func (c *DNSProviderCloudFlare) CleanUp(domain, token, keyAuth string) error
CleanUp removes the TXT record matching the specified parameters
func (*DNSProviderCloudFlare) Present ¶
func (c *DNSProviderCloudFlare) Present(domain, token, keyAuth string) error
Present creates a TXT record to fulfil the dns-01 challenge
type DNSProviderDNSimple ¶
type DNSProviderDNSimple struct {
// contains filtered or unexported fields
}
DNSProviderDNSimple is an implementation of the DNSProvider interface.
func NewDNSProviderDNSimple ¶
func NewDNSProviderDNSimple(dnsimpleEmail, dnsimpleAPIKey string) (*DNSProviderDNSimple, error)
NewDNSProviderDNSimple returns a DNSProviderDNSimple instance with a configured dnsimple client. Authentication is either done using the passed credentials or - when empty - using the environment variables DNSIMPLE_EMAIL and DNSIMPLE_API_KEY.
func (*DNSProviderDNSimple) CleanUp ¶
func (c *DNSProviderDNSimple) CleanUp(domain, token, keyAuth string) error
CleanUp removes the TXT record matching the specified parameters.
func (*DNSProviderDNSimple) Present ¶
func (c *DNSProviderDNSimple) Present(domain, token, keyAuth string) error
Present creates a TXT record to fulfil the dns-01 challenge.
type DNSProviderDigitalOcean ¶
type DNSProviderDigitalOcean struct {
// contains filtered or unexported fields
}
DNSProviderDigitalOcean is an implementation of the DNSProvider interface that uses DigitalOcean's REST API to manage TXT records for a domain.
func NewDNSProviderDigitalOcean ¶
func NewDNSProviderDigitalOcean(apiAuthToken string) (*DNSProviderDigitalOcean, error)
NewDNSProviderDigitalOcean returns a new DNSProviderDigitalOcean instance. apiAuthToken is the personal access token created in the DigitalOcean account control panel, and it will be sent in bearer authorization headers.
func (*DNSProviderDigitalOcean) CleanUp ¶
func (d *DNSProviderDigitalOcean) CleanUp(domain, token, keyAuth string) error
CleanUp removes the TXT record matching the specified parameters
func (*DNSProviderDigitalOcean) Present ¶
func (d *DNSProviderDigitalOcean) Present(domain, token, keyAuth string) error
Present creates a TXT record using the specified parameters
type DNSProviderManual ¶
type DNSProviderManual struct{}
DNSProviderManual is an implementation of the ChallengeProvider interface
func NewDNSProviderManual ¶
func NewDNSProviderManual() (*DNSProviderManual, error)
NewDNSProviderManual returns a DNSProviderManual instance.
func (*DNSProviderManual) CleanUp ¶
func (*DNSProviderManual) CleanUp(domain, token, keyAuth string) error
CleanUp prints instructions for manually removing the TXT record
func (*DNSProviderManual) Present ¶
func (*DNSProviderManual) Present(domain, token, keyAuth string) error
Present prints instructions for manually creating the TXT record
type DNSProviderRFC2136 ¶
type DNSProviderRFC2136 struct {
// contains filtered or unexported fields
}
DNSProviderRFC2136 is an implementation of the ChallengeProvider interface that uses dynamic DNS updates (RFC 2136) to create TXT records on a nameserver.
func NewDNSProviderRFC2136 ¶
func NewDNSProviderRFC2136(nameserver, tsigAlgorithm, tsigKey, tsigSecret string) (*DNSProviderRFC2136, error)
NewDNSProviderRFC2136 returns a new DNSProviderRFC2136 instance. To disable TSIG authentication 'tsigAlgorithm, 'tsigKey' and 'tsigSecret' must be set to the empty string. 'nameserver' must be a network address in the the form "host" or "host:port".
func (*DNSProviderRFC2136) CleanUp ¶
func (r *DNSProviderRFC2136) CleanUp(domain, token, keyAuth string) error
CleanUp removes the TXT record matching the specified parameters
func (*DNSProviderRFC2136) Present ¶
func (r *DNSProviderRFC2136) Present(domain, token, keyAuth string) error
Present creates a TXT record using the specified parameters
type DNSProviderRoute53 ¶
type DNSProviderRoute53 struct {
// contains filtered or unexported fields
}
DNSProviderRoute53 is an implementation of the DNSProvider interface
func NewDNSProviderRoute53 ¶
func NewDNSProviderRoute53(awsAccessKey, awsSecretKey, awsRegionName string) (*DNSProviderRoute53, error)
NewDNSProviderRoute53 returns a DNSProviderRoute53 instance with a configured route53 client. Authentication is either done using the passed credentials or - when empty - falling back to the customary AWS credential mechanisms, including the file referenced by $AWS_CREDENTIAL_FILE (defaulting to $HOME/.aws/credentials) optionally scoped to $AWS_PROFILE, credentials supplied by the environment variables AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY [ + AWS_SECURITY_TOKEN ], and finally credentials available via the EC2 instance metadata service.
func (*DNSProviderRoute53) CleanUp ¶
func (r *DNSProviderRoute53) CleanUp(domain, token, keyAuth string) error
CleanUp removes the TXT record matching the specified parameters
func (*DNSProviderRoute53) Present ¶
func (r *DNSProviderRoute53) Present(domain, token, keyAuth string) error
Present creates a TXT record using the specified parameters
type HTTPProviderServer ¶
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 ¶
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 ¶
func (s *HTTPProviderServer) CleanUp(domain, token, keyAuth string) error
CleanUp closes the HTTP server and removes the token from `HTTP01ChallengePath(token)`
func (*HTTPProviderServer) Present ¶
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 ¶
type KeyType string
KeyType represents the key algo as well as the key size or curve to use.
type Registration ¶
type Registration struct { Resource string `json:"resource,omitempty"` ID int `json:"id"` Key jose.JsonWebKey `json:"key"` Contact []string `json:"contact"` Agreement string `json:"agreement,omitempty"` Authorizations string `json:"authorizations,omitempty"` Certificates string `json:"certificates,omitempty"` }
Registration is returned by the ACME server after the registration The client implementation should save this registration somewhere.
type RegistrationResource ¶
type RegistrationResource struct { Body Registration `json:"body,omitempty"` URI string `json:"uri,omitempty"` NewAuthzURL string `json:"new_authzr_uri,omitempty"` TosURL string `json:"terms_of_service,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 TLSProviderServer ¶
type TLSProviderServer struct {
// contains filtered or unexported fields
}
TLSProviderServer implements ChallengeProvider for `TLS-SNI-01` challenge It may be instantiated without using the NewTLSProviderServer function if you want only to use the default values.
func NewTLSProviderServer ¶
func NewTLSProviderServer(iface, port string) *TLSProviderServer
NewTLSProviderServer creates a new TLSProviderServer 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 (*TLSProviderServer) CleanUp ¶
func (s *TLSProviderServer) CleanUp(domain, token, keyAuth string) error
CleanUp closes the HTTP server.
func (*TLSProviderServer) Present ¶
func (s *TLSProviderServer) Present(domain, token, keyAuth string) error
Present makes the keyAuth available as a cert
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.
Source Files
¶
- challenges.go
- client.go
- crypto.go
- dns_challenge.go
- dns_challenge_cloudflare.go
- dns_challenge_digitalocean.go
- dns_challenge_dnsimple.go
- dns_challenge_manual.go
- dns_challenge_rfc2136.go
- dns_challenge_route53.go
- error.go
- http.go
- http_challenge.go
- http_challenge_server.go
- jws.go
- messages.go
- pop_challenge.go
- provider.go
- tls_sni_challenge.go
- tls_sni_challenge_server.go