certwatcher

README

Certificate Watcher

Go package that provides the ability to hot-reload TLS certificates without downtime.

Usage

TODO: add usage

Installation

go get github.com/matthewpi/certwatcher

Licensing

All code in this repository is licensed under the MIT license with two exceptions.

Code under internal/sets and internal/wait is licensed under the Apache 2.0 license as a majority of the code was sourced from libraries of Kubernetes and was put in-tree to guarantee API stability and reduce the number of external dependencies necessary for this library to function. Thank you to the developers who made those wonderful utilities.

Documentation

Overview

Package certwatcher provides the ability to hot-reload TLS certificates without downtime.

Index

• func DefaultTLSConfig() *tls.Config
• type Options
• type TLSConfig
  • func (c *TLSConfig) GetTLSConfig(ctx context.Context) (*tls.Config, error)
• type Watcher
  • func New(options Options) (*Watcher, error)
  • func (w *Watcher) Certificate() *tls.Certificate
  • func (w *Watcher) GetCertificate(_ *tls.ClientHelloInfo) (*tls.Certificate, error)
  • func (w *Watcher) GetClientCertificate(_ *tls.CertificateRequestInfo) (*tls.Certificate, error)
  • func (w *Watcher) Reconfigure(ctx context.Context, certPath, keyPath string) error
  • func (w *Watcher) Start(ctx context.Context)

Functions

func DefaultTLSConfig

func DefaultTLSConfig() *tls.Config

DefaultTLSConfig returns a new *tls.Config with sensible defaults.

The returned config is a clone, so it can be modified without impacting other uses of the config.

The default *tls.Config returned here is used by our TLSConfig if am existing *tls.Config is not provided.

Types

type Options

type Options struct {
	// Debounce is the duration to wait before triggering a reload, it's purpose
	// is to ensure that if multiple watched files are updated during it's
	// duration, that multiple full reloads are not triggered.
	Debounce time.Duration

	// DontStaple controls whether OCSP stapling should be disabled when loading
	// certificates, by default it is enabled.
	DontStaple bool

	// Logger to use for the [Watcher] instance.
	Logger *slog.Logger
}

Options controls options for a Watcher. Changes to Options are ignored after being provided to a Watcher.

type TLSConfig

type TLSConfig struct {
	// Config is the TLS config we are wrapping.
	//
	// DO NOT pass this TLS config to a server or client, use the GetTLSConfig()
	// method instead. If you use this TLS config, it will not have the
	// certificate loaded from CertPath and KeyPath.
	Config *tls.Config

	// CertPath is a path to a TLS certificate.
	//
	// This field is optional, but if set then KeyPath must also be provided.
	CertPath string
	// KeyPath is a path to a TLS private key.
	//
	// This field is optional, but if set then CertPath must also be provided.
	KeyPath string

	// DontStaple controls whether OCSP stapling should be disabled when loading
	// certificates, by default it is enabled.
	DontStaple bool
	// contains filtered or unexported fields
}

TLSConfig is a wrapper for the stdlib *tls.Config.

func (*TLSConfig) GetTLSConfig

func (c *TLSConfig) GetTLSConfig(ctx context.Context) (*tls.Config, error)

GetTLSConfig returns the tls.Config for a listener. If CertPath and KeyPath are set, they will be loaded into the returned config, via a certwatcher. Otherwise, the TLSConfig will be returned unmodified.

type Watcher

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

Watcher watches for changes to TLS certificate files on disk and attempts to automatically reload the certificate. This is used to allow the graceful rotation of certificates.

Watcher is also capable of performing OCSP stapling when (re)loading certificates.

func New

func New(options Options) (*Watcher, error)

New creates a new certwatcher Watcher, capable of reloading certificates on the fly.

After calling New, you will want to configure it with Watcher.Reconfigure() and then run Watcher.Start().

func (*Watcher) Certificate

func (w *Watcher) Certificate() *tls.Certificate

Certificate returns the most recently loaded *tls.Certificate.

func (*Watcher) GetCertificate

func (w *Watcher) GetCertificate(_ *tls.ClientHelloInfo) (*tls.Certificate, error)

GetCertificate satisfies tls.Config.GetCertificate. This function should be used on a tls.Config to use the certificate loaded by certwatcher.

func (*Watcher) GetClientCertificate

func (w *Watcher) GetClientCertificate(_ *tls.CertificateRequestInfo) (*tls.Certificate, error)

GetClientCertificate satisfies tls.Config.GetClientCertificate. This function should be used on a tls.Config to use the certificate loaded by certwatcher.

func (*Watcher) Reconfigure

func (w *Watcher) Reconfigure(ctx context.Context, certPath, keyPath string) error

Reconfigure reconfigures the Watcher to watch the given `certPath` and `keyPath`.

This method is both used for initial configuration and for reconfiguration if the certificate paths need to be changed (e.g. config hot-reloading).

func (*Watcher) Start

func (w *Watcher) Start(ctx context.Context)

Start starts listening for fsnotify events and will automatically reload the certificate when necessary.