bundler

Documentation

Overview

Package bundler implements certificate bundling functionality for CFSSL.

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
• func PemBlockToString(block *pem.Block) string
• type Bundle
  • func (b *Bundle) MarshalJSON() ([]byte, error)
• type BundleFlavor
• type BundleStatus
• type Bundler
  • func NewBundler(caBundleFile, intBundleFile string, opt ...Option) (*Bundler, error)
  • func NewBundlerFromPEM(caBundlePEM, intBundlePEM []byte, opt ...Option) (*Bundler, error)
  • func (b *Bundler) Bundle(certs []*x509.Certificate, key crypto.Signer, flavor BundleFlavor) (*Bundle, error)
  • func (b *Bundler) BundleFromFile(bundleFile, keyFile string, flavor BundleFlavor, password string) (*Bundle, error)
  • func (b *Bundler) BundleFromPEMorDER(certsRaw, keyPEM []byte, flavor BundleFlavor, password string) (*Bundle, error)
  • func (b *Bundler) BundleFromRemote(serverName, ip string, flavor BundleFlavor) (*Bundle, error)
  • func (b *Bundler) VerifyOptions() x509.VerifyOptions
• type Option
  • func WithKeyUsages(usages ...x509.ExtKeyUsage) Option

Variables

var IntermediateStash string

IntermediateStash contains the path to the directory where downloaded intermediates should be saved. When unspecified, downloaded intermediates are not saved.

Functions

func PemBlockToString

func PemBlockToString(block *pem.Block) string

PemBlockToString turns a pem.Block into the string encoded form.

Types

type Bundle

type Bundle struct {
	Chain       []*x509.Certificate
	Cert        *x509.Certificate
	Root        *x509.Certificate
	Key         interface{}
	Issuer      *pkix.Name
	Subject     *pkix.Name
	Expires     time.Time
	LeafExpires 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 means the shortest chain with newest intermediates and
	// the most advanced crypto.
	Optimal BundleFlavor = "optimal"

	// Ubiquitous is aimed to provide the chain which is accepted
	// by the most platforms.
	Ubiquitous BundleFlavor = "ubiquitous"

	// Force means the bundler only verfiies the input as a valid bundle, not optimization is done.
	Force BundleFlavor = "force"
)

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
	// contains filtered or unexported fields
}

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, opt ...Option) (*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, opt ...Option) (*Bundler, error)

NewBundlerFromPEM creates a new Bundler from PEM-encoded root certificates and intermediate certificates. If caBundlePEM is nil, the resulting Bundler can only do "Force" bundle.

func (*Bundler) Bundle

func (b *Bundler) Bundle(certs []*x509.Certificate, key crypto.Signer, flavor BundleFlavor) (*Bundle, error)

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

func (*Bundler) BundleFromFile

func (b *Bundler) BundleFromFile(bundleFile, keyFile string, flavor BundleFlavor, password string) (*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) BundleFromPEMorDER

func (b *Bundler) BundleFromPEMorDER(certsRaw, keyPEM []byte, flavor BundleFlavor, password string) (*Bundle, error)

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

func (*Bundler) BundleFromRemote

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

BundleFromRemote fetches the certificate 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 certificate used by the server in this connection is used to build the bundle, which will necessarily be keyless.

func (*Bundler) VerifyOptions

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

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

type Option

type Option func(*options)

An Option sets options such as allowed key usages, etc.

func WithKeyUsages

func WithKeyUsages(usages ...x509.ExtKeyUsage) Option

WithKeyUsages lets you set which Extended Key Usage values are acceptable. By default x509.ExtKeyUsageAny will be used.