caddytls

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. It's mostly powered by the CertMagic package.

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
• Variables
• func GetSupportedCipherName(cipher uint16) (string, error)
• func GetSupportedProtocolName(protocol uint16) (string, error)
• func MakeTLSConfig(configs []*Config) (*tls.Config, error)
• func QualifiesForManagedTLS(c ConfigHolder) bool
• func RegisterClusterPlugin(name string, provider ClusterPluginConstructor)
• func RegisterConfigGetter(serverType string, fn ConfigGetter)
• func RegisterDNSProvider(name string, provider DNSProviderConstructor)
• func Revoke(domainName string) error
• func RotateSessionTicketKeys(cfg *tls.Config) chan struct{}
• func SetDefaultTLSParams(config *Config)
• type ChallengeProvider
• type ClientHelloInfo
  • func (info ClientHelloInfo) Key() string
• type ClusterPluginConstructor
• type Config
  • func NewConfig(inst *caddy.Instance) (*Config, error)
• type ConfigGetter
• type ConfigHolder
• type DNSProviderConstructor

Constants

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
)

const CertCacheInstStorageKey = "tls_cert_cache"

CertCacheInstStorageKey is the name of the key for accessing the certificate storage on the *caddy.Instance.

Variables

var ClientHelloTelemetry = true

ClientHelloTelemetry determines whether to report TLS ClientHellos to telemetry. Disable if doing it from a different package.

var KnownACMECAs = []string{
	"https://acme-v02.api.letsencrypt.org/directory",
}

KnownACMECAs is a list of ACME directory endpoints of known, public, and trusted ACME-compatible certificate authorities.

var SupportedCiphersMap = map[string]uint16{
	"ECDHE-ECDSA-AES256-GCM-SHA384":      tls.TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
	"ECDHE-RSA-AES256-GCM-SHA384":        tls.TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,
	"ECDHE-ECDSA-AES128-GCM-SHA256":      tls.TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
	"ECDHE-RSA-AES128-GCM-SHA256":        tls.TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,
	"ECDHE-ECDSA-WITH-CHACHA20-POLY1305": tls.TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,
	"ECDHE-RSA-WITH-CHACHA20-POLY1305":   tls.TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,
	"ECDHE-RSA-AES256-CBC-SHA":           tls.TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,
	"ECDHE-RSA-AES128-CBC-SHA":           tls.TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,
	"ECDHE-ECDSA-AES256-CBC-SHA":         tls.TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA,
	"ECDHE-ECDSA-AES128-CBC-SHA":         tls.TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA,
	"RSA-AES256-CBC-SHA":                 tls.TLS_RSA_WITH_AES_256_CBC_SHA,
	"RSA-AES128-CBC-SHA":                 tls.TLS_RSA_WITH_AES_128_CBC_SHA,
	"ECDHE-RSA-3DES-EDE-CBC-SHA":         tls.TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA,
	"RSA-3DES-EDE-CBC-SHA":               tls.TLS_RSA_WITH_3DES_EDE_CBC_SHA,
}

SupportedCiphersMap has supported ciphers, used only for parsing config.

Note that, at time of writing, HTTP/2 blacklists 276 cipher suites, including all but four of the suites below (the four GCM suites). See https://http2.github.io/http2-spec/#BadCipherSuites

TLS_FALLBACK_SCSV is not in this list because we manually ensure it is always added (even though it is not technically a cipher suite).

This map, like any map, is NOT ORDERED. Do not range over this map.

var SupportedProtocols = map[string]uint16{
	"tls1.0": tls.VersionTLS10,
	"tls1.1": tls.VersionTLS11,
	"tls1.2": tls.VersionTLS12,
	"tls1.3": tls.VersionTLS13,
}

SupportedProtocols is a map of supported protocols. HTTP/2 only supports TLS 1.2 and higher. If updating this map, also update tlsProtocolStringToMap in caddyhttp/fastcgi/fastcgi.go

