caddytls

package
v2.8.0-beta.2 Latest Latest
Warning

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

 Go to latest Published: May 7, 2024 License: Apache-2.0 Imports: 38 Imported by: 55

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var ErrPermissionDenied = errors.New("certificate not allowed by permission module")

ErrPermissionDenied is an error that should be wrapped or returned when the configured permission module does not allow a certificate to be issued, to distinguish that from other errors such as connection failure.

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(userEmail string) []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"`

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

	// 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:"-"`
	// 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) AllInternalSubjects added in v2.8.0 

func (ap *AutomationPolicy) AllInternalSubjects() bool

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

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 CA added in v2.8.0 

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

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

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

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

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

func (*ClientAuthentication) UnmarshalCaddyfile added in v2.8.0 

func (ca *ClientAuthentication) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

UnmarshalCaddyfile parses the Caddyfile segment to set up the client authentication. Syntax: 

client_auth {
	mode                   [request|require|verify_if_given|require_and_verify]
 	trust_pool			   <module> {
		...
	}
	trusted_leaf_cert      <base64_der>
	trusted_leaf_cert_file <filename>
	verifier               <module>
}

If `mode` is not provided, it defaults to `require_and_verify` if any of the following are provided: - `trusted_leaf_certs` - `trusted_leaf_cert_file` - `trust_pool`

Otherwise, it defaults to `require`.

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

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

	// 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.
	// 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"`
	// contains filtered or unexported fields
}

DNSChallengeConfig configures the ACME DNS challenge.

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

type FileCAPool added in v2.8.0 

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"`
	// contains filtered or unexported fields
}

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

func (FileCAPool) CaddyModule added in v2.8.0 

func (FileCAPool) CaddyModule() caddy.ModuleInfo

CaddyModule implements caddy.Module.

func (FileCAPool) CertPool added in v2.8.0 

func (f FileCAPool) CertPool() *x509.CertPool

func (*FileCAPool) Provision added in v2.8.0 

func (f *FileCAPool) Provision(ctx caddy.Context) error

Loads and decodes the DER and pem files to generate the certificate pool

func (*FileCAPool) UnmarshalCaddyfile added in v2.8.0 

func (fcap *FileCAPool) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

Syntax: 

trust_pool file [<pem_file>...] {
	pem_file <pem_file>...
}

The 'pem_file' directive can be specified multiple times.

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.
	//
	// 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"`
	// 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 HTTPCertPool added in v2.8.0 

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"`
	// contains filtered or unexported fields
}

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.

func (HTTPCertPool) CaddyModule added in v2.8.0 

func (HTTPCertPool) CaddyModule() caddy.ModuleInfo

CaddyModule implements caddy.Module.

func (HTTPCertPool) CertPool added in v2.8.0 

func (hcp HTTPCertPool) CertPool() *x509.CertPool

CertPool return the certificate pool generated from the HTTP responses

func (*HTTPCertPool) Provision added in v2.8.0 

func (hcp *HTTPCertPool) Provision(ctx caddy.Context) error

Provision implements caddy.Provisioner.

func (*HTTPCertPool) UnmarshalCaddyfile added in v2.8.0 

func (hcp *HTTPCertPool) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

Syntax: 

trust_pool http [<endpoints...>] {
		endpoints 	<endpoints...>
		tls 		<tls_config>
}

tls_config: 

	ca <ca_module>
	insecure_skip_verify
	handshake_timeout <duration>
	server_name <name>
	renegotiation <never|once|freely>

<ca_module> is the name of the CA module to source the trust

certificate pool and follows the syntax of the named CA module.

func (HTTPCertPool) Validate added in v2.8.0 

func (hcp HTTPCertPool) Validate() (err error)

report error if the endpoints are not valid URLs

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 InlineCAPool added in v2.8.0 

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"`
	// contains filtered or unexported fields
}

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

func (InlineCAPool) CaddyModule added in v2.8.0 

func (icp InlineCAPool) CaddyModule() caddy.ModuleInfo

CaddyModule implements caddy.Module.

func (InlineCAPool) CertPool added in v2.8.0 

func (icp InlineCAPool) CertPool() *x509.CertPool

CertPool implements CA.

func (*InlineCAPool) Provision added in v2.8.0 

func (icp *InlineCAPool) Provision(ctx caddy.Context) error

Provision implements caddy.Provisioner.

func (*InlineCAPool) UnmarshalCaddyfile added in v2.8.0 

func (icp *InlineCAPool) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

Syntax: 

trust_pool inline {
	trust_der <base64_der_cert>...
}

The 'trust_der' directive can be specified multiple times.

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 LazyCertPool 

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

	// Whether the validation step should try to load and provision the guest module to validate
	// the correctness of the configuration. Depeneding on the type of the guest module,
	// the resources may not be available at validation time. It is the
	// operator's responsibility to ensure the resources are available if `EagerValidation`/`eager_validation`
	// is set to `true`.
	EagerValidation bool `json:"eager_validation,omitempty"`
	// contains filtered or unexported fields
}

