Documentation ¶
Overview ¶
Package autocert provides automatic access to certificates from Let's Encrypt and any other ACME-based CA.
This package is a work in progress and makes no API stability promises.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Manager ¶
type Manager struct { // Prompt specifies a callback function to conditionally accept a CA's Terms of Service (TOS). // The registration may require the caller to agree to the CA's TOS. // If so, Manager calls Prompt with a TOS URL provided by the CA. Prompt should report // whether the caller agrees to the terms. // // To always accept the terms, the callers can use AcceptTOS. Prompt func(tosURL string) bool // Cache optionally stores and retrieves previously-obtained certificates. // If nil, certs will only be cached for the lifetime of the Manager. // // Manager passes the Cache certificates data encoded in PEM, with private/public // parts combined in a single Cache.Put call, private key first. Cache public.Cache // HostPolicy controls which domains the Manager will attempt // to retrieve new certificates for. It does not affect cached certs. // // If non-nil, HostPolicy is called before requesting a new cert. // If nil, all hosts are currently allowed. This is not recommended, // as it opens a potential attack where clients connect to a server // by IP address and pretend to be asking for an incorrect host name. // Manager will attempt to obtain a certificate for that host, incorrectly, // eventually reaching the CA's rate limit for certificate requests // and making it impossible to obtain actual certificates. // // See GetCertificate for more details. HostPolicy public.HostPolicy // RenewBefore optionally specifies how early certificates should // be renewed before they expire. // // If zero, they're renewed 30 days before expiration. RenewBefore time.Duration // Client is used to perform low-level operations, such as account registration // and requesting new certificates. // If Client is nil, a zero-value acme.Client is used with acme.LetsEncryptURL // directory endpoint and a newly-generated ECDSA P-256 key. // // Mutating the field after the first call of GetCertificate method will have no effect. Client *acme.Client // Email optionally specifies a contact email address. // This is used by CAs, such as Let's Encrypt, to notify about problems // with issued certificates. // // If the Client's account key is already registered, Email is not used. Email string // ForceRSA makes the Manager generate certificates with 2048-bit RSA keys. // // If false, a default is used. Currently the default // is EC-based keys using the P-256 curve. ForceRSA bool // Verify runs the identifier (domain) authorization flow // using each applicable ACME challenge type. Verify func(ctx context.Context, client *acme.Client, domain string) error // contains filtered or unexported fields }
Manager is a stateful certificate manager built on top of acme.Client. It obtains and refreshes certificates automatically using "tls-sni-01", "tls-sni-02" and "http-01" challenge types, as well as providing them to a TLS server via tls.Config.
You must specify a cache implementation, such as DirCache, to reuse obtained certificates across program restarts. Otherwise your server is very likely to exceed the certificate issuer's request rate limits.
func (*Manager) GetCertificate ¶
func (m *Manager) GetCertificate(hello *tls.ClientHelloInfo) (*tls.Certificate, error)
GetCertificate implements the tls.Config.GetCertificate hook. It provides a TLS certificate for hello.ServerName host, including answering *.acme.invalid (TLS-SNI) challenges. All other fields of hello are ignored.
If m.HostPolicy is non-nil, GetCertificate calls the policy before requesting a new cert. A non-nil error returned from m.HostPolicy halts TLS negotiation. The error is propagated back to the caller of GetCertificate and is user-visible. This does not affect cached certs. See HostPolicy field description for more details.