caddytls

package
v2.7.6 Latest Latest
Warning

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

 Go to latest Published: Dec 7, 2023 License: Apache-2.0 Imports: 36 Imported by: 52

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var SupportedCurves = map[string]tls.CurveID{
	"x25519":    tls.X25519,
	"secp256r1": tls.CurveP256,
	"secp384r1": tls.CurveP384,
	"secp521r1": tls.CurveP521,
}

SupportedCurves is the unordered map of supported curves. https://golang.org/pkg/crypto/tls/#CurveID

View Source 
var SupportedProtocols = map[string]uint16{
	"tls1.2": tls.VersionTLS12,
	"tls1.3": tls.VersionTLS13,
}

SupportedProtocols is a map of supported protocols.

Functions

func AllMatchingCertificates added in v2.7.0 

func AllMatchingCertificates(san string) []certmagic.Certificate

AllMatchingCertificates returns the list of all certificates in the cache which could be used to satisfy the given SAN.

func CipherSuiteID 

func CipherSuiteID(name string) uint16

CipherSuiteID returns the ID of the cipher suite associated with the given name, or 0 if the name is not recognized/supported.

func CipherSuiteNameSupported 

func CipherSuiteNameSupported(name string) bool

CipherSuiteNameSupported returns true if name is a supported cipher suite.

func DefaultIssuers added in v2.3.0 

func DefaultIssuers() []certmagic.Issuer

DefaultIssuers returns empty Issuers (not provisioned) to be used as defaults. This function is experimental and has no compatibility promises.

func DefaultIssuersProvisioned added in v2.4.0 

func DefaultIssuersProvisioned(ctx caddy.Context) ([]certmagic.Issuer, error)

DefaultIssuersProvisioned returns empty but provisioned default Issuers from DefaultIssuers(). This function is experimental and has no compatibility promises.

func ProtocolName 

func ProtocolName(id uint16) string

ProtocolName returns the standard name for the passed protocol version ID (e.g. "TLS1.3") or a fallback representation of the ID value if the version is not supported.

func SupportedCipherSuites 

func SupportedCipherSuites() []*tls.CipherSuite

SupportedCipherSuites returns a list of all the cipher suites Caddy supports. The list is NOT ordered by security preference.

Types

type ACMEIssuer 

type ACMEIssuer struct {
	// The URL to the CA's ACME directory endpoint. Default:
	// https://acme-v02.api.letsencrypt.org/directory
	CA string `json:"ca,omitempty"`

	// The URL to the test CA's ACME directory endpoint.
	// This endpoint is only used during retries if there
	// is a failure using the primary CA. Default:
	// https://acme-staging-v02.api.letsencrypt.org/directory
	TestCA string `json:"test_ca,omitempty"`

	// Your email address, so the CA can contact you if necessary.
	// Not required, but strongly recommended to provide one so
	// you can be reached if there is a problem. Your email is
	// not sent to any Caddy mothership or used for any purpose
	// other than ACME transactions.
	Email string `json:"email,omitempty"`

	// If you have an existing account with the ACME server, put
	// the private key here in PEM format. The ACME client will
	// look up your account information with this key first before
	// trying to create a new one. You can use placeholders here,
	// for example if you have it in an environment variable.
	AccountKey string `json:"account_key,omitempty"`

	// If using an ACME CA that requires an external account
	// binding, specify the CA-provided credentials here.
	ExternalAccount *acme.EAB `json:"external_account,omitempty"`

	// Time to wait before timing out an ACME operation.
	// Default: 0 (no timeout)
	ACMETimeout caddy.Duration `json:"acme_timeout,omitempty"`

	// Configures the various ACME challenge types.
	Challenges *ChallengesConfig `json:"challenges,omitempty"`

	// An array of files of CA certificates to accept when connecting to the
	// ACME CA. Generally, you should only use this if the ACME CA endpoint
	// is internal or for development/testing purposes.
	TrustedRootsPEMFiles []string `json:"trusted_roots_pem_files,omitempty"`

	// Preferences for selecting alternate certificate chains, if offered
	// by the CA. By default, the first offered chain will be selected.
	// If configured, the chains may be sorted and the first matching chain
	// will be selected.
	PreferredChains *ChainPreference `json:"preferred_chains,omitempty"`
	// contains filtered or unexported fields
}

ACMEIssuer manages certificates using the ACME protocol (RFC 8555).

func (ACMEIssuer) CaddyModule 

func (ACMEIssuer) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (*ACMEIssuer) GetACMEIssuer added in v2.2.0 

func (iss *ACMEIssuer) GetACMEIssuer() *ACMEIssuer

GetACMEIssuer returns iss. This is useful when other types embed ACMEIssuer, because type-asserting them to *ACMEIssuer will fail, but type-asserting them to an interface with only this method will succeed, and will still allow the embedded ACMEIssuer to be accessed and manipulated.

func (*ACMEIssuer) Issue 

func (iss *ACMEIssuer) Issue(ctx context.Context, csr *x509.CertificateRequest) (*certmagic.IssuedCertificate, error)

Issue obtains a certificate for the given csr.

func (*ACMEIssuer) IssuerKey 

func (iss *ACMEIssuer) IssuerKey() string

IssuerKey returns the unique issuer key for the configured CA endpoint.

func (*ACMEIssuer) PreCheck 

func (iss *ACMEIssuer) PreCheck(ctx context.Context, names []string, interactive bool) error

PreCheck implements the certmagic.PreChecker interface.

func (*ACMEIssuer) Provision 

func (iss *ACMEIssuer) Provision(ctx caddy.Context) error

Provision sets up iss.

func (*ACMEIssuer) Revoke 

func (iss *ACMEIssuer) Revoke(ctx context.Context, cert certmagic.CertificateResource, reason int) error

