acme

package
v1.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 5, 2018 License: MIT Imports: 34 Imported by: 0

Documentation

Overview

Package acme implements the ACME protocol for Let's Encrypt and other conforming providers.

Index

Constants

View Source 
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")
)
View Source 
const (
	EC256   = KeyType("P256")
	EC384   = KeyType("P384")
	RSA2048 = KeyType("2048")
	RSA4096 = KeyType("4096")
	RSA8192 = KeyType("8192")
)

Constants for all key types we support.

View Source 
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
)
View Source 
const (
	// DefaultPropagationTimeout default propagation timeout
	DefaultPropagationTimeout = 60 * time.Second

	// DefaultPollingInterval default polling interval
	DefaultPollingInterval = 2 * time.Second

	// DefaultTTL default TTL
	DefaultTTL = 120
)
View Source 
const (
	// ACMETLS1Protocol is the ALPN Protocol ID for the ACME-TLS/1 Protocol.
	ACMETLS1Protocol = "acme-tls/1"
)

Variables

View Source 
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(),
			},
		},
	}
)
View Source 
var DNSTimeout = 10 * time.Second

DNSTimeout is used to override the default DNS timeout of 10 seconds.

View Source 
var (
	// PreCheckDNS checks DNS propagation before notifying ACME that
	// the DNS challenge is ready.
	PreCheckDNS preCheckDNSFunc = checkDNSPropagation
)
View Source 
var RecursiveNameservers = getNameservers(defaultResolvConf, defaultNameservers)

RecursiveNameservers are used to pre-check DNS propagation

Functions

func ClearFqdnCache 

func ClearFqdnCache()

ClearFqdnCache clears the cache of fqdn to zone mappings. Primarily used in testing.

func DNS01Record 

func DNS01Record(domain, keyAuth string) (fqdn string, value string, ttl int)

DNS01Record returns a DNS record which will fulfill the `dns-01` challenge

func FindZoneByFqdn 

func FindZoneByFqdn(fqdn string, nameservers []string) (string, error)

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 

func GetOCSPForCert(bundle []byte) ([]byte, *ocsp.Response, error)

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 

func GetPEMCertExpiration(cert []byte) (time.Time, error)

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 

func HTTP01ChallengePath(token string) string

HTTP01ChallengePath returns the URL path for the `http-01` challenge

func TLSALPNChallengeBlocks 

func TLSALPNChallengeBlocks(domain, keyAuth string) ([]byte, []byte, error)

TLSALPNChallengeBlocks returns PEM blocks (certPEMBlock, keyPEMBlock) with the acmeValidation-v1 extension and domain name for the `tls-alpn-01` challenge.

func TLSALPNChallengeCert 

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.

func ToFqdn 

func ToFqdn(name string) string

ToFqdn converts the name into a fqdn appending a trailing dot.

func UnFqdn 

func UnFqdn(name string) string

UnFqdn converts the fqdn into a name removing the trailing dot.

func WaitFor 

func WaitFor(timeout, interval time.Duration, f func() (bool, error)) error

WaitFor polls the given function 'f', once every 'interval', up to 'timeout'.

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 

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 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 

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 

func NewClient(caDirURL string, user User, keyType KeyType) (*Client, error)

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 

func (c *Client) DeleteRegistration() error

DeleteRegistration deletes the client's user registration from the ACME server.

func (*Client) ExcludeChallenges 

func (c *Client) ExcludeChallenges(challenges []Challenge)

ExcludeChallenges explicitly removes challenges from the pool for solving.

func (*Client) GetExternalAccountRequired 

func (c *Client) GetExternalAccountRequired() bool

GetExternalAccountRequired returns the External Account Binding requirement of the Directory

func (*Client) GetToSURL 

func (c *Client) GetToSURL() string

GetToSURL returns the current ToS URL from the Directory

func (*Client) ObtainCertificate 

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 

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 

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 

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 

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 

func (c *Client) RevokeCertificate(certificate []byte) error

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 p that can solve the given challenge type.

func (*Client) SetHTTPAddress 

func (c *Client) SetHTTPAddress(iface string) error

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 

func (c *Client) SetTLSAddress(iface string) error

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 

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 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 NonceError 

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 

type ObtainError map[string]error

ObtainError is returned when there are specific errors available per domain. For example in ObtainCertificate

func (ObtainError) Error 

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 

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 

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 

func (t *TLSALPNProviderServer) CleanUp(domain, token, keyAuth string) error

CleanUp closes the HTTPS server.

func (*TLSALPNProviderServer) Present 

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.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.