jwkjson

README

Key JSON

import "github.com/a-novel-kit/jwt-core/jwk/json"

Handlers for the JSON Web Algorithm representation of keys.

• Key JSON
  • Encode
  • Decode

Encode

The encoder takes a key, and generates a JSON Web Key representation for it. The key can either be a private key, or a derived public key. The payload definition is usually shared between both.

payload, err := jwkjson.EncodeKey(key)

You can directly use this payload as part of your JWT generation. It supports JSON marshalling.

type JsonKey struct {
	MyCustomField any `json:"my_custom_field"`
	
	// Field will be inlined in the final result.
	*jwkjson.KeyPayload
}

myKey := JsonKey{
	MyCustomField: "foo",
	KeyPayload: payload,
}

encoded, err := json.Marshal(myKey)

The following algorithms are supported:

Algorithm	Key type	Method
Oct	Symmetric	EncodeOct(key []byte) *OctPayload
RSA	RSA	EncodeRSA[Key *rsa.PublicKey | *rsa.PrivateKey](key Key) *RSAPayload
ECDSA	ECDSA	EncodeEC[Key *ecdsa.PublicKey | *ecdsa.PrivateKey](key Key) (*ECPayload, error)
EdDSA	EdDSA	EncodeED[Key ed25519.PublicKey | ed25519.PrivateKey](key Key) *EDPayload
ECDH	ECDH	EncodeECDH[Key *ecdh.PublicKey | *ecdh.PrivateKey](key Key) (*ECDHPayload, error)

Decode

The decoder takes a JSON Web Key representation, and parses a keypair from it.

privateKey, publicKey, err := jwkjson.DecodeKey(jwk)

The decoder always returns a private and a public key (except for symmetric keys). If the payload represents a public key, then the private key will be nil.

The following algorithms are supported:

Algorithm	Method
Oct	DecodeOct(src *OctPayload) ([]byte, error)
RSA	DecodeRSA(src *RSAPayload) (*rsa.PrivateKey, *rsa.PublicKey, error)
ECDSA	DecodeEC(src *ECPayload) (*ecdsa.PrivateKey, *ecdsa.PublicKey, error)
EdDSA	DecodeED(src *EDPayload) (ed25519.PrivateKey, ed25519.PublicKey, error)
ECDH	DecodeECDH(src *ECDHPayload) (*ecdh.PrivateKey, *ecdh.PublicKey, error)

Documentation

Index

• Variables
• func DecodeEC(src *ECPayload) (*ecdsa.PrivateKey, *ecdsa.PublicKey, error)
• func DecodeECDH(src *ECDHPayload) (*ecdh.PrivateKey, *ecdh.PublicKey, error)
• func DecodeED(src *EDPayload) (ed25519.PrivateKey, ed25519.PublicKey, error)
• func DecodeOct(src *OctPayload) ([]byte, error)
• func DecodeRSA(src *RSAPayload) (*rsa.PrivateKey, *rsa.PublicKey, error)
• type ECDHPayload
  • func EncodeECDH[Key *ecdh.PublicKey | *ecdh.PrivateKey](key Key) (*ECDHPayload, error)
• type ECPayload
  • func EncodeEC[Key *ecdsa.PublicKey | *ecdsa.PrivateKey](key Key) (*ECPayload, error)
• type EDPayload
  • func EncodeED[Key ed25519.PublicKey | ed25519.PrivateKey](key Key) *EDPayload
• type OctPayload
  • func EncodeOct(key []byte) *OctPayload
• type RSAOtherPrime
• type RSAPayload
  • func EncodeRSA[Key *rsa.PublicKey | *rsa.PrivateKey](key Key) *RSAPayload

Variables

var ErrInvalidEDKey = errors.New("invalid EdDSA key")

var ErrUnsupportedCurve = errors.New("unsupported curve")

Functions

func DecodeEC

func DecodeEC(src *ECPayload) (*ecdsa.PrivateKey, *ecdsa.PublicKey, error)

DecodeEC takes the representation of a ECPayload and computes the key it contains.

func DecodeECDH

func DecodeECDH(src *ECDHPayload) (*ecdh.PrivateKey, *ecdh.PublicKey, error)

DecodeECDH decodes the ECDH-ES key from a JWK format.

func DecodeED

func DecodeED(src *EDPayload) (ed25519.PrivateKey, ed25519.PublicKey, error)

DecodeED decodes the EdDSA key from a JWK format.

func DecodeOct

func DecodeOct(src *OctPayload) ([]byte, error)

DecodeOct takes the representation of a OctPayload and computes the key it contains.

func DecodeRSA

func DecodeRSA(src *RSAPayload) (*rsa.PrivateKey, *rsa.PublicKey, error)

DecodeRSA takes the representation of a RSAPayload and computes the key it contains.

Types

type ECDHPayload