Revoke revokes the given certificate.

func (*ACMEIssuer) SetConfig 

func (iss *ACMEIssuer) SetConfig(cfg *certmagic.Config)

SetConfig sets the associated certmagic config for this issuer. This is required because ACME needs values from the config in order to solve the challenges during issuance. This implements the ConfigSetter interface.

func (*ACMEIssuer) UnmarshalCaddyfile added in v2.2.0 

func (iss *ACMEIssuer) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

UnmarshalCaddyfile deserializes Caddyfile tokens into iss. 

... acme [<directory_url>] {
    dir <directory_url>
    test_dir <test_directory_url>
    email <email>
    timeout <duration>
    disable_http_challenge
    disable_tlsalpn_challenge
    alt_http_port    <port>
    alt_tlsalpn_port <port>
    eab <key_id> <mac_key>
    trusted_roots <pem_files...>
    dns <provider_name> [<options>]
    propagation_delay <duration>
    propagation_timeout <duration>
    resolvers <dns_servers...>
    dns_ttl <duration>
    dns_challenge_override_domain <domain>
    preferred_chains [smallest] {
        root_common_name <common_names...>
        any_common_name  <common_names...>
    }
}

type AutomateLoader 

type AutomateLoader []string

AutomateLoader will automatically manage certificates for the names in the list, including obtaining and renewing certificates. Automated certificates are managed according to their matching automation policy, configured elsewhere in this app.

Technically, this is a no-op certificate loader module that is treated as a special case: it uses this app's automation features to load certificates for the list of hostnames, rather than loading certificates manually. But the end result is the same: certificates for these subject names will be loaded into the in-memory cache and may then be used.

func (AutomateLoader) CaddyModule 

func (AutomateLoader) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

type AutomationConfig 

type AutomationConfig struct {
	// The list of automation policies. The first policy matching
	// a certificate or subject name will be applied.
	Policies []*AutomationPolicy `json:"policies,omitempty"`

	// On-Demand TLS defers certificate operations to the
	// moment they are needed, e.g. during a TLS handshake.
	// Useful when you don't know all the hostnames at
	// config-time, or when you are not in control of the
	// domain names you are managing certificates for.
	// In 2015, Caddy became the first web server to
	// implement this experimental technology.
	//
	// Note that this field does not enable on-demand TLS;
	// it only configures it for when it is used. To enable
	// it, create an automation policy with `on_demand`.
	OnDemand *OnDemandConfig `json:"on_demand,omitempty"`

	// Caddy staples OCSP (and caches the response) for all
	// qualifying certificates by default. This setting
	// changes how often it scans responses for freshness,
	// and updates them if they are getting stale. Default: 1h
	OCSPCheckInterval caddy.Duration `json:"ocsp_interval,omitempty"`

	// Every so often, Caddy will scan all loaded, managed
	// certificates for expiration. This setting changes how
	// frequently the scan for expiring certificates is
	// performed. Default: 10m
	RenewCheckInterval caddy.Duration `json:"renew_interval,omitempty"`

	// How often to scan storage units for old or expired
	// assets and remove them. These scans exert lots of
	// reads (and list operations) on the storage module, so
	// choose a longer interval for large deployments.
	// Default: 24h
	//
	// Storage will always be cleaned when the process first
	// starts. Then, a new cleaning will be started this
	// duration after the previous cleaning started if the
	// previous cleaning finished in less than half the time
	// of this interval (otherwise next start will be skipped).
	StorageCleanInterval caddy.Duration `json:"storage_clean_interval,omitempty"`
	// contains filtered or unexported fields
}

AutomationConfig governs the automated management of TLS certificates.

type AutomationPolicy 

type AutomationPolicy struct {
	// Which subjects (hostnames or IP addresses) this policy applies to.
	//
	// This list is a filter, not a command. In other words, it is used
	// only to filter whether this policy should apply to a subject that
	// needs a certificate; it does NOT command the TLS app to manage a
	// certificate for that subject. To have Caddy automate a certificate
	// or specific subjects, use the "automate" certificate loader module
	// of the TLS app.
	SubjectsRaw []string `json:"subjects,omitempty"`

	// The modules that may issue certificates. Default: internal if all
	// subjects do not qualify for public certificates; othewise acme and
	// zerossl.
	IssuersRaw []json.RawMessage `json:"issuers,omitempty" caddy:"namespace=tls.issuance inline_key=module"`

	// Modules that can get a custom certificate to use for any
	// given TLS handshake at handshake-time. Custom certificates
	// can be useful if another entity is managing certificates
	// and Caddy need only get it and serve it. Specifying a Manager
	// enables on-demand TLS, i.e. it has the side-effect of setting
	// the on_demand parameter to `true`.
	//
	// TODO: This is an EXPERIMENTAL feature. Subject to change or removal.
	ManagersRaw []json.RawMessage `json:"get_certificate,omitempty" caddy:"namespace=tls.get_certificate inline_key=via"`

	// If true, certificates will be requested with MustStaple. Not all
	// CAs support this, and there are potentially serious consequences
	// of enabling this feature without proper threat modeling.
	MustStaple bool `json:"must_staple,omitempty"`

	// How long before a certificate's expiration to try renewing it,
	// as a function of its total lifetime. As a general and conservative
	// rule, it is a good idea to renew a certificate when it has about
	// 1/3 of its total lifetime remaining. This utilizes the majority
	// of the certificate's lifetime while still saving time to
	// troubleshoot problems. However, for extremely short-lived certs,
	// you may wish to increase the ratio to ~1/2.
	RenewalWindowRatio float64 `json:"renewal_window_ratio,omitempty"`

	// The type of key to generate for certificates.
	// Supported values: `ed25519`, `p256`, `p384`, `rsa2048`, `rsa4096`.
	KeyType string `json:"key_type,omitempty"`

	// Optionally configure a separate storage module associated with this
	// manager, instead of using Caddy's global/default-configured storage.
	StorageRaw json.RawMessage `json:"storage,omitempty" caddy:"namespace=caddy.storage inline_key=module"`

	// If true, certificates will be managed "on demand"; that is, during
	// TLS handshakes or when needed, as opposed to at startup or config
	// load. This enables On-Demand TLS for this policy.
	OnDemand bool `json:"on_demand,omitempty"`

	// Disables OCSP stapling. Disabling OCSP stapling puts clients at
	// greater risk, reduces their privacy, and usually lowers client
	// performance. It is NOT recommended to disable this unless you
	// are able to justify the costs.
	// EXPERIMENTAL. Subject to change.
	DisableOCSPStapling bool `json:"disable_ocsp_stapling,omitempty"`

	// Overrides the URLs of OCSP responders embedded in certificates.
	// Each key is a OCSP server URL to override, and its value is the
	// replacement. An empty value will disable querying of that server.
	// EXPERIMENTAL. Subject to change.
	OCSPOverrides map[string]string `json:"ocsp_overrides,omitempty"`

	// Issuers and Managers store the decoded issuer and manager modules;
	// they are only used to populate an underlying certmagic.Config's
	// fields during provisioning so that the modules can survive a
	// re-provisioning.
	Issuers  []certmagic.Issuer  `json:"-"`
	Managers []certmagic.Manager `json:"-"`
	// contains filtered or unexported fields
}

