mtls

Documentation

Overview

Package mtls has helper functionality for organizing and maintaining key material on disk and establishing connections between servers and clients using mTLS cryptography.

Index

• Variables
• func CertPool(providers ...*Provider) (pool *x509.CertPool, err error)
• func ClientCreds(endpoint string, chain *Provider, trusted ...*Provider) (_ grpc.DialOption, err error)
• func Config(chain *Provider, trusted ...*Provider) (_ *tls.Config, err error)
• func ServerCreds(chain *Provider, trusted ...*Provider) (_ grpc.ServerOption, err error)
• type Provider
  • func Load(path string) (provider *Provider, err error)
  • func New(chain []byte) (provider *Provider, err error)
  • func (p *Provider) Decode(reader *pem.Reader) (err error)
  • func (p *Provider) Dump(path string) (err error)
  • func (p *Provider) Encode(writer *pem.Writer) (err error)
  • func (p *Provider) GetKey() interface{}
  • func (p *Provider) GetKeyPair() (_ tls.Certificate, err error)
  • func (p *Provider) GetLeafCertificate() (*x509.Certificate, error)
  • func (p *Provider) GetRSAKey() (key *rsa.PrivateKey, err error)
  • func (p *Provider) IsPrivate() bool
  • func (p *Provider) String() string

Variables

var (
	ErrPrivateKeyRequired = errors.New("provider must contain a private key to initialize TLS certs")
	ErrNoCertificates     = errors.New("provider does not contain any certificates")
	ErrMissingKey         = errors.New("provider does not contain a private key")
	ErrZipEmpty           = errors.New("zip archive contains no providers")
	ErrZipTooMany         = errors.New("multiple providers in zip, is this a provider pool?")
)

Standard errors for error type checking

Functions

func CertPool

func CertPool(providers ...*Provider) (pool *x509.CertPool, err error)

CertPool returns an x509.CertPool, a collection of certificates with public keys that are used to verify clients or servers when connecting over mTLS. The CertPool is constructed from the providers passed in (whether they are private or not) and the collected CertPool is returned. This pool is provider-specific and does not include system certificates.

func ClientCreds

func ClientCreds(endpoint string, chain *Provider, trusted ...*Provider) (_ grpc.DialOption, err error)

ClientCreds returns a grpc.DialOption to connect a gRPC client with mTLS.

func Config

func Config(chain *Provider, trusted ...*Provider) (_ *tls.Config, err error)

Config returns a standardized mTLS configuration for all clients and servers that are using this package. The certificate is provided from the private provider and any additional providers can be added to extend the cert pool for verification.

func ServerCreds

func ServerCreds(chain *Provider, trusted ...*Provider) (_ grpc.ServerOption, err error)

ServerCreds returns a grpc.ServerOption to create a gRPC server with mTLS.

Types

type Provider

type Provider struct {
	// contains filtered or unexported fields
}

Provider wraps a PEM-encoded certificate chain, which can optionally include private keys and an additional pool of valid certificates. Providers with keys (referred to as private providers) are used to instantiate mTLS servers and to make secure connections from clients to servers.

func Load

func Load(path string) (provider *Provider, err error)

Load opens the certificate chain at the specified path and reads the data. TODO: handle compressed formats.

func New

func New(chain []byte) (provider *Provider, err error)

New creates a provider from PEM encoded data.

func (*Provider) Decode

func (p *Provider) Decode(reader *pem.Reader) (err error)

Decode PEM blocks and adds them to the provider. Certificates are appended to the Provider chain and Private Keys are decoded from PKCS8. All other block types return an error and stop processing the block or chain. Only the private key is verified for correctness, certificates are unverified.

func (*Provider) Dump

func (p *Provider) Dump(path string) (err error)

Dump the provider to the specified path for serialization.

func (*Provider) Encode

func (p *Provider) Encode(writer *pem.Writer) (err error)

Encode Provider in PCKS12 PEM format for serialization. Certificates are written to the array first. If the private key exists, it is written as the last PEM block.

func (*Provider) GetKey

func (p *Provider) GetKey() interface{}

GetKey returns the private key, or nil if this is a public provider.

func (*Provider) GetKeyPair

func (p *Provider) GetKeyPair() (_ tls.Certificate, err error)

GetKeyPair returns a tls.Certificate parsed from the PEM encoded data maintained by the provider. This method uses tls.X509KeyPair to ensure that the public/private key pair are suitable for use with an HTTP Server.

func (*Provider) GetLeafCertificate

func (p *Provider) GetLeafCertificate() (*x509.Certificate, error)

GetLeafCertificate returns the parsed x509 leaf certificate if it exists, returning an error if there are no certificates or if there is a parse error.

func (*Provider) GetRSAKey

func (p *Provider) GetRSAKey() (key *rsa.PrivateKey, err error)

GetRSAKeys returns a fully constructed RSA PrivateKey that includes the public key material property. This method errors if the key is not an RSA key or does not exist.

func (*Provider) IsPrivate

func (p *Provider) IsPrivate() bool

IsPrivate returns true if the Provider contains a non-nil key.

func (*Provider) String

func (p *Provider) String() string

String returns the common name of the Provider from the leaf certificate.