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 ¶
var ErrCacheMiss = errors.New("acme/autocert: certificate cache miss")
ErrCacheMiss is returned when a certificate is not found in cache.
Functions ¶
Types ¶
type Cache ¶
type Cache interface {
// Get returns a certificate data for the specified key.
// If there's no such key, Get returns ErrCacheMiss.
Get(ctx context.Context, key string) ([]byte, error)
// Put stores the data in the cache under the specified key.
// Underlying implementations may use any data storage format,
// as long as the reverse operation, Get, results in the original data.
Put(ctx context.Context, key string, data []byte) error
// Delete removes a certificate data from the cache under the specified key.
// If there's no such key in the cache, Delete returns nil.
Delete(ctx context.Context, key string) error
}
Cache is used by Manager to store and retrieve previously obtained certificates as opaque data.
The key argument of the methods refers to a domain name but need not be an FQDN. Cache implementations should not rely on the key naming pattern.
type DirCache ¶
type DirCache string
DirCache implements Cache using a directory on the local filesystem. If the directory does not exist, it will be created with 0700 permissions.
type HostPolicy ¶
HostPolicy specifies which host names the Manager is allowed to respond to. It returns a non-nil error if the host should be rejected. The returned error is accessible via tls.Conn.Handshake and its callers. See Manager's HostPolicy field and GetCertificate method docs for more details.
func HostWhitelist ¶
func HostWhitelist(hosts ...string) HostPolicy
HostWhitelist returns a policy where only the specified host names are allowed. Only exact matches are currently supported. Subdomains, regexp or wildcard will not match.
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 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 HostPolicy
// RenewBefore optionally specifies how early certificates should
// be renewed before they expire.
//
// If zero, they're renewed 1 week 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
// contains filtered or unexported fields
}
Manager is a stateful certificate manager built on top of acme.Client. It obtains and refreshes certificates automatically, as well as providing them to a TLS server via tls.Config.
A simple usage example:
m := autocert.Manager{
Prompt: autocert.AcceptTOS,
HostPolicy: autocert.HostWhitelist("example.org"),
}
s := &http.Server{
Addr: ":https",
TLSConfig: &tls.Config{GetCertificate: m.GetCertificate},
}
s.ListenAndServeTLS("", "")
To preserve issued certificates and improve overall performance, use a cache implementation of Cache. For instance, DirCache.
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.
Source Files