Functions

func GetSupportedCipherName

func GetSupportedCipherName(cipher uint16) (string, error)

GetSupportedCipherName returns the cipher name

func GetSupportedProtocolName

func GetSupportedProtocolName(protocol uint16) (string, error)

GetSupportedProtocolName returns the protocol name

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. This is used to create a single TLS configuration for a listener (a group of sites).

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 RegisterClusterPlugin

func RegisterClusterPlugin(name string, provider ClusterPluginConstructor)

RegisterClusterPlugin registers provider by name for facilitating cluster-wide operations like storage and synchronization.

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 Revoke

func Revoke(domainName string) error

Revoke revokes the certificate fro host via the ACME protocol. It assumes the certificate was obtained from certmagic.CA.

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.

TODO: See about moving this into CertMagic and using its Storage

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).

Types

type ChallengeProvider

type ChallengeProvider challenge.Provider

ChallengeProvider defines an own type that should be used in Caddy plugins over challenge.Provider. Using challenge.Provider causes version mismatches with vendored dependencies (see https://github.com/mattfarina/golang-broken-vendor)

challenge.Provider is an interface that allows the implementation of custom challenge providers. For more details, see: https://godoc.org/github.com/go-acme/lego/acme#ChallengeProvider

type ClientHelloInfo

type ClientHelloInfo struct {
	Version            uint16        `json:"version,omitempty"`
	CipherSuites       []uint16      `json:"cipher_suites,omitempty"`
	Extensions         []uint16      `json:"extensions,omitempty"`
	CompressionMethods []byte        `json:"compression,omitempty"`
	Curves             []tls.CurveID `json:"curves,omitempty"`
	Points             []uint8       `json:"points,omitempty"`

	// Whether a couple of fields are unknown; if not, the key will encode
	// differently to reflect that, as opposed to being known empty values.
	// (some fields may be unknown depending on what package is being used;
	// i.e. the Go standard lib doesn't expose some things)
	// (very important to NOT encode these to JSON)
	ExtensionsUnknown         bool `json:"-"`
	CompressionMethodsUnknown bool `json:"-"`
}

ClientHelloInfo is our own version of the standard lib's tls.ClientHelloInfo. As of May 2018, any fields populated by the Go standard library are not guaranteed to have their values in the original order as on the wire.

func (ClientHelloInfo) Key

func (info ClientHelloInfo) Key() string

Key returns a standardized string form of the data in info, useful for identifying duplicates.

type ClusterPluginConstructor

type ClusterPluginConstructor func() (certmagic.Storage, error)

ClusterPluginConstructor is a function type that is used to instantiate a new implementation of both certmagic.Storage and certmagic.Locker, which are required for successful use in cluster environments.

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,
	// must be normalized, and if an IP address, must
	// be normalized
	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

	// Allow mismatched TLS SNI and Host header when using TLS client authentication
	// If false (the default), the Host header in the HTTP request must
	// match the SNI value in the TLS handshake (if any).
	// This should be enabled whenever the TLS SNI and Host header
	// in the HTTP request can be different, for example when doing mTLS with multiple servers
	// and the upstream addresses do not match the HTTP request Host header.
	// If a site relies on TLS client authentication or any time you want to enforce that THIS site's TLS config
	// is used and not the TLS config of any other site
	// on the same listener, set this to false.
	// TODO: Check how relevant this is with TLS 1.3.
	InsecureDisableSNIMatching bool

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

	// Managed means this config should be managed
	// by the CertMagic Config (Manager field)
	Managed bool

	// Manager is how certificates are managed
	Manager *certmagic.Config

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

	// 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 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 NewConfig

func NewConfig(inst *caddy.Instance) (*Config, error)

NewConfig returns a new Config with a pointer to the instance's certificate cache. You will usually need to set other fields on the returned Config for successful practical use.

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) (ChallengeProvider, error)

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