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

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"`

	// The validity period to ask the CA to issue a certificate for.
	// Default: 0 (CA chooses lifetime).
	// This value is used to compute the "notAfter" field of the ACME order;
	// therefore the system must have a reasonably synchronized clock.
	// NOTE: Not all CAs support this. Check with your CA's ACME
	// documentation to see if this is allowed and what values may
	// be used. EXPERIMENTAL: Subject to change.
	CertificateLifetime	caddy.Duration	`json:"certificate_lifetime,omitempty"`

	rootPool	*x509.CertPool
	logger		*zap.Logger

	template	certmagic.ACMEIssuer	// set at Provision
	magic		*certmagic.Config	// set at PreCheck
	issuer		*certmagic.ACMEIssuer	// set at PreCheck; result of template + magic
}

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.

type AutomateLoader []string

AutomationConfig governs the automated management of TLS certificates.

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"`

	defaultPublicAutomationPolicy	*AutomationPolicy
	defaultInternalAutomationPolicy	*AutomationPolicy	// only initialized if necessary
}

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.

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; otherwise 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"`

	// If true, private keys already existing in storage
	// will be reused. Otherwise, a new key will be
	// created for every new certificate to mitigate
	// pinning and reduce the scope of key compromise.
	// TEMPORARY: Key pinning is against industry best practices.
	// This property will likely be removed in the future.
	// Do not rely on it forever; watch the release notes.
	ReusePrivateKeys	bool	`json:"reuse_private_keys,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:"-"`

	subjects	[]string
	magic		*certmagic.Config
	storage		certmagic.Storage

	// Whether this policy had explicit managers configured directly on it.
	hadExplicitManagers	bool
}

The interface to be implemented by all guest modules part of the namespace 'tls.ca_pool.source.'

type CA interface {
	CertPool() *x509.CertPool
}

CertCacheOptions configures the certificate cache.

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"`
}

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

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"`
}

CertKeyPEMPair pairs certificate and key PEM blocks.

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"`
}

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

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

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

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

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

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"`
}

ChallengesConfig configures the ACME challenges.

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"`
}

ClientAuthentication configures TLS client auth.

type ClientAuthentication struct {
	// Certificate authority module which provides the certificate pool of trusted certificates
	CARaw	json.RawMessage	`json:"ca,omitempty" caddy:"namespace=tls.ca_pool.source inline_key=provider"`
	ca	CA

	// Deprecated: Use the `ca` field with the `tls.ca_pool.source.inline` module instead.
	// 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"`

	// Deprecated: Use the `ca` field with the `tls.ca_pool.source.file` module instead.
	// 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.verifier.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.verifier inline_key=verifier"`

	verifiers	[]ClientCertificateVerifier

	// 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"`

	existingVerifyPeerCert	func([][]byte, [][]*x509.Certificate) error
}

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

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

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 ConfigSetter interface {
	SetConfig(cfg *certmagic.Config)
}

ConnectionMatcher is a type which matches TLS handshakes.

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

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.

type ConnectionPolicies []*ConnectionPolicy

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

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"`
	matchers	[]ConnectionMatcher

	// 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"`

	// Reject TLS connections. EXPERIMENTAL: May change.
	Drop	bool	`json:"drop,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"`

	// A module that can manipulate the context passed into CertMagic's
	// certificate management functions during TLS handshakes.
	// EXPERIMENTAL - subject to change or removal.
	HandshakeContextRaw	json.RawMessage	`json:"handshake_context,omitempty" caddy:"namespace=tls.context inline_key=module"`
	handshakeContext	HandshakeContext

	// 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:"-"`
}

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.

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"`
}

DNSChallengeConfig configures the ACME DNS challenge.

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

type DNSChallengeConfig struct {
	// The DNS provider module to use which will manage
	// the DNS records relevant to the ACME challenge.
	// Required.
	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"`

	solver	acmez.Solver
}

FileCAPool generates trusted root certificates pool from the designated DER and PEM file

type FileCAPool struct {
	// 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:"pem_files,omitempty"`

	pool	*x509.CertPool
}

FileLoader loads certificates and their associated keys from disk.

type FileLoader []CertKeyFilePair

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.

type FolderLoader []string

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

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.
	//
	// To indicate that this manager is not managing a certificate for
	// the described handshake, the endpoint should return HTTP 204
	// (No Content). Error statuses will indicate that the manager is
	// capable of providing a certificate but was unable to.
	URL	string	`json:"url,omitempty"`

	ctx	context.Context
}

The HTTPCertPool fetches the trusted root certificates from HTTP(S) endpoints. The TLS connection properties can be customized, including custom trusted root certificate. One example usage of this module is to get the trusted certificates from another Caddy instance that is running the PKI app and ACME server.

type HTTPCertPool struct {
	// the list of URLs that respond with PEM-encoded certificates to trust.
	Endpoints	[]string	`json:"endpoints,omitempty"`

	// Customize the TLS connection knobs to used during the HTTP call
	TLS	*TLSConfig	`json:"tls,omitempty"`

	pool	*x509.CertPool
}

HTTPChallengeConfig configures the ACME HTTP challenge.

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"`
}

This type doesn't have documentation.

type HandshakeContext interface {
	// HandshakeContext returns a context to pass into CertMagic's
	// GetCertificate function used to serve, load, and manage certs
	// during TLS handshakes. Generally you'll start with the context
	// from the ClientHelloInfo, but you may use other information
	// from it as well. Return an error to abort the handshake.
	HandshakeContext(*tls.ClientHelloInfo) (context.Context, error)
}

InlineCAPool is a certificate authority pool provider coming from a DER-encoded certificates in the config

type InlineCAPool 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"`

	pool	*x509.CertPool
}

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

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"`

	ca	*caddypki.CA
	logger	*zap.Logger
}

LeafCertClientAuth verifies the client's leaf certificate.

type LeafCertClientAuth struct {
	LeafCertificateLoadersRaw	[]json.RawMessage	`json:"leaf_certs_loaders,omitempty" caddy:"namespace=tls.leaf_cert_loader inline_key=loader"`
	trustedLeafCerts		[]*x509.Certificate
}

LeafCertificateLoader is a type that loads the trusted leaf certificates for the tls.leaf_cert_loader modules

type LeafCertificateLoader interface {
	LoadLeafCertificates() ([]*x509.Certificate, error)
}

LeafFileLoader loads leaf certificates from disk.

type LeafFileLoader struct {
	Files []string `json:"files,omitempty"`
}

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

type LeafFolderLoader struct {
	Folders []string `json:"folders,omitempty"`
}

LeafPEMLoader loads leaf certificates by decoding their PEM blocks directly. This has the advantage of not needing to store them on disk at all.

type LeafPEMLoader struct {
	Certificates []string `json:"certificates,omitempty"`
}

LeafStorageLoader loads leaf certificates from the globally configured storage module.

type LeafStorageLoader struct {
	// A list of certificate file names to be loaded from storage.
	Certificates	[]string	`json:"certificates,omitempty"`

	// The storage module where the trusted leaf certificates are stored. Absent
	// explicit storage implies the use of Caddy default storage.
	StorageRaw	json.RawMessage	`json:"storage,omitempty" caddy:"namespace=caddy.storage inline_key=module"`

	// Reference to the globally configured storage module.
	storage	certmagic.Storage

	ctx	caddy.Context
}

MatchLocalIP matches based on the IP address of the interface receiving the connection. Specific IPs or CIDR ranges can be specified.

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

	cidrs	[]netip.Prefix
	logger	*zap.Logger
}

MatchRegexp is an embeddable type for matching using regular expressions. It adds placeholders to the request's replacer. In fact, it is a copy of caddyhttp.MatchRegexp with a local replacer prefix and placeholders support in a regular expression pattern.

