jwk

Documentation

Overview

Package jwk implements JWK as described in https://tools.ietf.org/html/rfc7517

Example

package main

import (
	"log"

	"github.com/lestrrat-go/jwx/jwk"
)

func main() {
	set, err := jwk.Fetch("https://foobar.domain/json")
	if err != nil {
		log.Printf("failed to parse JWK: %s", err)
		return
	}

	// If you KNOW you have exactly one key, you can just
	// use set.Keys[0]
	keys := set.LookupKeyID("mykey")
	if len(keys) == 0 {
		log.Printf("failed to lookup key: %s", err)
		return
	}

	var key interface{}
	if err := keys[0].Raw(&key); err != nil {
		log.Printf("failed to generate public key: %s", err)
		return
	}
	// Use key for jws.Verify() or whatever
	_ = key
}

Index

• Constants
• func AssignKeyID(key Key, options ...Option) error
• func PublicKeyOf(v interface{}) (interface{}, error)
• type CertificateChain
  • func (c *CertificateChain) Accept(v interface{}) error
  • func (c CertificateChain) Get() []*x509.Certificate
  • func (c CertificateChain) MarshalJSON() ([]byte, error)
  • func (c *CertificateChain) UnmarshalJSON(buf []byte) error
• type ECDSAPrivateKey
  • func NewECDSAPrivateKey() ECDSAPrivateKey
• type ECDSAPublicKey
  • func NewECDSAPublicKey() ECDSAPublicKey
• type HeaderIterator
• type HeaderPair
• type HeaderVisitor
• type HeaderVisitorFunc
• type Key
  • func New(key interface{}) (Key, error)
  • func ParseKey(data []byte) (Key, error)
• type KeyIterator
• type KeyOperation
• type KeyOperationList
  • func (ops *KeyOperationList) Accept(v interface{}) error
  • func (ops *KeyOperationList) Get() KeyOperationList
• type KeyPair
• type KeyUsageType
• type Option
  • func WithHTTPClient(cl *http.Client) Option
  • func WithThumbprintHash(h crypto.Hash) Option
• type RSAPrivateKey
  • func NewRSAPrivateKey() RSAPrivateKey
• type RSAPublicKey
  • func NewRSAPublicKey() RSAPublicKey
• type Set
  • func Fetch(urlstring string, options ...Option) (*Set, error)
  • func FetchHTTP(jwkurl string, options ...Option) (*Set, error)
  • func FetchHTTPWithContext(ctx context.Context, jwkurl string, options ...Option) (*Set, error)
  • func Parse(in io.Reader) (*Set, error)
  • func ParseBytes(buf []byte) (*Set, error)
  • func ParseString(s string) (*Set, error)
  • func (s *Set) Iterate(ctx context.Context) KeyIterator
  • func (s *Set) Len() int
  • func (s Set) LookupKeyID(kid string) []Key
  • func (s *Set) UnmarshalJSON(data []byte) error
• type SymmetricKey
  • func NewSymmetricKey() SymmetricKey

Examples

• Package

Constants

const (
	ECDSACrvKey = "crv"
	ECDSADKey   = "d"
	ECDSAXKey   = "x"
	ECDSAYKey   = "y"
)

const (
	KeyTypeKey                = "kty"
	KeyUsageKey               = "use"
	KeyOpsKey                 = "key_ops"
	AlgorithmKey              = "alg"
	KeyIDKey                  = "kid"
	X509URLKey                = "x5u"
	X509CertChainKey          = "x5c"
	X509CertThumbprintKey     = "x5t"
	X509CertThumbprintS256Key = "x5t#S256"
)

const (
	RSADKey  = "d"
	RSADPKey = "dp"
	RSADQKey = "dq"
	RSAEKey  = "e"
	RSANKey  = "n"
	RSAPKey  = "p"
	RSAQKey  = "q"
	RSAQIKey = "qi"
)

const (
	SymmetricOctetsKey = "k"
)

Functions

func AssignKeyID

func AssignKeyID(key Key, options ...Option) error

AssignKeyID is a convenience function to automatically assign the "kid" section of the key, if it already doesn't have one. It uses Key.Thumbprint method with crypto.SHA256 as the default hashing algorithm

func PublicKeyOf

func PublicKeyOf(v interface{}) (interface{}, error)

PublicKeyOf returns the corresponding public key of the given value `v`. For example, if v is a `*rsa.PrivateKey`, then `*rsa.PublicKey` is returned.

