rootcerts

README

rootcerts

Functions for loading root certificates for TLS connections.

---

Go's standard library crypto/tls provides a common mechanism for configuring TLS connections in tls.Config. The RootCAs field on this struct is a pool of certificates for the client to use as a trust store when verifying server certificates.

This library contains utility functions for loading certificates destined for that field, as well as one other important thing:

When the RootCAs field is nil, the standard library attempts to load the host's root CA set. This behavior is OS-specific, and the Darwin implementation contains a bug that prevents trusted certificates from the System and Login keychains from being loaded. This library contains Darwin-specific behavior that works around that bug.

Example Usage

Here's a snippet demonstrating how this library is meant to be used:

func httpClient() (*http.Client, error)
	tlsConfig := &tls.Config{}
	err := rootcerts.ConfigureTLS(tlsConfig, &rootcerts.Config{
		CAFile:      os.Getenv("MYAPP_CAFILE"),
		CAPath:      os.Getenv("MYAPP_CAPATH"),
		Certificate: os.Getenv("MYAPP_CERTIFICATE"),
	})
	if err != nil {
		return nil, err
	}
	c := cleanhttp.DefaultClient()
	t := cleanhttp.DefaultTransport()
	t.TLSClientConfig = tlsConfig
	c.Transport = t
	return c, nil
}

Documentation

Overview

Package rootcerts contains functions to aid in loading CA certificates for TLS connections.

In addition, its default behavior on Darwin works around an open issue [1] in Go's crypto/x509 that prevents certicates from being loaded from the System or Login keychains.

[1] https://github.com/golang/go/issues/14514

Index

• func AppendCertificate(ca []byte) (*x509.CertPool, error)
• func ConfigureTLS(t *tls.Config, c *Config) error
• func LoadCACerts(c *Config) (*x509.CertPool, error)
• func LoadCAFile(caFile string) (*x509.CertPool, error)
• func LoadCAPath(caPath string) (*x509.CertPool, error)
• func LoadSystemCAs() (*x509.CertPool, error)
• type Config

Functions

func AppendCertificate

func AppendCertificate(ca []byte) (*x509.CertPool, error)

AppendCertificate appends an in-memory PEM-encoded certificate or bundle and returns a pool.

func ConfigureTLS

func ConfigureTLS(t *tls.Config, c *Config) error

ConfigureTLS sets up the RootCAs on the provided tls.Config based on the Config specified.

func LoadCACerts

func LoadCACerts(c *Config) (*x509.CertPool, error)

LoadCACerts loads a CertPool based on the Config specified.

func LoadCAFile

func LoadCAFile(caFile string) (*x509.CertPool, error)

LoadCAFile loads a single PEM-encoded file from the path specified.

func LoadCAPath

func LoadCAPath(caPath string) (*x509.CertPool, error)

LoadCAPath walks the provided path and loads all certificates encounted into a pool.

func LoadSystemCAs

func LoadSystemCAs() (*x509.CertPool, error)

LoadSystemCAs does nothing on non-Darwin systems. We return nil so that default behavior of standard TLS config libraries is triggered, which is to load system certs.

Types

type Config

type Config struct {
	// CAFile is a path to a PEM-encoded certificate file or bundle. Takes
	// precedence over CACertificate and CAPath.
	CAFile string

	// CACertificate is a PEM-encoded certificate or bundle. Takes precedence
	// over CAPath.
	CACertificate []byte

	// CAPath is a path to a directory populated with PEM-encoded certificates.
	CAPath string
}

Config determines where LoadCACerts will load certificates from. When CAFile, CACertificate and CAPath are blank, this library's functions will either load system roots explicitly and return them, or set the CertPool to nil to allow Go's standard library to load system certs.