type MatchRegexp struct {
	// A unique name for this regular expression. Optional,
	// but useful to prevent overwriting captures from other
	// regexp matchers.
	Name	string	`json:"name,omitempty"`

	// The regular expression to evaluate, in RE2 syntax,
	// which is the same general syntax used by Go, Perl,
	// and Python. For details, see
	// [Go's regexp package](https://golang.org/pkg/regexp/).
	// Captures are accessible via placeholders. Unnamed
	// capture groups are exposed as their numeric, 1-based
	// index, while named capture groups are available by
	// the capture group name.
	Pattern	string	`json:"pattern"`

	compiled	*regexp.Regexp
}

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.

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"`

	cidrs		[]netip.Prefix
	notCidrs	[]netip.Prefix
	logger		*zap.Logger
}

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

type MatchServerName []string

MatchServerNameRE matches based on SNI using a regular expression.

type MatchServerNameRE struct{ MatchRegexp }

OnDemandConfig configures on-demand TLS, for obtaining needed certificates at handshake-time. Because this feature can easily be abused, Caddy must ask permission to your application whether a particular domain is allowed to have a certificate issued for it.

type OnDemandConfig struct {
	// Deprecated. WILL BE REMOVED SOON. Use 'permission' instead with the `http` module.
	Ask	string	`json:"ask,omitempty"`

	// REQUIRED. A module that will determine whether a
	// certificate is allowed to be loaded from storage
	// or obtained from an issuer on demand.
	PermissionRaw	json.RawMessage	`json:"permission,omitempty" caddy:"namespace=tls.permission inline_key=module"`
	permission	OnDemandPermission
}

OnDemandPermission is a type that can give permission for whether a certificate should be allowed to be obtained or loaded from storage on-demand. EXPERIMENTAL: This API is experimental and subject to change.

type OnDemandPermission interface {
	// CertificateAllowed returns nil if a certificate for the given
	// name is allowed to be either obtained from an issuer or loaded
	// from storage on-demand.
	//
	// The context passed in has the associated *tls.ClientHelloInfo
	// value available at the certmagic.ClientHelloInfoCtxKey key.
	//
	// In the worst case, this function may be called as frequently
	// as every TLS handshake, so it should return as quick as possible
	// to reduce latency. In the normal case, this function is only
	// called when a certificate is needed that is not already loaded
	// into memory ready to serve.
	CertificateAllowed(ctx context.Context, name string) error
}

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.

type PEMLoader []CertKeyPEMPair

PKIIntermediateCAPool extracts the trusted intermediate certificates from Caddy's native 'pki' app

type PKIIntermediateCAPool struct {
	// List of the Authority names that are configured in the `pki` app whose intermediate certificates are trusted
	Authority	[]string	`json:"authority,omitempty"`

	ca	[]*caddypki.CA
	pool	*x509.CertPool
}

PKIRootCAPool extracts the trusted root certificates from Caddy's native 'pki' app

type PKIRootCAPool struct {
	// List of the Authority names that are configured in the `pki` app whose root certificates are trusted
	Authority	[]string	`json:"authority,omitempty"`

	ca	[]*caddypki.CA
	pool	*x509.CertPool
}

PermissionByHTTP determines permission for a TLS certificate by making a request to an HTTP endpoint.

type PermissionByHTTP struct {
	// The endpoint to access. It should be a full URL.
	// A query string parameter "domain" will be added to it,
	// containing the domain (or IP) for the desired certificate,
	// like so: `?domain=example.com`. Generally, this endpoint
	// is not exposed publicly to avoid a minor information leak
	// (which domains are serviced by your application).
	//
	// 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.
	Endpoint	string	`json:"endpoint"`

	logger		*zap.Logger
	replacer	*caddy.Replacer
}

PublicKeyAlgorithm is a JSON-unmarshalable wrapper type.

type PublicKeyAlgorithm x509.PublicKeyAlgorithm

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

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

SessionTicketService configures and manages TLS session tickets.

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"`

	keySource	STEKProvider
	configs		map[*tls.Config]struct{}
	stopChan	chan struct{}
	currentKeys	[][32]byte
	mu		*sync.Mutex
}

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

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"`

	// Reference to the globally configured storage module.
	storage	certmagic.Storage

	ctx	caddy.Context
}

StoragePool extracts the trusted certificates root from Caddy storage

type StoragePool struct {
	// The storage module where the trusted root certificates are stored. Absent
	// explicit storage implies the use of Caddy default storage.
	StorageRaw	json.RawMessage	`json:"storage,omitempty" caddy:"namespace=caddy.storage inline_key=module"`

	// The storage key/index to the location of the certificates
	PEMKeys	[]string	`json:"pem_keys,omitempty"`

	storage	certmagic.Storage
	pool	*x509.CertPool
}

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

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"`

	// Disables checks in certmagic that the configured storage is ready
	// and able to handle writing new content to it. These checks are
	// intended to prevent information loss (newly issued certificates), but
	// can be expensive on the storage.
	//
	// Disabling these checks should only be done when the storage
	// can be trusted to have enough capacity and no other problems.
	// EXPERIMENTAL. Subject to change.
	DisableStorageCheck	bool	`json:"disable_storage_check,omitempty"`

	// Disables the automatic cleanup of the storage backend.
	// This is useful when TLS is not being used to store certificates
	// and the user wants run their server in a read-only mode.
	//
	// Storage cleaning creates two files: instance.uuid and last_clean.json.
	// The instance.uuid file is used to identify the instance of Caddy
	// in a cluster. The last_clean.json file is used to store the last
	// time the storage was cleaned.
	// EXPERIMENTAL. Subject to change.
	DisableStorageClean	bool	`json:"disable_storage_clean,omitempty"`

	certificateLoaders	[]CertificateLoader
	automateNames		[]string
	ctx			caddy.Context
	storageCleanTicker	*time.Ticker
	storageCleanStop	chan struct{}
	logger			*zap.Logger
	events			*caddyevents.App

	// set of subjects with managed certificates,
	// and hashes of manually-loaded certificates
	// (managing's value is an optional issuer key, for distinction)
	managing, loaded	map[string]string
}

TLSALPNChallengeConfig configures the ACME TLS-ALPN challenge.

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"`
}

TLSConfig holds configuration related to the TLS configuration for the transport/client. copied from with minor modifications: modules/caddyhttp/reverseproxy/httptransport.go

type TLSConfig struct {
	// Provides the guest module that provides the trusted certificate authority (CA) certificates
	CARaw	json.RawMessage	`json:"ca,omitempty" caddy:"namespace=tls.ca_pool.source inline_key=provider"`

	// If true, TLS verification of server certificates will be disabled.
	// This is insecure and may be removed in the future. Do not use this
	// option except in testing or local development environments.
	InsecureSkipVerify	bool	`json:"insecure_skip_verify,omitempty"`

	// The duration to allow a TLS handshake to a server. Default: No timeout.
	HandshakeTimeout	caddy.Duration	`json:"handshake_timeout,omitempty"`

	// The server name used when verifying the certificate received in the TLS
	// handshake. By default, this will use the upstream address' host part.
	// You only need to override this if your upstream address does not match the
	// certificate the upstream is likely to use. For example if the upstream
	// address is an IP address, then you would need to configure this to the
	// hostname being served by the upstream server. Currently, this does not
	// support placeholders because the TLS config is not provisioned on each
	// connection, so a static value must be used.
	ServerName	string	`json:"server_name,omitempty"`

	// TLS renegotiation level. TLS renegotiation is the act of performing
	// subsequent handshakes on a connection after the first.
	// The level can be:
	//  - "never": (the default) disables renegotiation.
	//  - "once": allows a remote server to request renegotiation once per connection.
	//  - "freely": allows a remote server to repeatedly request renegotiation.
	Renegotiation	string	`json:"renegotiation,omitempty"`
}

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

