caddy: github.com/mholt/caddy/caddytls Index | Files

package caddytls

import "github.com/mholt/caddy/caddytls"

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

Package Files

config.go crypto.go handshake.go selfsigned.go setup.go tls.go

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

func GetSupportedCipherName Uses

func GetSupportedCipherName(cipher uint16) (string, error)

GetSupportedCipherName returns the cipher name

func GetSupportedProtocolName Uses

func GetSupportedProtocolName(protocol uint16) (string, error)

GetSupportedProtocolName returns the protocol name

func MakeTLSConfig Uses

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 Uses

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 Uses

func RegisterClusterPlugin(name string, provider ClusterPluginConstructor)

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

func RegisterConfigGetter Uses

func RegisterConfigGetter(serverType string, fn ConfigGetter)

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

func RegisterDNSProvider Uses

func RegisterDNSProvider(name string, provider DNSProviderConstructor)

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

func Revoke Uses

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 Uses

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 Uses

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

type ChallengeProvider Uses

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 Uses

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 Uses

func (info ClientHelloInfo) Key() string

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

type ClusterPluginConstructor Uses

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 Uses

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

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

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 Uses

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

ConfigGetter gets a Config keyed by key.

type ConfigHolder Uses

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 Uses

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.

Package caddytls imports 30 packages (graph) and is imported by 399 packages. Updated 2019-11-20. Refresh now. Tools for package owners.