vpki

README

vpki

-- import "astuart.co/vpki"

Package vpki provides a layer of abstraction between the golang stdlib crypto primitives and common crypto uses (e.g. serving HTTPS) and the functionality provided by Vault. Internally, the library generates private keys locally and sends CSRs to the vault server, so that private keys are never transmitted.

Usage

var (

	//DefaultTTL is the default TTL the library will request for certificates
	DefaultTTL = day
	//DefaultStrength is the default strength of RSA keys generated
	DefaultStrength = 2048
)

func ListenAndServeTLS

func ListenAndServeTLS(addr string, handler http.Handler, crt Certifier) error

ListenAndServeTLS mostly mirrors the http.ListenAndServeTLS API, but generates the certificates for the server automatically via vault, with a short TTL. The function only needs an additional Certifier parameter which can generate signed certificates in order to work properly.

type Certifier

type Certifier interface {
	Cert(cn string) (*tls.Certificate, error)
}

Certifier abstracts any object that can provide signed certificates (hopefully valid for their use case). Concrete implementations ought to provide their own ways to configure TTL, key strength, etc. The default provided implementation is vpki.Client.

type Client

type Client struct {
	Mount, Role, Addr, Email string
	Strength                 int
	TTL                      time.Duration
	HTTPClient               *http.Client
}

Client is the abstraction for a vault client, with convenience methods for obtaining golang tls.Certificates with minimum risk of key disclosure (keys are generated locally then CSRs sent to Vault).

func (*Client) Cert

func (c *Client) Cert(cn string) (*tls.Certificate, error)

Cert takes a server CommonName and retruns a tls.Certificate with a pre-parsed Leaf, or an error. The strength and ttl for the CSR are determined by the Client fields of the same names.

func (*Client) RawCert

func (c *Client) RawCert(cn string) (*RawPair, error)

RawCert is a very high-level method used to obtain the raw certificate data.

func (*Client) RawSignCSR

func (c *Client) RawSignCSR(csr *x509.CertificateRequest, k *rsa.PrivateKey, ttl time.Duration) (*RawPair, error)

RawSignCSR takes a certificate request template, private keye, and ttl, and returns the private/public keypair, unparsed, for any applications which may need to consume the certificates directly in their PEM form. The RawPair struct is used to help prevent transposition errors by explicitly naming the public/private pairs rather than returning two byte slices.

func (*Client) SetToken

func (c *Client) SetToken(t string)

SetToken sets the Vault token for the Client.

func (*Client) SignCSR

func (c *Client) SignCSR(csr *x509.CertificateRequest, k *rsa.PrivateKey, ttl time.Duration) (*tls.Certificate, error)

SignCSR takes an CertificateRequest template and ttl, and returns a tls.Certificate with a pre-parsed leaf, or an error.

type RawPair

type RawPair struct {
	Private, Public []byte
}

RawPair is a simple explicitly-named pair of byte slices returned by the RawPair function.

func RawCert

func RawCert(c Certifier, cn string) (*RawPair, error)

RawCert is a more-generic function that can take any certifier and return the PEM-encoded bytes for a requested common_name.

type SNICertifier

type SNICertifier interface {
	GetCertificate(*tls.ClientHelloInfo) (*tls.Certificate, error)
}

SNICertifier abstracts the basic GetCertificate method used in TLSOpts, and also implemented by libraries like rsc.io/letsencrypt

type ValidationError

type ValidationError struct {
	Domain   string
	Original error
}

func (*ValidationError) Error

func (ve *ValidationError) Error() string

type VaultError

type VaultError struct {
	Client Client
	Orig   error
}

VaultError is an error originating from a vault client. Errors coming from the vpki library should be type checked against this error (use a type switch)

func (*VaultError) Error

func (ve *VaultError) Error() string

Documentation

Overview

Package vpki provides a layer of abstraction between the golang stdlib crypto primitives and common crypto uses (e.g. serving HTTPS) and the functionality provided by Vault. Internally, the library generates private keys locally and sends CSRs to the vault server, so that private keys are never transmitted.

Index

• Variables
• func ListenAndServeTLS(addr string, handler http.Handler, crt Certifier) error
• type Certifier
• type Client
  • func (c *Client) Cert(cn string) (*tls.Certificate, error)
  • func (c *Client) GenCert(template *x509.CertificateRequest) (*RawPair, error)
  • func (c *Client) RawCert(cn string) (*RawPair, error)
  • func (c *Client) RawSignCSR(csr *x509.CertificateRequest, k *rsa.PrivateKey, ttl time.Duration) (*RawPair, error)
  • func (c *Client) RawSignCSRBytes(csr []byte, cn string, ttl time.Duration) ([]byte, error)
  • func (c *Client) RawSignIntermediateCSRBytes(csr []byte, cn string, ttl time.Duration) ([]byte, error)
  • func (c *Client) SetToken(t string)
  • func (c *Client) SignCSR(csr *x509.CertificateRequest, k *rsa.PrivateKey, ttl time.Duration) (*tls.Certificate, error)
• type RawCertifier
• type RawMarshaler
  • func (r *RawMarshaler) Cert(cn string) (*tls.Certificate, error)
