tlsreconciler

README

TLS Reconciler

A Hitless TLS Certificate Rotation Reconciliation Library.

Introduction

If a certificate got issued, it will have to be rotated.

Rotating TLS certificates manually may quickly get out of hand—particularly when you have to manage hundreds of certificates—and becomes completely unmanageable if you issue certificates that expire within hours, instead of months.
tlsreconciler is here to help with that, by reloading rotated certificate including root CA and provide TLS reconciliation to connections in real time and without restarting the application.

Quickstart

Installing

Using tlsreconciler is easy. First, use go get to install the latest version of the library.

go get github.com/shaj13/tlsreconciler

Next, include tlsreconciler in your application:

import (
    "github.com/shaj13/tlsreconciler"
)

Example

package main

import (
	"crypto/tls"
	"log"
	"net/http"
	"os"
	"os/signal"
	"syscall"

	"github.com/shaj13/tlsreconciler"
)

func HelloWorld(w http.ResponseWriter, req *http.Request) {
	w.Header().Set("Content-Type", "text/plain")
	w.Write([]byte("Hello World.\n"))
}

func main() {
	sigc := make(chan os.Signal, 1)
	defer close(sigc)

	signal.Notify(sigc, syscall.SIGHUP)

	// Options
	sig := tlsreconciler.WithSIGHUPReload(sigc)
	certs := tlsreconciler.WithCertificatesPaths("cert_file", "key_file", "ca_file")
	verify := tlsreconciler.WithVerifyConnection()
	cb := tlsreconciler.WithOnReload(func(c *tls.Config) {
		log.Println("TLS certificates rotated !!")
	})

	config := tlsreconciler.TLSConfig(sig, certs, verify, cb)
	server := http.Server{
		Addr:      ":443",
		Handler:   http.HandlerFunc(HelloWorld),
		TLSConfig: config,
	}

	server.ListenAndServeTLS("", "")
}

Contributing

1. Fork it
2. Download your fork to your PC (git clone https://github.com/your_username/tlsreconciler && cd tlsreconciler)
3. Create your feature branch (git checkout -b my-new-feature)
4. Make changes and add them (git add .)
5. Commit your changes (git commit -m 'Add some feature')
6. Push to the branch (git push origin my-new-feature)
7. Create new pull request

License

tlsreconciler is released under the MIT license. See LICENSE

Documentation

Overview

Package tlsreconciler implements hitless TLS certificate rotation reconciliation, by using certificate selection during the TLS handshake that tls.Config exposes.

Example

package main

import (
	"crypto/tls"
	"log"
	"net/http"
	"os"
	"os/signal"
	"syscall"

	"github.com/shaj13/tlsreconciler"
)

func HelloWorld(w http.ResponseWriter, req *http.Request) {
	w.Header().Set("Content-Type", "text/plain")
	w.Write([]byte("Hello World.\n"))
}

func main() {
	sigc := make(chan os.Signal, 1)
	defer close(sigc)

	signal.Notify(sigc, syscall.SIGHUP)

	// Options
	sig := tlsreconciler.WithSIGHUPReload(sigc)
	certs := tlsreconciler.WithCertificatesPaths("cert_file", "cert_key", "cert_ca")
	verify := tlsreconciler.WithVerifyConnection()
	cb := tlsreconciler.WithOnReload(func(c *tls.Config) {
		log.Println("TLS certificates rotated !!")
	})

	config := tlsreconciler.TLSConfig(sig, certs, verify, cb)
	server := http.Server{
		Addr:      ":443",
		Handler:   http.HandlerFunc(HelloWorld),
		TLSConfig: config,
	}

	server.ListenAndServeTLS("", "")
}

Index

• func TLSConfig(opts ...Option) *tls.Config
• type Option
  • func WithCertificatesPaths(cert, key, ca string) Option
  • func WithDurationRelaod(dur time.Duration) Option
  • func WithOnReload(f func(*tls.Config)) Option
  • func WithProvider(p Provider) Option
  • func WithReloadFunc(f func() bool) Option
  • func WithRootsLimit(n uint) Option
  • func WithSIGHUPReload(c chan os.Signal) Option
  • func WithVerifyConnection() Option
• type Provider

Examples

• Package

Functions

func TLSConfig

func TLSConfig(opts ...Option) *tls.Config

TLSConfig returns new tls.Config that reconcile certificates after a rotation. Calling TLSConfig without any option is similar to

new(tls.Config)

See the documentation of options for more information.

Types

type Option

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

Option configures reconciler using the functional options paradigm popularized by Rob Pike and Dave Cheney. If you're unfamiliar with this style, see https://commandcenter.blogspot.com/2014/01/self-referential-functions-and-design.html and https://dave.cheney.net/2014/10/17/functional-options-for-friendly-apis.

func WithCertificatesPaths

func WithCertificatesPaths(cert, key, ca string) Option

WithCertificatesPaths sets tlsreconciler provider to retrieve latest certificates from the given paths when there a reload signal.

Note: ca can be empty if reload CA not needed, or it can be path to CA bundle.

func WithDurationRelaod

func WithDurationRelaod(dur time.Duration) Option

WithDurationRelaod reload certificate and call the provider to retrieve the latest certificates when each duration elapse.

func WithOnReload

func WithOnReload(f func(*tls.Config)) Option

WithOnReload registers a function to call on relaod. this can be used to rotate session tickets, or any additional purposes like loging.

Reconciler calls f in its own goroutine.

func WithProvider

func WithProvider(p Provider) Option

WithProvider sets tlsreconciler provider to retrieve latest certificates when there a reload signal.

func WithReloadFunc

func WithReloadFunc(f func() bool) Option

WithReloadFunc registers func to determine if need to reload certificate and call the provider to retrieve the latest certificates.

Note: multiple goroutines may call f simultaneously.

func WithRootsLimit

func WithRootsLimit(n uint) Option

WithRootsLimit limits the number of old root CA to keep in the pool. One use case for this feature would be in a situation to keep backward compatibility to verify leaf certs of services that haven't reconciled there certificates yet.

WithRootsLimit used WithVerifyConnection, Otherwise, It's noop

Default 2.

func WithSIGHUPReload

func WithSIGHUPReload(c chan os.Signal) Option

WithSIGHUPReload reload certificate and call the provider to retrieve the latest certificates when SIGHUP received.

func WithVerifyConnection

func WithVerifyConnection() Option

WithVerifyConnection set tls.Config.VerifyConnection to verify tls conn certificate, using the reconciler CA pool that fulfilled from the provider based on previous rotations, Otherwise, the system roots or the platform verifier are used.

WithVerifyConnection also set tls.Config.InsecureSkipVerify to skip the default golang validation that tlsreconciler replacing. This will not disable VerifyConnection.

See the documentation of WithRootsLimit.

Note: tls.Config RootCAs and ClientCAs ignored when this option take place.

type Provider

type Provider interface {
	// Certificates retruns last rotated client or server (leaf) certificate
	// alongside root CA, or an error if occurs.
	//
	// Certificate may return nil for root CAs, if a predefined ca pool sat in tls.Config.
	Certificates() (*tls.Certificate, []*x509.Certificate, error)
}

Provider provides tls certificates. Any type that implements it may be used to reload and provide rotated certificates.