jwk

Documentation

Overview

Package jwk implements JWK functionality as defined in RFC 7517.

Index

• Constants
• func ECDSAPublicKey(v Value) (pkey *ecdsa.PublicKey, blindingValue []byte, err error)
• func ECDSAValues(v Value) (crv, x, y string, err error)
• func Ed25519PublicKey(v Value) (pkey ed25519.PublicKey, err error)
• func Ed25519Values(v Value) (x string, err error)
• func HMACSecretKey(v Value) ([]byte, error)
• func RSAPublicKey(v Value) (pkey *rsa.PublicKey, blindingValue []byte, err error)
• func RSAValues(v Value) (n, e, d string, err error)
• func SymmetricKey(v Value) (k string, err error)
• func Validate(v Value) error
• type ECDSA
• type ParameterName
• type RSA
• type Set
  • func FetchSet(ctx context.Context, url string, client *http.Client) (*Set, error)
  • func (s *Set) Get(keyID string) (Value, error)
  • func (s *Set) Validate() error
• type Symmetric
• type URLSetCache
  • func NewURLSetCache(client *http.Client, refreshInterval, cacheDuration time.Duration) *URLSetCache
  • func (c *URLSetCache) Fetch(ctx context.Context, url string) (*Set, error)
  • func (c *URLSetCache) Get(ctx context.Context, url string) (*Set, error)
  • func (c *URLSetCache) GetKey(ctx context.Context, url string, keyID string) (Value, error)
  • func (c *URLSetCache) Range(fn func(url string, key Value) bool)
  • func (c *URLSetCache) Refresh(ctx context.Context, url string) (*Set, error)
  • func (c *URLSetCache) RefreshAll(ctx context.Context) error
  • func (c *URLSetCache) Start(ctx context.Context) error
• type Value
  • func ValueFromPublicKey(pubKey any) (Value, error)

Constants

const (
	KeyType              ParameterName = "kty"      // https://datatracker.ietf.org/doc/html/rfc7517#section-4.1
	PublicKeyUse         ParameterName = "use"      // https://datatracker.ietf.org/doc/html/rfc7517#section-4.2
	KeyOperations        ParameterName = "key_ops"  // https://datatracker.ietf.org/doc/html/rfc7517#section-4.3
	Algorithm            ParameterName = "alg"      // https://datatracker.ietf.org/doc/html/rfc7517#section-4.4
	KeyID                ParameterName = "kid"      // https://datatracker.ietf.org/doc/html/rfc7517#section-4.5
	X509URL              ParameterName = "x5u"      // https://datatracker.ietf.org/doc/html/rfc7517#section-4.6
	X509CertificateChain ParameterName = "x5c"      // https://datatracker.ietf.org/doc/html/rfc7517#section-4.7
	X509SHA1Thumbprint   ParameterName = "x5t"      // https://datatracker.ietf.org/doc/html/rfc7517#section-4.8
	X509SHA256Thumbprint ParameterName = "x5t#S256" // https://datatracker.ietf.org/doc/html/rfc7517#section-4.9

	// K is the symmetric key value within a JWK.
	// https://datatracker.ietf.org/doc/html/rfc7517#appendix-A.3
	K Symmetric = "k"

	// Curve is the curve value within an ECDSA JWK, such as "P-256".
	// https://datatracker.ietf.org/doc/html/rfc7517#appendix-A.3
	Curve ECDSA = "crv"
	X     ECDSA = "x" // X is the x-coordinate for the elliptic curve point.
	Y     ECDSA = "y" // Y is the y-coordinate for the elliptic curve point.

	N RSA = "n" // N is the RSA public modulus value.
	E RSA = "e" // E is the RSA public exponent value.
	D RSA = "d" // D is the RSA private exponent value.
)

Functions

func ECDSAPublicKey

func ECDSAPublicKey(v Value) (pkey *ecdsa.PublicKey, blindingValue []byte, err error)

ECDSAPublicKey returns the ECDSA public key and blinding value, or an error if the key is not an ECDSA public key.

func ECDSAValues

func ECDSAValues(v Value) (crv, x, y string, err error)

ECDSAValues returns the values for the ECDSA key type.

func Ed25519PublicKey

func Ed25519PublicKey(v Value) (pkey ed25519.PublicKey, err error)

Ed25519PublicKey returns the Ed25519 public key, or an error if the key is not an Ed25519 public key.

