bundler

Documentation

Overview

package bundler implements certificate bundling functionality for CF-SSL.

Package bundler provides an API for creating certificate bundles, which contain a trust chain of certificates. Generally, the bundles will also include the private key (but this is not strictly required). In this package, a bundle refers to a certificate with full trust chain -- all certificates in the chain in one file or buffer.

The first step in creating a certificate bundle is to create a Bundler. A Bundler must be created from a pre-existing certificate authority bundle and an intermediate certificate bundle. Once the Bundler is initialised, bundles may be created using a variety of methods: from PEM- or DER-encoded files, directly from the relevant Go structures, or by starting with the certificate from a remote system. These functions return a Bundle value, which may be serialised to JSON.

Index

• Variables
• type Bundle
  • func (b *Bundle) MarshalJSON() ([]byte, error)
• type BundleFlavor
• type BundleStatus
• type Bundler
  • func NewBundler(caBundleFile, intBundleFile string) (*Bundler, error)
  • func NewBundlerFromPEM(caBundlePEM, intBundlePEM []byte) (*Bundler, error)
  • func (b *Bundler) Bundle(certs []*x509.Certificate, key interface{}, flavor BundleFlavor) (*Bundle, error)
  • func (b *Bundler) BundleFromFile(bundleFile, keyFile string, flavor BundleFlavor) (*Bundle, error)
  • func (b *Bundler) BundleFromPEM(certsPEM, keyPEM []byte, flavor BundleFlavor) (*Bundle, error)
  • func (b *Bundler) BundleFromRemote(serverName, ip string) (*Bundle, error)
  • func (b *Bundler) VerifyOptions() x509.VerifyOptions

Variables

var IntermediateStash = "intermediates"

intermediateStash contains the path to the directory where downloaded intermediates should be saved.

Types

type Bundle

type Bundle struct {
	Chain     []*x509.Certificate
	Cert      *x509.Certificate
	Key       interface{}
	Issuer    *pkix.Name
	Subject   *pkix.Name
	Expires   *time.Time
	Hostnames []string
	Status    *BundleStatus
}

A Bundle contains a certificate and its trust chain. It is intended to store the most widely applicable chain, with shortness an explicit goal.

func (*Bundle) MarshalJSON

func (b *Bundle) MarshalJSON() ([]byte, error)

MarshalJSON serialises the bundle to JSON. The resulting JSON structure contains the bundle (as a sequence of PEM-encoded certificates), the certificate, the private key, the size of they key, the issuer(s), the subject name(s), the expiration, the hostname(s), the OCSP server, and the signature on the certificate.

type BundleFlavor

type BundleFlavor string

BundleFlavor is named optimization strategy on certificate chain selection when bundling.

const (
	Optimal    BundleFlavor = "optimal"    // Optimal means the shortest chain with newest intermediates and the most advanced crypto.
	Ubiquitous BundleFlavor = "ubiquitous" // Ubiquitous is aimed to provide the chain which is accepted by the most platforms.
)

type BundleStatus

type BundleStatus struct {
	// A flag on whether a new bundle is generated
	IsRebundled bool `json:"rebundled"`
	// A list of SKIs of expiring certificates
	ExpiringSKIs []string `json:"expiring_SKIs"`
	// A list of untrusted root store names
	Untrusted []string `json:"untrusted_root_stores"`
	// A list of human readable warning messages based on the bundle status.
	Messages []string `json:"messages"`
	// A status code consists of binary flags
	Code int `json:"code"`
}

BundleStatus is designated for various status reporting.

type Bundler

type Bundler struct {
	RootPool         *x509.CertPool
	IntermediatePool *x509.CertPool
	KnownIssuers     map[string]bool
}

A Bundler contains the certificate pools for producing certificate bundles. It contains any intermediates and root certificates that should be used.

func NewBundler

func NewBundler(caBundleFile, intBundleFile string) (*Bundler, error)

NewBundler creates a new Bundler from the files passed in; these files should contain a list of valid root certificates and a list of valid intermediate certificates, respectively.

func NewBundlerFromPEM

func NewBundlerFromPEM(caBundlePEM, intBundlePEM []byte) (*Bundler, error)

NewBundlerFromPEM creates a new Bundler from PEM-encoded root certificates and intermediate certificates.

func (*Bundler) Bundle

func (b *Bundler) Bundle(certs []*x509.Certificate, key interface{}, flavor BundleFlavor) (*Bundle, error)

Bundle takes an X509 certificate (already in the Certificate structure), a private key in one of the appropriate formats (i.e. *rsa.PrivateKey or *ecdsa.PrivateKey), using them to build a certificate bundle.

func (*Bundler) BundleFromFile

func (b *Bundler) BundleFromFile(bundleFile, keyFile string, flavor BundleFlavor) (*Bundle, error)

BundleFromFile takes a set of files containing the PEM-encoded leaf certificate (optionally along with some intermediate certs), the PEM-encoded private key and returns the bundle built from that key and the certificate(s).

func (*Bundler) BundleFromPEM

func (b *Bundler) BundleFromPEM(certsPEM, keyPEM []byte, flavor BundleFlavor) (*Bundle, error)

BundleFromPEM builds a certificate bundle from the set of byte slices containing the PEM-encoded certificate(s), private key.

func (*Bundler) BundleFromRemote

func (b *Bundler) BundleFromRemote(serverName, ip string) (*Bundle, error)

BundleFromRemote fetches the certificate chain served by the server at serverName (or ip, if the ip argument is not the empty string). It is expected that the method will be able to make a connection at port 443. The chain used by the server in this connection is used to rebuild the bundle.

func (*Bundler) VerifyOptions

func (b *Bundler) VerifyOptions() x509.VerifyOptions

VerifyOptions generates an x509 VerifyOptions structure that can be used for verifying certificates.