tinyca

Documentation

Overview

Package tinyca implements a small and flexible Certificate Authority. The CA issues client certificates signed by a root certificate and private key.

tinyca exposes a simple HTTP API to issue certificates. tinyca is primarily meant to issue client certificates for mTLS authentication.

The CA also provides an interface to customize the certificate template. This allows applications to add application-specific data to issued certificates, along with the standard bifrost fields.

Index

• Constants
• func CACertTemplate(ns, id uuid.UUID) (*x509.Certificate, error)
• func ParseValidity(notBefore string, notAfter string) (time.Time, time.Time, error)
• func TLSClientCertTemplate() *x509.Certificate
• type CA
  • func New(cert *bifrost.Certificate, key *bifrost.PrivateKey, gauntlet Gauntlet) (*CA, error)
  • func (ca *CA) AddRoutes(mux *http.ServeMux, metrics bool)
  • func (ca *CA) Close() error
  • func (ca *CA) IssueCertificate(asn1CSR []byte, notBefore, notAfter time.Time) ([]byte, error)
  • func (ca *CA) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type Gauntlet

Constants

const GauntletTimeout = 100 * time.Millisecond

GauntletTimeout is the maximum time the CA Gauntlet function is allowed to run.

const MaxIssueValidity = 30 * 24 * time.Hour

MaxIssueValidity is the maximum validity period for issued certificates.

Functions

func CACertTemplate

func CACertTemplate(ns, id uuid.UUID) (*x509.Certificate, error)

CACertTemplate returns a new x509.Certificate template for a CA certificate.

func ParseValidity

func ParseValidity(notBefore string, notAfter string) (time.Time, time.Time, error)

ParseValidity parses notBefore and notAfter into time.Time values. notBefore and notAfter can either be in RFC3339 format or a duration offset from the current time. Offset durations are parsed using time.ParseDuration. If notBefore is empty or set to "now", it defaults to the current time. If notAfter is empty, it behaves as if it is set to "+1h". Negative validity periods are not allowed.

func TLSClientCertTemplate

func TLSClientCertTemplate() *x509.Certificate

TLSClientCertTemplate returns a new x509.Certificate template for a client certificate.

Types

type CA

type CA struct {
	io.Closer
	// contains filtered or unexported fields
}

CA is a simple Certificate Authority. The CA issues client certificates signed by a root certificate and private key. The CA provides an HTTP handler to issue certificates. The CA also provides a Gauntlet function to customize the certificate template. Call Close to release resources when done.

func New

func New(
	cert *bifrost.Certificate,
	key *bifrost.PrivateKey,
	gauntlet Gauntlet,
) (*CA, error)

New returns a new Certificate Authority. CA signs client certificates with the provided root certificate and private key. CA uses the provided gauntlet func to customise issued certificates.

func (*CA) AddRoutes

func (ca *CA) AddRoutes(mux *http.ServeMux, metrics bool)

AddRoutes adds the CA's HTTP handlers to the provided ServeMux. The CA's HTTP handlers are: - GET /namespace: returns the namespace of the CA. - POST /issue: issues a certificate.

func (*CA) Close

func (ca *CA) Close() error

Close releases resources held by the CA. Multiple calls to Close are safe.

func (*CA) IssueCertificate

func (ca *CA) IssueCertificate(asn1CSR []byte, notBefore, notAfter time.Time) ([]byte, error)

IssueCertificate issues a client certificate for a valid certificate request parsed from asn1CSR.

func (*CA) ServeHTTP

func (ca *CA) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP issues a certificate if a valid certificate request is read from the request.

Requests carrying a content-type of "text/plain" should have a PEM encoded certificate request. Requests carrying a content-type of "application/octet-stream" should submit the ASN.1 DER encoded form instead.

type Gauntlet

type Gauntlet func(ctx context.Context, csr *bifrost.CertificateRequest) (tmpl *x509.Certificate, err error)

Gauntlet is the signature for a function that validates a certificate request. If the second return value is non-nil, then the certificate request is denied. If the first return value is nil, the default template TLSClientCertTemplate will be used. If the function exceeds GauntletTimeout, ctx will be cancelled and the request will be denied with an error. The template will be used to issue a client certificate. Consult the x509 package for the full list of fields that can be set. tinyca will overwrite the following template fields:

• NotBefore
• NotAfter
• SignatureAlgorithm
• Issuer
• Subject.Organization
• Subject.CommonName

If SerialNumber is nil, a random value will be generated.