package letsencrypt // import "rsc.io/letsencrypt" Package letsencrypt obtains TLS certificates from LetsEncrypt.org. LetsEncrypt.org is a service that issues free SSL/TLS certificates to servers that can prove control over the given domain's DNS records or the servers pointed at by those records. Quick Start A complete HTTP/HTTPS web server using TLS certificates from LetsEncrypt.org, redirecting all HTTP access to HTTPS, and maintaining TLS certificates in a file letsencrypt.cache across server restarts. package main import ( "fmt" "log" "net/http" "rsc.io/letsencrypt" ) func main() { http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) { fmt.Fprintf(w, "Hello, TLS!\n") }) var m letsencrypt.Manager if err := m.CacheFile("letsencrypt.cache"); err != nil { log.Fatal(err) } log.Fatal(m.Serve()) } Overview The fundamental type in this package is the Manager, which manages obtaining and refreshing a collection of TLS certificates, typically for use by an HTTPS server. The example above shows the most basic use of a Manager. The use can be customized by calling additional methods of the Manager. Registration A Manager m registers anonymously with LetsEncrypt.org, including agreeing to the letsencrypt.org terms of service, the first time it needs to obtain a certificate. To register with a particular email address and with the option of a prompt for agreement with the terms of service, call m.Register. GetCertificate The Manager's GetCertificate method returns certificates from the Manager's cache, filling the cache by requesting certificates from LetsEncrypt.org. In this way, a server with a tls.Config.GetCertificate set to m.GetCertificate will demand load a certificate for any host name it serves. To force loading of certificates ahead of time, install m.GetCertificate as before but then call m.Cert for each host name. A Manager can only obtain a certificate for a given host name if it can prove control of that host name to LetsEncrypt.org. By default it proves control by answering an HTTPS-based challenge: when the LetsEncrypt.org servers connect to the named host on port 443 (HTTPS), the TLS SNI handshake must use m.GetCertificate to obtain a per-host certificate. The most common way to satisfy this requirement is for the host name to resolve to the IP address of a (single) computer running m.ServeHTTPS, or at least running a Go TLS server with tls.Config.GetCertificate set to m.GetCertificate. However, other configurations are possible. For example, a group of machines could use an implementation of tls.Config.GetCertificate that cached certificates but handled cache misses by making RPCs to a Manager m on an elected leader machine. In typical usage, then, the setting of tls.Config.GetCertificate to m.GetCertificate serves two purposes: it provides certificates to the TLS server for ordinary serving, and it also answers challenges to prove ownership of the domains in order to obtain those certificates. To force the loading of a certificate for a given host into the Manager's cache, use m.Cert. Persistent Storage If a server always starts with a zero Manager m, the server effectively fetches a new certificate for each of its host name from LetsEncrypt.org on each restart. This is unfortunate both because the server cannot start if LetsEncrypt.org is unavailable and because LetsEncrypt.org limits how often it will issue a certificate for a given host name (at time of writing, the limit is 5 per week for a given host name). To save server state proactively to a cache file and to reload the server state from that same file when creating a new manager, call m.CacheFile with the name of the file to use. For alternate storage uses, m.Marshal returns the current state of the Manager as an opaque string, m.Unmarshal sets the state of the Manager using a string previously returned by m.Marshal (usually a different m), and m.Watch returns a channel that receives notifications about state changes. Limits To avoid hitting basic rate limits on LetsEncrypt.org, a given Manager limits all its interactions to at most one request every minute, with an initial allowed burst of 20 requests. By default, if GetCertificate is asked for a certificate it does not have, it will in turn ask LetsEncrypt.org for that certificate. This opens a potential attack where attackers connect to a server by IP address and pretend to be asking for an incorrect host name. Then GetCertificate will attempt to obtain a certificate for that host, incorrectly, eventually hitting LetsEncrypt.org's rate limit for certificate requests and making it impossible to obtain actual certificates. Because servers hold certificates for months at a time, however, an attack would need to be sustained over a time period of at least a month in order to cause real problems. To mitigate this kind of attack, a given Manager limits itself to an average of one certificate request for a new host every three hours, with an initial allowed burst of up to 20 requests. Long-running servers will therefore stay within the LetsEncrypt.org limit of 300 failed requests per month. Certificate refreshes are not subject to this limit. To eliminate the attack entirely, call m.SetHosts to enumerate the exact set of hosts that are allowed in certificate requests. Web Servers The basic requirement for use of a Manager is that there be an HTTPS server running on port 443 and calling m.GetCertificate to obtain TLS certificates. Using standard primitives, the way to do this is: srv := &http.Server{ Addr: ":https", TLSConfig: &tls.Config{ GetCertificate: m.GetCertificate, }, } srv.ListenAndServeTLS("", "") However, this pattern of serving HTTPS with demand-loaded TLS certificates comes up enough to wrap into a single method m.ServeHTTPS. Similarly, many HTTPS servers prefer to redirect HTTP clients to the HTTPS URLs. That functionality is provided by RedirectHTTP. The combination of serving HTTPS with demand-loaded TLS certificates and serving HTTPS redirects to HTTP clients is provided by m.Serve, as used in the original example above. func RedirectHTTP(w http.ResponseWriter, r *http.Request) type Manager struct { ... }