tlsconfig

package
v1.12.3 Latest Latest
Warning

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

 Go to latest Published: Feb 27, 2026 License: MIT Imports: 14 Imported by: 7

Documentation

Index

Constants

View Source 
const (
	// CertMaxPermissions is the maximum permissions allowed for the certificate file.
	CertMaxPermissions = 0644

	// KeyMaxPermissions is the maximum permissions allowed for the key file.
	KeyMaxPermissions = 0600

	// DefaultExpirationWarnTime is the default advanced warning to give for expiring certificates.
	DefaultExpirationWarnTime = 5 * (24 * time.Hour)

	// DefaultCertificateCheckTime is the default duration between certificate checks.
	DefaultCertificateCheckTime = time.Hour
)

Variables

View Source 
var (
	ErrCertificateNil            = errors.New("TLS certificate is nil")
	ErrCertificateEmpty          = errors.New("TLS certificate is empty")
	ErrCertificateRequestInfoNil = errors.New("CertificateRequestInfo is nil")
	ErrLoadedCertificateInvalid  = errors.New("LoadedCertificate is invalid")
	ErrPathEmpty                 = errors.New("empty path")
)
View Source 
var (
	// ErrNoCertLoader indicates that an operation requiring a TLSCertLoader did not have one available.
	// This can happen if the TLSConfigManager was created without a certificate for client-side use only.
	ErrNoCertLoader = errors.New("no TLSCertLoader available")
)

Functions

This section is empty.

Types

type Config 

type Config struct {
	Ciphers    []string `toml:"ciphers"`
	MinVersion string   `toml:"min-version"`
	MaxVersion string   `toml:"max-version"`
}

func NewConfig 

func NewConfig() Config

func (Config) Parse 

func (c Config) Parse() (out *tls.Config, err error)

func (Config) Validate 

func (c Config) Validate() error

type LoadCertificateOpt added in v1.12.3 

type LoadCertificateOpt func(*loadCertificateConfig)

LoadCertificateOpt are functions to change the behavior of LoadCertificate.

func WithLoadCertificateIgnoreFilePermissions added in v1.12.3 

func WithLoadCertificateIgnoreFilePermissions(ignore bool) LoadCertificateOpt

WithLoadCertificateIgnoreFilePermissions instructs LoadCertificate to ignore file permissions if ignore is true.

type LoadedCertificate added in v1.12.3 

type LoadedCertificate struct {

	// CertPath is the path the certificate was loaded from.
	CertificatePath string

	// KeyPath is the path the private key was loaded from.
	KeyPath string

	// Certificate is the certificate that was loaded.
	Certificate *tls.Certificate

	// Leaf is the parsed x509 certificate of Certificate's leaf certificate.
	Leaf *x509.Certificate
	// contains filtered or unexported fields
}

LoadedCertificate encapsulates information about a loaded certificate.

func LoadCertificate added in v1.12.3 

func LoadCertificate(certPath, keyPath string, opts ...LoadCertificateOpt) (LoadedCertificate, error)

LoadCertificate loads a key pair from certPath and keyPath, performing several checks along the way. If any checks fail or an error occurs loading the files, then an error is returned. If keyPath is empty, then certPath is assumed to contain both the certificate and the private key. Only trusted input (standard configuration files) should be used for certPath and keyPath.

func (*LoadedCertificate) IsValid added in v1.12.3 

func (lc *LoadedCertificate) IsValid() bool

type TLSCertLoader added in v1.12.3 

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

TLSCertLoader handles loading TLS certificates, providing them to a tls.Config, and monitoring the certificate for expiration.

func NewTLSCertLoader added in v1.12.3 

func NewTLSCertLoader(certPath, keyPath string, opts ...TLSCertLoaderOpt) (rCertLoader *TLSCertLoader, rErr error)

NewTLSCertLoader creates a TLSCertLoader loaded with the certifcate found in certPath and keyPath. Only trusted input (standard configuration files) should be used for certPath and keyPath. If the certificate can not be loaded, an error is returned. On success, a monitor is setup to periodically check the certificate for expiration.

func (*TLSCertLoader) Certificate added in v1.12.3 

func (cl *TLSCertLoader) Certificate() *tls.Certificate

Certificate returns the currently loaded certificate, which may be nil.

func (*TLSCertLoader) Close added in v1.12.3 

func (cl *TLSCertLoader) Close() error

Close shuts down the goroutine monitoring certificate expiration. Even after the monitoring goroutine is shutdown, Load and GetCertificate will continue to work normally.

func (*TLSCertLoader) GetCertificate added in v1.12.3 

func (cl *TLSCertLoader) GetCertificate(*tls.ClientHelloInfo) (*tls.Certificate, error)

GetCertificate is for use with a tls.Config's GetCertificate member. This allows a tls.Config to dynamically update its certificate when Load changes the active certificate.

func (*TLSCertLoader) GetClientCertificate added in v1.12.3 

func (cl *TLSCertLoader) GetClientCertificate(cri *tls.CertificateRequestInfo) (*tls.Certificate, error)