AutomationPolicy designates the policy for automating the management (obtaining, renewal, and revocation) of managed TLS certificates.

An AutomationPolicy value is not valid until it has been provisioned; use the `AddAutomationPolicy()` method on the TLS app to properly provision a new policy.

func (*AutomationPolicy) Provision 

func (ap *AutomationPolicy) Provision(tlsApp *TLS) error

Provision sets up ap and builds its underlying CertMagic config.

func (*AutomationPolicy) Subjects 

func (ap *AutomationPolicy) Subjects() []string

Subjects returns the list of subjects with all placeholders replaced.

type CertCacheOptions added in v2.1.0 

type CertCacheOptions struct {
	// Maximum number of certificates to allow in the
	// cache. If reached, certificates will be randomly
	// evicted to make room for new ones. Default: 10,000
	Capacity int `json:"capacity,omitempty"`
}

CertCacheOptions configures the certificate cache.

type CertKeyFilePair 

type CertKeyFilePair struct {
	// Path to the certificate (public key) file.
	Certificate string `json:"certificate"`

	// Path to the private key file.
	Key string `json:"key"`

	// The format of the cert and key. Can be "pem". Default: "pem"
	Format string `json:"format,omitempty"`

	// Arbitrary values to associate with this certificate.
	// Can be useful when you want to select a particular
	// certificate when there may be multiple valid candidates.
	Tags []string `json:"tags,omitempty"`
}

CertKeyFilePair pairs certificate and key file names along with their encoding format so that they can be loaded from disk.

type CertKeyPEMPair 

type CertKeyPEMPair struct {
	// The certificate (public key) in PEM format.
	CertificatePEM string `json:"certificate"`

	// The private key in PEM format.
	KeyPEM string `json:"key"`

	// Arbitrary values to associate with this certificate.
	// Can be useful when you want to select a particular
	// certificate when there may be multiple valid candidates.
	Tags []string `json:"tags,omitempty"`
}

CertKeyPEMPair pairs certificate and key PEM blocks.

type Certificate 

type Certificate struct {
	tls.Certificate
	Tags []string
}

Certificate is a TLS certificate, optionally associated with arbitrary tags.

type CertificateLoader 

type CertificateLoader interface {
	LoadCertificates() ([]Certificate, error)
}

CertificateLoader is a type that can load certificates. Certificates can optionally be associated with tags.

type ChainPreference added in v2.3.0 

type ChainPreference struct {
	// Prefer chains with the fewest number of bytes.
	Smallest *bool `json:"smallest,omitempty"`

	// Select first chain having a root with one of
	// these common names.
	RootCommonName []string `json:"root_common_name,omitempty"`

	// Select first chain that has any issuer with one
	// of these common names.
	AnyCommonName []string `json:"any_common_name,omitempty"`
}

ChainPreference describes the client's preferred certificate chain, useful if the CA offers alternate chains. The first matching chain will be selected.

func ParseCaddyfilePreferredChainsOptions added in v2.4.2 

func ParseCaddyfilePreferredChainsOptions(d *caddyfile.Dispenser) (*ChainPreference, error)

type ChallengesConfig 

type ChallengesConfig struct {
	// HTTP configures the ACME HTTP challenge. This
	// challenge is enabled and used automatically
	// and by default.
	HTTP *HTTPChallengeConfig `json:"http,omitempty"`

	// TLSALPN configures the ACME TLS-ALPN challenge.
	// This challenge is enabled and used automatically
	// and by default.
	TLSALPN *TLSALPNChallengeConfig `json:"tls-alpn,omitempty"`

	// Configures the ACME DNS challenge. Because this
	// challenge typically requires credentials for
	// interfacing with a DNS provider, this challenge is
	// not enabled by default. This is the only challenge
	// type which does not require a direct connection
	// to Caddy from an external server.
	//
	// NOTE: DNS providers are currently being upgraded,
	// and this API is subject to change, but should be
	// stabilized soon.
	DNS *DNSChallengeConfig `json:"dns,omitempty"`

	// Optionally customize the host to which a listener
	// is bound if required for solving a challenge.
	BindHost string `json:"bind_host,omitempty"`
}

ChallengesConfig configures the ACME challenges.

type ClientAuthentication 

