Consume JWK

The jwk.Key type

Key managers are built around the jwk.Key format. This is a special struct that can hold both JSON and concrete key data.

To use the key encoded in a given jwk.Key object, just call its Key() method. The object can also be directly marshalled into valid JSON, using the standard encoding/json package - or any compatible package.

var jsonKey jwk.Key[T]

// The concrete key, that can be directly used for cryptographic operations.
key := jsonKey.Key()

// Produces a valid JSON out-of-the-box, given it was generated by
// the library.
serialized, _ := json.Marshal(jsonKey)

A consumer takes a deserialized jwa.JWK object as an input. This is a special object that only consumes generic fields, and delays the parsing of the key itself. Thus, headers can be properly checked before attempting to parse the key.

Warning

Key consumers are very strict about checking the key headers. To be successfully consumed by this package, a JSON Web Key MUST explicitly state its target usage, key operations, and algorithm. For encryption keys, the "alg" value MUST be set to the value intended for the "enc" header of the JWT.

This is a security measure to prevent misusage of a key.

Symmetric keys

AES (CEK)

package main

import (
	"github.com/a-novel-kit/jwt/jwa"
	"github.com/a-novel-kit/jwt/jwk"
)

func main() {
	// Raw key, with only header information.
	var rawKey *jwa.JWK

	// Uses the Key format described above.
	// The headers of the key are checked: only a key
	// that perfectly matches the provided preset will
	// be accepted.
	key, _ := jwk.ConsumeAES(rawKey, jwk.A128CBC)
}

Available presets for use as Content-Encryption Keys (CEK) are:

Preset	Target "enc"
jwk.A128CBC	A128CBC-HS256
jwk.A192CBC	A192CBC-HS384
jwk.A256CBC	A256CBC-HS512
jwk.A128GCM	A128GCM
jwk.A192GCM	A192GCM
jwk.A256GCM	A256GCM

AES (KEK)

package main

import (
	"github.com/a-novel-kit/jwt/jwa"
	"github.com/a-novel-kit/jwt/jwk"
)

func main() {
	// Raw key, with only header information.
	var rawKey *jwa.JWK

	// Uses the Key format described above.
	// The headers of the key are checked: only a key
	// that perfectly matches the provided preset will
    // be accepted.
	key, _ := jwk.ConsumeAES(rawKey, jwk.A128KW)
}

Available presets for use as Key-Encryption Keys (KEK) are:

Preset	Target "alg"
jwk.A128KW	A128KW
jwk.A192KW	A192KW
jwk.A256KW	A256KW
jwk.A128GCMKW	A128GCMKW
jwk.A192GCMKW	A192GCMKW
jwk.A256GCMKW	A256GCMKW

HMAC (Sig)

package main

import (
	"github.com/a-novel-kit/jwt/jwa"
	"github.com/a-novel-kit/jwt/jwk"
)

func main() {
	// Raw key, with only header information.
	var rawKey *jwa.JWK

	// Uses the Key format described above.
	// The headers of the key are checked: only a key
	// that perfectly matches the provided preset will
	// be accepted.
	key, _ := jwk.ConsumeHMAC(rawKey, jwk.HS256)
}

Available presets for use as Signature keys are:

Preset	Target "alg"
jwk.HS256	HS256
jwk.HS384	HS384
jwk.HS512	HS512

Asymmetric keys

ECDH (Key Agr)

package main

import (
	"github.com/a-novel-kit/jwt/jwa"
	"github.com/a-novel-kit/jwt/jwk"
)

func main() {
	// Raw key, with only header information.
	var rawKey *jwa.JWK

	// Uses the Key format described above.
	// The headers of the key are checked: only a key
	// that perfectly matches the provided preset will
	// be accepted.
	privateKey, publicKey, _ := jwk.ConsumeECDH(rawKey)
}

ECDSA (Sig)

package main

import (
	"github.com/a-novel-kit/jwt/jwa"
	"github.com/a-novel-kit/jwt/jwk"
)

func main() {
	// Raw key, with only header information.
	var rawKey *jwa.JWK

	// Uses the Key format described above.
	// The headers of the key are checked: only a key
	// that perfectly matches the provided preset will
	// be accepted.
	privateKey, publicKey, _ := jwk.ConsumeECDSA(rawKey, jwk.ES256)
}

Available presets for use as Signature keys are:

Preset	Target "alg"
jwk.ES256	ES256
jwk.ES384	ES384
jwk.ES512	ES512

ED25519 (Sig)

package main

import (
	"github.com/a-novel-kit/jwt/jwa"
	"github.com/a-novel-kit/jwt/jwk"
)

func main() {
	// Raw key, with only header information.
	var rawKey *jwa.JWK

	// Uses the Key format described above.
	// The headers of the key are checked: only a key
	// that perfectly matches the provided preset will
	// be accepted.
	privateKey, publicKey, _ := jwk.ConsumeED25519(rawKey)
}

RSA (Sig)

package main

import (
	"github.com/a-novel-kit/jwt/jwa"
	"github.com/a-novel-kit/jwt/jwk"
)

func main() {
	// Raw key, with only header information.
	var rawKey *jwa.JWK

	// Uses the Key format described above.
	// The headers of the key are checked: only a key
	// that perfectly matches the provided preset will
	// be accepted.
	privateKey, publicKey, _ := jwk.ConsumeRSA(rawKey, jwk.RS256)
}

Available presets for use as Signature keys are:

Preset	Target "alg"
jwk.RS256	RS256
jwk.RS384	RS384
jwk.RS512	RS512
jwk.PS256	PS256
jwk.PS384	PS384
jwk.PS512	PS512

RSA (Key Enc)

package main

import (
	"github.com/a-novel-kit/jwt/jwa"
	"github.com/a-novel-kit/jwt/jwk"
)

func main() {
	// Raw key, with only header information.
	var rawKey *jwa.JWK

	// Uses the Key format described above.
	// The headers of the key are checked: only a key
	// that perfectly matches the provided preset will
	// be accepted.
	privateKey, publicKey, _ := jwk.ConsumeRSA(rawKey, jwk.RSAOAEP)
}

Available presets for use as Key-Encryption keys are:

Preset	Target "alg"
⚠️ jwk.RSAOAEP	RSAOAEP
jwk.RSAOAEP256	RSAOAEP256

Caution

RSA-OAEP without sha256 is deprecated, as it relies on the broken SHA1 algorithm. It is still available for compatibility reasons, but should not be used in new applications.

See this post for explanation