jwkutil

Documentation

Overview

Package jwkutil provides utilities for working with JSON Web Keys and JSON Web Key Sets as defined in RFC 7517.

Index

• Variables
• func LoadKey(path, keyID string) (jwk.Key, error)
• func NewKeyPair(keyID string, alg jwa.SignatureAlgorithm) (jwk.Set, jwk.Set, error)
• func NewSymmetricKeyPairFromString(id, key string, alg jwa.SignatureAlgorithm) (jwk.Set, jwk.Set, error)
• func Validate(key jwk.Key) error

Variables

var (
	ErrNoSigningKeyID = errors.New(
		"a signing key ID is required when using a JWKS that does not have exactly one signing key",
	)
	ErrNoFirstKey = errors.New(
		"could not retrieve first key from a JWKS that has exactly one signing key. Maybe the JWKS file is corrupt?",
	)
	ErrCouldNotFindKeyByID = errors.New("could not be found in JWKS")
)

var (
	ValidRSAAlgorithms = []jwa.SignatureAlgorithm{jwa.PS512}
	ValidECAlgorithms  = []jwa.SignatureAlgorithm{jwa.ES512}
	ValidOKPAlgorithms = []jwa.SignatureAlgorithm{jwa.EdDSA}

	ValidSigningAlgorithms = concat(
		ValidRSAAlgorithms,
		ValidECAlgorithms,
		ValidOKPAlgorithms,
	)

	ValidAlgsForKeyType = map[jwa.KeyType][]jwa.SignatureAlgorithm{
		jwa.RSA: {jwa.PS512},
		jwa.EC:  {jwa.ES512},
		jwa.OKP: {jwa.EdDSA},
	}

	UnsupportedAlgorithms = []jwa.SignatureAlgorithm{
		jwa.HS256, jwa.HS384, jwa.HS512,
		jwa.RS256, jwa.RS384, jwa.RS512,
	}
)

var (
	ErrKeyMissingAlg                         = errors.New("key is missing algorithm")
	ErrUnsupportedKeyType                    = errors.New("unsupported key type")
	ErrInvalidSigningAlgorithm               = errors.New("invalid signing algorithm")
	ErrUnsupportedSigningAlgorithm           = errors.New("unsupported signing algorithm")
	ErrUnsupportedSigningAlgorithmForKeyType = errors.New("unsupported signing algorithm for key type")
)

Functions

func LoadKey

func LoadKey(path, keyID string) (jwk.Key, error)

LoadKey parses a JSON Web Key Set from a file path and returns the JSON Web Key identified by `keyID`. If the `keyID` is empty and the JSON Web Key Set is a singleton, it returns the only key in the key set.

func NewKeyPair

func NewKeyPair(keyID string, alg jwa.SignatureAlgorithm) (jwk.Set, jwk.Set, error)

NewKeyPair generates a new key pair for the given algorithm and gives it the kid specified in `keyID`. The returned key sets contain the public and private keys and an error in that order.

func NewSymmetricKeyPairFromString

func NewSymmetricKeyPairFromString(id, key string, alg jwa.SignatureAlgorithm) (jwk.Set, jwk.Set, error)

NewSymmetricKeyPairFromString creates a symmetric key pair from the given key string and gives it the kid specified in `keyID`. Both returned jwk.Set values are the same symmetric key.

func Validate

func Validate(key jwk.Key) error

Validate takes a jwk and ensures that it's suitable for use as a key for use in signing and verifying Buildkite Job signatures. It checks that the key has an algorithm, and that the algorithm is supported for the key type - we don't support RS- series signing algorithms for RSA keys, for example, and we don't support HMAC signing algorithms at all. It does not check that the key is valid for signing or verifying.