153 lines
6.2 KiB
Plaintext
153 lines
6.2 KiB
Plaintext
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 { ... }
|