kenginetls

package
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Sep 29, 2024 License: MIT Imports: 5 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

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.

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

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; othewise acme and
	// zerossl.
	// TODO: type this
	Issuers []any `json:"issuers,omitempty"`

	// 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`.
	//
	// This is an EXPERIMENTAL feature. Subject to change or removal.
	// TODO: type this
	Managers []any `json:"get_certificate,omitempty"`

	// 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.
	// TODO: type this
	Storage any `json:"storage,omitempty"`

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

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

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

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

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

type CA 

type CA interface {
	IAmACA()
}

CA . TODO: document

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 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 Certificates 

type Certificates struct {
	// Automate .
	// TODO: document
	Automate AutomateLoader `json:"automate,omitempty"`

	// LoadPEM 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.
	LoadPEM []CertKeyPEMPair `json:"load_pem,omitempty"`
}

Certificates . TODO: document

type ClientAuthentication 

type ClientAuthentication struct {
	// 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.
	Verifiers []Verifier `json:"verifiers,omitempty"`

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

ClientAuthentication configures TLS client auth.

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.

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.
	// TODO: type this
	Matchers kengine.ModuleMap `json:"match,omitempty"`

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

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

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

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.

type FileCAPool 

type FileCAPool struct {
	// Provider is the name of this provider for the JSON config.
	// DO NOT USE this. This is a special value to represent this provider.
	// It will be overwritten when we are marshalled.
	Provider FileCAPoolProvider `json:"provider"`

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

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

func (FileCAPool) IAmACA 

func (FileCAPool) IAmACA()

type FileCAPoolProvider 

type FileCAPoolProvider string

func (FileCAPoolProvider) MarshalJSON 

func (FileCAPoolProvider) MarshalJSON() ([]byte, error)

type InlineCAPool 

type InlineCAPool struct {
	// Provider is the name of this provider for the JSON config.
	// DO NOT USE this. This is a special value to represent this provider.
	// It will be overwritten when we are marshalled.
	Provider InlineCAPoolProvider `json:"provider"`

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

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

func (InlineCAPool) IAmACA 

func (InlineCAPool) IAmACA()

type InlineCAPoolProvider 

type InlineCAPoolProvider string

func (InlineCAPoolProvider) MarshalJSON 

func (InlineCAPoolProvider) MarshalJSON() ([]byte, error)

type LeafVerifier 

type LeafVerifier struct {
	// Verifier is the name of this verifier for the JSON config.
	// DO NOT USE this. This is a special value to represent this verifier.
	// It will be overwritten when we are marshalled.
	Verifier LeafVerifierName `json:"verifier"`
}

LeafVerifier . TODO: document

type LeafVerifierName 

type LeafVerifierName string

func (LeafVerifierName) MarshalJSON 

func (LeafVerifierName) MarshalJSON() ([]byte, error)

type OnDemandConfig 

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

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 PKIIntermediateCAPool 

type PKIIntermediateCAPool struct {
	// Provider is the name of this provider for the JSON config.
	// DO NOT USE this. This is a special value to represent this provider.
	// It will be overwritten when we are marshalled.
	Provider PKIIntermediateCAPoolProvider `json:"provider"`

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

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

func (PKIIntermediateCAPool) IAmACA 

func (PKIIntermediateCAPool) IAmACA()

type PKIIntermediateCAPoolProvider 

type PKIIntermediateCAPoolProvider string

func (PKIIntermediateCAPoolProvider) MarshalJSON 

func (PKIIntermediateCAPoolProvider) MarshalJSON() ([]byte, error)

type PKIRootCAPool 

type PKIRootCAPool struct {
	// Provider is the name of this provider for the JSON config.
	// DO NOT USE this. This is a special value to represent this provider.
	// It will be overwritten when we are marshalled.
	Provider PKIRootCAPoolProvider `json:"provider"`

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

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

func (PKIRootCAPool) IAmACA 

func (PKIRootCAPool) IAmACA()

type PKIRootCAPoolProvider 

type PKIRootCAPoolProvider string

func (PKIRootCAPoolProvider) MarshalJSON 

func (PKIRootCAPoolProvider) MarshalJSON() ([]byte, error)

type PublicKeyAlgorithm 

type PublicKeyAlgorithm x509.PublicKeyAlgorithm

PublicKeyAlgorithm is a JSON-unmarshalable wrapper type.

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.
	// TODO: type this
	KeySource any `json:"key_source,omitempty"`

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

SessionTicketService configures and manages TLS session tickets.

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.
	Certificates *Certificates `json:"certificates,omitempty"`

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

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

type Verifier 

type Verifier struct {
	// Leaf .
	// TODO: document
	Leaf *LeafVerifier `json:"leaf,omitempty"`
}

Verifier . TODO: document

Source Files

View all Source files

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.