GetClientCertificate is for use with a tls.Config's GetClientCertificate member. This allows a tls.Config to dynamically update its client certificates when Load changes the active certificate.

func (*TLSCertLoader) Leaf added in v1.12.3 

func (cl *TLSCertLoader) Leaf() *x509.Certificate

Leaf returns the parsed x509 certificate of the currently loaded certificate. If no certificate is loaded then nil is returned.

func (*TLSCertLoader) Load added in v1.12.3 

func (cl *TLSCertLoader) Load(certPath, keyPath string) (rErr error)

Load loads the certificate at the given certificate path and private keyfile path. Only trusted input (standard configuration files) should be used for certPath and keyPath.

func (*TLSCertLoader) Paths added in v1.12.3 

func (cl *TLSCertLoader) Paths() (certPath, keyPath string)

Paths returns the path of the currently loaded certificate and private key. The keyPath will be the file containing the private key, even if no keyPath was provided to NewTLSCertLoader / Load.

func (*TLSCertLoader) PrepareLoad added in v1.12.3 

func (cl *TLSCertLoader) PrepareLoad(certPath, keyPath string) (func() error, error)

PrepareLoad verifies that the certificate at certPath and keyPath will load without error. If the certificate can be loaded, a function that will apply the certificate reload is returned. Otherwise, an error is returned.

func (*TLSCertLoader) SetCertificate added in v1.12.3 

func (cl *TLSCertLoader) SetCertificate(l LoadedCertificate) error

SetCertificate sets the currently loaded certificate from a LoadedCertificate. Will also log any warnings about certificate (e.g. expired, about to expire, etc.).

func (*TLSCertLoader) SetupTLSConfig added in v1.12.3 

func (cl *TLSCertLoader) SetupTLSConfig(tlsConfig *tls.Config)

SetupTLSConfig modifies tlsConfig to use cl for server and client certificates. tlsConfig may be nil. If other fields like tlsConfig.Certificates or tlsConfig.NameToCertificate have been set, then cl's certificate may not be used as expected.

func (*TLSCertLoader) WaitForMonitorStart added in v1.12.3 

func (cl *TLSCertLoader) WaitForMonitorStart()

WaitForMonitorStart will wait for the certificate monitor goroutine to start. This is mainly useful for tests to avoid race conditions.

type TLSCertLoaderOpt added in v1.12.3 

type TLSCertLoaderOpt func(*TLSCertLoader)

func WithCertLoaderCertificateCheckInterval added in v1.12.3 

func WithCertLoaderCertificateCheckInterval(d time.Duration) TLSCertLoaderOpt

WithCertLoaderCertificateCheckInterval sets how often to check for certificate expiration.

func WithCertLoaderExpirationAdvanced added in v1.12.3 

func WithCertLoaderExpirationAdvanced(d time.Duration) TLSCertLoaderOpt

WithCertLoaderExpirationAdvanced sets the how far ahead a CertLoader will warn about a certificate that is about to expire.

func WithCertLoaderIgnoreFilePermissions added in v1.12.3 

func WithCertLoaderIgnoreFilePermissions(ignore bool) TLSCertLoaderOpt

WithCertLoaderIgnoreFilePermissions skips file permission checking when loading certificates.

func WithCertLoaderLogger added in v1.12.3 

func WithCertLoaderLogger(logger *zap.Logger) TLSCertLoaderOpt

WithCertLoaderLogger assigns a logger for to use.

type TLSConfigManager added in v1.12.3 

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

TLSConfigManager will manage a TLS configuration and make sure that only one instance of its tls.Config exists. Different TLSConfigManager objects will have different configurations, even if they are instantiated in exactly the same way. No struct member is modified once the NewTLSConfigManager constructor is finished.

func NewClientTLSConfigManager added in v1.12.3 

func NewClientTLSConfigManager(useTLS bool, baseConfig *tls.Config, allowInsecure bool, opts ...TLSConfigManagerOpt) (*TLSConfigManager, error)

NewClientTLSConfigManager creates a TLSConfigManager that is only useful for clients without client certificates. TLS is enabled when useTLS is true. Certificate verification is skipped when allowInsecure is true. This is convenience wrapper for NewTLSConfigManager(useTLS, baseConfig, "", "", allowInsecure).

func NewDisabledTLSConfigManager added in v1.12.3 

func NewDisabledTLSConfigManager() *TLSConfigManager

NewDisabledTLSConfigManager creates a TLSConfigManager that has TLS disabled. This is a convenience function equivalent to NewTLSConfigManager(false, nil, "", "", false). In addition to being more concise, NewDisabledTLSConfigManager can not return an error.

func NewTLSConfigManager added in v1.12.3 

func NewTLSConfigManager(useTLS bool, baseConfig *tls.Config, certPath, keyPath string, allowInsecure bool, opts ...TLSConfigManagerOpt) (*TLSConfigManager, error)

NewTLSConfigManager returns a TLSConfigManager with the given configuration. If useTLS is true, then the certificate is loaded immediately if specified and the tls.Config instantiated. If no certPath and no keyPath is provided, then no TLSCertLoader is created. For this case, the returned TLSConfigManager can be used for client operations (e.g. Dial), but not for server operations (e.g. Listen). The allowInsecure parameter has no effect on server operations.

