extensions

Documentation

Overview

Package extensions contains extensions to TLS certificate handling.

Index

• Constants
• Variables
• func AddExtraExtension(cert *x509.Certificate, exts ...pkix.Extension) (err error)
• func NewRevocationExt(key crypto.PrivateKey, revokedCert *x509.Certificate) (pkix.Extension, error)
• type Config
• type ExtensionID
• type HandlerFactories
  • func (factories *HandlerFactories) Register(newHandlers ...*HandlerFactory)
  • func (factories HandlerFactories) WithOptions(opts *Options) HandlerFuncMap
• type HandlerFactory
  • func NewHandlerFactory(id *ExtensionID, handlerFactory HandlerFactoryFunc) *HandlerFactory
  • func (handlerFactory *HandlerFactory) ID() *ExtensionID
  • func (handlerFactory *HandlerFactory) NewHandlerFunc(opts *Options) HandlerFunc
• type HandlerFactoryFunc
• type HandlerFunc
• type HandlerFuncMap
• type Options
• type Revocation
  • func (r Revocation) Marshal() ([]byte, error)
  • func (r *Revocation) Sign(key crypto.PrivateKey) error
  • func (r *Revocation) TBSBytes() []byte
  • func (r *Revocation) Unmarshal(data []byte) error
  • func (r Revocation) Verify(signingCert *x509.Certificate) error
• type RevocationDB

Constants

const (
	// RevocationBucket is the bolt bucket to store revocation data in.
	RevocationBucket = "revocations"
)

Variables

var (
	// DefaultHandlers is a slice of handlers that we use by default.
	//   - IDVersionHandler
	DefaultHandlers HandlerFactories

	// CAWhitelistSignedLeafHandler verifies that the leaf cert of the remote peer's
	// identity was signed by one of the CA certs in the whitelist.
	CAWhitelistSignedLeafHandler = NewHandlerFactory(
		&SignedCertExtID, caWhitelistSignedLeafHandler,
	)

	// SignedCertExtID is the asn1 object ID for a pkix extension holding a
	// signature of the cert it's extending, signed by some CA (e.g. the root cert chain).
	// This extensionHandler allows for an additional signature per certificate.
	SignedCertExtID = ExtensionID{2, 999, 1, 1}
	// RevocationExtID is the asn1 object ID for a pkix extension containing the
	// most recent certificate revocation data
	// for the current TLS cert chain.
	RevocationExtID = ExtensionID{2, 999, 1, 2}
	// IdentityVersionExtID is the asn1 object ID for a pkix extension that
	// specifies the identity version of the certificate chain.
	IdentityVersionExtID = ExtensionID{2, 999, 2, 1}
	// IdentityPOWCounterExtID is the asn1 object ID for a pkix extension that
	// specifies how many times to hash the CA public key to calculate the node ID.
	IdentityPOWCounterExtID = ExtensionID{2, 999, 2, 2}

	// Error is used when an error occurs while processing an extension.
	Error = errs.Class("extension")

	// ErrVerifyCASignedLeaf is used when a signed leaf extension signature wasn't produced
	// by any CA in the whitelist.
	ErrVerifyCASignedLeaf = Error.New("leaf not signed by any CA in the whitelist")
	// ErrUniqueExtensions is used when multiple extensions have the same Id.
	ErrUniqueExtensions = Error.New("extensions are not unique")
)

var (
	// RevocationCheckHandler ensures that a remote peer's certificate chain
	// doesn't contain any revoked certificates.
	RevocationCheckHandler = NewHandlerFactory(&RevocationExtID, revocationChecker)
	// RevocationUpdateHandler looks for certificate revocation extensions on a
	// remote peer's certificate chain, adding them to the revocation DB if valid.
	RevocationUpdateHandler = NewHandlerFactory(&RevocationExtID, revocationUpdater)
)

var ErrRevocation = errs.Class("revocation processing")

ErrRevocation is used when an error occurs involving a certificate revocation.

var ErrRevocationDB = errs.Class("revocation database")

ErrRevocationDB is used when an error occurs involving the revocations database.

var ErrRevocationTimestamp = Error.New("revocation timestamp is older than last known revocation")

ErrRevocationTimestamp is used when a revocation's timestamp is older than the last recorded revocation.

var ErrRevokedCert = ErrRevocation.New("a certificate in the chain is revoked")

ErrRevokedCert is used when a certificate in the chain is revoked and not expected to be.

Functions

func AddExtraExtension

func AddExtraExtension(cert *x509.Certificate, exts ...pkix.Extension) (err error)

