Documentation
¶
Index ¶
- func GetCertificate(certFile, keyFile string) (func(*tls.ClientHelloInfo) (*tls.Certificate, error), error)
- func GetClientCertificate(certFile, keyFile string) (func(*tls.CertificateRequestInfo) (*tls.Certificate, error), error)
- func GetRootCAs(path string) (*x509.CertPool, error)
- func WithDisableAutoReload() func(*Manager)
- type Certificate
- type Certificate2
- type GetCertificateFunc
- type LoadX509KeyPairFunc
- type Manager
- func (m *Manager) AddCertificate(certFile, keyFile string) (err error)
- func (m *Manager) DisableAutoReload() bool
- func (m *Manager) GetAllCertificates() []*x509.Certificate
- func (m *Manager) GetCertificate(hello *tls.ClientHelloInfo) (*tls.Certificate, error)
- func (m *Manager) GetClientCertificate(reqInfo *tls.CertificateRequestInfo) (*tls.Certificate, error)
- func (m *Manager) ReloadCerts()
- func (m *Manager) ReloadOnSignal(sig ...os.Signal)
- func (m *Manager) UpdateReloadDuration(t time.Duration)
- type Manager2
- func (m *Manager2) Close()
- func (m *Manager2) GetAllCertificates() []*x509.Certificate
- func (m *Manager2) GetCertificate(hello *tls.ClientHelloInfo) (*tls.Certificate, error)
- func (m *Manager2) GetClientCertificate(reqInfo *tls.CertificateRequestInfo) (*tls.Certificate, error)
- func (m *Manager2) HasCerts() bool
- func (m *Manager2) Subscribe(callback func(*Certificate2)) func()
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func GetCertificate ¶ added in v3.4.3
func GetCertificate(certFile, keyFile string) (func(*tls.ClientHelloInfo) (*tls.Certificate, error), error)
GetCertificate returns a function that returns the given certificate/key pair for use in tls.Config.GetCertificate.
The certificate is cached globally and persists for the application lifetime. Multiple calls with the same certFile and keyFile will return closures that reference the same underlying Certificate2 instance. The certificate will automatically reload when the underlying files change.
Example usage:
certFunc, err := GetCertificate("server.crt", "server.key")
if err != nil {
return err
}
tlsConfig := &tls.Config{
GetCertificate: certFunc,
}
func GetClientCertificate ¶ added in v3.4.3
func GetClientCertificate(certFile, keyFile string) (func(*tls.CertificateRequestInfo) (*tls.Certificate, error), error)
GetClientCertificate returns a function that returns the given certificate/key pair for use in tls.Config.GetClientCertificate.
The certificate is cached globally and persists for the application lifetime. Multiple calls with the same certFile and keyFile will return closures that reference the same underlying Certificate2 instance. The certificate will automatically reload when the underlying files change.
Example usage:
certFunc, err := GetClientCertificate("client.crt", "client.key")
if err != nil {
return err
}
tlsConfig := &tls.Config{
GetClientCertificate: certFunc,
}
func GetRootCAs ¶
GetRootCAs loads all X.509 certificates at the given path and adds them to the list of system root CAs, if available. The returned CA pool is a conjunction of the system root CAs and the certificate(s) at the given path.
If path is a regular file, LoadCAs simply adds it to the CA pool if the file contains a valid X.509 certificate
If the path points to a directory, LoadCAs iterates over all top-level files within the directory and adds them to the CA pool if they contain a valid X.509 certificate.
func WithDisableAutoReload ¶ added in v3.1.5
func WithDisableAutoReload() func(*Manager)
WithDisableAutoReload disables automatic reloading
Types ¶
type Certificate ¶
type Certificate struct {
// contains filtered or unexported fields
}
Certificate is a chain of one or more reloadable certificates.
func NewCertificate ¶
func NewCertificate(certFile, keyFile string, loadX509KeyPair LoadX509KeyPairFunc) (*Certificate, error)
NewCertificate returns a new Certificate from the given certficate and private key file. On a reload event, the certificate is reloaded using the loadX509KeyPair function.
func (*Certificate) Get ¶
func (c *Certificate) Get() tls.Certificate
Get returns the current TLS certificate.
func (*Certificate) Notify ¶
func (c *Certificate) Notify(events chan<- tls.Certificate)
Notify notifies the given events channel whenever the certificate has been reloaded successfully. The new certificate is sent to the channel receiver.
func (*Certificate) Reload ¶
func (c *Certificate) Reload() error
Reload reloads the certificate and sends notifications to all listeners that subscribed via Notify.
func (*Certificate) Stop ¶
func (c *Certificate) Stop(events chan<- tls.Certificate)
Stop stops notifying the given events channel whenever the certificate has been reloaded successfully.
func (*Certificate) Watch ¶
Watch starts watching the certificate and private key file for any changes and reloads the Certificate whenever a change is detected.
Additionally, Watch listens on the given list of OS signals and reloads the Certificate whenever it encounters one of the signals. Further, Watch reloads the certificate periodically if interval > 0.
type Certificate2 ¶ added in v3.4.3
type Certificate2 struct {
atomic.Pointer[tls.Certificate]
// contains filtered or unexported fields
}
Certificate2 wraps a tls.Certificate and automatically reloads it when the underlying files change. It is safe for concurrent use.
The certificate is reloaded when filesystem events occur on the underlying cert and key files. Reloads happen automatically and transparently to callers. If a reload fails (e.g., due to invalid cert data or read errors during file update), the certificate remains unchanged and subscribers are not notified. This allows graceful degradation if cert files are temporarily inconsistent.
func NewCertificate2 ¶ added in v3.4.3
func NewCertificate2(certFile, keyFile string) (*Certificate2, error)
NewCertificate2 creates a new Certificate which watches the given certFile and keyFile for changes and reloads them automatically.
func (*Certificate2) Close ¶ added in v3.4.3
func (c *Certificate2) Close()
Close stops watching the certificate files and releases all resources.
func (*Certificate2) Subscribe ¶ added in v3.4.3
func (c *Certificate2) Subscribe(callback func(*Certificate2)) func()
Subscribe will register a callback which is called with the updated Certificate2 instance each time the certificate is reloaded. The returned function should be called to unsubscribe when the certificate is no longer needed. Closing the certificate will automatically unsubscribe all subscribers.
The callback runs in a dedicated goroutine per subscription. The callback must not block indefinitely; if it does, that subscription's goroutine will hang and the internal notification channel will not be consumed. A hung callback will not prevent other subscriptions from being notified, but will leak a goroutine until the certificate is closed.
Make sure not to block in the callback to avoid blocking the internal certificate reloading goroutine and to ensure prompt cleanup of resources.
type GetCertificateFunc ¶
type GetCertificateFunc func(hello *tls.ClientHelloInfo) (*tls.Certificate, error)
GetCertificateFunc is a callback that allows a TLS stack deliver different certificates based on the client trying to establish a TLS connection.
For example, a GetCertificateFunc can return different TLS certificates depending upon the TLS SNI sent by the client.
type LoadX509KeyPairFunc ¶
type LoadX509KeyPairFunc func(certFile, keyFile string) (tls.Certificate, error)
LoadX509KeyPairFunc is a function that parses a private key and certificate file and returns a TLS certificate on success.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager is a TLS certificate manager that can handle multiple certificates. When a client tries to establish a TLS connection, Manager will try to pick a certificate that can be validated by the client.
For instance, if the client specifies a TLS SNI then Manager will try to find the corresponding certificate. If there is no such certificate it will fallback to the certificate named public.crt.
Manager will automatically reload certificates if the corresponding file changes.
func NewManager ¶
func NewManager(ctx context.Context, certFile, keyFile string, loadX509KeyPair LoadX509KeyPairFunc, opts ...func(*Manager)) (manager *Manager, err error)
NewManager returns a new Manager that handles one certificate specified via the certFile and keyFile. It will use the loadX509KeyPair function to (re)load certificates.
The certificate loaded from certFile is considered the default certificate. If a client does not send the TLS SNI extension then Manager will return this certificate.
func (*Manager) AddCertificate ¶
AddCertificate adds the TLS certificate in certFile resp. keyFile to the Manager.
If there is already a certificate with the same base name it will be replaced by the newly added one.
func (*Manager) DisableAutoReload ¶ added in v3.1.5
DisableAutoReload returns if automatic reloading is disabled
func (*Manager) GetAllCertificates ¶ added in v3.0.27
func (m *Manager) GetAllCertificates() []*x509.Certificate
GetAllCertificates returns all the certificates loaded
func (*Manager) GetCertificate ¶
func (m *Manager) GetCertificate(hello *tls.ClientHelloInfo) (*tls.Certificate, error)
GetCertificate returns a TLS certificate based on the client hello.
It tries to find a certificate that would be accepted by the client according to the client hello. However, if no certificate can be found GetCertificate returns the certificate loaded from the Public file.
func (*Manager) GetClientCertificate ¶
func (m *Manager) GetClientCertificate(reqInfo *tls.CertificateRequestInfo) (*tls.Certificate, error)
GetClientCertificate returns a TLS certificate for mTLS based on the certificate request.
It tries to find a certificate that would be accepted by the server according to the certificate request. However, if no certificate can be found GetClientCertificate returns the certificate loaded from the Public file.
func (*Manager) ReloadCerts ¶
func (m *Manager) ReloadCerts()
ReloadCerts will forcefully reload all certs.
func (*Manager) ReloadOnSignal ¶
ReloadOnSignal specifies one or more signals that will trigger certificates reloading. If called multiple times with the same signal certificates
func (*Manager) UpdateReloadDuration ¶
UpdateReloadDuration set custom symlink reload duration
type Manager2 ¶ added in v3.4.3
type Manager2 struct {
// contains filtered or unexported fields
}
Manager2 manages TLS certificates and automatically reloads them when the underlying files change or a SIGHUP signal is received.
func NewManager2 ¶ added in v3.4.3
func NewManager2(loadCerts func() ([]*Certificate2, error)) (*Manager2, error)
NewManager2 creates a new certificate manager which loads certificates using the provided loadCerts function. The manager will automatically update the loaded certificates when:
- The underlying file changed (reloads a single certificate)
- A SIGHUP signal is received (this will rescan all certificates)
The manager is using internal synchronization and is safe for concurrent use. Make sure to call Close when the manager is no longer needed.
func (*Manager2) Close ¶ added in v3.4.3
func (m *Manager2) Close()
Close stops the certificate manager and releases all resources.
func (*Manager2) GetAllCertificates ¶ added in v3.4.3
func (m *Manager2) GetAllCertificates() []*x509.Certificate
GetAllCertificates returns a copy of all loaded certificates
func (*Manager2) GetCertificate ¶ added in v3.4.3
func (m *Manager2) GetCertificate(hello *tls.ClientHelloInfo) (*tls.Certificate, error)
GetCertificate returns a TLS certificate based on the client hello.
It tries to find a certificate that would be accepted by the client according to the client hello. However, if no certificate can be found GetCertificate returns the first certificate as the "default"
func (*Manager2) GetClientCertificate ¶ added in v3.4.3
func (m *Manager2) GetClientCertificate(reqInfo *tls.CertificateRequestInfo) (*tls.Certificate, error)
GetClientCertificate returns a TLS certificate for mTLS based on the certificate request.
It tries to find a certificate that would be accepted by the server according to the certificate request. If no matching certificate can be found, an error is returned.
BREAKING CHANGE: Compared to `Manager.GetClientCertificate` this implementation won't return the first certificate if only one certificate is loaded. This is because in mTLS scenarios the server usually requests specific client certificates and we should not present a certificate that is not requested by the server. It was also inconsistent with the behavior when more certificates have been loaded and none of them matches the client hello.
func (*Manager2) Subscribe ¶ added in v3.4.3
func (m *Manager2) Subscribe(callback func(*Certificate2)) func()
Subscribe will register a callback which is called when one or all certificates have been reloaded. The callback receives the updated certificate when a single certificate is reloaded or `nil` when all certificates have been reloaded. Closing the manager will automatically unsubscribe all subscribers.
Make sure not to block in the callback to avoid blocking the internal certificate reloading goroutine.
Source Files