keychainjwt

README

keychainjwt

A Go library for handling certificate-based trust chain secured JWS and JWTs.

Features

• Extracts and validates the certificate chains from JWS/JWTs against trusted roots.
• Customizable trust policies and options

Installation

To install the library, use go get:

go get github.com/xmidt-org/keychainjwt

Documentation

Index

• Variables
• type Option
  • func RequirePolicies(policies ...string) Option
  • func TrustedIntermediates(cert ...*x509.Certificate) Option
  • func TrustedRoots(cert ...*x509.Certificate) Option
  • func WithTimeFunc(now func() time.Time) Option
• type Trust
  • func New(opts ...Option) (*Trust, error)
  • func (t Trust) GetKey(text []byte) (alg string, key any, err error)
  • func (t Trust) Roots() []*x509.Certificate

Variables

var (
	ErrUnexpectedSigner = errors.New("expected exactly one signer")
	ErrMissingHeader    = errors.New("header is missing")
	ErrDisallowedAlg    = errors.New("disallowed alg type")
	ErrDecodingCert     = errors.New("decoding cert error")
	ErrParsingCert      = errors.New("cert parsing error")
	ErrInvalidCert      = errors.New("invalid cert")
	ErrMissingPolicy    = errors.New("missing policy")
	ErrParsingJWT       = errors.New("invalid jwt")
	ErrValidatingChain  = errors.New("chain validation problem")
)

Types

type Option

type Option interface {
	// contains filtered or unexported methods
}

Option is an interface that defines a function to apply an option to a Trust object.

func RequirePolicies

func RequirePolicies(policies ...string) Option

RequirePolicies sets the required policies for the Trust object.

func TrustedIntermediates

func TrustedIntermediates(cert ...*x509.Certificate) Option

TrustedIntermediates adds the provided intermediate certificates to the Trust object.

func TrustedRoots

func TrustedRoots(cert ...*x509.Certificate) Option

TrustedRoots adds the provided root certificates to the Trust object.

func WithTimeFunc

func WithTimeFunc(now func() time.Time) Option

WithTimeFunc sets the function to retrieve the current time for the Trust object.

type Trust

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

Trust is a struct that holds the trusted roots, intermediates, and policies for verifying a JWT or JWS signature based on the x5c header.

func New

func New(opts ...Option) (*Trust, error)

New creates a new Trust object with the provided options. If no options are provided, the Trust object is created with no trusted roots, intermediates, or required policies. The current time function is set to time.Now by default. Unless the system CA store is passed in as an option, it is not used since that would default to trusting more than expected.

func (Trust) GetKey

func (t Trust) GetKey(text []byte) (alg string, key any, err error)

GetKey returns the public key from the x5c header of a JWS/JWT signature if the signature is valid and the certificate chain is trusted. The public key is returned as an interface{} to allow for different key types. If the provided text is not a valid JWS/JWT, the x5c header is missing, or the certificate chain is not trusted, an error is returned. The algorithm string provided in the header is also returned.

func (Trust) Roots

func (t Trust) Roots() []*x509.Certificate

Roots returns the trusted root certificates for the Trust object.