If given a public key, then the same public key will be returned. For example, if v is a `*rsa.PublicKey`, then the same value is returned.

If v is of a type that we don't support, an error is returned.

This is useful when you are dealing with the jwk.Key interface alone and you don't know before hand what the underlying key type is, but you still want to obtain the corresponding public key

Types

type CertificateChain

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

func (*CertificateChain) Accept

func (c *CertificateChain) Accept(v interface{}) error

func (CertificateChain) Get

func (c CertificateChain) Get() []*x509.Certificate

func (CertificateChain) MarshalJSON

func (c CertificateChain) MarshalJSON() ([]byte, error)

func (*CertificateChain) UnmarshalJSON

func (c *CertificateChain) UnmarshalJSON(buf []byte) error

type ECDSAPrivateKey

type ECDSAPrivateKey interface {
	Key
	FromRaw(*ecdsa.PrivateKey) error
	Crv() jwa.EllipticCurveAlgorithm
	D() []byte
	X() []byte
	Y() []byte
	PublicKey() (ECDSAPublicKey, error)
}

func NewECDSAPrivateKey

func NewECDSAPrivateKey() ECDSAPrivateKey

type ECDSAPublicKey

type ECDSAPublicKey interface {
	Key
	FromRaw(*ecdsa.PublicKey) error
	Crv() jwa.EllipticCurveAlgorithm
	X() []byte
	Y() []byte
}

func NewECDSAPublicKey

func NewECDSAPublicKey() ECDSAPublicKey

type HeaderIterator

type HeaderIterator = mapiter.Iterator

type HeaderPair

type HeaderPair = mapiter.Pair

type HeaderVisitor

type HeaderVisitor = iter.MapVisitor

type HeaderVisitorFunc

type HeaderVisitorFunc = iter.MapVisitorFunc

type Key

type Key interface {
	// Get returns the value of a single field. The second boolean return value
	// will be false if the field is not stored in the source
	//
	// This method, which returns an `interface{}`, exists because
	// these objects can contain extra _arbitrary_ fields that users can
	// specify, and there is no way of knowing what type they could be
	Get(string) (interface{}, bool)

	// Set sets the value of a single field. Note that certain fields,
	// notably "kty" cannot be altered, but will not return an error
	//
	// This method, which takes an `interface{}`, exists because
	// these objects can contain extra _arbitrary_ fields that users can
	// specify, and there is no way of knowing what type they could be
	Set(string, interface{}) error

	// Raw creates the corresponding raw key. For example,
	// EC types would create *ecdsa.PublicKey or *ecdsa.PrivateKey,
	// and OctetSeq types create a []byte key.
	//
	// If you do not know the exact type of a jwk.Key before attempting
	// to obtain the raw key, you can simply pass a pointer to an
	// empty interface as the first argument.
	//
	// If you already know the exact type, it is recommended that you
	// pass a pointer to the actual key type (e.g. *rsa.PrivateKey, *ecdsa.PublicKey
	// for efficiency
	Raw(interface{}) error

	// Thumbprint returns the JWK thumbprint using the indicated
	// hashing algorithm, according to RFC 7638
	Thumbprint(crypto.Hash) ([]byte, error)

	// Iterate returns an iterator that returns all keys and values
	Iterate(ctx context.Context) HeaderIterator

	// Walk is a utility tool that allows a visitor to iterate all keys and values
	Walk(context.Context, HeaderVisitor) error

	// AsMap is a utility tool returns a map that contains the same fields as the source
	AsMap(context.Context) (map[string]interface{}, error)

	// PrivateParams returns the non-standard elements in the source structure
	PrivateParams() map[string]interface{}

	KeyType() jwa.KeyType
	KeyUsage() string
	KeyOps() KeyOperationList
	Algorithm() string
	KeyID() string
	X509URL() string
	X509CertChain() []*x509.Certificate
	X509CertThumbprint() string
	X509CertThumbprintS256() string
}

Key defines the minimal interface for each of the key types. Their use and implementation differ significantly between each key types, so you should use type assertions to perform more specific tasks with each key

func New

func New(key interface{}) (Key, error)

New creates a jwk.Key from the given key (RSA/ECDSA/symmetric keys).

The constructor auto-detects the type of key to be instantiated based on the input type:

* "crypto/rsa".PrivateKey and "crypto/rsa".PublicKey creates an RSA based key * "crypto/ecdsa".PrivateKey and "crypto/ecdsa".PublicKey creates an EC based key * []byte creates a symmetric key

func ParseKey

