kp

Documentation

Overview

Package kp describes transport key providers and provides a reference implementation.

KeyProviders are used by clients and servers as a mechanism for providing keys and signing CSRs. It is a mechanism designed to allow switching out how private keys and their associated certificates are managed, such as supporting PKCS #11. The StandardProvider provides disk-backed PEM-encoded certificates and private keys. DiskFallback is a provider that will attempt to retrieve the certificate from a CA first, falling back to a disk-backed pair. This is useful for test a CA while providing a failover solution.

Index

• Variables
• type KeyProvider
• type StandardPaths
• type StandardProvider
  • func NewStandardProvider(id *core.Identity) (*StandardProvider, error)
  • func (sp *StandardProvider) Certificate() *x509.Certificate
  • func (sp *StandardProvider) CertificateRequest(req *csr.CertificateRequest) ([]byte, error)
  • func (sp *StandardProvider) Check() error
  • func (sp *StandardProvider) Generate(algo string, size int) (err error)
  • func (sp *StandardProvider) Load() (err error)
  • func (sp *StandardProvider) Persistent() bool
  • func (sp *StandardProvider) Ready() bool
  • func (sp *StandardProvider) SetCertificatePEM(certPEM []byte) error
  • func (sp *StandardProvider) SignCSR(tpl *x509.CertificateRequest) ([]byte, error)
  • func (sp *StandardProvider) SignalFailure(err error) bool
  • func (sp *StandardProvider) Store() error
  • func (sp *StandardProvider) X509KeyPair() (tls.Certificate, error)

Variables

var (
	// ErrMissingKeyPath is returned if the StandardProvider has
	// specified a certificate path but not a key path.
	ErrMissingKeyPath = errors.New("transport: standard provider is missing a private key path to accompany the certificate path")

	// ErrMissingCertPath is returned if the StandardProvider has
	// specified a private key path but not a certificate path.
	ErrMissingCertPath = errors.New("transport: standard provider is missing a certificate path to accompany the certificate path")
)

var ErrCertificateUnavailable = errors.New("transport: certificate unavailable")

ErrCertificateUnavailable is returned when a key is available, but there is no accompanying certificate.

Types

type KeyProvider

type KeyProvider interface {
	// Certificate returns the associated certificate, or nil if
	// one isn't ready.
	Certificate() *x509.Certificate

	// Given some metadata about a certificate request, the
	// provider should be able to generate a new CSR.
	CertificateRequest(*csr.CertificateRequest) ([]byte, error)

	// Check returns an error if the provider has an invalid setup.
	Check() error

	// Generate should trigger the creation of a new private
	// key. This will invalidate any certificates stored in the
	// key provider.
	Generate(algo string, size int) error

	// Load causes a private key and certificate associated with
	// this provider to be loaded into memory and be prepared for
	// use.
	Load() error

	// Persistent returns true if the provider keeps state on disk.
	Persistent() bool

	// Ready returns true if the provider has a key and
	// certificate.
	Ready() bool

	// SetCertificatePEM takes a PEM-encoded certificate and
	// associates it with this key provider.
	SetCertificatePEM([]byte) error

	// SignalFailure is used to notify the KeyProvider that an
	// error has occurred obtaining a certificate. If this returns
	// true, the caller should re-attempt to refresh the
	// keys. This, for example, can be used to implement failover
	// key providers that require different keys.
	SignalFailure(err error) bool

	// SignCSR allows a templated CSR to be signed.
	SignCSR(csr *x509.CertificateRequest) ([]byte, error)

	// Store should perform whatever actions are necessary such
	// that a call to Load later will reload the key and
	// certificate associated with this provider.
	Store() error

	// X509KeyPair returns a tls.Certficate. The returns
	// tls.Certificate should have a parsed Leaf certificate.
	X509KeyPair() (tls.Certificate, error)
}

A KeyProvider provides some mechanism for managing private keys and certificates. It is not required to store the crypto.Signer itself.

type StandardPaths

type StandardPaths struct {
	KeyFile  string `json:"private_key"`
	CertFile string `json:"certificate"`
}

StandardPaths contains a path to a key file and certificate file.

type StandardProvider

type StandardProvider struct {
	Paths StandardPaths `json:"paths"`
	// contains filtered or unexported fields
}

StandardProvider provides unencrypted PEM-encoded certificates and private keys. If paths are provided, the key and certificate will be stored on disk.

func NewStandardProvider

func NewStandardProvider(id *core.Identity) (*StandardProvider, error)

NewStandardProvider sets up new StandardProvider from the information contained in an Identity.

func (*StandardProvider) Certificate

func (sp *StandardProvider) Certificate() *x509.Certificate

Certificate returns the associated certificate, or nil if one isn't ready.

func (*StandardProvider) CertificateRequest

func (sp *StandardProvider) CertificateRequest(req *csr.CertificateRequest) ([]byte, error)

CertificateRequest takes some metadata about a certificate request, and attempts to produce a certificate signing request suitable for sending to a certificate authority.

func (*StandardProvider) Check

func (sp *StandardProvider) Check() error

Check ensures that the paths are valid for the provider.

func (*StandardProvider) Generate

func (sp *StandardProvider) Generate(algo string, size int) (err error)

Generate generates a new private key.

func (*StandardProvider) Load

func (sp *StandardProvider) Load() (err error)

Load a private key and certificate from disk.

func (*StandardProvider) Persistent

func (sp *StandardProvider) Persistent() bool

Persistent returns true if the key and certificate will be stored on disk.

func (*StandardProvider) Ready

func (sp *StandardProvider) Ready() bool

Ready returns true if the provider has a key and certificate loaded. The certificate should be checked by the end user for validity.

func (*StandardProvider) SetCertificatePEM

func (sp *StandardProvider) SetCertificatePEM(certPEM []byte) error

SetCertificatePEM receives a PEM-encoded certificate and loads it into the provider.

func (*StandardProvider) SignCSR

func (sp *StandardProvider) SignCSR(tpl *x509.CertificateRequest) ([]byte, error)

SignCSR takes a template certificate request and signs it.

func (*StandardProvider) SignalFailure

func (sp *StandardProvider) SignalFailure(err error) bool

SignalFailure is provided to implement the KeyProvider interface, and always returns false.

func (*StandardProvider) Store

func (sp *StandardProvider) Store() error

Store writes the key and certificate to disk, if necessary.

func (*StandardProvider) X509KeyPair

func (sp *StandardProvider) X509KeyPair() (tls.Certificate, error)

X509KeyPair returns a tls.Certificate for the provider.