type Tailscale struct {
	logger *zap.Logger
}

ZeroSSLIssuer uses the ZeroSSL API to get certificates. Note that this is distinct from ZeroSSL's ACME endpoint. To use ZeroSSL's ACME endpoint, use the ACMEIssuer configured with ZeroSSL's ACME directory endpoint.

type ZeroSSLIssuer struct {
	// The API key (or "access key") for using the ZeroSSL API.
	// REQUIRED.
	APIKey	string	`json:"api_key,omitempty"`

	// How many days the certificate should be valid for.
	// Only certain values are accepted; see ZeroSSL docs.
	ValidityDays	int	`json:"validity_days,omitempty"`

	// The host to bind to when opening a listener for
	// verifying domain names (or IPs).
	ListenHost	string	`json:"listen_host,omitempty"`

	// If HTTP is forwarded from port 80, specify the
	// forwarded port here.
	AlternateHTTPPort	int	`json:"alternate_http_port,omitempty"`

	// Use CNAME validation instead of HTTP. ZeroSSL's
	// API uses CNAME records for DNS validation, similar
	// to how Let's Encrypt uses TXT records for the
	// DNS challenge.
	CNAMEValidation	*DNSChallengeConfig	`json:"cname_validation,omitempty"`

	logger	*zap.Logger
	storage	certmagic.Storage
	issuer	*certmagic.ZeroSSLIssuer
}

bigInt is a big.Int type that interops with JSON encodings as a string.

type bigInt struct{ big.Int }

customCertLifetime allows us to customize certificates that are issued by Smallstep libs, particularly the NotBefore & NotAfter dates.

type customCertLifetime time.Duration

This type doesn't have documentation.

type destructableWriter struct{ *os.File }

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

func AllMatchingCertificates(san string) []certmagic.Certificate {
	return certCache.AllMatchingCertificates(san)
}

Cognitive complexity: 0, Cyclomatic complexity: 1

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

func CipherSuiteID(name string) uint16 {
	for _, cs := range SupportedCipherSuites() {
		if cs.Name == name {
			return cs.ID
		}
	}
	return 0
}

Cognitive complexity: 5, Cyclomatic complexity: 3

CipherSuiteNameSupported returns true if name is a supported cipher suite.

func CipherSuiteNameSupported(name string) bool {
	return CipherSuiteID(name) != 0
}

Cognitive complexity: 0, Cyclomatic complexity: 1

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

func DefaultIssuers(userEmail string) []certmagic.Issuer {
	issuers := []certmagic.Issuer{new(ACMEIssuer)}
	if strings.TrimSpace(userEmail) != "" {
		issuers = append(issuers, &ACMEIssuer{
			CA:	certmagic.ZeroSSLProductionCA,
			Email:	userEmail,
		})
	}
	return issuers
}

Cognitive complexity: 4, Cyclomatic complexity: 2

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

func DefaultIssuersProvisioned(ctx caddy.Context) ([]certmagic.Issuer, error) {
	issuers := DefaultIssuers("")
	for i, iss := range issuers {
		if prov, ok := iss.(caddy.Provisioner); ok {
			err := prov.Provision(ctx)
			if err != nil {
				return nil, fmt.Errorf("provisioning default issuer %d: %T: %v", i, iss, err)
			}
		}
	}
	return issuers, nil
}

Cognitive complexity: 7, Cyclomatic complexity: 4

ParseCaddyfileNestedMatcherSet parses the Caddyfile tokens for a nested matcher set, and returns its raw module map value.

func ParseCaddyfileNestedMatcherSet(d *caddyfile.Dispenser) (caddy.ModuleMap, error) {
	matcherMap := make(map[string]ConnectionMatcher)

	tokensByMatcherName := make(map[string][]caddyfile.Token)
	for nesting := d.Nesting(); d.NextArg() || d.NextBlock(nesting); {
		matcherName := d.Val()
		tokensByMatcherName[matcherName] = append(tokensByMatcherName[matcherName], d.NextSegment()...)
	}

	for matcherName, tokens := range tokensByMatcherName {
		dd := caddyfile.NewDispenser(tokens)
		dd.Next()	// consume wrapper name

		unm, err := caddyfile.UnmarshalModule(dd, "tls.handshake_match."+matcherName)
		if err != nil {
			return nil, err
		}
		cm, ok := unm.(ConnectionMatcher)
		if !ok {
			return nil, fmt.Errorf("matcher module '%s' is not a connection matcher", matcherName)
		}
		matcherMap[matcherName] = cm
	}

	matcherSet := make(caddy.ModuleMap)
	for name, matcher := range matcherMap {
		jsonBytes, err := json.Marshal(matcher)
		if err != nil {
			return nil, fmt.Errorf("marshaling %T matcher: %v", matcher, err)
		}
		matcherSet[name] = jsonBytes
	}

	return matcherSet, nil
}

Cognitive complexity: 14, Cyclomatic complexity: 8

func ParseCaddyfilePreferredChainsOptions(d *caddyfile.Dispenser) (*ChainPreference, error) {
	chainPref := new(ChainPreference)
	if d.NextArg() {
		smallestOpt := d.Val()
		if smallestOpt == "smallest" {
			trueBool := true
			chainPref.Smallest = &trueBool
			if d.NextArg() {	// Only one argument allowed
				return nil, d.ArgErr()
			}
			if d.NextBlock(d.Nesting()) {	// Don't allow other options when smallest == true
				return nil, d.Err("No more options are accepted when using the 'smallest' option")
			}
		} else {	// Smallest option should always be 'smallest' or unset
			return nil, d.Errf("Invalid argument '%s'", smallestOpt)
		}
	}
	for nesting := d.Nesting(); d.NextBlock(nesting); {
		switch d.Val() {
		case "root_common_name":
			rootCommonNameOpt := d.RemainingArgs()
			chainPref.RootCommonName = rootCommonNameOpt
			if rootCommonNameOpt == nil {
				return nil, d.ArgErr()
			}
			if chainPref.AnyCommonName != nil {
				return nil, d.Err("Can't set root_common_name when any_common_name is already set")
			}

		case "any_common_name":
			anyCommonNameOpt := d.RemainingArgs()
			chainPref.AnyCommonName = anyCommonNameOpt
			if anyCommonNameOpt == nil {
				return nil, d.ArgErr()
			}
			if chainPref.RootCommonName != nil {
				return nil, d.Err("Can't set any_common_name when root_common_name is already set")
			}

		default:
			return nil, d.Errf("Received unrecognized parameter '%s'", d.Val())
		}
	}

	if chainPref.Smallest == nil && chainPref.RootCommonName == nil && chainPref.AnyCommonName == nil {
		return nil, d.Err("No options for preferred_chains received")
	}

	return chainPref, nil
}

Cognitive complexity: 26, Cyclomatic complexity: 16

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 ProtocolName(id uint16) string {
	for k, v := range SupportedProtocols {
		if v == id {
			return k
		}
	}

	for k, v := range unsupportedProtocols {
		if v == id {
			return k
		}
	}

	return fmt.Sprintf("0x%04x", id)
}

Cognitive complexity: 10, Cyclomatic complexity: 5

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

func SupportedCipherSuites() []*tls.CipherSuite {
	return tls.CipherSuites()
}

Cognitive complexity: 0, Cyclomatic complexity: 1

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 (iss *ACMEIssuer) GetACMEIssuer() *ACMEIssuer	{ return iss }

Cognitive complexity: 0, Cyclomatic complexity: 1

GetRenewalInfo wraps the underlying GetRenewalInfo method and satisfies the CertMagic interface for ARI support.