type ECDHPayload struct {
	// Crv (curve) parameter.
	//
	// Since the proposal of adding 448 curve variants to the standard library was declined due to complexity and
	// low benefits, it is currently not supported by this library. Thus, using a curve value other than "X25519"
	// will throw an error.
	//
	// https://github.com/golang/go/issues/29390
	//
	// You may still use your own decoded that supports x448.
	Crv string `json:"crv"`
	// X coordinate parameter.
	X string `json:"x"`

	// D (ECC private key) parameter.
	D string `json:"d,omitempty"`
}

ECDHPayload wraps a ECDH-ES key in a JWK format.

func EncodeECDH

func EncodeECDH[Key *ecdh.PublicKey | *ecdh.PrivateKey](key Key) (*ECDHPayload, error)

EncodeECDH encodes the ECDH-ES key into a JWK format.

type ECPayload

type ECPayload struct {
	// Crv (curve) parameter.
	//
	// https://datatracker.ietf.org/doc/html/rfc7518#section-6.2.1.1
	//
	// The "crv" (curve) parameter identifies the cryptographic curve used
	// with the key. Curve values from [DSS] used by this specification
	// are:
	//
	// o "P-256"
	// o "P-384"
	// o "P-521"
	//
	// These values are registered in the IANA "JSON Web CEK Elliptic Curve"
	// registry defined in Section 7.6. Additional "crv" values can be
	// registered by other specifications. Specifications registering
	// additional curves must define what parameters are used to represent
	// keys for the curves registered. The "crv" value is a case-sensitive
	// string.
	//
	// SEC1 [SEC1] point compression is not supported for any of these three
	// curves.
	Crv string `json:"crv"`
	// X coordinate parameter.
	//
	// https://datatracker.ietf.org/doc/html/rfc7518#section-6.2.1.2
	//
	// The "x" (x coordinate) parameter contains the x coordinate for the
	// Elliptic Curve point. It is represented as the base64url encoding of
	// the octet string representation of the coordinate, as defined in
	// Section 2.3.5 of SEC1 [SEC1]. The length of this octet string MUST
	// be the full size of a coordinate for the curve specified in the "crv"
	// parameter. For example, if the value of "crv" is "P-521", the octet
	// string must be 66 octets long.
	X string `json:"x"`
	// Y coordinate parameter.
	//
	// https://datatracker.ietf.org/doc/html/rfc7518#section-6.2.1.3
	//
	// The "y" (y coordinate) parameter contains the y coordinate for the
	// Elliptic Curve point. It is represented as the base64url encoding of
	// the octet string representation of the coordinate, as defined in
	// Section 2.3.5 of SEC1 [SEC1]. The length of this octet string MUST
	// be the full size of a coordinate for the curve specified in the "crv"
	// parameter. For example, if the value of "crv" is "P-521", the octet
	// string must be 66 octets long.
	Y string `json:"y"`

	// D (ECC private key) parameter.
	//
	// https://datatracker.ietf.org/doc/html/rfc7518#section-6.2.2.1
	//
	// The "d" (ECC private key) parameter contains the Elliptic Curve
	// private key value. It is represented as the base64url encoding of
	// the octet string representation of the private key value, as defined
	// in Section 2.3.7 of SEC1 [SEC1]. The length of this octet string
	// MUST be ceiling(log-base-2(n)/8) octets (where n is the order of the
	// curve).
	D string `json:"d,omitempty"`
}

ECPayload wraps a ECDSA key in a JWK format.

func EncodeEC

func EncodeEC[Key *ecdsa.PublicKey | *ecdsa.PrivateKey](key Key) (*ECPayload, error)

EncodeEC takes a key and create a ECPayload representation of it.

type EDPayload

type EDPayload struct {
	// Crv (curve) parameter.
	//
	// Since the proposal of adding 448 curve variants to the standard library was declined due to complexity and
	// low benefits, it is currently not supported by this library. Thus, using a curve value other than "Ed25519"
	// will throw an error.
	//
	// https://github.com/golang/go/issues/29390
	//
	// You may still use your own decoded that supports x448.
	Crv string `json:"crv"`
	// X coordinate parameter.
	X string `json:"x"`

	// D (ECC private key) parameter.
	D string `json:"d,omitempty"`
}

EDPayload wraps a EDDSA key in a JWK format.

func EncodeED

func EncodeED[Key ed25519.PublicKey | ed25519.PrivateKey](key Key) *EDPayload

EncodeED returns the JWK representation of an EdDSA key.

type OctPayload

type OctPayload struct {
	// K (CEK Value) Parameter.
	//
	// https://datatracker.ietf.org/doc/html/rfc7518#section-6.4.1
	//
	// The "k" (key value) parameter contains the value of the symmetric (or
	// other single-valued) key. It is represented as the base64url
	// encoding of the octet sequence containing the key value.
	K string `json:"k"`
}

OctPayload wraps a symmetric key in a JWK format.

func EncodeOct

func EncodeOct(key []byte) *OctPayload

EncodeOct takes a key and create a OctPayload representation of it.

type RSAOtherPrime