func (*TLSConfigManager) Close added in v1.12.3 

func (cm *TLSConfigManager) Close() error

Close closes the underlying TLSCertLoader, if present. This is safe to call multiple times.

func (*TLSConfigManager) Dial added in v1.12.3 

func (cm *TLSConfigManager) Dial(network, address string) (net.Conn, error)

Dial a remote for network and addressing using the current configuration.

func (*TLSConfigManager) DialWithDialer added in v1.12.3 

func (cm *TLSConfigManager) DialWithDialer(dialer *net.Dialer, network, address string) (net.Conn, error)

Dial a remote for network and addressing using the given dialer and current configuration.

func (*TLSConfigManager) Listen added in v1.12.3 

func (cm *TLSConfigManager) Listen(network, address string) (net.Listener, error)

Return a net.Listener for network and address based on current configuration.

func (*TLSConfigManager) PrepareCertificateLoad added in v1.12.3 

func (cm *TLSConfigManager) PrepareCertificateLoad(certPath, keyPath string) (func() error, error)

PrepareCertificateLoad is a wrapper for the TLSCertLoader's PrepareLoad method. If TLS is not enabled, then a NOP callback is returned.

func (*TLSConfigManager) TLSCertLoader added in v1.12.3 

func (cm *TLSConfigManager) TLSCertLoader() *TLSCertLoader

TLSCertLoader returns the certificate loader for this TLSConfigManager. When no certificate is provided the return value is nil.

func (*TLSConfigManager) TLSConfig added in v1.12.3 

func (cm *TLSConfigManager) TLSConfig() *tls.Config

TLSConfig returns a tls.Config for use with dial and listen functions. When TLS is disabled the return is nil. The returned tls.Config is a clone and does not need to be cloned again.

func (*TLSConfigManager) UseTLS added in v1.12.3 

func (cm *TLSConfigManager) UseTLS() bool

UseTLS returns true if this TLSConfigManager is configured to use TLS. It is a convenience wrapper around TLSConfig.

type TLSConfigManagerOpt added in v1.12.3 

type TLSConfigManagerOpt func(*tlsConfigManagerConfig)

TLSConfigManagerOpt is an option for use with NewTLSConfigManager and related constructors.

func WithAllowInsecure added in v1.12.3 

func WithAllowInsecure(allowInsecure bool) TLSConfigManagerOpt

WithAllowInsecure sets if the config manager should allow insecure TLS.

func WithBaseConfig added in v1.12.3 

func WithBaseConfig(baseConfig *tls.Config) TLSConfigManagerOpt

WithBaseConfig sets the config manager's base *tls.Config.

func WithCertificate added in v1.12.3 

func WithCertificate(certPath, keyPath string) TLSConfigManagerOpt

WithCertificate sets the config manager's certificate and private key path.

func WithCertificateCheckInterval added in v1.12.3 

func WithCertificateCheckInterval(d time.Duration) TLSConfigManagerOpt

WithCertificateCheckInterval sets how often to check for certificate expiration.

func WithClientAuth added in v1.12.3 

func WithClientAuth(auth tls.ClientAuthType) TLSConfigManagerOpt

WithClientAuth specifies the type TLS client authentication a server should perform.

func WithClientCAFiles added in v1.12.3 

func WithClientCAFiles(pemFiles ...string) TLSConfigManagerOpt

WithClientCAFiles specifies a list of paths to PEM files that contain root CA for client authentication.

func WithClientCAIncludeSystem added in v1.12.3 

func WithClientCAIncludeSystem(includeSystem bool) TLSConfigManagerOpt

WithClientCAIncludeSystem specifies if the system CA should be included in the client CA for client authentication.

func WithExpirationAdvanced added in v1.12.3 

func WithExpirationAdvanced(d time.Duration) TLSConfigManagerOpt

WithExpirationAdvanced sets the how far ahead the underlying CertLoader will warn about a certificate that is about to expire.

func WithIgnoreFilePermissions added in v1.12.3 

func WithIgnoreFilePermissions(ignore bool) TLSConfigManagerOpt

WithIgnoreFilePermissions ignores file permissions when loading certificates.

func WithLogger added in v1.12.3 

func WithLogger(logger *zap.Logger) TLSConfigManagerOpt

WithLogger assigns a logger for to use.

func WithRootCAFiles added in v1.12.3 

func WithRootCAFiles(pemFiles ...string) TLSConfigManagerOpt

WithRootCAFiles specifies a list of paths to PEM files that contain root CAs.

func WithRootCAIncludeSystem added in v1.12.3 

func WithRootCAIncludeSystem(includeSystem bool) TLSConfigManagerOpt

WithRootCAIncludeSystem specifies if the system CA should be included in the root CA.

func WithUseTLS added in v1.12.3 

func WithUseTLS(useTLS bool) TLSConfigManagerOpt

WithUseTLS sets if the config manager should use TLS.

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.