caddytls

package
v0.10.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 19, 2017 License: Apache-2.0 Imports: 34 Imported by: 0

Documentation

Overview

Package caddytls facilitates the management of TLS assets and integrates Let's Encrypt functionality into Caddy with first-class support for creating and renewing certificates automatically. It also implements the tls directive.

This package is meant to be used by Caddy server types. To use the tls directive, a server type must import this package and call RegisterConfigGetter(). The server type must make and keep track of the caddytls.Config structs that this package produces. It must also add tls to its list of directives. When it comes time to make the server instances, the server type can call MakeTLSConfig() to convert a []caddytls.Config to a single tls.Config for use in tls.NewListener(). It is also recommended to call RotateSessionTicketKeys() when starting a new listener.

Index

Constants

View Source 
const (
	// HTTPChallengePort is the officially designated port for
	// the HTTP challenge according to the ACME spec.
	HTTPChallengePort = "80"

	// TLSSNIChallengePort is the officially designated port for
	// the TLS-SNI challenge according to the ACME spec.
	TLSSNIChallengePort = "443"

	// DefaultHTTPAlternatePort is the port on which the ACME
	// client will open a listener and solve the HTTP challenge.
	// If this alternate port is used instead of the default
	// port, then whatever is listening on the default port must
	// be capable of proxying or forwarding the request to this
	// alternate port.
	DefaultHTTPAlternatePort = "5033"
)
View Source 
const (
	// NumTickets is how many tickets to hold and consider
	// to decrypt TLS sessions.
	NumTickets = 4

	// TicketRotateInterval is how often to generate
	// new ticket for TLS PFS encryption
	TicketRotateInterval = 10 * time.Hour
)
View Source 
const (
	// RenewInterval is how often to check certificates for renewal.
	RenewInterval = 12 * time.Hour

	// RenewDurationBefore is how long before expiration to renew certificates.
	RenewDurationBefore = (24 * time.Hour) * 30

	// RenewDurationBeforeAtStartup is how long before expiration to require
	// a renewed certificate when the process is first starting up (see #1680).
	// A wider window between RenewDurationBefore and this value will allow
	// Caddy to start under duress but hopefully this duration will give it
	// enough time for the blockage to be relieved.
	RenewDurationBeforeAtStartup = (24 * time.Hour) * 7

	// OCSPInterval is how often to check if OCSP stapling needs updating.
	OCSPInterval = 1 * time.Hour
)

Variables

View Source 
var (
	// DefaultEmail represents the Let's Encrypt account email to use if none provided.
	DefaultEmail string

	// Agreed indicates whether user has agreed to the Let's Encrypt SA.
	Agreed bool

	// DefaultCAUrl is the default URL to the CA's ACME directory endpoint.
	// It's very important to set this unless you set it in every Config.
	DefaultCAUrl string

	// DefaultKeyType is used as the type of key for new certificates
	// when no other key type is specified.
	DefaultKeyType = acme.RSA2048

	// DisableHTTPChallenge will disable all HTTP challenges.
	DisableHTTPChallenge bool

	// DisableTLSSNIChallenge will disable all TLS-SNI challenges.
	DisableTLSSNIChallenge bool
)

Functions

func DeleteOldStapleFiles added in v0.9.1 

func DeleteOldStapleFiles()

DeleteOldStapleFiles deletes cached OCSP staples that have expired. TODO: Should we do this for certificates too?

func HTTPChallengeHandler 

func HTTPChallengeHandler(w http.ResponseWriter, r *http.Request, listenHost, altPort string) bool

HTTPChallengeHandler proxies challenge requests to ACME client if the request path starts with challengeBasePath. It returns true if it handled the request and no more needs to be done; it returns false if this call was a no-op and the request still needs handling.

func HostQualifies 

func HostQualifies(hostname string) bool

HostQualifies returns true if the hostname alone appears eligible for automatic HTTPS. For example, localhost, empty hostname, and IP addresses are not eligible because we cannot obtain certificates for those names.

func MakeTLSConfig 

func MakeTLSConfig(configs []*Config) (*tls.Config, error)

MakeTLSConfig makes a tls.Config from configs. The returned tls.Config is programmed to load the matching caddytls.Config based on the hostname in SNI, but that's all.

func QualifiesForManagedTLS 

func QualifiesForManagedTLS(c ConfigHolder) bool