type ClientAuthentication struct {
	// A list of base64 DER-encoded CA certificates
	// against which to validate client certificates.
	// Client certs which are not signed by any of
	// these CAs will be rejected.
	TrustedCACerts []string `json:"trusted_ca_certs,omitempty"`

	// TrustedCACertPEMFiles is a list of PEM file names
	// from which to load certificates of trusted CAs.
	// Client certificates which are not signed by any of
	// these CA certificates will be rejected.
	TrustedCACertPEMFiles []string `json:"trusted_ca_certs_pem_files,omitempty"`

	// DEPRECATED: This field is deprecated and will be removed in
	// a future version. Please use the `validators` field instead
	// with the tls.client_auth.leaf module instead.
	//
	// A list of base64 DER-encoded client leaf certs
	// to accept. If this list is not empty, client certs
	// which are not in this list will be rejected.
	TrustedLeafCerts []string `json:"trusted_leaf_certs,omitempty"`

	// Client certificate verification modules. These can perform
	// custom client authentication checks, such as ensuring the
	// certificate is not revoked.
	VerifiersRaw []json.RawMessage `json:"verifiers,omitempty" caddy:"namespace=tls.client_auth inline_key=verifier"`

	// The mode for authenticating the client. Allowed values are:
	//
	// Mode | Description
	// -----|---------------
	// `request` | Ask clients for a certificate, but allow even if there isn't one; do not verify it
	// `require` | Require clients to present a certificate, but do not verify it
	// `verify_if_given` | Ask clients for a certificate; allow even if there isn't one, but verify it if there is
	// `require_and_verify` | Require clients to present a valid certificate that is verified
	//
	// The default mode is `require_and_verify` if any
	// TrustedCACerts or TrustedCACertPEMFiles or TrustedLeafCerts
	// are provided; otherwise, the default mode is `require`.
	Mode string `json:"mode,omitempty"`
	// contains filtered or unexported fields
}

ClientAuthentication configures TLS client auth.

func (ClientAuthentication) Active 

func (clientauth ClientAuthentication) Active() bool

Active returns true if clientauth has an actionable configuration.

func (*ClientAuthentication) ConfigureTLSConfig 

func (clientauth *ClientAuthentication) ConfigureTLSConfig(cfg *tls.Config) error

ConfigureTLSConfig sets up cfg to enforce clientauth's configuration.

type ClientCertificateVerifier added in v2.5.2 

type ClientCertificateVerifier interface {
	VerifyClientCertificate(rawCerts [][]byte, verifiedChains [][]*x509.Certificate) error
}

ClientCertificateVerifier is a type which verifies client certificates. It is called during verifyPeerCertificate in the TLS handshake.

type ConfigSetter 

type ConfigSetter interface {
	SetConfig(cfg *certmagic.Config)
}

ConfigSetter is implemented by certmagic.Issuers that need access to a parent certmagic.Config as part of their provisioning phase. For example, the ACMEIssuer requires a config so it can access storage and the cache to solve ACME challenges.

type ConnectionMatcher 

type ConnectionMatcher interface {
	Match(*tls.ClientHelloInfo) bool
}

ConnectionMatcher is a type which matches TLS handshakes.

type ConnectionPolicies 

type ConnectionPolicies []*ConnectionPolicy

ConnectionPolicies govern the establishment of TLS connections. It is an ordered group of connection policies; the first matching policy will be used to configure TLS connections at handshake-time.

func (ConnectionPolicies) Provision 

func (cp ConnectionPolicies) Provision(ctx caddy.Context) error

Provision sets up each connection policy. It should be called during the Validate() phase, after the TLS app (if any) is already set up.

func (ConnectionPolicies) TLSConfig 

func (cp ConnectionPolicies) TLSConfig(_ caddy.Context) *tls.Config

TLSConfig returns a standard-lib-compatible TLS configuration which selects the first matching policy based on the ClientHello.

type ConnectionPolicy 

type ConnectionPolicy struct {
	// How to match this policy with a TLS ClientHello. If
	// this policy is the first to match, it will be used.
	MatchersRaw caddy.ModuleMap `json:"match,omitempty" caddy:"namespace=tls.handshake_match"`

	// How to choose a certificate if more than one matched
	// the given ServerName (SNI) value.
	CertSelection *CustomCertSelectionPolicy `json:"certificate_selection,omitempty"`

	// The list of cipher suites to support. Caddy's
	// defaults are modern and secure.
	CipherSuites []string `json:"cipher_suites,omitempty"`

	// The list of elliptic curves to support. Caddy's
	// defaults are modern and secure.
	Curves []string `json:"curves,omitempty"`

	// Protocols to use for Application-Layer Protocol
	// Negotiation (ALPN) during the handshake.
	ALPN []string `json:"alpn,omitempty"`

	// Minimum TLS protocol version to allow. Default: `tls1.2`
	ProtocolMin string `json:"protocol_min,omitempty"`

	// Maximum TLS protocol version to allow. Default: `tls1.3`
	ProtocolMax string `json:"protocol_max,omitempty"`

	// Enables and configures TLS client authentication.
	ClientAuthentication *ClientAuthentication `json:"client_authentication,omitempty"`

	// DefaultSNI becomes the ServerName in a ClientHello if there
	// is no policy configured for the empty SNI value.
	DefaultSNI string `json:"default_sni,omitempty"`

	// FallbackSNI becomes the ServerName in a ClientHello if
	// the original ServerName doesn't match any certificates
	// in the cache. The use cases for this are very niche;
	// typically if a client is a CDN and passes through the
	// ServerName of the downstream handshake but can accept
	// a certificate with the origin's hostname instead, then
	// you would set this to your origin's hostname. Note that
	// Caddy must be managing a certificate for this name.
	//
	// This feature is EXPERIMENTAL and subject to change or removal.
	FallbackSNI string `json:"fallback_sni,omitempty"`

	// Also known as "SSLKEYLOGFILE", TLS secrets will be written to
	// this file in NSS key log format which can then be parsed by
	// Wireshark and other tools. This is INSECURE as it allows other
	// programs or tools to decrypt TLS connections. However, this
	// capability can be useful for debugging and troubleshooting.
	// **ENABLING THIS LOG COMPROMISES SECURITY!**
	//
	// This feature is EXPERIMENTAL and subject to change or removal.
	InsecureSecretsLog string `json:"insecure_secrets_log,omitempty"`

	// TLSConfig is the fully-formed, standard lib TLS config
	// used to serve TLS connections. Provision all
	// ConnectionPolicies to populate this. It is exported only
	// so it can be minimally adjusted after provisioning
	// if necessary (like to adjust NextProtos to disable HTTP/2),
	// and may be unexported in the future.
	TLSConfig *tls.Config `json:"-"`
	// contains filtered or unexported fields
}

