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 ¶
Examples ¶
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 ¶
func AcceptTOS ¶
AcceptTOS is a Manager.Prompt function that always returns true to indicate acceptance of the CA's Terms of Service during account registration.
func NewListener ¶
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 ¶
package main
import (
"fmt"
"log"
"net/http"
"github.com/Psiphon-Labs/psiphon-tunnel-core/psiphon/common/crypto/acme/autocert"
)
func main() {
mux := http.NewServeMux()
mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
fmt.Fprintf(w, "Hello, TLS user! Your config: %+v", r.TLS)
})
log.Fatal(http.Serve(autocert.NewListener("example.com"), mux))
}
Output:
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 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
// 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.
To preserve issued certificates and improve overall performance, use a cache implementation of Cache. For instance, DirCache.
Example ¶
package main
import (
"crypto/tls"
"net/http"
"github.com/Psiphon-Labs/psiphon-tunnel-core/psiphon/common/crypto/acme/autocert"
)
func main() {
m := autocert.Manager{
Prompt: autocert.AcceptTOS,
HostPolicy: autocert.HostWhitelist("example.org"),
}
s := &http.Server{
Addr: ":https",
TLSConfig: &tls.Config{GetCertificate: m.GetCertificate},
}
s.ListenAndServeTLS("", "")
}
Output:
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.
func (*Manager) Listener ¶
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.
Source Files