LazyCertPool defers the generation of the certificate pool from the guest module to demand-time rather than at provisionig time. The gain of the lazy load adds a risk of failure to load the certificates at demand time because the validation that's typically done at provisioning is deferred. The validation can be enforced to run before runtime by setting `EagerValidation`/`eager_validation` to `true`. It is the operator's responsibility to ensure the resources are available if `EagerValidation`/`eager_validation` is set to `true`. The module also incurs performance cost at every demand.

func (LazyCertPool) CaddyModule 

func (LazyCertPool) CaddyModule() caddy.ModuleInfo

CaddyModule implements caddy.Module.

func (LazyCertPool) CertPool 

func (lcp LazyCertPool) CertPool() *x509.CertPool

CertPool loads the guest module and returns the CertPool from there TODO: Cache?

func (*LazyCertPool) Provision 

func (lcp *LazyCertPool) Provision(ctx caddy.Context) error

Provision implements caddy.Provisioner.

func (*LazyCertPool) UnmarshalCaddyfile 

func (lcp *LazyCertPool) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

Syntax: 

trust_pool lazy {
	backend <ca_module>
	eager_validation
}

The `backend` directive specifies the CA module to use to provision the certificate pool. The `eager_validation` directive specifies that the validation step should try to load and provision the guest module to validate the correctness of the configuration. Depeneding on the type of the guest module, the resources may not be available at validation time. It is the operator's responsibility to ensure the resources are available if `EagerValidation`/`eager_validation` is set to `true`.

The `backend` directive is required.

func (LazyCertPool) Validate 

func (lcp LazyCertPool) Validate() error

If EagerValidation is `true`, it attempts to load and provision the guest module to ensure the guesst module's configuration is correct. Depeneding on the type of the guest module, the resources may not be available at validation time. It is the operator's responsibility to ensure the resources are available if `EagerValidation` is set to `true`.

type LeafCertClientAuth added in v2.5.2 

type LeafCertClientAuth struct {
	LeafCertificateLoadersRaw []json.RawMessage `json:"leaf_certs_loaders,omitempty" caddy:"namespace=tls.leaf_cert_loader inline_key=loader"`
	// contains filtered or unexported fields
}

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) Provision added in v2.8.0 

func (l *LeafCertClientAuth) Provision(ctx caddy.Context) error

func (LeafCertClientAuth) VerifyClientCertificate added in v2.5.2 

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

type LeafCertificateLoader added in v2.8.0 

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

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

type LeafFileLoader added in v2.8.0 

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

LeafFileLoader loads leaf certificates from disk.

func (LeafFileLoader) CaddyModule added in v2.8.0 

func (LeafFileLoader) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (LeafFileLoader) LoadLeafCertificates added in v2.8.0 

func (fl LeafFileLoader) LoadLeafCertificates() ([]*x509.Certificate, error)

LoadLeafCertificates returns the certificates to be loaded by fl.

func (*LeafFileLoader) Provision added in v2.8.0 

func (fl *LeafFileLoader) Provision(ctx caddy.Context) error

Provision implements caddy.Provisioner.

type LeafFolderLoader added in v2.8.0 

type LeafFolderLoader struct {
	Folders []string `json:"folders,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.

func (LeafFolderLoader) CaddyModule added in v2.8.0 

func (LeafFolderLoader) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (LeafFolderLoader) LoadLeafCertificates added in v2.8.0 

func (fl LeafFolderLoader) LoadLeafCertificates() ([]*x509.Certificate, error)

LoadLeafCertificates loads all the leaf certificates in the directories listed in fl from all files ending with .pem.

func (*LeafFolderLoader) Provision added in v2.8.0 

func (fl *LeafFolderLoader) Provision(ctx caddy.Context) error

Provision implements caddy.Provisioner.

type LeafPEMLoader added in v2.8.0 

type LeafPEMLoader struct {
	Certificates []string `json:"certificates,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.

func (LeafPEMLoader) CaddyModule added in v2.8.0 

func (LeafPEMLoader) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (LeafPEMLoader) LoadLeafCertificates added in v2.8.0 

func (pl LeafPEMLoader) LoadLeafCertificates() ([]*x509.Certificate, error)

LoadLeafCertificates returns the certificates contained in pl.

func (*LeafPEMLoader) Provision added in v2.8.0 

func (pl *LeafPEMLoader) Provision(ctx caddy.Context) error

Provision implements caddy.Provisioner.

type LeafStorageLoader added in v2.8.0 

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"`
	// contains filtered or unexported fields
}

LeafStorageLoader loads leaf certificates from the globally configured storage module.

func (LeafStorageLoader) CaddyModule added in v2.8.0 

func (LeafStorageLoader) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (LeafStorageLoader) LoadLeafCertificates added in v2.8.0 

func (sl LeafStorageLoader) LoadLeafCertificates() ([]*x509.Certificate, error)