func (iss *ACMEIssuer) GetRenewalInfo(ctx context.Context, cert certmagic.Certificate) (acme.RenewalInfo, error) {
	return iss.issuer.GetRenewalInfo(ctx, cert)
}

Cognitive complexity: 0, Cyclomatic complexity: 1

Issue obtains a certificate for the given csr.

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

Cognitive complexity: 0, Cyclomatic complexity: 1

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

func (iss *ACMEIssuer) IssuerKey() string {
	return iss.issuer.IssuerKey()
}

Cognitive complexity: 0, Cyclomatic complexity: 1

PreCheck implements the certmagic.PreChecker interface.

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

Cognitive complexity: 0, Cyclomatic complexity: 1

Provision sets up iss.

func (iss *ACMEIssuer) Provision(ctx caddy.Context) error {
	iss.logger = ctx.Logger()

	repl := caddy.NewReplacer()

	// expand email address, if non-empty
	if iss.Email != "" {
		email, err := repl.ReplaceOrErr(iss.Email, true, true)
		if err != nil {
			return fmt.Errorf("expanding email address '%s': %v", iss.Email, err)
		}
		iss.Email = email
	}

	// expand account key, if non-empty
	if iss.AccountKey != "" {
		accountKey, err := repl.ReplaceOrErr(iss.AccountKey, true, true)
		if err != nil {
			return fmt.Errorf("expanding account key PEM '%s': %v", iss.AccountKey, err)
		}
		iss.AccountKey = accountKey
	}

	// DNS providers
	if iss.Challenges != nil && iss.Challenges.DNS != nil && iss.Challenges.DNS.ProviderRaw != nil {
		val, err := ctx.LoadModule(iss.Challenges.DNS, "ProviderRaw")
		if err != nil {
			return fmt.Errorf("loading DNS provider module: %v", err)
		}
		iss.Challenges.DNS.solver = &certmagic.DNS01Solver{
			DNSManager: certmagic.DNSManager{
				DNSProvider:		val.(certmagic.DNSProvider),
				TTL:			time.Duration(iss.Challenges.DNS.TTL),
				PropagationDelay:	time.Duration(iss.Challenges.DNS.PropagationDelay),
				PropagationTimeout:	time.Duration(iss.Challenges.DNS.PropagationTimeout),
				Resolvers:		iss.Challenges.DNS.Resolvers,
				OverrideDomain:		iss.Challenges.DNS.OverrideDomain,
			},
		}
	}

	// add any custom CAs to trust store
	if len(iss.TrustedRootsPEMFiles) > 0 {
		iss.rootPool = x509.NewCertPool()
		for _, pemFile := range iss.TrustedRootsPEMFiles {
			pemData, err := os.ReadFile(pemFile)
			if err != nil {
				return fmt.Errorf("loading trusted root CA's PEM file: %s: %v", pemFile, err)
			}
			if !iss.rootPool.AppendCertsFromPEM(pemData) {
				return fmt.Errorf("unable to add %s to trust pool: %v", pemFile, err)
			}
		}
	}

	var err error
	iss.template, err = iss.makeIssuerTemplate()
	if err != nil {
		return err
	}

	return nil
}

Cognitive complexity: 25, Cyclomatic complexity: 14

Revoke revokes the given certificate.

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

Cognitive complexity: 0, Cyclomatic complexity: 1

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 (iss *ACMEIssuer) SetConfig(cfg *certmagic.Config) {
	iss.magic = cfg
	iss.issuer = certmagic.NewACMEIssuer(cfg, iss.template)
}

Cognitive complexity: 0, Cyclomatic complexity: 1

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

func (iss *ACMEIssuer) UnmarshalCaddyfile(d *caddyfile.Dispenser) error {
	d.Next()	// consume issuer name

	if d.NextArg() {
		iss.CA = d.Val()
		if d.NextArg() {
			return d.ArgErr()
		}
	}

	for d.NextBlock(0) {
		switch d.Val() {
		case "lifetime":
			var lifetimeStr string
			if !d.AllArgs(&lifetimeStr) {
				return d.ArgErr()
			}
			lifetime, err := caddy.ParseDuration(lifetimeStr)
			if err != nil {
				return d.Errf("invalid lifetime %s: %v", lifetimeStr, err)
			}
			if lifetime < 0 {
				return d.Errf("lifetime must be >= 0: %s", lifetime)
			}
			iss.CertificateLifetime = caddy.Duration(lifetime)

		case "dir":
			if iss.CA != "" {
				return d.Errf("directory is already specified: %s", iss.CA)
			}
			if !d.AllArgs(&iss.CA) {
				return d.ArgErr()
			}

		case "test_dir":
			if !d.AllArgs(&iss.TestCA) {
				return d.ArgErr()
			}

		case "email":
			if !d.AllArgs(&iss.Email) {
				return d.ArgErr()
			}

		case "timeout":
			var timeoutStr string
			if !d.AllArgs(&timeoutStr) {
				return d.ArgErr()
			}
			timeout, err := caddy.ParseDuration(timeoutStr)
			if err != nil {
				return d.Errf("invalid timeout duration %s: %v", timeoutStr, err)
			}
			iss.ACMETimeout = caddy.Duration(timeout)

		case "disable_http_challenge":
			if d.NextArg() {
				return d.ArgErr()
			}
			if iss.Challenges == nil {
				iss.Challenges = new(ChallengesConfig)
			}
			if iss.Challenges.HTTP == nil {
				iss.Challenges.HTTP = new(HTTPChallengeConfig)
			}
			iss.Challenges.HTTP.Disabled = true

		case "disable_tlsalpn_challenge":
			if d.NextArg() {
				return d.ArgErr()
			}
			if iss.Challenges == nil {
				iss.Challenges = new(ChallengesConfig)
			}
			if iss.Challenges.TLSALPN == nil {
				iss.Challenges.TLSALPN = new(TLSALPNChallengeConfig)
			}
			iss.Challenges.TLSALPN.Disabled = true

		case "alt_http_port":
			if !d.NextArg() {
				return d.ArgErr()
			}
			port, err := strconv.Atoi(d.Val())
			if err != nil {
				return d.Errf("invalid port %s: %v", d.Val(), err)
			}
			if iss.Challenges == nil {
				iss.Challenges = new(ChallengesConfig)
			}
			if iss.Challenges.HTTP == nil {
				iss.Challenges.HTTP = new(HTTPChallengeConfig)
			}
			iss.Challenges.HTTP.AlternatePort = port

		case "alt_tlsalpn_port":
			if !d.NextArg() {
				return d.ArgErr()
			}
			port, err := strconv.Atoi(d.Val())
			if err != nil {
				return d.Errf("invalid port %s: %v", d.Val(), err)
			}
			if iss.Challenges == nil {
				iss.Challenges = new(ChallengesConfig)
			}
			if iss.Challenges.TLSALPN == nil {
				iss.Challenges.TLSALPN = new(TLSALPNChallengeConfig)
			}
			iss.Challenges.TLSALPN.AlternatePort = port

		case "eab":
			iss.ExternalAccount = new(acme.EAB)
			if !d.AllArgs(&iss.ExternalAccount.KeyID, &iss.ExternalAccount.MACKey) {
				return d.ArgErr()
			}

		case "trusted_roots":
			iss.TrustedRootsPEMFiles = d.RemainingArgs()

		case "dns":
			if !d.NextArg() {
				return d.ArgErr()
			}
			provName := d.Val()
			if iss.Challenges == nil {
				iss.Challenges = new(ChallengesConfig)
			}
			if iss.Challenges.DNS == nil {
				iss.Challenges.DNS = new(DNSChallengeConfig)
			}
			unm, err := caddyfile.UnmarshalModule(d, "dns.providers."+provName)
			if err != nil {
				return err
			}
			iss.Challenges.DNS.ProviderRaw = caddyconfig.JSONModuleObject(unm, "name", provName, nil)

		case "propagation_delay":
			if !d.NextArg() {
				return d.ArgErr()
			}
			delayStr := d.Val()
			delay, err := caddy.ParseDuration(delayStr)
			if err != nil {
				return d.Errf("invalid propagation_delay duration %s: %v", delayStr, err)
			}
			if iss.Challenges == nil {
				iss.Challenges = new(ChallengesConfig)
			}
			if iss.Challenges.DNS == nil {
				iss.Challenges.DNS = new(DNSChallengeConfig)
			}
			iss.Challenges.DNS.PropagationDelay = caddy.Duration(delay)

		case "propagation_timeout":
			if !d.NextArg() {
				return d.ArgErr()
			}
			timeoutStr := d.Val()
			var timeout time.Duration
			if timeoutStr == "-1" {
				timeout = time.Duration(-1)
			} else {
				var err error
				timeout, err = caddy.ParseDuration(timeoutStr)
				if err != nil {
					return d.Errf("invalid propagation_timeout duration %s: %v", timeoutStr, err)
				}
			}
			if iss.Challenges == nil {
				iss.Challenges = new(ChallengesConfig)
			}
			if iss.Challenges.DNS == nil {
				iss.Challenges.DNS = new(DNSChallengeConfig)
			}
			iss.Challenges.DNS.PropagationTimeout = caddy.Duration(timeout)

		case "resolvers":
			if iss.Challenges == nil {
				iss.Challenges = new(ChallengesConfig)
			}
			if iss.Challenges.DNS == nil {
				iss.Challenges.DNS = new(DNSChallengeConfig)
			}
			iss.Challenges.DNS.Resolvers = d.RemainingArgs()
			if len(iss.Challenges.DNS.Resolvers) == 0 {
				return d.ArgErr()
			}

		case "dns_ttl":
			if !d.NextArg() {
				return d.ArgErr()
			}
			ttlStr := d.Val()
			ttl, err := caddy.ParseDuration(ttlStr)
			if err != nil {
				return d.Errf("invalid dns_ttl duration %s: %v", ttlStr, err)
			}
			if iss.Challenges == nil {
				iss.Challenges = new(ChallengesConfig)
			}
			if iss.Challenges.DNS == nil {
				iss.Challenges.DNS = new(DNSChallengeConfig)
			}
			iss.Challenges.DNS.TTL = caddy.Duration(ttl)

		case "dns_challenge_override_domain":
			arg := d.RemainingArgs()
			if len(arg) != 1 {
				return d.ArgErr()
			}
			if iss.Challenges == nil {
				iss.Challenges = new(ChallengesConfig)
			}
			if iss.Challenges.DNS == nil {
				iss.Challenges.DNS = new(DNSChallengeConfig)
			}
			iss.Challenges.DNS.OverrideDomain = arg[0]

		case "preferred_chains":
			chainPref, err := ParseCaddyfilePreferredChainsOptions(d)
			if err != nil {
				return err
			}
			iss.PreferredChains = chainPref

		default:
			return d.Errf("unrecognized ACME issuer property: %s", d.Val())
		}
	}
	return nil
}