QualifiesForManagedTLS returns true if c qualifies for for managed TLS (but not on-demand TLS specifically). It does NOT check to see if a cert and key already exist for the config. If the return value is true, you should be OK to set c.TLSConfig().Managed to true; then you should check that value in the future instead, because the process of setting up the config may make it look like it doesn't qualify even though it originally did.

func RegisterConfigGetter 

func RegisterConfigGetter(serverType string, fn ConfigGetter)

RegisterConfigGetter registers fn as the way to get a Config for server type serverType.

func RegisterDNSProvider 

func RegisterDNSProvider(name string, provider DNSProviderConstructor)

RegisterDNSProvider registers provider by name for solving the ACME DNS challenge.

func RegisterStorageProvider added in v0.9.2 

func RegisterStorageProvider(name string, provider StorageConstructor)

RegisterStorageProvider registers provider by name for storing tls data

func RenewManagedCertificates 

func RenewManagedCertificates(allowPrompts bool) (err error)

RenewManagedCertificates renews managed certificates.

func Revoke 

func Revoke(host string) error

Revoke revokes the certificate for host via ACME protocol. It assumes the certificate was obtained from the CA at DefaultCAUrl.

func RotateSessionTicketKeys 

func RotateSessionTicketKeys(cfg *tls.Config) chan struct{}

RotateSessionTicketKeys rotates the TLS session ticket keys on cfg every TicketRotateInterval. It spawns a new goroutine so this function does NOT block. It returns a channel you should close when you are ready to stop the key rotation, like when the server using cfg is no longer running.

func SetDefaultTLSParams 

func SetDefaultTLSParams(config *Config)

SetDefaultTLSParams sets the default TLS cipher suites, protocol versions, and server preferences of a server.Config if they were not previously set (it does not overwrite; only fills in missing values).

func UpdateOCSPStaples 

func UpdateOCSPStaples()

UpdateOCSPStaples updates the OCSP stapling in all eligible, cached certificates.

OCSP maintenance strives to abide the relevant points on Ryan Sleevi's recommendations for good OCSP support: https://gist.github.com/sleevi/5efe9ef98961ecfb4da8

Types

type ACMEClient 

type ACMEClient struct {
	AllowPrompts bool
	// contains filtered or unexported fields
}

ACMEClient is a wrapper over acme.Client with some custom state attached. It is used to obtain, renew, and revoke certificates with ACME.

func (*ACMEClient) Obtain 

func (c *ACMEClient) Obtain(name string) error

Obtain obtains a single certificate for name. It stores the certificate on the disk if successful. This function is safe for concurrent use.

Right now our storage mechanism only supports one name per certificate, so this function (along with Renew and Revoke) only accepts one domain as input. It can be easily modified to support SAN certificates if our storage mechanism is upgraded later.

Callers who have access to a Config value should use the ObtainCert method on that instead of this lower-level method.

func (*ACMEClient) Renew 

func (c *ACMEClient) Renew(name string) error

Renew renews the managed certificate for name. This function is safe for concurrent use.

Callers who have access to a Config value should use the RenewCert method on that instead of this lower-level method.

func (*ACMEClient) Revoke 

func (c *ACMEClient) Revoke(name string) error

Revoke revokes the certificate for name and deltes it from storage.

type Certificate 

type Certificate struct {
	tls.Certificate

	// Names is the list of names this certificate is written for.
	// The first is the CommonName (if any), the rest are SAN.
	Names []string

	// NotAfter is when the certificate expires.
	NotAfter time.Time

	// OCSP contains the certificate's parsed OCSP response.
	OCSP *ocsp.Response

	// Config is the configuration with which the certificate was
	// loaded or obtained and with which it should be maintained.
	Config *Config
}

Certificate is a tls.Certificate with associated metadata tacked on. Even if the metadata can be obtained by parsing the certificate, we can be more efficient by extracting the metadata once so it's just there, ready to use.

type Config 