ConnectionPolicy specifies the logic for handling a TLS handshake. An empty policy is valid; safe and sensible defaults will be used.

func (ConnectionPolicy) SettingsEmpty added in v2.1.0 

func (p ConnectionPolicy) SettingsEmpty() bool

SettingsEmpty returns true if p's settings (fields except the matchers) are all empty/unset.

type CustomCertSelectionPolicy 

type CustomCertSelectionPolicy struct {
	// The certificate must have one of these serial numbers.
	SerialNumber []bigInt `json:"serial_number,omitempty"`

	// The certificate must have one of these organization names.
	SubjectOrganization []string `json:"subject_organization,omitempty"`

	// The certificate must use this public key algorithm.
	PublicKeyAlgorithm PublicKeyAlgorithm `json:"public_key_algorithm,omitempty"`

	// The certificate must have at least one of the tags in the list.
	AnyTag []string `json:"any_tag,omitempty"`

	// The certificate must have all of the tags in the list.
	AllTags []string `json:"all_tags,omitempty"`
}

CustomCertSelectionPolicy represents a policy for selecting the certificate used to complete a handshake when there may be multiple options. All fields specified must match the candidate certificate for it to be chosen. This was needed to solve https://github.com/caddyserver/caddy/issues/2588.

func (CustomCertSelectionPolicy) SelectCertificate 

func (p CustomCertSelectionPolicy) SelectCertificate(hello *tls.ClientHelloInfo, choices []certmagic.Certificate) (certmagic.Certificate, error)

SelectCertificate implements certmagic.CertificateSelector. It only chooses a certificate that at least meets the criteria in p. It then chooses the first non-expired certificate that is compatible with the client. If none are valid, it chooses the first viable candidate anyway.

type DNSChallengeConfig 

type DNSChallengeConfig struct {
	// The DNS provider module to use which will manage
	// the DNS records relevant to the ACME challenge.
	ProviderRaw json.RawMessage `json:"provider,omitempty" caddy:"namespace=dns.providers inline_key=name"`

	// The TTL of the TXT record used for the DNS challenge.
	TTL caddy.Duration `json:"ttl,omitempty"`

	// How long to wait before starting propagation checks.
	// Default: 0 (no wait).
	PropagationDelay caddy.Duration `json:"propagation_delay,omitempty"`

	// Maximum time to wait for temporary DNS record to appear.
	// Set to -1 to disable propagation checks.
	// Default: 2 minutes.
	PropagationTimeout caddy.Duration `json:"propagation_timeout,omitempty"`

	// Custom DNS resolvers to prefer over system/built-in defaults.
	// Often necessary to configure when using split-horizon DNS.
	Resolvers []string `json:"resolvers,omitempty"`

	// Override the domain to use for the DNS challenge. This
	// is to delegate the challenge to a different domain,
	// e.g. one that updates faster or one with a provider API.
	OverrideDomain string `json:"override_domain,omitempty"`
	// contains filtered or unexported fields
}

DNSChallengeConfig configures the ACME DNS challenge.

NOTE: This API is still experimental and is subject to change.

type FileLoader 

type FileLoader []CertKeyFilePair

FileLoader loads certificates and their associated keys from disk.

func (FileLoader) CaddyModule 

func (FileLoader) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (FileLoader) LoadCertificates 

func (fl FileLoader) LoadCertificates() ([]Certificate, error)

LoadCertificates returns the certificates to be loaded by fl.

func (FileLoader) Provision added in v2.7.6 

func (fl FileLoader) Provision(ctx caddy.Context) error

Provision implements caddy.Provisioner.

type FolderLoader 

type FolderLoader []string

FolderLoader loads certificates and their associated keys from disk by recursively walking the specified directories, looking for PEM files which contain both a certificate and a key.

func (FolderLoader) CaddyModule 

func (FolderLoader) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (FolderLoader) LoadCertificates 

func (fl FolderLoader) LoadCertificates() ([]Certificate, error)

LoadCertificates loads all the certificates+keys in the directories listed in fl from all files ending with .pem. This method of loading certificates expects the certificate and key to be bundled into the same file.

func (FolderLoader) Provision added in v2.7.6 

func (fl FolderLoader) Provision(ctx caddy.Context) error

Provision implements caddy.Provisioner.

type HTTPCertGetter added in v2.5.0 

type HTTPCertGetter struct {
	// The URL from which to download the certificate. Required.
	//
	// The URL will be augmented with query string parameters taken
	// from the TLS handshake:
	//
	// - server_name: The SNI value
	// - signature_schemes: Comma-separated list of hex IDs of signatures
	// - cipher_suites: Comma-separated list of hex IDs of cipher suites
	//
	// To be valid, the response must be HTTP 200 with a PEM body
	// consisting of blocks for the certificate chain and the private
	// key.
	URL string `json:"url,omitempty"`
	// contains filtered or unexported fields
}

