letsencrypt

func (*Manager) CacheFile ¶

func (m *Manager) CacheFile(name string) error

func (*Manager) Cert ¶

func (m *Manager) Cert(host string) (*tls.Certificate, error)

Cert returns the certificate for the given host name, obtaining a new one if necessary.

As noted in the documentation for Manager and for the GetCertificate method, obtaining a certificate requires that m.GetCertificate be associated with host. In most servers, simply starting a TLS server with a configuration referring to m.GetCertificate is sufficient, and Cert need not be called.

The main use of Cert is to force the manager to obtain a certificate for a particular host name ahead of time.

func (*Manager) GetCertificate ¶

func (m *Manager) GetCertificate(clientHello *tls.ClientHelloInfo) (*tls.Certificate, error)

GetCertificate can be placed a tls.Config's GetCertificate field to make the TLS server use Let's Encrypt certificates. Each time a client connects to the TLS server expecting a new host name, the TLS server's call to GetCertificate will trigger an exchange with the Let's Encrypt servers to obtain that certificate, subject to the manager rate limits.

As noted in the Manager's documentation comment, to obtain a certificate for a given host name, that name must resolve to a computer running a TLS server on port 443 that obtains TLS SNI certificates by calling m.GetCertificate. In the standard usage, then, installing m.GetCertificate in the tls.Config both automatically provisions the TLS certificates needed for ordinary HTTPS service and answers the challenges from LetsEncrypt.org.

func (*Manager) Marshal ¶

func (m *Manager) Marshal() string

Marshal returns an encoding of the manager's state, suitable for writing to disk and reloading by calling Unmarshal. The state includes registration status, the configured host list from SetHosts, and all known certificates, including their private cryptographic keys. Consequently, the state should be kept private.

func (*Manager) Register ¶

func (m *Manager) Register(email string, prompt func(string) bool) error

Register registers the manager with letsencrypt.org, using the given email address. Registration may require agreeing to the letsencrypt.org terms of service. If so, Register calls prompt(url) where url is the URL of the terms of service. Prompt should report whether the caller agrees to the terms. A nil prompt func is taken to mean that the user always agrees. The email address is sent to LetsEncrypt.org but otherwise unchecked; it can be omitted by passing the empty string.

Calling Register is only required to make sure registration uses a particular email address or to insert an explicit prompt into the registration sequence. If the manager is not registered, it will automatically register with no email address and automatic agreement to the terms of service at the first call to Cert or GetCertificate.

func (*Manager) Registered ¶

func (m *Manager) Registered() bool

Registered reports whether the manager has registered with letsencrypt.org yet.

func (*Manager) SetHosts ¶

func (m *Manager) SetHosts(hosts []string)

SetHosts sets the manager's list of known host names. If the list is non-nil, the manager will only ever attempt to acquire certificates for host names on the list. If the list is nil, the manager does not restrict the hosts it will ask for certificates for.

func (*Manager) Unmarshal ¶

func (m *Manager) Unmarshal(enc string) error

Unmarshal restores the state encoded by a previous call to Marshal (perhaps on a different Manager in a different program).

func (*Manager) Watch ¶

func (m *Manager) Watch() <-chan struct{}

Watch returns the manager's watch channel, which delivers a notification after every time the manager's state (as exposed by Marshal and Unmarshal) changes. All calls to Watch return the same watch channel.

The watch channel includes notifications about changes before the first call to Watch, so that in the pattern below, the range loop executes once immediately, saving the result of setup (along with any background updates that may have raced in quickly).

m := new(letsencrypt.Manager)
setup(m)
go backgroundUpdates(m)
for range m.Watch() {
	save(m.Marshal())
}