type Config struct {
	// The hostname or class of hostnames this config is
	// designated for; can contain wildcard characters
	// according to RFC 6125 §6.4.3 - this field MUST
	// be set in order for things to work as expected
	Hostname string

	// Whether TLS is enabled
	Enabled bool

	// Minimum and maximum protocol versions to allow
	ProtocolMinVersion uint16
	ProtocolMaxVersion uint16

	// The list of cipher suites; first should be
	// TLS_FALLBACK_SCSV to prevent degrade attacks
	Ciphers []uint16

	// Whether to prefer server cipher suites
	PreferServerCipherSuites bool

	// The list of preferred curves
	CurvePreferences []tls.CurveID

	// Client authentication policy
	ClientAuth tls.ClientAuthType

	// List of client CA certificates to allow, if
	// client authentication is enabled
	ClientCerts []string

	// Manual means user provides own certs and keys
	Manual bool

	// Managed means config qualifies for implicit,
	// automatic, managed TLS; as opposed to the user
	// providing and managing the certificate manually
	Managed bool

	// OnDemand means the class of hostnames this
	// config applies to may obtain and manage
	// certificates at handshake-time (as opposed
	// to pre-loaded at startup); OnDemand certs
	// will be managed the same way as preloaded
	// ones, however, if an OnDemand cert fails to
	// renew, it is removed from the in-memory
	// cache; if this is true, Managed must
	// necessarily be true
	OnDemand bool

	// SelfSigned means that this hostname is
	// served with a self-signed certificate
	// that we generated in memory for convenience
	SelfSigned bool

	// The endpoint of the directory for the ACME
	// CA we are to use
	CAUrl string

	// The host (ONLY the host, not port) to listen
	// on if necessary to start a listener to solve
	// an ACME challenge
	ListenHost string

	// The alternate port (ONLY port, not host)
	// to use for the ACME HTTP challenge; this
	// port will be used if we proxy challenges
	// coming in on port 80 to this alternate port
	AltHTTPPort string

	// The alternate port (ONLY port, not host)
	// to use for the ACME TLS-SNI challenge.
	// The system must forward the standard port
	// for the TLS-SNI challenge to this port.
	AltTLSSNIPort string

	// The string identifier of the DNS provider
	// to use when solving the ACME DNS challenge
	DNSProvider string

	// The email address to use when creating or
	// using an ACME account (fun fact: if this
	// is set to "off" then this config will not
	// qualify for managed TLS)
	ACMEEmail string

	// The type of key to use when generating
	// certificates
	KeyType acme.KeyType

	// The storage creator; use StorageFor() to get a guaranteed
	// non-nil Storage instance. Note, Caddy may call this frequently
	// so implementors are encouraged to cache any heavy instantiations.
	StorageProvider string

	// The state needed to operate on-demand TLS
	OnDemandState OnDemandState

	// Add the must staple TLS extension to the CSR generated by lego/acme
	MustStaple bool

	// The list of protocols to choose from for Application Layer
	// Protocol Negotiation (ALPN).
	ALPN []string
	// contains filtered or unexported fields
}

Config describes how TLS should be configured and used.

func (*Config) CacheManagedCertificate added in v0.10.0 

func (cfg *Config) CacheManagedCertificate(domain string) (Certificate, error)

CacheManagedCertificate loads the certificate for domain into the cache, flagging it as Managed and, if onDemand is true, as "OnDemand" (meaning that it was obtained or loaded during a TLS handshake).

This method is safe for concurrent use.

func (*Config) GetCertificate added in v0.10.0 

func (cfg *Config) GetCertificate(clientHello *tls.ClientHelloInfo) (*tls.Certificate, error)

GetCertificate gets a certificate to satisfy clientHello. In getting the certificate, it abides the rules and settings defined in the Config that matches clientHello.ServerName. It first checks the in- memory cache, then, if the config enables "OnDemand", it accesses disk, then accesses the network if it must obtain a new certificate via ACME.

This method is safe for use as a tls.Config.GetCertificate callback.

func (*Config) ObtainCert 

func (c *Config) ObtainCert(name string, allowPrompts bool) error

ObtainCert obtains a certificate for name using c, as long as a certificate does not already exist in storage for that name. The name must qualify and c must be flagged as Managed. This function is a no-op if storage already has a certificate for name.

It only obtains and stores certificates (and their keys), it does not load them into memory. If allowPrompts is true, the user may be shown a prompt.

func (*Config) RenewCert 

func (c *Config) RenewCert(name string, allowPrompts bool) error

RenewCert renews the certificate for name using c. It stows the renewed certificate and its assets in storage if successful.

func (*Config) StorageFor 

func (c *Config) StorageFor(caURL string) (Storage, error)

