kenginetls

package
v1.0.4 Latest Latest
Warning

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

 Go to latest Published: Sep 29, 2024 License: Apache-2.0 Imports: 42 Imported by: 0

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 

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 

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 

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

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

func ParseKenginefileNestedMatcherSet 

func ParseKenginefileNestedMatcherSet(d *kenginefile.Dispenser) (kengine.ModuleMap, error)

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

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 Kengine 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 Kengine 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 kengine.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 kengine.Duration `json:"certificate_lifetime,omitempty"`
	// contains filtered or unexported fields
}

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

func (*ACMEIssuer) GetACMEIssuer 

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

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

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

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

func (ACMEIssuer) KengineModule() kengine.ModuleInfo

KengineModule returns the Kengine module information.

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

func (iss *ACMEIssuer) UnmarshalKenginefile(d *kenginefile.Dispenser) error

UnmarshalKenginefile deserializes Kenginefile 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) KengineModule 

func (AutomateLoader) KengineModule() kengine.ModuleInfo

KengineModule returns the Kengine 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, Kengine 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"`

	// Kengine 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 kengine.Duration `json:"ocsp_interval,omitempty"`

	// Every so often, Kengine will scan all loaded, managed
	// certificates for expiration. This setting changes how
	// frequently the scan for expiring certificates is
	// performed. Default: 10m
	RenewCheckInterval kengine.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 kengine.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 Kengine 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" kengine:"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 Kengine 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" kengine:"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 Kengine's global/default-configured storage.
	StorageRaw json.RawMessage `json:"storage,omitempty" kengine:"namespace=kengine.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 

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 

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 

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 

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 ParseKenginefilePreferredChainsOptions 

func ParseKenginefilePreferredChainsOptions(d *kenginefile.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 Kengine 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" kengine:"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" kengine:"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) UnmarshalKenginefile 

func (ca *ClientAuthentication) UnmarshalKenginefile(d *kenginefile.Dispenser) error

UnmarshalKenginefile parses the Kenginefile 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 

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 kengine.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(_ kengine.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 kengine.ModuleMap `json:"match,omitempty" kengine:"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. Kengine's
	// defaults are modern and secure.
	CipherSuites []string `json:"cipher_suites,omitempty"`

	// The list of elliptic curves to support. Kengine'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
	// Kengine 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 

func (p ConnectionPolicy) SettingsEmpty() bool

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

func (*ConnectionPolicy) UnmarshalKenginefile 

func (cp *ConnectionPolicy) UnmarshalKenginefile(d *kenginefile.Dispenser) error

UnmarshalKenginefile sets up the ConnectionPolicy from Kenginefile tokens. Syntax: 

connection_policy {
	alpn                  <values...>
	cert_selection {
		...
	}
	ciphers               <cipher_suites...>
	client_auth {
		...
	}
	curves                <curves...>
	default_sni           <server_name>
	match {
		...
	}
	protocols             <min> [<max>]
	# EXPERIMENTAL:
	drop
	fallback_sni          <server_name>
	insecure_secrets_log  <log_file>
}

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

func (*CustomCertSelectionPolicy) UnmarshalKenginefile 

func (p *CustomCertSelectionPolicy) UnmarshalKenginefile(d *kenginefile.Dispenser) error

UnmarshalKenginefile sets up the CustomCertSelectionPolicy from Kenginefile tokens. Syntax: 

cert_selection {
	all_tags             <values...>
	any_tag              <values...>
	public_key_algorithm <dsa|ecdsa|rsa>
	serial_number        <big_integers...>
	subject_organization <values...>
}

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" kengine:"namespace=dns.providers inline_key=name"`

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

	// How long to wait before starting propagation checks.
	// Default: 0 (no wait).
	PropagationDelay kengine.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 kengine.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 

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

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

func (FileCAPool) KengineModule 

func (FileCAPool) KengineModule() kengine.ModuleInfo

KengineModule implements kengine.Module.

func (*FileCAPool) Provision 

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

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

func (*FileCAPool) UnmarshalKenginefile 

func (fcap *FileCAPool) UnmarshalKenginefile(d *kenginefile.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) KengineModule 

func (FileLoader) KengineModule() kengine.ModuleInfo

KengineModule returns the Kengine module information.

