rootcerts

README

Root CA Certificates for Go

This project converts root certificate authority certificates provided by the Mozilla project into a .go package that can be statically compiled into a Go project.

Motivation

Many Go programs need to access remote SSL/TLS services (eg. over https). The crypto/tls package validates remote certificates by loading public CA certificates from the filesystem as provided by the operating system (eg. in /etc/ssl).

This works well, unless the program is running in any environment where these certificates are not installed, are not accessible, or are out of date. This commonly occurs when running Go programs in a minimal docker container or the binary is distributed as-is to end users who may or may not be running the program on a machine with up to date certificates installed/accessible.

Compiling the root certificates into the program provides guaranteed stable access to them without external dependencies.

Alternatives

Instead of compiling the certificates into the binary, one could:

• Install packages at the OS level and mount /etc/ssl as a volume for the container
• Add a certificates layer to the image when defining the Dockerfile

Compiling the certificates may, however, be simpler to deploy in many cases and result in a predictable outcome whether the binary is executed in a container or on a host.

Usage

You may either use the certificates provided at the root level of this project, which are periodically refreshed, or use the gencerts tool to create a rootcerts.go file that may be copied into your project.

Calling the UpdateDefaultTransport method will make the certificates available to the default http transport, which is sufficient for many projects.

Using gencerts

The gencerts tool reads a certdata.txt file, either from the local filesystem, or directly from the Mozilla Mercurial site (though note, it uses https by default so does itself require local ca certificates!)

Note also that the format of certdata.txt changes occasionally, which may break the gencerts tool. Relying on -download for a production build process may thus be a bad idea!

gencerts -download -package mypackage -target rootcerts.go

gencerts will generate a rootcerts.go and also a rootcerts_16.go if there are any certificate with a negative serial number. Only Go version 1.6 and later supports such certificates, so rootcerts_16.go uses a build flag to ensure compatibility with older versions of Go.

Other Notes

gencerts only outputs certificates that the certdata.txt file has labeled as a trusted delegator (ie. certificates that are suitable for use a certificate authority).

Certificates may be marked as trusted for servers, email or code signing.

Useful Resources

Some of the information I came across while writing this tool:

• [https://github.com/ralphholz/root-store-archaeology]
• [http://curl.haxx.se/cvssource/lib/mk-ca-bundle.pl]
• Ubuntu ca-certificates package (certdata2pem.py)

Similar Projects

• https://github.com/breml/rootcerts

Documentation

Overview

Package rootcerts provides a Go conversion of Mozilla's certdata.txt file, extracting trusted CA certificates only.

It was generated using the gencerts tool using the following command line:

gencerts -download -target rootcerts.go -package rootcerts

This package allows for the embedding of root CA certificates directly into a Go executable, reducing or negating the need for Go to have access to root certificates provided by the operating system in order to validate certificates issued by those authorities.

Root certificates can be accessed through this package, or may be easily installed into the http package's DefaultTransport by calling UpdateDefaultTransport.

Index

• func ServerCertPool() *x509.CertPool
• func UpdateDefaultTransport() error
• type Cert
  • func Certs() []Cert
  • func CertsByTrust(t TrustLevel) (result []Cert)
  • func (c *Cert) X509Cert() *x509.Certificate
• type TrustLevel

Functions

func ServerCertPool

func ServerCertPool() *x509.CertPool

ServerCertPool returns a pool containing all root CA certificates that are trusted for issuing server certificates.

func UpdateDefaultTransport

func UpdateDefaultTransport() error

UpdateDefaultTransport updates the configuration for http.DefaultTransport to use the root CA certificates defined here when used as an HTTP client.

It will return an error if the DefaultTransport is not actually an *http.Transport.

Types

type Cert

type Cert struct {
	Label  string
	Serial string
	Trust  TrustLevel
	DER    []byte
}

A Cert defines a single unparsed certificate.

func Certs

func Certs() []Cert

Certs returns all trusted certificates extracted from certdata.txt.

func CertsByTrust

func CertsByTrust(t TrustLevel) (result []Cert)

CertsByTrust returns only those certificates that match all bits of the specified TrustLevel.

func (*Cert) X509Cert

func (c *Cert) X509Cert() *x509.Certificate

X509Cert parses the certificate into a *x509.Certificate.

type TrustLevel

type TrustLevel int

TrustLevel defines for which purposes the certificate is trusted to issue certificates (ie. to act as a CA)

const (
	ServerTrustedDelegator TrustLevel = 1 << iota // Trusted for issuing server certificates
	EmailTrustedDelegator                         // Trusted for issuing email certificates
	CodeTrustedDelegator                          // Trusted for issuing code signing certificates
)