• type RawPair
  • func RawCert(c Certifier, cn string) (*RawPair, error)
• type SNICertifier
• type ValidationError
  • func (ve *ValidationError) Error() string
• type VaultError
  • func (ve *VaultError) Error() string

Variables

var (

	//DefaultTTL is the default TTL the library will request for certificates
	DefaultTTL = day
	//DefaultStrength is the default strength of RSA keys generated
	DefaultStrength = 2048
)

Functions

func ListenAndServeTLS

func ListenAndServeTLS(addr string, handler http.Handler, crt Certifier) error

ListenAndServeTLS mostly mirrors the http.ListenAndServeTLS API, but generates the certificates for the server automatically via vault, with a short TTL. The function only needs an additional Certifier parameter which can generate signed certificates in order to work properly.

Types

type Certifier

type Certifier interface {
	Cert(cn string) (*tls.Certificate, error)
}

Certifier abstracts any object that can provide signed certificates (hopefully valid for their use case). Concrete implementations ought to provide their own ways to configure TTL, key strength, etc. The default provided implementation is vpki.Client.

type Client

type Client struct {
	Mount, Role, Addr, Email string
	Strength                 int
	TTL                      time.Duration
	HTTPClient               *http.Client
	// contains filtered or unexported fields
}

Client is the abstraction for a vault client, with convenience methods for obtaining golang tls.Certificates with minimum risk of key disclosure (keys are generated locally then CSRs sent to Vault).

func (*Client) Cert

func (c *Client) Cert(cn string) (*tls.Certificate, error)

Cert takes a server CommonName and retruns a tls.Certificate with a pre-parsed Leaf, or an error. The strength and ttl for the CSR are determined by the Client fields of the same names.

func (*Client) GenCert

func (c *Client) GenCert(template *x509.CertificateRequest) (*RawPair, error)

GenCert takes a CertificateRequest template, generates a key, obtains a signed certificate, and returns the lot

func (*Client) RawCert

func (c *Client) RawCert(cn string) (*RawPair, error)

RawCert is a very high-level method used to obtain the raw certificate data.

func (*Client) RawSignCSR

func (c *Client) RawSignCSR(csr *x509.CertificateRequest, k *rsa.PrivateKey, ttl time.Duration) (*RawPair, error)

RawSignCSR takes a certificate request template, private keye, and ttl, and returns the private/public keypair, unparsed, for any applications which may need to consume the certificates directly in their PEM form. The RawPair struct is used to help prevent transposition errors by explicitly naming the public/private pairs rather than returning two byte slices.

func (*Client) RawSignCSRBytes

func (c *Client) RawSignCSRBytes(csr []byte, cn string, ttl time.Duration) ([]byte, error)

RawSignCSRBytes takes the bytes of a Certificate Signing Request, the CN and the ttl, and returns raw bytes of the signed certificate bundle.

func (*Client) RawSignIntermediateCSRBytes

func (c *Client) RawSignIntermediateCSRBytes(csr []byte, cn string, ttl time.Duration) ([]byte, error)

RawSignIntermediateCSRBytes takes the bytes of a Certificate Signing Request, the CN and the ttl, and returns raw bytes of the signed certificate bundle.

func (*Client) SetToken

func (c *Client) SetToken(t string)

SetToken sets the Vault token for the Client.

func (*Client) SignCSR

func (c *Client) SignCSR(csr *x509.CertificateRequest, k *rsa.PrivateKey, ttl time.Duration) (*tls.Certificate, error)

SignCSR takes an CertificateRequest template and ttl, and returns a tls.Certificate with a pre-parsed leaf, or an error.

type RawCertifier

type RawCertifier interface {
	RawCert(string) (*RawPair, error)
}

RawCertifier is an interface implemented by types that can give back a RawPair

type RawMarshaler

type RawMarshaler struct {
	RawCertifier
}

RawMarshaler abstracts a RawCertifier and offers to return parsed tls.Certificates

func (*RawMarshaler) Cert

func (r *RawMarshaler) Cert(cn string) (*tls.Certificate, error)

Cert uses the original interface's RawCert method and returns a tls.Certificate

type RawPair

type RawPair struct {
	Private, Public []byte
}

RawPair is a simple explicitly-named pair of byte slices returned by the RawPair function.

func RawCert

func RawCert(c Certifier, cn string) (*RawPair, error)

RawCert is a more-generic function that can take any certifier and return the PEM-encoded bytes for a requested common_name.

type SNICertifier

type SNICertifier interface {
	GetCertificate(*tls.ClientHelloInfo) (*tls.Certificate, error)
}

SNICertifier abstracts the basic GetCertificate method used in TLSOpts, and also implemented by libraries like rsc.io/letsencrypt

type ValidationError

type ValidationError struct {
	Domain   string
	Original error
}

ValidationError is a structured type that contains additional error context.

func (*ValidationError) Error

func (ve *ValidationError) Error() string

type VaultError

type VaultError struct {
	Client Client
	Orig   error
}

VaultError is an error originating from a vault client. Errors coming from the vpki library should be type checked against this error (use a type switch)

func (*VaultError) Error

func (ve *VaultError) Error() string