LoadLeafCertificates returns the certificates to be loaded by sl.

func (*LeafStorageLoader) Provision added in v2.8.0 

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

Provision loads the storage module for sl.

type MatchLocalIP added in v2.8.0 

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

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

func (MatchLocalIP) CaddyModule added in v2.8.0 

func (MatchLocalIP) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (MatchLocalIP) Match added in v2.8.0 

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

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

func (*MatchLocalIP) Provision added in v2.8.0 

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

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

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 {
	// DEPRECATED. WILL BE REMOVED SOON. Use 'permission' instead.
	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"`

	// 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"`
	// contains filtered or unexported fields
}

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 OnDemandPermission added in v2.8.0 

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
}

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 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 PKIIntermediateCAPool added in v2.8.0 

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"`
	// contains filtered or unexported fields
}

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

func (PKIIntermediateCAPool) CaddyModule added in v2.8.0 

func (PKIIntermediateCAPool) CaddyModule() caddy.ModuleInfo

CaddyModule implements caddy.Module.

func (PKIIntermediateCAPool) CertPool added in v2.8.0 

func (p PKIIntermediateCAPool) CertPool() *x509.CertPool

return the certificate pool generated with intermediate certificates from the PKI app

func (*PKIIntermediateCAPool) Provision added in v2.8.0 

func (p *PKIIntermediateCAPool) Provision(ctx caddy.Context) error

Loads the PKI app and load the intermediate certificates into the certificate pool

func (*PKIIntermediateCAPool) UnmarshalCaddyfile added in v2.8.0 

func (pic *PKIIntermediateCAPool) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

Syntax: 

trust_pool pki_intermediate [<ca_name>...] {
	authority <ca_name>...
}

The 'authority' directive can be specified multiple times.

type PKIRootCAPool added in v2.8.0 

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"`
	// contains filtered or unexported fields
}

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

func (PKIRootCAPool) CaddyModule added in v2.8.0 

func (PKIRootCAPool) CaddyModule() caddy.ModuleInfo

CaddyModule implements caddy.Module.

func (PKIRootCAPool) CertPool added in v2.8.0 

func (p PKIRootCAPool) CertPool() *x509.CertPool

return the certificate pool generated with root certificates from the PKI app

func (*PKIRootCAPool) Provision added in v2.8.0 

func (p *PKIRootCAPool) Provision(ctx caddy.Context) error

Loads the PKI app and load the root certificates into the certificate pool

func (*PKIRootCAPool) UnmarshalCaddyfile added in v2.8.0 

func (pkir *PKIRootCAPool) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

Syntax: 

trust_pool pki_root [<ca_name>...] {
	authority <ca_name>...
}

The 'authority' directive can be specified multiple times.

type PermissionByHTTP added in v2.8.0 

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"`
	// contains filtered or unexported fields
}

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

func (PermissionByHTTP) CaddyModule added in v2.8.0 

func (PermissionByHTTP) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (PermissionByHTTP) CertificateAllowed added in v2.8.0 

func (p PermissionByHTTP) CertificateAllowed(ctx context.Context, name string) error

func (*PermissionByHTTP) Provision added in v2.8.0 

func (p *PermissionByHTTP) Provision(ctx caddy.Context) error

func (*PermissionByHTTP) UnmarshalCaddyfile added in v2.8.0 

func (p *PermissionByHTTP) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

UnmarshalCaddyfile implements caddyfile.Unmarshaler.

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. WILL LIKELY BE REMOVED SOON. Instead of using this rate limiter, use a proper tool such as a level 3 or 4 firewall and/or a permission module to apply rate limits.

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 StoragePool added in v2.8.0 

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"`
	// contains filtered or unexported fields
}

StoragePool extracts the trusted certificates root from Caddy storage

func (StoragePool) CaddyModule added in v2.8.0 

func (StoragePool) CaddyModule() caddy.ModuleInfo

CaddyModule implements caddy.Module.

func (StoragePool) CertPool added in v2.8.0 

func (p StoragePool) CertPool() *x509.CertPool

func (*StoragePool) Provision added in v2.8.0 

func (ca *StoragePool) Provision(ctx caddy.Context) error

Provision implements caddy.Provisioner.

func (*StoragePool) UnmarshalCaddyfile added in v2.8.0 

func (sp *StoragePool) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

Syntax: 

trust_pool storage [<storage_keys>...] {
	storage <storage_module>
	keys	<storage_keys>...
}

The 'keys' directive can be specified multiple times. The'storage' directive is optional and defaults to the default storage module.

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 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 (*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 TLSConfig added in v2.8.0 

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

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

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 {
	// 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"`
	// contains filtered or unexported fields
}

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.

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) Provision added in v2.2.0 

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

Provision sets up the issuer.

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> {
	    validity_days <days>
	    alt_http_port <port>
	    dns <provider_name> ...
	    propagation_delay <duration>
	    propagation_timeout <duration>
	    resolvers <list...>
	    dns_ttl <duration>
}

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.