HTTPCertGetter can get a certificate via HTTP(S) request.

func (HTTPCertGetter) CaddyModule added in v2.5.0 

func (hcg HTTPCertGetter) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (HTTPCertGetter) GetCertificate added in v2.5.0 

func (hcg HTTPCertGetter) GetCertificate(ctx context.Context, hello *tls.ClientHelloInfo) (*tls.Certificate, error)

func (*HTTPCertGetter) Provision added in v2.5.0 

func (hcg *HTTPCertGetter) Provision(ctx caddy.Context) error

func (*HTTPCertGetter) UnmarshalCaddyfile added in v2.5.0 

func (hcg *HTTPCertGetter) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

UnmarshalCaddyfile deserializes Caddyfile tokens into ts. 

... http <url>

type HTTPChallengeConfig 

type HTTPChallengeConfig struct {
	// If true, the HTTP challenge will be disabled.
	Disabled bool `json:"disabled,omitempty"`

	// An alternate port on which to service this
	// challenge. Note that the HTTP challenge port is
	// hard-coded into the spec and cannot be changed,
	// so you would have to forward packets from the
	// standard HTTP challenge port to this one.
	AlternatePort int `json:"alternate_port,omitempty"`
}

HTTPChallengeConfig configures the ACME HTTP challenge.

type InternalIssuer 

type InternalIssuer struct {
	// The ID of the CA to use for signing. The default
	// CA ID is "local". The CA can be configured with the
	// `pki` app.
	CA string `json:"ca,omitempty"`

	// The validity period of certificates.
	Lifetime caddy.Duration `json:"lifetime,omitempty"`

	// If true, the root will be the issuer instead of
	// the intermediate. This is NOT recommended and should
	// only be used when devices/clients do not properly
	// validate certificate chains.
	SignWithRoot bool `json:"sign_with_root,omitempty"`
	// contains filtered or unexported fields
}

InternalIssuer is a certificate issuer that generates certificates internally using a locally-configured CA which can be customized using the `pki` app.

func (InternalIssuer) CaddyModule 

func (InternalIssuer) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (InternalIssuer) Issue 

func (iss InternalIssuer) Issue(ctx context.Context, csr *x509.CertificateRequest) (*certmagic.IssuedCertificate, error)

Issue issues a certificate to satisfy the CSR.

func (InternalIssuer) IssuerKey 

func (iss InternalIssuer) IssuerKey() string

IssuerKey returns the unique issuer key for the confgured CA endpoint.

func (*InternalIssuer) Provision 

func (iss *InternalIssuer) Provision(ctx caddy.Context) error

Provision sets up the issuer.

func (*InternalIssuer) UnmarshalCaddyfile added in v2.2.0 

func (iss *InternalIssuer) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

UnmarshalCaddyfile deserializes Caddyfile tokens into iss. 

... internal {
    ca       <name>
    lifetime <duration>
    sign_with_root
}

type LeafCertClientAuth added in v2.5.2 

type LeafCertClientAuth struct {
	TrustedLeafCerts []*x509.Certificate
}

LeafCertClientAuth verifies the client's leaf certificate.

func (LeafCertClientAuth) CaddyModule added in v2.5.2 

func (LeafCertClientAuth) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (LeafCertClientAuth) VerifyClientCertificate added in v2.5.2 

func (l LeafCertClientAuth) VerifyClientCertificate(rawCerts [][]byte, _ [][]*x509.Certificate) error

type MatchRemoteIP added in v2.4.0 

type MatchRemoteIP struct {
	// The IPs or CIDR ranges to match.
	Ranges []string `json:"ranges,omitempty"`

	// The IPs or CIDR ranges to *NOT* match.
	NotRanges []string `json:"not_ranges,omitempty"`
	// contains filtered or unexported fields
}

MatchRemoteIP matches based on the remote IP of the connection. Specific IPs or CIDR ranges can be specified.

Note that IPs can sometimes be spoofed, so do not rely on this as a replacement for actual authentication.

func (MatchRemoteIP) CaddyModule added in v2.4.0 

func (MatchRemoteIP) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (MatchRemoteIP) Match added in v2.4.0 

func (m MatchRemoteIP) Match(hello *tls.ClientHelloInfo) bool

Match matches hello based on the connection's remote IP.

func (*MatchRemoteIP) Provision added in v2.4.0 

func (m *MatchRemoteIP) Provision(ctx caddy.Context) error

Provision parses m's IP ranges, either from IP or CIDR expressions.

type MatchServerName 

type MatchServerName []string

MatchServerName matches based on SNI. Names in this list may use left-most-label wildcards, similar to wildcard certificates.

func (MatchServerName) CaddyModule 

func (MatchServerName) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (MatchServerName) Match 

func (m MatchServerName) Match(hello *tls.ClientHelloInfo) bool

Match matches hello based on SNI.

type OnDemandConfig 

type OnDemandConfig struct {
	// REQUIRED. If Caddy needs to load a certificate from
	// storage or obtain/renew a certificate during a TLS
	// handshake, it will perform a quick HTTP request to
	// this URL to check if it should be allowed to try to
	// get a certificate for the name in the "domain" query
	// string parameter, like so: `?domain=example.com`.
	// The endpoint must return a 200 OK status if a certificate
	// is allowed; anything else will cause it to be denied.
	// Redirects are not followed.
	Ask string `json:"ask,omitempty"`

	// DEPRECATED. An optional rate limit to throttle
	// the checking of storage and the issuance of
	// certificates from handshakes if not already in
	// storage. WILL BE REMOVED IN A FUTURE RELEASE.
	RateLimit *RateLimit `json:"rate_limit,omitempty"`
}