type RSAOtherPrime struct {
	// R prime factor.
	//
	// https://datatracker.ietf.org/doc/html/rfc7518#section-6.3.2.7.1
	//
	// The "r" (prime factor) parameter within an "oth" array member
	// represents the value of a subsequent prime factor. It is represented
	// as a Base64urlUInt-encoded value.
	R string `json:"r"`
	// D factor CRT exponent.
	//
	// https://datatracker.ietf.org/doc/html/rfc7518#section-6.3.2.7.2
	//
	// The "d" (factor CRT exponent) parameter within an "oth" array member
	// represents the CRT exponent of the corresponding prime factor. It is
	// represented as a Base64urlUInt-encoded value.
	D string `json:"d"`
	// T factor CRT coefficient.
	//
	// https://datatracker.ietf.org/doc/html/rfc7518#section-6.3.2.7.3
	//
	// The "t" (factor CRT coefficient) parameter within an "oth" array
	// member represents the CRT coefficient of the corresponding prime
	// factor. It is represented as a Base64urlUInt-encoded value.
	T string `json:"t"`
}

type RSAPayload

type RSAPayload struct {
	// N modulus of the key.
	//
	// https://datatracker.ietf.org/doc/html/rfc7518#section-6.3.1.1
	//
	// The "n" (modulus) parameter contains the modulus value for the RSA
	// public key. It is represented as a Base64urlUInt-encoded value.
	//
	// Note that implementers have found that some cryptographic libraries
	// prefix an extra zero-valued octet to the modulus representations they
	// return, for instance, returning 257 octets for a 2048-bit key, rather
	// than 256. Implementations using such libraries will need to take
	// care to omit the extra octet from the base64url-encoded
	// representation.
	N string `json:"n"`
	// E exponent of the key.
	//
	// https://datatracker.ietf.org/doc/html/rfc7518#section-6.3.1.2
	//
	// The "e" (exponent) parameter contains the exponent value for the RSA
	// public key. It is represented as a Base64urlUInt-encoded value.
	//
	// For instance, when representing the value 65537, the octet sequence
	// to be base64url-encoded MUST consist of the three octets [1, 0, 1];
	// the resulting representation for this value is "AQAB".
	E string `json:"e"`

	// D private exponent of the key.
	//
	// https://datatracker.ietf.org/doc/html/rfc7518#section-6.3.2.1
	//
	// The "d" (private exponent) parameter contains the private exponent
	// value for the RSA private key. It is represented as a Base64urlUInt-
	// encoded value.
	D string `json:"d,omitempty"`

	// P first prime factor of the key.
	//
	// https://datatracker.ietf.org/doc/html/rfc7518#section-6.3.2.2
	//
	// The "p" (first prime factor) parameter contains the first prime
	// factor. It is represented as a Base64urlUInt-encoded value.
	P string `json:"p,omitempty"`
	// Q second prime factor of the key.
	//
	// https://datatracker.ietf.org/doc/html/rfc7518#section-6.3.2.3
	//
	// The "q" (second prime factor) parameter contains the second prime
	// factor. It is represented as a Base64urlUInt-encoded value.
	Q string `json:"q,omitempty"`

	// DP first factor CRT exponent.
	//
	//https://datatracker.ietf.org/doc/html/rfc7518#section-6.3.2.4
	//
	// The "dp" (first factor CRT exponent) parameter contains the Chinese
	// Remainder Theorem (CRT) exponent of the first factor. It is
	// represented as a Base64urlUInt-encoded value.
	DP string `json:"dp,omitempty"`
	// DQ second factor CRT exponent.
	//
	// https://datatracker.ietf.org/doc/html/rfc7518#section-6.3.2.5
	//
	// The "dq" (second factor CRT exponent) parameter contains the CRT
	// exponent of the second factor. It is represented as a Base64urlUInt-
	// encoded value.
	DQ string `json:"dq,omitempty"`
	// QI first CRT coefficient.
	//
	// https://datatracker.ietf.org/doc/html/rfc7518#section-6.3.2.6
	//
	// The "qi" (first CRT coefficient) parameter contains the CRT
	// coefficient of the second factor. It is represented as a
	// Base64urlUInt-encoded value.
	QI string `json:"qi,omitempty"`

	// Oth other primes info.
	//
	// https://datatracker.ietf.org/doc/html/rfc7518#section-6.3.2.7
	//
	// The "oth" (other primes info) parameter contains an array of
	// information about any third and subsequent primes, should they exist.
	// When only two primes have been used (the normal case), this parameter
	// MUST be omitted. When three or more primes have been used, the
	// number of array elements MUST be the number of primes used minus two.
	// For more information on this case, see the description of the
	// OtherPrimeInfo parameters in Appendix A.1.2 of RFC 3447 [RFC3447],
	// upon which the following parameters are modeled. If the consumer of
	// a JWK does not support private keys with more than two primes and it
	// encounters a private key that includes the "oth" parameter, then it
	// MUST NOT use the key. Each array element MUST be an object with the
	// following members.
	Oth []RSAOtherPrime `json:"oth,omitempty"`
}

RSAPayload wraps a RSA key in a JWK format.

func EncodeRSA

func EncodeRSA[Key *rsa.PublicKey | *rsa.PrivateKey](key Key) *RSAPayload

EncodeRSA takes a key and create a RSAPayload representation of it.