autotls

Documentation

Overview

Package autotls automatically configures TLS (for SMTP, IMAP, HTTP) by requesting certificates with ACME, typically from Let's Encrypt.

Index

• type Manager
  • func Load(name, acmeDir, contactEmail, directoryURL string, eabKeyID string, ...) (*Manager, error)
  • func (m *Manager) CertAvailable(ctx context.Context, log mlog.Log, host dns.Domain) (bool, error)
  • func (m *Manager) HostPolicy(ctx context.Context, host string) (rerr error)
  • func (m *Manager) Hostnames() []dns.Domain
  • func (m *Manager) SetAllowedHostnames(log mlog.Log, resolver dns.Resolver, hostnames map[dns.Domain]struct{}, ...)
  • func (m *Manager) TLSConfig(fallbackHostname dns.Domain, fallbackNoSNI, fallbackUnknownSNI bool) *tls.Config

Types

type Manager

type Manager struct {
	ACMETLSConfig *tls.Config // For serving HTTPS on port 443, which is required for certificate requests to succeed.
	Manager       *autocert.Manager

	sync.Mutex
	// contains filtered or unexported fields
}

Manager is in charge of a single ACME identity, and automatically requests certificates for allowlisted hosts.

func Load

func Load(name, acmeDir, contactEmail, directoryURL string, eabKeyID string, eabKey []byte, getPrivateKey func(host string, keyType autocert.KeyType) (crypto.Signer, error), shutdown <-chan struct{}) (*Manager, error)

Load returns an initialized autotls manager for "name" (used for the ACME key file and requested certs and their keys). All files are stored within acmeDir.

contactEmail must be a valid email address to which notifications about ACME can be sent. directoryURL is the ACME starting point.

eabKeyID and eabKey are for external account binding when making a new account, which some ACME providers require.

getPrivateKey is called to get the private key for the host and key type. It can be used to deliver a specific (e.g. always the same) private key for a host, or a newly generated key.

When shutdown is closed, no new TLS connections can be created.

func (*Manager) CertAvailable

func (m *Manager) CertAvailable(ctx context.Context, log mlog.Log, host dns.Domain) (bool, error)

CertAvailable checks whether a non-expired ECDSA certificate is available in the cache for host. No other checks than expiration are done.

func (*Manager) HostPolicy

func (m *Manager) HostPolicy(ctx context.Context, host string) (rerr error)

HostPolicy decides if a host is allowed for use with ACME, i.e. whether a certificate will be returned if present and/or will be requested if not yet present. Only hosts added with SetAllowedHostnames are allowed. During shutdown, no new connections are allowed.

func (*Manager) Hostnames

func (m *Manager) Hostnames() []dns.Domain

Hostnames returns the allowed host names for use with ACME.

func (*Manager) SetAllowedHostnames

func (m *Manager) SetAllowedHostnames(log mlog.Log, resolver dns.Resolver, hostnames map[dns.Domain]struct{}, publicIPs []string, checkHosts bool)

SetAllowedHostnames sets a new list of allowed hostnames for automatic TLS. After setting the host names, a goroutine is start to check that new host names are fully served by publicIPs (only if non-empty and there is no unspecified address in the list). If no, log an error with a warning that ACME validation may fail.

func (*Manager) TLSConfig

func (m *Manager) TLSConfig(fallbackHostname dns.Domain, fallbackNoSNI, fallbackUnknownSNI bool) *tls.Config

TLSConfig returns a TLS server config that optionally returns a certificate for fallbackHostname if no SNI was done, or for an unknown hostname.

If fallbackNoSNI is set, TLS connections without SNI will use a certificate for fallbackHostname. Otherwise, connections without SNI will fail with a message that no TLS certificate is available.

If fallbackUnknownSNI is set, TLS connections with an SNI hostname that is not allowlisted will instead use a certificate for fallbackHostname. Otherwise, such TLS connections will fail.