func (FileLoader) LoadCertificates 

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

LoadCertificates returns the certificates to be loaded by fl.

func (FileLoader) Provision 

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

Provision implements kengine.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) KengineModule 

func (FolderLoader) KengineModule() kengine.ModuleInfo

KengineModule returns the Kengine 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 

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

Provision implements kengine.Provisioner.

type HTTPCertGetter 

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

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

func (HTTPCertGetter) KengineModule 

func (hcg HTTPCertGetter) KengineModule() kengine.ModuleInfo

KengineModule returns the Kengine module information.

func (*HTTPCertGetter) Provision 

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

func (*HTTPCertGetter) UnmarshalKenginefile 

func (hcg *HTTPCertGetter) UnmarshalKenginefile(d *kenginefile.Dispenser) error

UnmarshalKenginefile deserializes Kenginefile tokens into ts. 

... http <url>

type HTTPCertPool 

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 Kengine instance that is running the PKI app and ACME server.

func (HTTPCertPool) CertPool 

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

CertPool return the certificate pool generated from the HTTP responses

func (HTTPCertPool) KengineModule 

func (HTTPCertPool) KengineModule() kengine.ModuleInfo

KengineModule implements kengine.Module.

func (*HTTPCertPool) Provision 

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

Provision implements kengine.Provisioner.

func (*HTTPCertPool) UnmarshalKenginefile 

func (hcp *HTTPCertPool) UnmarshalKenginefile(d *kenginefile.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 

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 

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

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

CertPool implements CA.

func (InlineCAPool) KengineModule 

func (icp InlineCAPool) KengineModule() kengine.ModuleInfo

KengineModule implements kengine.Module.

func (*InlineCAPool) Provision 

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

Provision implements kengine.Provisioner.

func (*InlineCAPool) UnmarshalKenginefile 

func (icp *InlineCAPool) UnmarshalKenginefile(d *kenginefile.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 kengine.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) 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 configured CA endpoint.

func (InternalIssuer) KengineModule 

func (InternalIssuer) KengineModule() kengine.ModuleInfo

KengineModule returns the Kengine module information.

func (*InternalIssuer) Provision 

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

Provision sets up the issuer.

func (*InternalIssuer) UnmarshalKenginefile 

func (iss *InternalIssuer) UnmarshalKenginefile(d *kenginefile.Dispenser) error

UnmarshalKenginefile deserializes Kenginefile tokens into iss. 

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

type LeafCertClientAuth 

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

LeafCertClientAuth verifies the client's leaf certificate.

func (LeafCertClientAuth) KengineModule 

func (LeafCertClientAuth) KengineModule() kengine.ModuleInfo

KengineModule returns the Kengine module information.

func (*LeafCertClientAuth) Provision 

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

func (LeafCertClientAuth) VerifyClientCertificate 

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

type LeafCertificateLoader 

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 

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

LeafFileLoader loads leaf certificates from disk.

func (LeafFileLoader) KengineModule 

func (LeafFileLoader) KengineModule() kengine.ModuleInfo

KengineModule returns the Kengine module information.

func (LeafFileLoader) LoadLeafCertificates 

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

LoadLeafCertificates returns the certificates to be loaded by fl.

func (*LeafFileLoader) Provision 

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

Provision implements kengine.Provisioner.

type LeafFolderLoader 

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

func (LeafFolderLoader) KengineModule() kengine.ModuleInfo

KengineModule returns the Kengine module information.

func (LeafFolderLoader) LoadLeafCertificates 

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 

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

Provision implements kengine.Provisioner.

type LeafPEMLoader 

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

func (LeafPEMLoader) KengineModule() kengine.ModuleInfo

KengineModule returns the Kengine module information.

func (LeafPEMLoader) LoadLeafCertificates 

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

LoadLeafCertificates returns the certificates contained in pl.

func (*LeafPEMLoader) Provision 

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

Provision implements kengine.Provisioner.

type LeafStorageLoader 

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 Kengine default storage.
	StorageRaw json.RawMessage `json:"storage,omitempty" kengine:"namespace=kengine.storage inline_key=module"`
	// contains filtered or unexported fields
}

LeafStorageLoader loads leaf certificates from the globally configured storage module.

func (LeafStorageLoader) KengineModule 