func ParseKey(data []byte) (Key, error)

type KeyIterator

type KeyIterator = arrayiter.Iterator

type KeyOperation

type KeyOperation string

const (
	KeyOpSign       KeyOperation = "sign"       // (compute digital signature or MAC)
	KeyOpVerify     KeyOperation = "verify"     // (verify digital signature or MAC)
	KeyOpEncrypt    KeyOperation = "encrypt"    // (encrypt content)
	KeyOpDecrypt    KeyOperation = "decrypt"    // (decrypt content and validate decryption, if applicable)
	KeyOpWrapKey    KeyOperation = "wrapKey"    // (encrypt key)
	KeyOpUnwrapKey  KeyOperation = "unwrapKey"  // (decrypt key and validate decryption, if applicable)
	KeyOpDeriveKey  KeyOperation = "deriveKey"  // (derive key)
	KeyOpDeriveBits KeyOperation = "deriveBits" // (derive bits not to be used as a key)
)

type KeyOperationList

type KeyOperationList []KeyOperation

func (*KeyOperationList) Accept

func (ops *KeyOperationList) Accept(v interface{}) error

func (*KeyOperationList) Get

func (ops *KeyOperationList) Get() KeyOperationList

type KeyPair

type KeyPair = arrayiter.Pair

type KeyUsageType

type KeyUsageType string

KeyUsageType is used to denote what this key should be used for

const (
	// ForSignature is the value used in the headers to indicate that
	// this key should be used for signatures
	ForSignature KeyUsageType = "sig"
	// ForEncryption is the value used in the headers to indicate that
	// this key should be used for encryptiong
	ForEncryption KeyUsageType = "enc"
)

type Option

type Option = option.Interface

func WithHTTPClient

func WithHTTPClient(cl *http.Client) Option

func WithThumbprintHash

func WithThumbprintHash(h crypto.Hash) Option

type RSAPrivateKey

type RSAPrivateKey interface {
	Key
	FromRaw(*rsa.PrivateKey) error
	D() []byte
	DP() []byte
	DQ() []byte
	E() []byte
	N() []byte
	P() []byte
	Q() []byte
	QI() []byte
	PublicKey() (RSAPublicKey, error)
}

func NewRSAPrivateKey

func NewRSAPrivateKey() RSAPrivateKey

type RSAPublicKey

type RSAPublicKey interface {
	Key
	FromRaw(*rsa.PublicKey) error
	E() []byte
	N() []byte
}

func NewRSAPublicKey

func NewRSAPublicKey() RSAPublicKey

type Set

type Set struct {
	Keys []Key `json:"keys"`
}

Set is a convenience struct to allow generating and parsing JWK sets as opposed to single JWKs

func Fetch

func Fetch(urlstring string, options ...Option) (*Set, error)

Fetch fetches a JWK resource specified by a URL

func FetchHTTP

func FetchHTTP(jwkurl string, options ...Option) (*Set, error)

FetchHTTP wraps FetchHTTPWithContext using the background context.

func FetchHTTPWithContext

func FetchHTTPWithContext(ctx context.Context, jwkurl string, options ...Option) (*Set, error)

FetchHTTPWithContext fetches the remote JWK and parses its contents

func Parse

func Parse(in io.Reader) (*Set, error)

Parse parses JWK from the incoming io.Reader. This function can handle both single-key and multi-key formats. If you know before hand which format the incoming data is in, you might want to consider using "encoding/json" directly

Note that a successful parsing does NOT guarantee a valid key

func ParseBytes

func ParseBytes(buf []byte) (*Set, error)

ParseBytes parses JWK from the incoming byte buffer.

Note that a successful parsing does NOT guarantee a valid key

func ParseString

func ParseString(s string) (*Set, error)

ParseString parses JWK from the incoming string.

Note that a successful parsing does NOT guarantee a valid key

func (*Set) Iterate

func (s *Set) Iterate(ctx context.Context) KeyIterator

func (*Set) Len

func (s *Set) Len() int

func (Set) LookupKeyID

func (s Set) LookupKeyID(kid string) []Key

LookupKeyID looks for keys matching the given key id. Note that the Set *may* contain multiple keys with the same key id

func (*Set) UnmarshalJSON

func (s *Set) UnmarshalJSON(data []byte) error

type SymmetricKey

type SymmetricKey interface {
	Key
	FromRaw([]byte) error
	Octets() []byte
}

func NewSymmetricKey

func NewSymmetricKey() SymmetricKey