StorageFor obtains a TLS Storage instance for the given CA URL which should be unique for every different ACME CA. If a StorageCreator is set on this Config, it will be used. Otherwise the default file storage implementation is used. When the error is nil, this is guaranteed to return a non-nil Storage instance.

type ConfigGetter 

type ConfigGetter func(c *caddy.Controller) *Config

ConfigGetter gets a Config keyed by key.

type ConfigHolder 

type ConfigHolder interface {
	TLSConfig() *Config
	Host() string
	Port() string
}

ConfigHolder is any type that has a Config; it presumably is connected to a hostname and port on which it is serving.

type DNSProviderConstructor 

type DNSProviderConstructor func(credentials ...string) (acme.ChallengeProvider, error)

DNSProviderConstructor is a function that takes credentials and returns a type that can solve the ACME DNS challenges.

type ErrNotExist added in v0.9.2 

type ErrNotExist interface {
	error
}

ErrNotExist is returned by Storage implementations when a resource is not found. It is similar to os.ErrNotExist except this is a type, not a variable.

type FileStorage 

type FileStorage struct {
	Path string
	// contains filtered or unexported fields
}

FileStorage facilitates forming file paths derived from a root directory. It is used to get file paths in a consistent, cross-platform way or persisting ACME assets on the file system.

func (*FileStorage) DeleteSite 

func (s *FileStorage) DeleteSite(domain string) error

DeleteSite implements Storage.DeleteSite by deleting just the cert from disk. If it is not present, an instance of ErrNotExist is returned.

func (*FileStorage) LoadSite 

func (s *FileStorage) LoadSite(domain string) (*SiteData, error)

LoadSite implements Storage.LoadSite by loading it from disk. If it is not present, an instance of ErrNotExist is returned.

func (*FileStorage) LoadUser 

func (s *FileStorage) LoadUser(email string) (*UserData, error)

LoadUser implements Storage.LoadUser by loading it from disk. If it is not present, an instance of ErrNotExist is returned.

func (*FileStorage) MostRecentUserEmail 

func (s *FileStorage) MostRecentUserEmail() string

MostRecentUserEmail implements Storage.MostRecentUserEmail by finding the most recently written sub directory in the users' directory. It is named after the email address. This corresponds to the most recent call to StoreUser.

func (*FileStorage) SiteExists 

func (s *FileStorage) SiteExists(domain string) (bool, error)

SiteExists implements Storage.SiteExists by checking for the presence of cert and key files.

func (*FileStorage) StoreSite 

func (s *FileStorage) StoreSite(domain string, data *SiteData) error

StoreSite implements Storage.StoreSite by writing it to disk. The base directories needed for the file are automatically created as needed.

func (*FileStorage) StoreUser 

func (s *FileStorage) StoreUser(email string, data *UserData) error

StoreUser implements Storage.StoreUser by writing it to disk. The base directories needed for the file are automatically created as needed.

func (*FileStorage) TryLock added in v0.9.2 

func (s *FileStorage) TryLock(name string) (Waiter, error)

TryLock attempts to get a lock for name, otherwise it returns a Waiter value to wait until the other process is finished.

func (*FileStorage) Unlock added in v0.9.2 

func (s *FileStorage) Unlock(name string) error

Unlock unlocks name.

type OnDemandState added in v0.9.1 

type OnDemandState struct {
	// The number of certificates that have been issued on-demand
	// by this config. It is only safe to modify this count atomically.
	// If it reaches MaxObtain, on-demand issuances must fail.
	ObtainedCount int32

	// Set from max_certs in tls config, it specifies the
	// maximum number of certificates that can be issued.
	MaxObtain int32
}

OnDemandState contains some state relevant for providing on-demand TLS.

type SiteData 

type SiteData struct {
	// Cert is the public cert byte array.
	Cert []byte
	// Key is the private key byte array.
	Key []byte
	// Meta is metadata about the site used by Caddy.
	Meta []byte
}

SiteData contains persisted items pertaining to an individual site.

type Storage 