func (LeafStorageLoader) KengineModule() kengine.ModuleInfo

KengineModule returns the Kengine module information.

func (LeafStorageLoader) LoadLeafCertificates 

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

LoadLeafCertificates returns the certificates to be loaded by sl.

func (*LeafStorageLoader) Provision 

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

Provision loads the storage module for sl.

type MatchLocalIP 

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

func (MatchLocalIP) KengineModule() kengine.ModuleInfo

KengineModule returns the Kengine module information.

func (MatchLocalIP) Match 

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

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

func (*MatchLocalIP) Provision 

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

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

func (*MatchLocalIP) UnmarshalKenginefile 

func (m *MatchLocalIP) UnmarshalKenginefile(d *kenginefile.Dispenser) error

UnmarshalKenginefile sets up the MatchLocalIP from Kenginefile tokens. Syntax: 

local_ip <ranges...>

type MatchRegexp 

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

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 kenginehttp.MatchRegexp with a local replacer prefix and placeholders support in a regular expression pattern.

func (*MatchRegexp) Match 

func (mre *MatchRegexp) Match(input string, repl *kengine.Replacer) bool

Match returns true if input matches the compiled regular expression in m. It sets values on the replacer repl associated with capture groups, using the given scope (namespace).

func (*MatchRegexp) Provision 

func (mre *MatchRegexp) Provision(kengine.Context) error

Provision compiles the regular expression which may include placeholders.

func (*MatchRegexp) UnmarshalKenginefile 

func (mre *MatchRegexp) UnmarshalKenginefile(d *kenginefile.Dispenser) error

UnmarshalKenginefile implements kenginefile.Unmarshaler.

func (*MatchRegexp) Validate 

func (mre *MatchRegexp) Validate() error

Validate ensures mre is set up correctly.

type MatchRemoteIP 

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

func (MatchRemoteIP) KengineModule() kengine.ModuleInfo

KengineModule returns the Kengine module information.

func (MatchRemoteIP) Match 

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

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

func (*MatchRemoteIP) Provision 

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

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

func (*MatchRemoteIP) UnmarshalKenginefile 

func (m *MatchRemoteIP) UnmarshalKenginefile(d *kenginefile.Dispenser) error

UnmarshalKenginefile sets up the MatchRemoteIP from Kenginefile tokens. Syntax: 

remote_ip <ranges...>

Note: IPs and CIDRs prefixed with ! symbol are treated as not_ranges

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

func (MatchServerName) KengineModule() kengine.ModuleInfo

KengineModule returns the Kengine module information.

func (MatchServerName) Match 

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

Match matches hello based on SNI.

func (*MatchServerName) UnmarshalKenginefile 

func (m *MatchServerName) UnmarshalKenginefile(d *kenginefile.Dispenser) error

UnmarshalKenginefile sets up the MatchServerName from Kenginefile tokens. Syntax: 

sni <domains...>

type MatchServerNameRE 

type MatchServerNameRE struct{ MatchRegexp }

MatchServerNameRE matches based on SNI using a regular expression.

func (MatchServerNameRE) KengineModule 

func (MatchServerNameRE) KengineModule() kengine.ModuleInfo

KengineModule returns the Kengine module information.

func (MatchServerNameRE) Match 

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

Match matches hello based on SNI using a regular expression.

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" kengine:"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 Kengine can "ask" if it should be allowed to manage certificates for a given hostname.

type OnDemandPermission 

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

func (PEMLoader) KengineModule() kengine.ModuleInfo

KengineModule returns the Kengine module information.

func (PEMLoader) LoadCertificates 

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

LoadCertificates returns the certificates contained in pl.

func (PEMLoader) Provision 

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

Provision implements kengine.Provisioner.

type PKIIntermediateCAPool 

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 Kengine's native 'pki' app

func (PKIIntermediateCAPool) CertPool 

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

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

func (PKIIntermediateCAPool) KengineModule 

func (PKIIntermediateCAPool) KengineModule() kengine.ModuleInfo

KengineModule implements kengine.Module.

func (*PKIIntermediateCAPool) Provision 

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

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

func (*PKIIntermediateCAPool) UnmarshalKenginefile 

func (pic *PKIIntermediateCAPool) UnmarshalKenginefile(d *kenginefile.Dispenser) error

Syntax: 

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