OnDemandConfig configures on-demand TLS, for obtaining needed certificates at handshake-time. Because this feature can easily be abused, you should use this to establish rate limits and/or an internal endpoint that Caddy can "ask" if it should be allowed to manage certificates for a given hostname.

type PEMLoader 

type PEMLoader []CertKeyPEMPair

PEMLoader loads certificates and their associated keys by decoding their PEM blocks directly. This has the advantage of not needing to store them on disk at all.

func (PEMLoader) CaddyModule 

func (PEMLoader) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (PEMLoader) LoadCertificates 

func (pl PEMLoader) LoadCertificates() ([]Certificate, error)

LoadCertificates returns the certificates contained in pl.

func (PEMLoader) Provision added in v2.7.6 

func (pl PEMLoader) Provision(ctx caddy.Context) error

Provision implements caddy.Provisioner.

type PublicKeyAlgorithm 

type PublicKeyAlgorithm x509.PublicKeyAlgorithm

PublicKeyAlgorithm is a JSON-unmarshalable wrapper type.

func (*PublicKeyAlgorithm) UnmarshalJSON 

func (a *PublicKeyAlgorithm) UnmarshalJSON(b []byte) error

UnmarshalJSON satisfies json.Unmarshaler.

type RateLimit 

type RateLimit struct {
	// A duration value. Storage may be checked and a certificate may be
	// obtained 'burst' times during this interval.
	Interval caddy.Duration `json:"interval,omitempty"`

	// How many times during an interval storage can be checked or a
	// certificate can be obtained.
	Burst int `json:"burst,omitempty"`
}

DEPRECATED. RateLimit specifies an interval with optional burst size.

type STEKProvider 

type STEKProvider interface {
	// Initialize provides the STEK configuration to the STEK
	// module so that it can obtain and manage keys accordingly.
	// It returns the initial key(s) to use. Implementations can
	// rely on Next() being called if Initialize() returns
	// without error, so that it may know when it is done.
	Initialize(config *SessionTicketService) ([][32]byte, error)

	// Next returns the channel through which the next session
	// ticket keys will be transmitted until doneChan is closed.
	// Keys should be sent on keysChan as they are updated.
	// When doneChan is closed, any resources allocated in
	// Initialize() must be cleaned up.
	Next(doneChan <-chan struct{}) (keysChan <-chan [][32]byte)
}

STEKProvider is a type that can provide session ticket ephemeral keys (STEKs).

type SessionTicketService 

type SessionTicketService struct {
	// KeySource is the method by which Caddy produces or obtains
	// TLS session ticket keys (STEKs). By default, Caddy generates
	// them internally using a secure pseudorandom source.
	KeySource json.RawMessage `json:"key_source,omitempty" caddy:"namespace=tls.stek inline_key=provider"`

	// How often Caddy rotates STEKs. Default: 12h.
	RotationInterval caddy.Duration `json:"rotation_interval,omitempty"`

	// The maximum number of keys to keep in rotation. Default: 4.
	MaxKeys int `json:"max_keys,omitempty"`

	// Disables STEK rotation.
	DisableRotation bool `json:"disable_rotation,omitempty"`

	// Disables TLS session resumption by tickets.
	Disabled bool `json:"disabled,omitempty"`
	// contains filtered or unexported fields
}

SessionTicketService configures and manages TLS session tickets.

func (SessionTicketService) RotateSTEKs 

func (s SessionTicketService) RotateSTEKs(keys [][32]byte) ([][32]byte, error)

RotateSTEKs rotates the keys in keys by producing a new key and eliding the oldest one. The new slice of keys is returned.

type StorageLoader added in v2.4.0 

type StorageLoader struct {
	// A list of pairs of certificate and key file names along with their
	// encoding format so that they can be loaded from storage.
	Pairs []CertKeyFilePair `json:"pairs,omitempty"`
	// contains filtered or unexported fields
}

StorageLoader loads certificates and their associated keys from the globally configured storage module.

func (StorageLoader) CaddyModule added in v2.4.0 

func (StorageLoader) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (StorageLoader) LoadCertificates added in v2.4.0 

func (sl StorageLoader) LoadCertificates() ([]Certificate, error)

LoadCertificates returns the certificates to be loaded by sl.

func (*StorageLoader) Provision added in v2.4.0 

func (sl *StorageLoader) Provision(ctx caddy.Context) error

Provision loads the storage module for sl.

type TLS 

type TLS struct {
	// Certificates to load into memory for quick recall during
	// TLS handshakes. Each key is the name of a certificate
	// loader module.
	//
	// The "automate" certificate loader module can be used to
	// specify a list of subjects that need certificates to be
	// managed automatically. The first matching automation
	// policy will be applied to manage the certificate(s).
	//
	// All loaded certificates get pooled
	// into the same cache and may be used to complete TLS
	// handshakes for the relevant server names (SNI).
	// Certificates loaded manually (anything other than
	// "automate") are not automatically managed and will
	// have to be refreshed manually before they expire.
	CertificatesRaw caddy.ModuleMap `json:"certificates,omitempty" caddy:"namespace=tls.certificates"`

	// Configures certificate automation.
	Automation *AutomationConfig `json:"automation,omitempty"`

	// Configures session ticket ephemeral keys (STEKs).
	SessionTickets *SessionTicketService `json:"session_tickets,omitempty"`

	// Configures the in-memory certificate cache.
	Cache *CertCacheOptions `json:"cache,omitempty"`

	// Disables OCSP stapling for manually-managed certificates only.
	// To configure OCSP stapling for automated certificates, use an
	// automation policy instead.
	//
	// Disabling OCSP stapling puts clients at greater risk, reduces their
	// privacy, and usually lowers client performance. It is NOT recommended
	// to disable this unless you are able to justify the costs.
	// EXPERIMENTAL. Subject to change.
	DisableOCSPStapling bool `json:"disable_ocsp_stapling,omitempty"`
	// contains filtered or unexported fields
}