Cognitive complexity: 124, Cyclomatic complexity: 71

AllInternalSubjects returns true if all the subjects on this policy are internal.

func (ap *AutomationPolicy) AllInternalSubjects() bool {
	return !slices.ContainsFunc(ap.subjects, func(s string) bool {
		return !certmagic.SubjectIsInternal(s)
	})
}

Cognitive complexity: 1, Cyclomatic complexity: 1

Subjects returns the list of subjects with all placeholders replaced.

func (ap *AutomationPolicy) Subjects() []string {
	return ap.subjects
}

Cognitive complexity: 0, Cyclomatic complexity: 1

ConfigureTLSConfig sets up cfg to enforce clientauth's configuration.

func (clientauth *ClientAuthentication) ConfigureTLSConfig(cfg *tls.Config) error {
	// if there's no actionable client auth, simply disable it
	if !clientauth.Active() {
		cfg.ClientAuth = tls.NoClientCert
		return nil
	}

	// enforce desired mode of client authentication
	if len(clientauth.Mode) > 0 {
		switch clientauth.Mode {
		case "request":
			cfg.ClientAuth = tls.RequestClientCert
		case "require":
			cfg.ClientAuth = tls.RequireAnyClientCert
		case "verify_if_given":
			cfg.ClientAuth = tls.VerifyClientCertIfGiven
		case "require_and_verify":
			cfg.ClientAuth = tls.RequireAndVerifyClientCert
		default:
			return fmt.Errorf("client auth mode not recognized: %s", clientauth.Mode)
		}
	} else {
		// otherwise, set a safe default mode
		if len(clientauth.TrustedCACerts) > 0 ||
			len(clientauth.TrustedCACertPEMFiles) > 0 ||
			len(clientauth.TrustedLeafCerts) > 0 ||
			clientauth.CARaw != nil || clientauth.ca != nil {
			cfg.ClientAuth = tls.RequireAndVerifyClientCert
		} else {
			cfg.ClientAuth = tls.RequireAnyClientCert
		}
	}

	// enforce CA verification by adding CA certs to the ClientCAs pool
	if clientauth.ca != nil {
		cfg.ClientCAs = clientauth.ca.CertPool()
	}

	// TODO: DEPRECATED: Only here for backwards compatibility.
	// If leaf cert is specified, enforce by adding a client auth module
	if len(clientauth.TrustedLeafCerts) > 0 {
		caddy.Log().Named("tls.connection_policy").Warn("trusted_leaf_certs is deprecated; use leaf verifier module instead")
		var trustedLeafCerts []*x509.Certificate
		for _, clientCertString := range clientauth.TrustedLeafCerts {
			clientCert, err := decodeBase64DERCert(clientCertString)
			if err != nil {
				return fmt.Errorf("parsing certificate: %v", err)
			}
			trustedLeafCerts = append(trustedLeafCerts, clientCert)
		}
		clientauth.verifiers = append(clientauth.verifiers, LeafCertClientAuth{trustedLeafCerts: trustedLeafCerts})
	}

	// if a custom verification function already exists, wrap it
	clientauth.existingVerifyPeerCert = cfg.VerifyPeerCertificate
	cfg.VerifyPeerCertificate = clientauth.verifyPeerCertificate
	return nil
}

Cognitive complexity: 26, Cyclomatic complexity: 17

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 (t *TLS) AddAutomationPolicy(ap *AutomationPolicy) error {
	if t.Automation == nil {
		t.Automation = new(AutomationConfig)
	}
	err := ap.Provision(t)
	if err != nil {
		return err
	}
	// sort new automation policies just before any other which is a superset
	// of this one; if we find an existing policy that covers every subject in
	// ap but less specifically (e.g. a catch-all policy, or one with wildcards
	// or with fewer subjects), insert ap just before it, otherwise ap would
	// never be used because the first matching policy is more general
	for i, existing := range t.Automation.Policies {
		// first see if existing is superset of ap for all names
		var otherIsSuperset bool
	outer:
		for _, thisSubj := range ap.subjects {
			for _, otherSubj := range existing.subjects {
				if certmagic.MatchWildcard(thisSubj, otherSubj) {
					otherIsSuperset = true
					break outer
				}
			}
		}
		// if existing AP is a superset or if it contains fewer names (i.e. is
		// more general), then new AP is more specific, so insert before it
		if otherIsSuperset || len(existing.SubjectsRaw) < len(ap.SubjectsRaw) {
			t.Automation.Policies = append(t.Automation.Policies[:i],
				append([]*AutomationPolicy{ap}, t.Automation.Policies[i:]...)...)
			return nil
		}
	}
	// otherwise just append the new one
	t.Automation.Policies = append(t.Automation.Policies, ap)
	return nil
}