type Storage interface {
	// SiteExists returns true if this site exists in storage.
	// Site data is considered present when StoreSite has been called
	// successfully (without DeleteSite having been called, of course).
	SiteExists(domain string) (bool, error)

	// TryLock is called before Caddy attempts to obtain or renew a
	// certificate for a certain name and store it. From the perspective
	// of this method and its companion Unlock, the actions of
	// obtaining/renewing and then storing the certificate are atomic,
	// and both should occur within a lock. This prevents multiple
	// processes -- maybe distributed ones -- from stepping on each
	// other's space in the same shared storage, and from spamming
	// certificate providers with multiple, redundant requests.
	//
	// If a lock could be obtained, (nil, nil) is returned and you may
	// continue normally. If not (meaning another process is already
	// working on that name), a Waiter value will be returned upon
	// which you can Wait() until it is finished, and then return
	// when it unblocks. If waiting, do not unlock!
	//
	// To prevent deadlocks, all implementations (where this concern
	// is relevant) should put a reasonable expiration on the lock in
	// case Unlock is unable to be called due to some sort of storage
	// system failure or crash.
	TryLock(name string) (Waiter, error)

	// Unlock unlocks the mutex for name. Only callers of TryLock who
	// successfully obtained the lock (no Waiter value was returned)
	// should call this method, and it should be called only after
	// the obtain/renew and store are finished, even if there was
	// an error (or a timeout).
	Unlock(name string) error

	// LoadSite obtains the site data from storage for the given domain and
	// returns it. If data for the domain does not exist, an error value
	// of type ErrNotExist is returned. For multi-server storage, care
	// should be taken to make this load atomic to prevent race conditions
	// that happen with multiple data loads.
	LoadSite(domain string) (*SiteData, error)

	// StoreSite persists the given site data for the given domain in
	// storage. For multi-server storage, care should be taken to make this
	// call atomic to prevent half-written data on failure of an internal
	// intermediate storage step. Implementers can trust that at runtime
	// this function will only be invoked after LockRegister and before
	// UnlockRegister of the same domain.
	StoreSite(domain string, data *SiteData) error

	// DeleteSite deletes the site for the given domain from storage.
	// Multi-server implementations should attempt to make this atomic. If
	// the site does not exist, an error value of type ErrNotExist is returned.
	DeleteSite(domain string) error

	// LoadUser obtains user data from storage for the given email and
	// returns it. If data for the email does not exist, an error value
	// of type ErrNotExist is returned. Multi-server implementations
	// should take care to make this operation atomic for all loaded
	// data items.
	LoadUser(email string) (*UserData, error)

	// StoreUser persists the given user data for the given email in
	// storage. Multi-server implementations should take care to make this
	// operation atomic for all stored data items.
	StoreUser(email string, data *UserData) error

	// MostRecentUserEmail provides the most recently used email parameter
	// in StoreUser. The result is an empty string if there are no
	// persisted users in storage.
	MostRecentUserEmail() string
}

Storage is an interface abstracting all storage used by Caddy's TLS subsystem. Implementations of this interface store both site and user data.

func NewFileStorage added in v0.9.2 

func NewFileStorage(caURL *url.URL) (Storage, error)

NewFileStorage is a StorageConstructor function that creates a new Storage instance backed by the local disk. The resulting Storage instance is guaranteed to be non-nil if there is no error.

type StorageConstructor added in v0.9.2 

type StorageConstructor func(caURL *url.URL) (Storage, error)

StorageConstructor is a function type that is used in the Config to instantiate a new Storage instance. This function can return a nil Storage even without an error.

type User 

type User struct {
	Email        string
	Registration *acme.RegistrationResource
	// contains filtered or unexported fields
}

User represents a Let's Encrypt user account.

func (User) GetEmail 

func (u User) GetEmail() string

GetEmail gets u's email.

func (User) GetPrivateKey 

func (u User) GetPrivateKey() crypto.PrivateKey

GetPrivateKey gets u's private key.

func (User) GetRegistration 

func (u User) GetRegistration() *acme.RegistrationResource

GetRegistration gets u's registration resource.

type UserData 

type UserData struct {
	// Reg is the user registration byte array.
	Reg []byte
	// Key is the user key byte array.
	Key []byte
}

UserData contains persisted items pertaining to a user.

type Waiter added in v0.9.2 

type Waiter interface {
	Wait()
}

Waiter is a type that can block until a storage lock is released.

Source Files

View all Source files

Directories

Path Synopsis
Package storagetest provides utilities to assist in testing caddytls.Storage implementations.
 Package storagetest provides utilities to assist in testing caddytls.Storage implementations.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.