TLS provides TLS facilities including certificate loading and management, client auth, and more.

func (*TLS) AddAutomationPolicy 

func (t *TLS) AddAutomationPolicy(ap *AutomationPolicy) error

AddAutomationPolicy provisions and adds ap to the list of the app's automation policies. If an existing automation policy exists that has fewer hosts in its list than ap does, ap will be inserted before that other policy (this helps ensure that ap will be prioritized/chosen over, say, a catch-all policy).

func (TLS) CaddyModule 

func (TLS) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (*TLS) Cleanup 

func (t *TLS) Cleanup() error

Cleanup frees up resources allocated during Provision.

func (*TLS) HandleHTTPChallenge 

func (t *TLS) HandleHTTPChallenge(w http.ResponseWriter, r *http.Request) bool

HandleHTTPChallenge ensures that the HTTP challenge is handled for the certificate named by r.Host, if it is an HTTP challenge request. It requires that the automation policy for r.Host has an issuer of type *certmagic.ACMEManager, or one that is ACME-enabled (GetACMEIssuer()).

func (*TLS) HasCertificateForSubject added in v2.7.0 

func (t *TLS) HasCertificateForSubject(subject string) bool

func (*TLS) Manage 

func (t *TLS) Manage(names []string) error

Manage immediately begins managing names according to the matching automation policy.

func (*TLS) Provision 

func (t *TLS) Provision(ctx caddy.Context) error

Provision sets up the configuration for the TLS app.

func (*TLS) Start 

func (t *TLS) Start() error

Start activates the TLS module.

func (*TLS) Stop 

func (t *TLS) Stop() error

Stop stops the TLS module and cleans up any allocations.

func (*TLS) Validate 

func (t *TLS) Validate() error

Validate validates t's configuration.

type TLSALPNChallengeConfig 

type TLSALPNChallengeConfig struct {
	// If true, the TLS-ALPN challenge will be disabled.
	Disabled bool `json:"disabled,omitempty"`

	// An alternate port on which to service this
	// challenge. Note that the TLS-ALPN challenge port
	// is hard-coded into the spec and cannot be changed,
	// so you would have to forward packets from the
	// standard TLS-ALPN challenge port to this one.
	AlternatePort int `json:"alternate_port,omitempty"`
}

TLSALPNChallengeConfig configures the ACME TLS-ALPN challenge.

type Tailscale added in v2.5.0 

type Tailscale struct {
	// contains filtered or unexported fields
}

Tailscale is a module that can get certificates from the local Tailscale process.

func (Tailscale) CaddyModule added in v2.5.0 

func (Tailscale) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (Tailscale) GetCertificate added in v2.5.0 

func (ts Tailscale) GetCertificate(ctx context.Context, hello *tls.ClientHelloInfo) (*tls.Certificate, error)

func (*Tailscale) Provision added in v2.5.0 

func (ts *Tailscale) Provision(ctx caddy.Context) error

func (Tailscale) UnmarshalCaddyfile added in v2.5.0 

func (Tailscale) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

UnmarshalCaddyfile deserializes Caddyfile tokens into ts. 

... tailscale

type ZeroSSLIssuer added in v2.2.0 

type ZeroSSLIssuer struct {
	*ACMEIssuer

	// The API key (or "access key") for using the ZeroSSL API.
	// This is optional, but can be used if you have an API key
	// already and don't want to supply your email address.
	APIKey string `json:"api_key,omitempty"`
	// contains filtered or unexported fields
}

ZeroSSLIssuer makes an ACME issuer for getting certificates from ZeroSSL by automatically generating EAB credentials. Please be sure to set a valid email address in your config so you can access/manage your domains in your ZeroSSL account.

This issuer is only needed for automatic generation of EAB credentials. If manually configuring/reusing EAB credentials, the standard ACMEIssuer may be used if desired.

func (*ZeroSSLIssuer) CaddyModule added in v2.2.0 

func (*ZeroSSLIssuer) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (*ZeroSSLIssuer) Issue added in v2.2.0 

func (iss *ZeroSSLIssuer) Issue(ctx context.Context, csr *x509.CertificateRequest) (*certmagic.IssuedCertificate, error)

Issue obtains a certificate for the given csr.

func (*ZeroSSLIssuer) IssuerKey added in v2.2.0 

func (iss *ZeroSSLIssuer) IssuerKey() string

IssuerKey returns the unique issuer key for the configured CA endpoint.

func (*ZeroSSLIssuer) PreCheck added in v2.2.0 

func (iss *ZeroSSLIssuer) PreCheck(ctx context.Context, names []string, interactive bool) error

PreCheck implements the certmagic.PreChecker interface.

func (*ZeroSSLIssuer) Provision added in v2.2.0 

func (iss *ZeroSSLIssuer) Provision(ctx caddy.Context) error

Provision sets up iss.

func (*ZeroSSLIssuer) Revoke added in v2.2.0 

func (iss *ZeroSSLIssuer) Revoke(ctx context.Context, cert certmagic.CertificateResource, reason int) error

Revoke revokes the given certificate.

func (*ZeroSSLIssuer) UnmarshalCaddyfile added in v2.2.0 

func (iss *ZeroSSLIssuer) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

UnmarshalCaddyfile deserializes Caddyfile tokens into iss. 

... zerossl [<api_key>] {
    ...
}

Any of the subdirectives for the ACME issuer can be used in the block.

Source Files

View all Source files

Directories

Path Synopsis
Package distributedstek provides TLS session ticket ephemeral keys (STEKs) in a distributed fashion by utilizing configured storage for locking and key sharing.
 Package distributedstek provides TLS session ticket ephemeral keys (STEKs) in a distributed fashion by utilizing configured storage for locking and key sharing.

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.