Cognitive complexity: 18, Cyclomatic complexity: 9

Cleanup frees up resources allocated during Provision.

func (t *TLS) Cleanup() error {
	// stop the session ticket rotation goroutine
	if t.SessionTickets != nil {
		t.SessionTickets.stop()
	}

	// if a new TLS app was loaded, remove certificates from the cache that are no longer
	// being managed or loaded by the new config; if there is no more TLS app running,
	// then stop cert maintenance and let the cert cache be GC'ed
	if nextTLS, err := caddy.ActiveContext().AppIfConfigured("tls"); err == nil && nextTLS != nil {
		nextTLSApp := nextTLS.(*TLS)

		// compute which certificates were managed or loaded into the cert cache by this
		// app instance (which is being stopped) that are not managed or loaded by the
		// new app instance (which just started), and remove them from the cache
		var noLongerManaged []certmagic.SubjectIssuer
		var reManage, noLongerLoaded []string
		for subj, currentIssuerKey := range t.managing {
			// It's a bit nuanced: managed certs can sometimes be different enough that we have to
			// swap them out for a different one, even if they are for the same subject/domain.
			// We consider "private" certs (internal CA/locally-trusted/etc) to be significantly
			// distinct from "public" certs (production CAs/globally-trusted/etc) because of the
			// implications when it comes to actual deployments: switching between an internal CA
			// and a production CA, for example, is quite significant. Switching from one public CA
			// to another, however, is not, and for our purposes we consider those to be the same.
			// Anyway, if the next TLS app does not manage a cert for this name at all, definitely
			// remove it from the cache. But if it does, and it's not the same kind of issuer/CA
			// as we have, also remove it, so that it can swap it out for the right one.
			if nextIssuerKey, ok := nextTLSApp.managing[subj]; !ok || nextIssuerKey != currentIssuerKey {
				// next app is not managing a cert for this domain at all or is using a different issuer, so remove it
				noLongerManaged = append(noLongerManaged, certmagic.SubjectIssuer{Subject: subj, IssuerKey: currentIssuerKey})

				// then, if the next app is managing a cert for this name, but with a different issuer, re-manage it
				if ok && nextIssuerKey != currentIssuerKey {
					reManage = append(reManage, subj)
				}
			}
		}
		for hash := range t.loaded {
			if _, ok := nextTLSApp.loaded[hash]; !ok {
				noLongerLoaded = append(noLongerLoaded, hash)
			}
		}

		// remove the certs
		certCacheMu.RLock()
		certCache.RemoveManaged(noLongerManaged)
		certCache.Remove(noLongerLoaded)
		certCacheMu.RUnlock()

		// give the new TLS app a "kick" to manage certs that it is configured for
		// with its own configuration instead of the one we just evicted
		if err := nextTLSApp.Manage(reManage); err != nil {
			if c := t.logger.Check(zapcore.ErrorLevel, "re-managing unloaded certificates with new config"); c != nil {
				c.Write(
					zap.Strings("subjects", reManage),
					zap.Error(err),
				)
			}
		}
	} else {
		// no more TLS app running, so delete in-memory cert cache
		certCache.Stop()
		certCacheMu.Lock()
		certCache = nil
		certCacheMu.Unlock()
	}

	return nil
}

Cognitive complexity: 23, Cyclomatic complexity: 13

HandleHTTPChallenge ensures that the ACME HTTP challenge or ZeroSSL HTTP validation request 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 that implements GetACMEIssuer() or is a *ZeroSSLIssuer.

func (t *TLS) HandleHTTPChallenge(w http.ResponseWriter, r *http.Request) bool {
	acmeChallenge := certmagic.LooksLikeHTTPChallenge(r)
	zerosslValidation := certmagic.LooksLikeZeroSSLHTTPValidation(r)

	// no-op if it's not an ACME challenge request
	if !acmeChallenge && !zerosslValidation {
		return false
	}

	// try all the issuers until we find the one that initiated the challenge
	ap := t.getAutomationPolicyForName(r.Host)

	if acmeChallenge {
		type acmeCapable interface{ GetACMEIssuer() *ACMEIssuer }

		for _, iss := range ap.magic.Issuers {
			if acmeIssuer, ok := iss.(acmeCapable); ok {
				if acmeIssuer.GetACMEIssuer().issuer.HandleHTTPChallenge(w, r) {
					return true
				}
			}
		}

		// it's possible another server in this process initiated the challenge;
		// users have requested that Caddy only handle HTTP challenges it initiated,
		// so that users can proxy the others through to their backends; but we
		// might not have an automation policy for all identifiers that are trying
		// to get certificates (e.g. the admin endpoint), so we do this manual check
		if challenge, ok := certmagic.GetACMEChallenge(r.Host); ok {
			return certmagic.SolveHTTPChallenge(t.logger, w, r, challenge.Challenge)
		}
	} else if zerosslValidation {
		for _, iss := range ap.magic.Issuers {
			if ziss, ok := iss.(*ZeroSSLIssuer); ok {
				if ziss.issuer.HandleZeroSSLHTTPValidation(w, r) {
					return true
				}
			}
		}
	}

	return false
}

Cognitive complexity: 23, Cyclomatic complexity: 12

func (t *TLS) HasCertificateForSubject(subject string) bool {
	certCacheMu.RLock()
	allMatchingCerts := certCache.AllMatchingCertificates(subject)
	certCacheMu.RUnlock()
	for _, cert := range allMatchingCerts {
		// check if the cert is manually loaded by this config
		if _, ok := t.loaded[cert.Hash()]; ok {
			return true
		}
		// check if the cert is automatically managed by this config
		for _, name := range cert.Names {
			if _, ok := t.managing[name]; ok {
				return true
			}
		}
	}
	return false
}

Cognitive complexity: 10, Cyclomatic complexity: 5

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

func (t *TLS) Manage(names []string) error {
	// for a large number of names, we can be more memory-efficient
	// by making only one certmagic.Config for all the names that
	// use that config, rather than calling ManageAsync once for
	// every name; so first, bin names by AutomationPolicy
	policyToNames := make(map[*AutomationPolicy][]string)
	for _, name := range names {
		ap := t.getAutomationPolicyForName(name)
		policyToNames[ap] = append(policyToNames[ap], name)
	}

	// now that names are grouped by policy, we can simply make one
	// certmagic.Config for each (potentially large) group of names
	// and call ManageAsync just once for the whole batch
	for ap, names := range policyToNames {
		err := ap.magic.ManageAsync(t.ctx.Context, names)
		if err != nil {
			const maxNamesToDisplay = 100
			if len(names) > maxNamesToDisplay {
				names = append(names[:maxNamesToDisplay], fmt.Sprintf("(%d more...)", len(names)-maxNamesToDisplay))
			}
			return fmt.Errorf("automate: manage %v: %v", names, err)
		}
		for _, name := range names {
			// certs that are issued solely by our internal issuer are a little bit of
			// a special case: if you have an initial config that manages example.com
			// using internal CA, then after testing it you switch to a production CA,
			// you wouldn't want to keep using the same self-signed cert, obviously;
			// so we differentiate these by associating the subject with its issuer key;
			// we do this because CertMagic has no notion of "InternalIssuer" like we
			// do, so we have to do this logic ourselves
			var issuerKey string
			if len(ap.Issuers) == 1 {
				if intIss, ok := ap.Issuers[0].(*InternalIssuer); ok && intIss != nil {
					issuerKey = intIss.IssuerKey()
				}
			}
			t.managing[name] = issuerKey
		}
	}

	return nil
}

