dynamictls

README

DynamicTLS

DynamicTLS watches the filesystem and updates TLS configuration when certificate changes occur.

It provides simple integrations with HTTP/1.1, HTTP/2, gRPC, and Prometheus.

Examples

HTTP Server

// create metrics
observer, err := tlsprom.NewObserver(
    tlsprom.WithHTTP(),
    tlsprom.WithServer(),
)
check(err)
prometheus.MustRegister(observer)

// create TLS config
cfg, err := dynamictls.NewConfig(
    dynamictls.WithObserver(observer),
    dynamictls.WithCertificate(primaryCertFile, primaryKeyFile),
    dynamictls.WithCertificate(secondaryCertFile, secondaryKeyFile),
    dynamictls.WithRootCAs(caFile),
    dynamictls.WithHTTP(), // NB: adds HTTP/2 and HTTP/1.1 protocols
)
check(err)
defer cfg.Close()

// listen and serve
lis, err := cfg.Listen(context.Background(), "tcp", addr)
check(err)
check(http.Serve(lis, http.DefaultServeMux))

HTTP Client

// create metrics
observer, err := tlsprom.NewObserver(
    tlsprom.WithHTTP(),
    tlsprom.WithClient(),
)
check(err)
prometheus.MustRegister(observer)

// create TLS config
cfg, err := dynamictls.NewConfig(
    dynamictls.WithObserver(observer),
    dynamictls.WithBase(&tls.Config{
        MinVersion: tls.VersionTLS12,
    }),
    dynamictls.WithCertificate(certFile, keyFile),
    dynamictls.WithRootCAs(caFile),
    dynamictls.WithHTTP(), // NB: adds HTTP/2 and HTTP/1.1 protocols
)
check(err)
defer cfg.Close()

// create HTTP client
client := &http.Client{
    Transport: &http.Transport{
        DialTLSContext:    cfg.Dial, // NB: DialTLSContext added in go 1.14
        ForceAttemptHTTP2: true,     // NB: required if using a custom dialer with HTTP/2
    },
}
defer client.CloseIdleConnections()

gRPC Server

// create metrics
observer, err := tlsprom.NewObserver(
    tlsprom.WithGRPC(),
    tlsprom.WithServer(),
)
check(err)
prometheus.MustRegister(observer)

// create TLS config
cfg, err := dynamictls.NewConfig(
    dynamictls.WithObserver(observer),
    dynamictls.WithBase(&tls.Config{
        ClientAuth: tls.RequireAndVerifyClientCert,
        MinVersion: tls.VersionTLS13,
    }),
    dynamictls.WithCertificate(certFile, keyFile),
    dynamictls.WithRootCAs(caFile), // NB: metrics use RootCAs to verify local cert expiration
    dynamictls.WithClientCAs(caFile),
    dynamictls.WithHTTP2(),
)
check(err)
defer cfg.Close()

// create server with credentials
creds, err := grpctls.NewCredentials(cfg)
check(err)
srv := grpc.NewServer(grpc.Creds(creds))
pb.RegisterTestServiceServer(srv, &testServer{})

// listen and serve
lis, err := net.Listen("tcp", addr) // NB: use plain listener
check(err)
check(srv.Serve(lis))

gRPC Client

// create metrics
observer, err := tlsprom.NewObserver(
    tlsprom.WithGRPC(),
    tlsprom.WithClient(),
)
check(err)
prometheus.MustRegister(observer)

// create TLS config
cfg, err := dynamictls.NewConfig(
    dynamictls.WithObserver(observer),
    dynamictls.WithBase(&tls.Config{
        MinVersion: tls.VersionTLS13,
    }),
    dynamictls.WithCertificate(certFile, keyFile),
    dynamictls.WithRootCAs(caFile),
    dynamictls.WithHTTP2(),
)
check(err)
defer cfg.Close()

// create client with credentials
creds, err := grpctls.NewCredentials(cfg)
check(err)
conn, err := grpc.Dial(
    addr,
    grpc.WithTransportCredentials(creds),
    grpc.WithDefaultCallOptions(grpc.WaitForReady(true)),
)
check(err)
defer conn.Close()
client := pb.NewTestServiceClient(conn)

Documentation

Overview

Package dynamictls implements dynamic TLS configuration.

Index

• func NewListener(inner net.Listener, config *Config) net.Listener
• type Config
  • func NewConfig(options ...Option) (cfg *Config, err error)
  • func (cfg *Config) Close() error
  • func (cfg *Config) Config() *tls.Config
  • func (cfg *Config) Dial(ctx context.Context, network, address string) (net.Conn, error)
  • func (cfg *Config) Listen(ctx context.Context, network, address string) (net.Listener, error)