AddExtraExtension adds one or more extensions to a certificate for serialization. NB: this *does not* serialize or persist the extension into the certificates's raw bytes. To add a persistent extension use `FullCertificateAuthority.AddExtension` or `ManageableIdentity.AddExtension`.

func NewRevocationExt

func NewRevocationExt(key crypto.PrivateKey, revokedCert *x509.Certificate) (pkix.Extension, error)

NewRevocationExt generates a revocation extension for a certificate.

Types

type Config

type Config struct {
	Revocation          bool `default:"true" help:"if true, client leaves may contain the most recent certificate revocation for the current certificate"`
	WhitelistSignedLeaf bool `` /* 197-byte string literal not displayed */
}

Config is used to bind cli flags for determining which extensions will be used by the server.

type ExtensionID

type ExtensionID = asn1.ObjectIdentifier

ExtensionID is an alias to an `asn1.ObjectIdentifier`.

type HandlerFactories

type HandlerFactories []*HandlerFactory

HandlerFactories is a collection of `HandlerFactory`s for convenience. Defines `Register` and `WithOptions` methods.

func (*HandlerFactories) Register

func (factories *HandlerFactories) Register(newHandlers ...*HandlerFactory)

Register adds an extension handler factory to the list.

func (HandlerFactories) WithOptions

func (factories HandlerFactories) WithOptions(opts *Options) HandlerFuncMap

WithOptions builds a `HandlerFuncMap` by calling each `HandlerFactory` with the passed `Options` pointer and using the respective `ExtensionID` pointer as the key.

type HandlerFactory

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

HandlerFactory holds a factory for a handler function given the passed `Options`. For use in handling extensions with the corresponding ExtensionID.

func NewHandlerFactory

func NewHandlerFactory(id *ExtensionID, handlerFactory HandlerFactoryFunc) *HandlerFactory

NewHandlerFactory builds a `HandlerFactory` pointer from an `ExtensionID` and a `HandlerFactoryFunc`.

func (*HandlerFactory) ID

func (handlerFactory *HandlerFactory) ID() *ExtensionID

ID returns the `ExtensionID` pointer stored with this factory. This factory will only handle extensions that have a matching id value.

func (*HandlerFactory) NewHandlerFunc

func (handlerFactory *HandlerFactory) NewHandlerFunc(opts *Options) HandlerFunc

NewHandlerFunc returns a new `HandlerFunc` with the passed `Options`.

type HandlerFactoryFunc

type HandlerFactoryFunc func(options *Options) HandlerFunc

HandlerFactoryFunc is a factory function used to build `HandlerFunc`s given the passed options.

type HandlerFunc

type HandlerFunc func(pkix.Extension, [][]*x509.Certificate) error

HandlerFunc takes an extension and the remote peer's certificate chains for use in extension handling.

type HandlerFuncMap

type HandlerFuncMap map[*ExtensionID]HandlerFunc

HandlerFuncMap maps an `ExtensionID` pointer to a `HandlerFunc`. Because an `ExtensionID` is a pointer , one can use a new pointer to the same asn1 object ID constant to store multiple `HandlerFunc`s for the same underlying extension id value.

type Options

type Options struct {
	PeerCAWhitelist []*x509.Certificate
	RevocationDB    RevocationDB
	PeerIDVersions  string
}

Options holds common options for use in handling extensions.

type Revocation

type Revocation struct {
	Timestamp int64
	KeyHash   []byte
	Signature []byte
}

Revocation represents a certificate revocation for storage in the revocation database and for use in a TLS extension.

func (Revocation) Marshal

func (r Revocation) Marshal() ([]byte, error)

Marshal serializes a revocation to bytes.

func (*Revocation) Sign

func (r *Revocation) Sign(key crypto.PrivateKey) error

Sign generates a signature using the passed key and attaches it to the revocation.

func (*Revocation) TBSBytes

func (r *Revocation) TBSBytes() []byte

TBSBytes (ToBeSigned) returns the hash of the revoked certificate key hash and the timestamp (i.e. hash(hash(cert bytes) + timestamp)).

func (*Revocation) Unmarshal

func (r *Revocation) Unmarshal(data []byte) error

Unmarshal deserializes a revocation from bytes.

func (Revocation) Verify

func (r Revocation) Verify(signingCert *x509.Certificate) error

Verify checks if the signature of the revocation was produced by the passed cert's public key.

type RevocationDB

type RevocationDB interface {
	Get(ctx context.Context, chain []*x509.Certificate) (*Revocation, error)
	Put(ctx context.Context, chain []*x509.Certificate, ext pkix.Extension) error
	List(ctx context.Context) ([]*Revocation, error)
}

RevocationDB stores certificate revocation data.