Cognitive complexity: 17, Cyclomatic complexity: 9

Start activates the TLS module.

func (t *TLS) Start() error {
	// warn if on-demand TLS is enabled but no restrictions are in place
	if t.Automation.OnDemand == nil || (t.Automation.OnDemand.Ask == "" && t.Automation.OnDemand.permission == nil) {
		for _, ap := range t.Automation.Policies {
			if ap.OnDemand && ap.isWildcardOrDefault() {
				if c := t.logger.Check(zapcore.WarnLevel, "YOUR SERVER MAY BE VULNERABLE TO ABUSE: on-demand TLS is enabled, but no protections are in place"); c != nil {
					c.Write(zap.String("docs", "https://caddyserver.com/docs/automatic-https#on-demand-tls"))
				}
				break
			}
		}
	}

	// now that we are running, and all manual certificates have
	// been loaded, time to load the automated/managed certificates
	err := t.Manage(t.automateNames)
	if err != nil {
		return fmt.Errorf("automate: managing %v: %v", t.automateNames, err)
	}

	if !t.DisableStorageClean {
		// start the storage cleaner goroutine and ticker,
		// which cleans out expired certificates and more
		t.keepStorageClean()
	}

	return nil
}

Cognitive complexity: 11, Cyclomatic complexity: 9

Stop stops the TLS module and cleans up any allocations.

func (t *TLS) Stop() error {
	// stop the storage cleaner goroutine and ticker
	if t.storageCleanStop != nil {
		close(t.storageCleanStop)
	}
	if t.storageCleanTicker != nil {
		t.storageCleanTicker.Stop()
	}
	return nil
}

Cognitive complexity: 4, Cyclomatic complexity: 3

func (bi *bigInt) UnmarshalJSON(p []byte) error {
	if string(p) == "null" {
		return nil
	}
	var stringRep string
	err := json.Unmarshal(p, &stringRep)
	if err != nil {
		return err
	}
	_, ok := bi.SetString(stringRep, 10)
	if !ok {
		return fmt.Errorf("not a valid big integer: %s", p)
	}
	return nil
}

Cognitive complexity: 6, Cyclomatic complexity: 4

CaddyModule returns the Caddy module information.

func (ACMEIssuer) CaddyModule() caddy.ModuleInfo {
	return caddy.ModuleInfo{
		ID:	"tls.issuance.acme",
		New:	func() caddy.Module { return new(ACMEIssuer) },
	}
}

Cognitive complexity: 2, Cyclomatic complexity: 1

Active returns true if clientauth has an actionable configuration.

func (clientauth ClientAuthentication) Active() bool {
	return len(clientauth.TrustedCACerts) > 0 ||
		len(clientauth.TrustedCACertPEMFiles) > 0 ||
		len(clientauth.TrustedLeafCerts) > 0 ||	// TODO: DEPRECATED
		len(clientauth.VerifiersRaw) > 0 ||
		len(clientauth.Mode) > 0 ||
		clientauth.CARaw != nil || clientauth.ca != nil
}

Cognitive complexity: 0, Cyclomatic complexity: 7

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

func (cp ConnectionPolicies) TLSConfig(_ caddy.Context) *tls.Config {
	// using ServerName to match policies is extremely common, especially in configs
	// with lots and lots of different policies; we can fast-track those by indexing
	// them by SNI, so we don't have to iterate potentially thousands of policies
	// (TODO: this map does not account for wildcards, see if this is a problem in practice? look for reports of high connection latency with wildcard certs but low latency for non-wildcards in multi-thousand-cert deployments)
	indexedBySNI := make(map[string]ConnectionPolicies)
	if len(cp) > 30 {
		for _, p := range cp {
			for _, m := range p.matchers {
				if sni, ok := m.(MatchServerName); ok {
					for _, sniName := range sni {
						indexedBySNI[sniName] = append(indexedBySNI[sniName], p)
					}
				}
			}
		}
	}

	return &tls.Config{
		MinVersion:	tls.VersionTLS12,
		GetConfigForClient: func(hello *tls.ClientHelloInfo) (*tls.Config, error) {
			// filter policies by SNI first, if possible, to speed things up
			// when there may be lots of policies
			possiblePolicies := cp
			if indexedPolicies, ok := indexedBySNI[hello.ServerName]; ok {
				possiblePolicies = indexedPolicies
			}

		policyLoop:
			for _, pol := range possiblePolicies {
				for _, matcher := range pol.matchers {
					if !matcher.Match(hello) {
						continue policyLoop
					}
				}
				if pol.Drop {
					return nil, fmt.Errorf("dropping connection")
				}
				return pol.TLSConfig, nil
			}

			return nil, fmt.Errorf("no server TLS configuration available for ClientHello: %+v", hello)
		},
	}
}

Cognitive complexity: 27, Cyclomatic complexity: 11

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

func (p ConnectionPolicy) SettingsEmpty() bool {
	return p.CertSelection == nil &&
		p.CipherSuites == nil &&
		p.Curves == nil &&
		p.ALPN == nil &&
		p.ProtocolMin == "" &&
		p.ProtocolMax == "" &&
		p.ClientAuthentication == nil &&
		p.DefaultSNI == "" &&
		p.InsecureSecretsLog == ""
}

Cognitive complexity: 0, Cyclomatic complexity: 9

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.

func (p CustomCertSelectionPolicy) SelectCertificate(hello *tls.ClientHelloInfo, choices []certmagic.Certificate) (certmagic.Certificate, error) {
	viable := make([]certmagic.Certificate, 0, len(choices))

nextChoice:
	for _, cert := range choices {
		if len(p.SerialNumber) > 0 {
			var found bool
			for _, sn := range p.SerialNumber {
				snInt := sn.Int	// avoid taking address of iteration variable (gosec warning)
				if cert.Leaf.SerialNumber.Cmp(&snInt) == 0 {
					found = true
					break
				}
			}
			if !found {
				continue
			}
		}

		if len(p.SubjectOrganization) > 0 {
			found := slices.ContainsFunc(p.SubjectOrganization, func(s string) bool {
				return slices.Contains(cert.Leaf.Subject.Organization, s)
			})
			if !found {
				continue
			}
		}

		if p.PublicKeyAlgorithm != PublicKeyAlgorithm(x509.UnknownPublicKeyAlgorithm) &&
			PublicKeyAlgorithm(cert.Leaf.PublicKeyAlgorithm) != p.PublicKeyAlgorithm {
			continue
		}

		if len(p.AnyTag) > 0 {
			var found bool
			for _, tag := range p.AnyTag {
				if cert.HasTag(tag) {
					found = true
					break
				}
			}
			if !found {
				continue
			}
		}

		if len(p.AllTags) > 0 {
			for _, tag := range p.AllTags {
				if !cert.HasTag(tag) {
					continue nextChoice
				}
			}
		}

		// this certificate at least meets the policy's requirements,
		// but we still have to check expiration and compatibility
		viable = append(viable, cert)
	}

	if len(viable) == 0 {
		return certmagic.Certificate{}, fmt.Errorf("no certificates matched custom selection policy")
	}

	return certmagic.DefaultCertificateSelector(hello, viable)
}

Cognitive complexity: 38, Cyclomatic complexity: 18

LoadCertificates returns the certificates to be loaded by fl.