func Ed25519Values

func Ed25519Values(v Value) (x string, err error)

Ed25519Values returns the values for the Ed25519 key type.

func HMACSecretKey

func HMACSecretKey(v Value) ([]byte, error)

HMACSecretKey returns the HMAC secret key (symmetric key).

func RSAPublicKey

func RSAPublicKey(v Value) (pkey *rsa.PublicKey, blindingValue []byte, err error)

RSAPublicKey returns the RSA public key and blinding value, or an error if the key is not an RSA public key.

func RSAValues

func RSAValues(v Value) (n, e, d string, err error)

RSAValues returns the values for the RSA key type.

func SymmetricKey

func SymmetricKey(v Value) (k string, err error)

SymmetricKey returns the symmetric key.

func Validate

func Validate(v Value) error

Validate checks that the required parameters are present for the given key type, and that the values are valid.

Types

type ECDSA

type ECDSA = ParameterName

https://datatracker.ietf.org/doc/html/rfc7517#section-4

type ParameterName

type ParameterName = string

https://datatracker.ietf.org/doc/html/rfc7517#section-4

type RSA

type RSA = ParameterName

https://datatracker.ietf.org/doc/html/rfc7517#section-4

type Set

type Set struct {
	// Keys is a list of JWK values.
	//
	// https://datatracker.ietf.org/doc/html/rfc7517#section-5.1
	Keys []Value `json:"keys"`
}

Set is a JWK set as defined in RFC 7517.

https://datatracker.ietf.org/doc/html/rfc7517#section-5

func FetchSet

func FetchSet(ctx context.Context, url string, client *http.Client) (*Set, error)

FetchSet fetches a JWK set from the given URL and HTTP client.

func (*Set) Get

func (s *Set) Get(keyID string) (Value, error)

Get returns the key that matches the given key id.

func (*Set) Validate

func (s *Set) Validate() error

Validate validates the JWK set, returning an error if any of the keys are invalid.

type Symmetric

type Symmetric = ParameterName

https://datatracker.ietf.org/doc/html/rfc7517#section-4

type URLSetCache

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

URLSetCache is a cache of JWK sets keyed by URL that can be easily used to verify JWTs from multiple issuers. It handles refreshing the JWK sets when they expire, retrying failed fetches, and caching the JWK sets for a configurable amount of time.

func NewURLSetCache

func NewURLSetCache(client *http.Client, refreshInterval, cacheDuration time.Duration) *URLSetCache

NewURLSetCache returns a new JWK set cache.

func (*URLSetCache) Fetch

func (c *URLSetCache) Fetch(ctx context.Context, url string) (*Set, error)

Fetch fetches the JWK set for the given URL.

func (*URLSetCache) Get

func (c *URLSetCache) Get(ctx context.Context, url string) (*Set, error)

Get returns the JWK set for the given URL, fetching it if it is not already cached.

func (*URLSetCache) GetKey

func (c *URLSetCache) GetKey(ctx context.Context, url string, keyID string) (Value, error)

GetKey returns the first key from the JWK set for the given URL that matches the given key id, fetching the JWK set if it is not already cached.

func (*URLSetCache) Range

func (c *URLSetCache) Range(fn func(url string, key Value) bool)

Range iterates over the JWK sets in the cache, calling the given function for each URL and key. If the function returns false, the iteration will stop.

func (*URLSetCache) Refresh

func (c *URLSetCache) Refresh(ctx context.Context, url string) (*Set, error)

Refresh refreshes the JWK set for the given URL.

func (*URLSetCache) RefreshAll

func (c *URLSetCache) RefreshAll(ctx context.Context) error

RefreshAll refreshes all JWK sets in the cache.

func (*URLSetCache) Start

func (c *URLSetCache) Start(ctx context.Context) error

Start starts the JWK set cache, refreshing the JWK sets at the given interval. It will block until the context is canceled, and will only return an error if the refresh fails, possibly due to a network error.

Most callers will want to call this in a goroutine after creating the cache.

type Value

type Value = map[ParameterName]any

Value is a JSON object containing the parameters describing the cryptographic operations and parameters employed.

https://datatracker.ietf.org/doc/html/rfc7517#section-4

func ValueFromPublicKey

func ValueFromPublicKey(pubKey any) (Value, error)

ValueFromPublicKey returns a JWK value from the given public key.