1package letsencrypt // import "rsc.io/letsencrypt" 2 3Package letsencrypt obtains TLS certificates from LetsEncrypt.org. 4 5LetsEncrypt.org is a service that issues free SSL/TLS certificates to 6servers that can prove control over the given domain's DNS records or the 7servers pointed at by those records. 8 9 10Warning 11 12Like any other random code you find on the internet, this package should not 13be relied upon in important, production systems without thorough testing to 14ensure that it meets your needs. 15 16In the long term you should be using 17https://golang.org/x/crypto/acme/autocert instead of this package. Send 18improvements there, not here. 19 20This is a package that I wrote for my own personal web sites (swtch.com, 21rsc.io) in a hurry when my paid-for SSL certificate was expiring. It has no 22tests, has barely been used, and there is some anecdotal evidence that it 23does not properly renew certificates in a timely fashion, so servers that 24run for more than 3 months may run into trouble. I don't run this code 25anymore: to simplify maintenance, I moved the sites off of Ubuntu VMs and 26onto Google App Engine, configured with inexpensive long-term certificates 27purchased from cheapsslsecurity.com. 28 29This package was interesting primarily as an example of how simple the API 30for using LetsEncrypt.org could be made, in contrast to the low-level 31implementations that existed at the time. In that respect, it helped inform 32the design of the golang.org/x/crypto/acme/autocert package. 33 34 35Quick Start 36 37A complete HTTP/HTTPS web server using TLS certificates from 38LetsEncrypt.org, redirecting all HTTP access to HTTPS, and maintaining TLS 39certificates in a file letsencrypt.cache across server restarts. 40 41 package main 42 43 import ( 44 "fmt" 45 "log" 46 "net/http" 47 "rsc.io/letsencrypt" 48 ) 49 50 func main() { 51 http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) { 52 fmt.Fprintf(w, "Hello, TLS!\n") 53 }) 54 var m letsencrypt.Manager 55 if err := m.CacheFile("letsencrypt.cache"); err != nil { 56 log.Fatal(err) 57 } 58 log.Fatal(m.Serve()) 59 } 60 61 62Overview 63 64The fundamental type in this package is the Manager, which manages obtaining 65and refreshing a collection of TLS certificates, typically for use by an 66HTTPS server. The example above shows the most basic use of a Manager. The 67use can be customized by calling additional methods of the Manager. 68 69 70Registration 71 72A Manager m registers anonymously with LetsEncrypt.org, including agreeing 73to the letsencrypt.org terms of service, the first time it needs to obtain a 74certificate. To register with a particular email address and with the option 75of a prompt for agreement with the terms of service, call m.Register. 76 77 78GetCertificate 79 80The Manager's GetCertificate method returns certificates from the Manager's 81cache, filling the cache by requesting certificates from LetsEncrypt.org. In 82this way, a server with a tls.Config.GetCertificate set to m.GetCertificate 83will demand load a certificate for any host name it serves. To force loading 84of certificates ahead of time, install m.GetCertificate as before but then 85call m.Cert for each host name. 86 87A Manager can only obtain a certificate for a given host name if it can 88prove control of that host name to LetsEncrypt.org. By default it proves 89control by answering an HTTPS-based challenge: when the LetsEncrypt.org 90servers connect to the named host on port 443 (HTTPS), the TLS SNI handshake 91must use m.GetCertificate to obtain a per-host certificate. The most common 92way to satisfy this requirement is for the host name to resolve to the IP 93address of a (single) computer running m.ServeHTTPS, or at least running a 94Go TLS server with tls.Config.GetCertificate set to m.GetCertificate. 95However, other configurations are possible. For example, a group of machines 96could use an implementation of tls.Config.GetCertificate that cached 97certificates but handled cache misses by making RPCs to a Manager m on an 98elected leader machine. 99 100In typical usage, then, the setting of tls.Config.GetCertificate to 101m.GetCertificate serves two purposes: it provides certificates to the TLS 102server for ordinary serving, and it also answers challenges to prove 103ownership of the domains in order to obtain those certificates. 104 105To force the loading of a certificate for a given host into the Manager's 106cache, use m.Cert. 107 108 109Persistent Storage 110 111If a server always starts with a zero Manager m, the server effectively 112fetches a new certificate for each of its host name from LetsEncrypt.org on 113each restart. This is unfortunate both because the server cannot start if 114LetsEncrypt.org is unavailable and because LetsEncrypt.org limits how often 115it will issue a certificate for a given host name (at time of writing, the 116limit is 5 per week for a given host name). To save server state proactively 117to a cache file and to reload the server state from that same file when 118creating a new manager, call m.CacheFile with the name of the file to use. 119 120For alternate storage uses, m.Marshal returns the current state of the 121Manager as an opaque string, m.Unmarshal sets the state of the Manager using 122a string previously returned by m.Marshal (usually a different m), and 123m.Watch returns a channel that receives notifications about state changes. 124 125 126Limits 127 128To avoid hitting basic rate limits on LetsEncrypt.org, a given Manager 129limits all its interactions to at most one request every minute, with an 130initial allowed burst of 20 requests. 131 132By default, if GetCertificate is asked for a certificate it does not have, 133it will in turn ask LetsEncrypt.org for that certificate. This opens a 134potential attack where attackers connect to a server by IP address and 135pretend to be asking for an incorrect host name. Then GetCertificate will 136attempt to obtain a certificate for that host, incorrectly, eventually 137hitting LetsEncrypt.org's rate limit for certificate requests and making it 138impossible to obtain actual certificates. Because servers hold certificates 139for months at a time, however, an attack would need to be sustained over a 140time period of at least a month in order to cause real problems. 141 142To mitigate this kind of attack, a given Manager limits itself to an average 143of one certificate request for a new host every three hours, with an initial 144allowed burst of up to 20 requests. Long-running servers will therefore stay 145within the LetsEncrypt.org limit of 300 failed requests per month. 146Certificate refreshes are not subject to this limit. 147 148To eliminate the attack entirely, call m.SetHosts to enumerate the exact set 149of hosts that are allowed in certificate requests. 150 151 152Web Servers 153 154The basic requirement for use of a Manager is that there be an HTTPS server 155running on port 443 and calling m.GetCertificate to obtain TLS certificates. 156Using standard primitives, the way to do this is: 157 158 srv := &http.Server{ 159 Addr: ":https", 160 TLSConfig: &tls.Config{ 161 GetCertificate: m.GetCertificate, 162 }, 163 } 164 srv.ListenAndServeTLS("", "") 165 166However, this pattern of serving HTTPS with demand-loaded TLS certificates 167comes up enough to wrap into a single method m.ServeHTTPS. 168 169Similarly, many HTTPS servers prefer to redirect HTTP clients to the HTTPS 170URLs. That functionality is provided by RedirectHTTP. 171 172The combination of serving HTTPS with demand-loaded TLS certificates and 173serving HTTPS redirects to HTTP clients is provided by m.Serve, as used in 174the original example above. 175 176func RedirectHTTP(w http.ResponseWriter, r *http.Request) 177type Manager struct { ... } 178