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
- type BundleFlavor
- type BundleStatus
- type Bundler
- 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
Constants ¶
This section is empty.
Variables ¶
var HTTPClient = http.DefaultClient
HTTPClient is an instance of http.Client that will be used for all HTTP requests.
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 ¶
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 ¶
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 verifies 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 ¶
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 ¶
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.