This package is not in the latest version of its module.
Go to latest Published: May 22, 2026 License: BSD-3-ClauseThe Go module system was introduced in Go 1.11 and is the official dependency management solution for Go.
Redistributable licenses place minimal restrictions on how software can be used, modified, and redistributed.
Modules with tagged versions give importers more predictable builds.
When a project reaches major version v1 it is considered stable.
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.
DefaultACMEDirectory is the default ACME Directory URL used when the Manager's Client is nil.
ErrCacheMiss is returned when a certificate is not found in cache.
AcceptTOS is a Manager.Prompt function that always returns true to indicate acceptance of the CA's Terms of Service during account registration.
NewListener returns a net.Listener that listens on the standard TLS port (443) on all interfaces and returns *tls.Conn connections with LetsEncrypt certificates for the provided domain or domains.
It enables one-line HTTPS servers:
log.Fatal(http.Serve(autocert.NewListener("example.com"), handler))NewListener is a convenience function for a common configuration. More complex or custom configurations can use the autocert.Manager type instead.
Use of this function implies acceptance of the LetsEncrypt Terms of Service. If domains is not empty, the provided domains are passed to HostWhitelist. If domains is empty, the listener will do LetsEncrypt challenges for any requested domain, which is not recommended.
Certificates are cached in a "golang-autocert" directory under an operating system-specific cache or temp directory. This may not be suitable for servers spanning multiple machines.
The returned listener uses a *tls.Config that enables HTTP/2, and should only be used with servers that support HTTP/2.
The returned Listener also enables TCP keep-alives on the accepted connections. The returned *tls.Conn are returned before their TLS handshake has completed.
Example ¶Cache is used by Manager to store and retrieve previously obtained certificates and other account data as opaque blobs.
Cache implementations should not rely on the key naming pattern. Keys can include any printable ASCII characters, except the following: \/:*?"<>|
DirCache implements Cache using a directory on the local filesystem. If the directory does not exist, it will be created with 0700 permissions.
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.
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.
Note that all hosts will be converted to Punycode via idna.Lookup.ToASCII so that Manager.GetCertificate can handle the Unicode IDN and mixedcase hosts correctly. Invalid hosts will be silently ignored.
Manager is a stateful certificate manager built on top of acme.Client. It obtains and refreshes certificates automatically using "tls-alpn-01" or "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.
Example ¶GetCertificate implements the tls.Config.GetCertificate hook. It provides a TLS certificate for hello.ServerName host, including answering tls-alpn-01 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.
If GetCertificate is used directly, instead of via Manager.TLSConfig, package users will also have to add acme.ALPNProto to NextProtos for tls-alpn-01, or use HTTPHandler for http-01.
HTTPHandler configures the Manager to provision ACME "http-01" challenge responses. It returns an http.Handler that responds to the challenges and must be running on port 80. If it receives a request that is not an ACME challenge, it delegates the request to the optional fallback handler.
If fallback is nil, the returned handler redirects all GET and HEAD requests to the default TLS port 443 with 302 Found status code, preserving the original request path and query. It responds with 400 Bad Request to all other HTTP methods. The fallback is not protected by the optional HostPolicy.
Because the fallback handler is run with unencrypted port 80 requests, the fallback should not serve TLS-only requests.
If HTTPHandler is never called, the Manager will only use the "tls-alpn-01" challenge for domain verification.
Listener listens on the standard TLS port (443) on all interfaces and returns a net.Listener returning *tls.Conn connections.
The returned listener uses a *tls.Config that enables HTTP/2, and should only be used with servers that support HTTP/2.
The returned Listener also enables TCP keep-alives on the accepted connections. The returned *tls.Conn are returned before their TLS handshake has completed.
Unlike NewListener, it is the caller's responsibility to initialize the Manager m's Prompt, Cache, HostPolicy, and other desired options.
| ? | : This menu |
| / | : Search site |
| f or F | : Jump to |
| y or Y | : Canonical URL |