• type Observer
• type Option
  • func WithBase(config *tls.Config) Option
  • func WithCertificate(certFile, keyFile string) Option
  • func WithClientCAs(file string) Option
  • func WithHTTP() Option
  • func WithHTTP1() Option
  • func WithHTTP2() Option
  • func WithLogger(log logr.Logger) Option
  • func WithObserver(observer Observer) Option
  • func WithRootCAs(file string) Option

Examples

• Config.Dial
• Config.Listen

Functions

func NewListener

func NewListener(inner net.Listener, config *Config) net.Listener

NewListener creates a Listener which accepts connections from an inner Listener and wraps each connection with TLS.

Types

type Config

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

A Config is used to configure a TLS client or server.

func NewConfig

func NewConfig(options ...Option) (cfg *Config, err error)

NewConfig returns a new Config with the given options. It's an error if no dynamic file options are specified.

func (*Config) Close

func (cfg *Config) Close() error

Close closes the file watcher associated with the config.

func (*Config) Config

func (cfg *Config) Config() *tls.Config

Config returns the latest TLS config. It is shared and must not be modified.

func (*Config) Dial

func (cfg *Config) Dial(ctx context.Context, network, address string) (net.Conn, error)

Dial connects to the given network address and initiates a TLS handshake, returning the resulting TLS connection.

Example

observer, err := tlsprom.NewObserver(
	tlsprom.WithHTTP(),
	tlsprom.WithClient(),
)
check(err)
prometheus.MustRegister(observer)

cfg, err := dynamictls.NewConfig(
	dynamictls.WithObserver(observer),
	dynamictls.WithBase(&tls.Config{
		MinVersion: tls.VersionTLS12,
	}),
	dynamictls.WithCertificate(certFile, keyFile),
	dynamictls.WithRootCAs(caFile),
	dynamictls.WithHTTP(), // NB: adds HTTP/2 and HTTP/1.1 protocols
)
check(err)
defer cfg.Close()

client := &http.Client{
	Transport: &http.Transport{
		DialTLSContext:    cfg.Dial, // NB: DialTLSContext added in go 1.14
		ForceAttemptHTTP2: true,     // NB: required if using a custom dialer with HTTP/2
	},
}
defer client.CloseIdleConnections()

func (*Config) Listen

func (cfg *Config) Listen(ctx context.Context, network, address string) (net.Listener, error)

Listen creates a TLS listener accepting connections on the given network address.

Example

observer, err := tlsprom.NewObserver(
	tlsprom.WithHTTP(),
	tlsprom.WithServer(),
)
check(err)
prometheus.MustRegister(observer)

cfg, err := dynamictls.NewConfig(
	dynamictls.WithObserver(observer),
	dynamictls.WithCertificate(primaryCertFile, primaryKeyFile),
	dynamictls.WithCertificate(secondaryCertFile, secondaryKeyFile),
	dynamictls.WithRootCAs(caFile),
	dynamictls.WithHTTP(), // NB: adds HTTP/2 and HTTP/1.1 protocols
)
check(err)
defer cfg.Close()

lis, err := cfg.Listen(context.Background(), "tcp", addr)
check(err)
check(http.Serve(lis, http.DefaultServeMux))

type Observer

type Observer interface {
	ObserveConfig(cfg *tls.Config)
	ObserveReadError(err error)
}

An Observer observes when new config data is loaded or an error occurs loading new config data.

type Option

type Option interface {
	// contains filtered or unexported methods
}

An Option applies optional configuration.

func WithBase

func WithBase(config *tls.Config) Option

WithBase returns an Option that sets a base TLS config.

func WithCertificate

func WithCertificate(certFile, keyFile string) Option

WithCertificate returns an Option that adds the public/private key pair in the PEM encoded files to the config's certificates.

func WithClientCAs

func WithClientCAs(file string) Option

WithClientCAs returns an Option that adds the certificates in the file to the config's client certificate pool.

func WithHTTP

func WithHTTP() Option

WithHTTP returns an Option that adds HTTP/2 and HTTP/1.1 protocol negotiation to the config.

func WithHTTP1

func WithHTTP1() Option

WithHTTP1 returns an Option that adds HTTP/1.1 protocol negotiation to the config.

func WithHTTP2

func WithHTTP2() Option

WithHTTP2 returns an Option that adds HTTP/2 protocol negotiation to the config.

func WithLogger

func WithLogger(log logr.Logger) Option

WithLogger returns an Option that sets the logger for errors.

func WithObserver

func WithObserver(observer Observer) Option

WithObserver returns an Option that registers the Observer.

func WithRootCAs

func WithRootCAs(file string) Option

WithRootCAs returns an Option that adds the certificates in the file to the config's root certificate pool.