func (fl FileLoader) LoadCertificates() ([]Certificate, error) {
	certs := make([]Certificate, 0, len(fl))
	for _, pair := range fl {
		certData, err := os.ReadFile(pair.Certificate)
		if err != nil {
			return nil, err
		}
		keyData, err := os.ReadFile(pair.Key)
		if err != nil {
			return nil, err
		}

		var cert tls.Certificate
		switch pair.Format {
		case "":
			fallthrough

		case "pem":
			// if the start of the key file looks like an encrypted private key,
			// reject it with a helpful error message
			if strings.Contains(string(keyData[:40]), "ENCRYPTED") {
				return nil, fmt.Errorf("encrypted private keys are not supported; please decrypt the key first")
			}

			cert, err = tls.X509KeyPair(certData, keyData)

		default:
			return nil, fmt.Errorf("unrecognized certificate/key encoding format: %s", pair.Format)
		}
		if err != nil {
			return nil, err
		}

		certs = append(certs, Certificate{Certificate: cert, Tags: pair.Tags})
	}
	return certs, nil
}

Cognitive complexity: 16, Cyclomatic complexity: 9

report error if the endpoints are not valid URLs

func (hcp HTTPCertPool) Validate() (err error) {
	for _, u := range hcp.Endpoints {
		_, e := url.Parse(u)
		if e != nil {
			err = errors.Join(err, e)
		}
	}
	return err
}

Cognitive complexity: 5, Cyclomatic complexity: 3

CertPool implements CA.

func (icp InlineCAPool) CertPool() *x509.CertPool {
	return icp.pool
}

Cognitive complexity: 0, Cyclomatic complexity: 1

func (l LeafCertClientAuth) VerifyClientCertificate(rawCerts [][]byte, _ [][]*x509.Certificate) error {
	if len(rawCerts) == 0 {
		return fmt.Errorf("no client certificate provided")
	}

	remoteLeafCert, err := x509.ParseCertificate(rawCerts[0])
	if err != nil {
		return fmt.Errorf("can't parse the given certificate: %s", err.Error())
	}

	for _, trustedLeafCert := range l.trustedLeafCerts {
		if remoteLeafCert.Equal(trustedLeafCert) {
			return nil
		}
	}

	return fmt.Errorf("client leaf certificate failed validation")
}

Cognitive complexity: 9, Cyclomatic complexity: 5

LoadLeafCertificates returns the certificates to be loaded by fl.

func (fl LeafFileLoader) LoadLeafCertificates() ([]*x509.Certificate, error) {
	certificates := make([]*x509.Certificate, 0, len(fl.Files))
	for _, path := range fl.Files {
		ders, err := convertPEMFilesToDERBytes(path)
		if err != nil {
			return nil, err
		}
		certs, err := x509.ParseCertificates(ders)
		if err != nil {
			return nil, err
		}
		certificates = append(certificates, certs...)
	}
	return certificates, nil
}

Cognitive complexity: 7, Cyclomatic complexity: 4

Match matches hello based on SNI.

func (m MatchServerName) Match(hello *tls.ClientHelloInfo) bool {
	repl := caddy.NewReplacer()
	// caddytls.TestServerNameMatcher calls this function without any context
	if ctx := hello.Context(); ctx != nil {
		// In some situations the existing context may have no replacer
		if replAny := ctx.Value(caddy.ReplacerCtxKey); replAny != nil {
			repl = replAny.(*caddy.Replacer)
		}
	}

	for _, name := range m {
		rs := repl.ReplaceAll(name, "")
		if certmagic.MatchWildcard(hello.ServerName, rs) {
			return true
		}
	}
	return false
}

Cognitive complexity: 9, Cyclomatic complexity: 5

func (p PermissionByHTTP) CertificateAllowed(ctx context.Context, name string) error {
	// run replacer on endpoint URL (for environment variables) -- return errors to prevent surprises (#5036)
	askEndpoint, err := p.replacer.ReplaceOrErr(p.Endpoint, true, true)
	if err != nil {
		return fmt.Errorf("preparing 'ask' endpoint: %v", err)
	}

	askURL, err := url.Parse(askEndpoint)
	if err != nil {
		return fmt.Errorf("parsing ask URL: %v", err)
	}
	qs := askURL.Query()
	qs.Set("domain", name)
	askURL.RawQuery = qs.Encode()
	askURLString := askURL.String()

	var remote string
	if chi, ok := ctx.Value(certmagic.ClientHelloInfoCtxKey).(*tls.ClientHelloInfo); ok && chi != nil {
		remote = chi.Conn.RemoteAddr().String()
	}

	if c := p.logger.Check(zapcore.DebugLevel, "asking permission endpoint"); c != nil {
		c.Write(
			zap.String("remote", remote),
			zap.String("domain", name),
			zap.String("url", askURLString),
		)
	}

	resp, err := onDemandAskClient.Get(askURLString)
	if err != nil {
		return fmt.Errorf("checking %v to determine if certificate for hostname '%s' should be allowed: %v",
			askEndpoint, name, err)
	}
	resp.Body.Close()

	if c := p.logger.Check(zapcore.DebugLevel, "response from permission endpoint"); c != nil {
		c.Write(
			zap.String("remote", remote),
			zap.String("domain", name),
			zap.String("url", askURLString),
			zap.Int("status", resp.StatusCode),
		)
	}

	if resp.StatusCode < 200 || resp.StatusCode > 299 {
		return fmt.Errorf("%s: %w %s - non-2xx status code %d", name, ErrPermissionDenied, askEndpoint, resp.StatusCode)
	}

	return nil
}

Cognitive complexity: 14, Cyclomatic complexity: 10

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

func (s SessionTicketService) RotateSTEKs(keys [][32]byte) ([][32]byte, error) {
	// produce a new key
	newKey, err := s.generateSTEK()
	if err != nil {
		return nil, fmt.Errorf("generating STEK: %v", err)
	}

	// we need to prepend this new key to the list of
	// keys so that it is preferred, but we need to be
	// careful that we do not grow the slice larger
	// than MaxKeys, otherwise we'll be storing one
	// more key in memory than we expect; so be sure
	// that the slice does not grow beyond the limit
	// even for a brief period of time, since there's
	// no guarantee when that extra allocation will
	// be overwritten; this is why we first trim the
	// length to one less the max, THEN prepend the
	// new key
	if len(keys) >= s.MaxKeys {
		keys[len(keys)-1] = [32]byte{}	// zero-out memory of oldest key
		keys = keys[:s.MaxKeys-1]	// trim length of slice
	}
	keys = append([][32]byte{newKey}, keys...)	// prepend new key

	return keys, nil
}

Cognitive complexity: 6, Cyclomatic complexity: 3

func (ts Tailscale) GetCertificate(ctx context.Context, hello *tls.ClientHelloInfo) (*tls.Certificate, error) {
	canGetCert, err := ts.canHazCertificate(ctx, hello)
	if err == nil && !canGetCert {
		return nil, nil	// pass-thru: Tailscale can't offer a cert for this name
	}
	if err != nil {
		if c := ts.logger.Check(zapcore.WarnLevel, "could not get status; will try to get certificate anyway"); c != nil {
			c.Write(zap.Error(err))
		}
	}
	return tscert.GetCertificateWithContext(ctx, hello)
}

Cognitive complexity: 6, Cyclomatic complexity: 5

func (bi bigInt) MarshalJSON() ([]byte, error) {
	return json.Marshal(bi.String())
}

Cognitive complexity: 0, Cyclomatic complexity: 1

func (d customCertLifetime) Modify(cert *x509.Certificate, _ provisioner.SignOptions) error {
	cert.NotBefore = time.Now()
	cert.NotAfter = cert.NotBefore.Add(time.Duration(d))
	return nil
}

Cognitive complexity: 0, Cyclomatic complexity: 1

func (d destructableWriter) Destruct() error	{ return d.Close() }

Cognitive complexity: 0, Cyclomatic complexity: 1

This type doesn't have documentation.

type testAddr string

This type doesn't have documentation.

type testConn struct {
	*net.TCPConn
	addr	testAddr
}