The 'authority' directive can be specified multiple times.

type PKIRootCAPool 

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 Kengine's native 'pki' app

func (PKIRootCAPool) CertPool 

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

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

func (PKIRootCAPool) KengineModule 

func (PKIRootCAPool) KengineModule() kengine.ModuleInfo

KengineModule implements kengine.Module.

func (*PKIRootCAPool) Provision 

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

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

func (*PKIRootCAPool) UnmarshalKenginefile 

func (pkir *PKIRootCAPool) UnmarshalKenginefile(d *kenginefile.Dispenser) error

Syntax: 

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

The 'authority' directive can be specified multiple times.

type PermissionByHTTP 

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

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

func (PermissionByHTTP) KengineModule 

func (PermissionByHTTP) KengineModule() kengine.ModuleInfo

KengineModule returns the Kengine module information.

func (*PermissionByHTTP) Provision 

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

func (*PermissionByHTTP) UnmarshalKenginefile 

func (p *PermissionByHTTP) UnmarshalKenginefile(d *kenginefile.Dispenser) error

UnmarshalKenginefile implements kenginefile.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 kengine.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 Kengine produces or obtains
	// TLS session ticket keys (STEKs). By default, Kengine generates
	// them internally using a secure pseudorandom source.
	KeySource json.RawMessage `json:"key_source,omitempty" kengine:"namespace=tls.stek inline_key=provider"`

	// How often Kengine rotates STEKs. Default: 12h.
	RotationInterval kengine.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 

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

func (StorageLoader) KengineModule() kengine.ModuleInfo

KengineModule returns the Kengine module information.

func (StorageLoader) LoadCertificates 

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

LoadCertificates returns the certificates to be loaded by sl.

func (*StorageLoader) Provision 

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

Provision loads the storage module for sl.

type StoragePool 

type StoragePool struct {
	// The storage module where the trusted root certificates are stored. Absent
	// explicit storage implies the use of Kengine default storage.
	StorageRaw json.RawMessage `json:"storage,omitempty" kengine:"namespace=kengine.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 Kengine storage

func (StoragePool) CertPool 

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

func (StoragePool) KengineModule 

func (StoragePool) KengineModule() kengine.ModuleInfo

KengineModule implements kengine.Module.

func (*StoragePool) Provision 

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

Provision implements kengine.Provisioner.

func (*StoragePool) UnmarshalKenginefile 

func (sp *StoragePool) UnmarshalKenginefile(d *kenginefile.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 kengine.ModuleMap `json:"certificates,omitempty" kengine:"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"`
	// 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) 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 

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

func (TLS) KengineModule 

func (TLS) KengineModule() kengine.ModuleInfo

KengineModule returns the Kengine module information.

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

type TLSConfig struct {
	// Provides the guest module that provides the trusted certificate authority (CA) certificates
	CARaw json.RawMessage `json:"ca,omitempty" kengine:"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 kengine.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/kenginehttp/reverseproxy/httptransport.go

type Tailscale 

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

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

func (Tailscale) GetCertificate 

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

func (Tailscale) KengineModule 

func (Tailscale) KengineModule() kengine.ModuleInfo

KengineModule returns the Kengine module information.

func (*Tailscale) Provision 

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

func (Tailscale) UnmarshalKenginefile 

func (Tailscale) UnmarshalKenginefile(d *kenginefile.Dispenser) error

UnmarshalKenginefile deserializes Kenginefile tokens into ts. 

... tailscale

type ZeroSSLIssuer 

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

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

Issue obtains a certificate for the given csr.

func (*ZeroSSLIssuer) IssuerKey 

func (iss *ZeroSSLIssuer) IssuerKey() string

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

func (*ZeroSSLIssuer) KengineModule 

func (*ZeroSSLIssuer) KengineModule() kengine.ModuleInfo

KengineModule returns the Kengine module information.

func (*ZeroSSLIssuer) Provision 

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

Provision sets up the issuer.

func (*ZeroSSLIssuer) Revoke 

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

Revoke revokes the given certificate.

func (*ZeroSSLIssuer) UnmarshalKenginefile 

func (iss *ZeroSSLIssuer) UnmarshalKenginefile(d *kenginefile.Dispenser) error

UnmarshalKenginefile deserializes Kenginefile 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.