JSON Web Key Usage

Inspect and use individual JWK items from a keyring. More...

Collaboration diagram for JSON Web Key Usage:

Typedefs
typedef struct jwk_item	jwk_item_t
	Object representation of a JWK.

Enumerations
enum	jwk_key_type_t {   JWK_KEY_TYPE_NONE = 0 , JWK_KEY_TYPE_EC , JWK_KEY_TYPE_RSA , JWK_KEY_TYPE_OKP ,   JWK_KEY_TYPE_OCT , JWK_KEY_TYPE_AKP }
	JWK Key Types. More...
enum	jwk_pub_key_use_t { JWK_PUB_KEY_USE_NONE = 0 , JWK_PUB_KEY_USE_SIG , JWK_PUB_KEY_USE_ENC }
	Usage types for JWK public keys. More...
enum	jwk_key_op_t {   JWK_KEY_OP_NONE = 0x0000 , JWK_KEY_OP_SIGN = 0x0001 , JWK_KEY_OP_VERIFY = 0x0002 , JWK_KEY_OP_ENCRYPT = 0x0004 ,   JWK_KEY_OP_DECRYPT = 0x0008 , JWK_KEY_OP_WRAP = 0x0010 , JWK_KEY_OP_UNWRAP = 0x0020 , JWK_KEY_OP_DERIVE_KEY = 0x0040 ,   JWK_KEY_OP_DERIVE_BITS = 0x0080 , JWK_KEY_OP_INVALID = 0xffff }
	Allowed key operations for JWK private keys. More...

Functions
const jwk_item_t *	jwks_item_get (const jwk_set_t *jwk_set, size_t index)
	Return the index'th jwk_item in the jwk_set.
jwk_item_t *	jwks_find_bykid (jwk_set_t *jwk_set, const char *kid)
	Find a jwk_item_t with a specific kid (Key ID).
int	jwks_item_is_private (const jwk_item_t *item)
	Whether this key is private (or public).
int	jwks_item_error (const jwk_item_t *item)
	Check the error condition for this JWK.
const char *	jwks_item_error_msg (const jwk_item_t *item)
	Check the error message for a JWK Item.
const char *	jwks_item_curve (const jwk_item_t *item)
	A curve name, if applicable, for this key.
const char *	jwks_item_kid (const jwk_item_t *item)
	A kid (Key ID) for this JWK.
jwt_alg_t	jwks_item_alg (const jwk_item_t *item)
	The algorithm for this JWK.
jwk_key_type_t	jwks_item_kty (const jwk_item_t *item)
	The Key Type of this JWK.
jwk_pub_key_use_t	jwks_item_use (const jwk_item_t *item)
	The "use" field for this JWK.
jwk_key_op_t	jwks_item_key_ops (const jwk_item_t *item)
	The "key_ops" field for this JWK.
const char *	jwks_item_pem (const jwk_item_t *item)
	The PEM generated for the JWK.
size_t	jwks_item_x5c_count (const jwk_item_t *item)
	Number of certificates in the JWK x5c chain.
const unsigned char *	jwks_item_x5c (const jwk_item_t *item, size_t index, size_t *len)
	Get a certificate from the JWK x5c chain (DER).
const char *	jwks_item_x5t (const jwk_item_t *item)
	The JWK x5t (SHA-1 certificate thumbprint).
const char *	jwks_item_x5t_s256 (const jwk_item_t *item)
	The JWK x5t#S256 (SHA-256 certificate thumbprint).
char *	jwks_item_export (const jwk_item_t *item, int priv)
	Serialize a single JWK item to a JWK JSON string.
char *	jwks_export (const jwk_set_t *jwk_set, int priv)
	Serialize a whole keyring to a JWKS JSON string.
char *	jwks_item_thumbprint (const jwk_item_t *item, jwk_thumbprint_alg_t alg)
	Compute the JWK Thumbprint of a key.
char *	jwks_item_thumbprint_uri (const jwk_item_t *item, jwk_thumbprint_alg_t alg)
	Compute the JWK Thumbprint URI of a key.
jwk_item_t *	jwks_find_bythumbprint (jwk_set_t *jwk_set, jwk_thumbprint_alg_t alg, const char *thumbprint)
	Find a key in a set by its JWK Thumbprint.
jwk_item_t *	jwks_find_bythumbprint_uri (jwk_set_t *jwk_set, const char *uri)
	Find a key in a set by its JWK Thumbprint URI.
int	jwks_item_key_oct (const jwk_item_t *item, const unsigned char **buf, size_t *len)
	Retrieve binary octet data of a key.
int	jwks_item_key_bits (const jwk_item_t *item)
	The number of bits in this JWK.
int	jwks_item_free (jwk_set_t *jwk_set, size_t index)
	Free remove and free the nth jwk_item_t in a jwk_set.
int	jwks_item_free_all (jwk_set_t *jwk_set)
	Remove and free all jwk_item_t in a jwk_set_t.
int	jwks_item_free_bad (jwk_set_t *jwk_set)
	Free all keys marked with an error in a jwk_set_t.
size_t	jwks_item_count (const jwk_set_t *jwk_set)
	Return the number of keys in a jwk_set_t.

Detailed Description

Inspect and use individual JWK items from a keyring.

Functionality for using a JWK (represented as a jwk_item_t) to sign and validate JWT objects.

Typedef Documentation

jwk_item_t

typedef struct jwk_item jwk_item_t

Object representation of a JWK.

This object is produced by importing a JWK or JWKS into a jwk_set_t object. It represents single key and is used when generating or verifying JWT.

Since

3.0.0

Enumeration Type Documentation

jwk_key_op_t

enum jwk_key_op_t

Allowed key operations for JWK private keys.

Corresponds to the "key_ops" attribute in a JWK that represents a private key. These can be bitwise compares to the key_ops attribute of a jwk_item_t. These flags are used internally to decide if a JWK can be used for certain operations.

if (jwk_item_t.key_ops & (JWK_KEY_OP_SIGN | JWK_KEY_OP_ENCRYPT)) {
    ...
}

RFC-7517 Sec 4.3

Since

3.0.0

Enumerator
JWK_KEY_OP_NONE	No key_op set
JWK_KEY_OP_SIGN	Signing
JWK_KEY_OP_VERIFY	Signature verification
JWK_KEY_OP_ENCRYPT	Used for encryption
JWK_KEY_OP_DECRYPT	Used for decrypting
JWK_KEY_OP_WRAP	For wrapping other keys
JWK_KEY_OP_UNWRAP	For unwrappng other keys
JWK_KEY_OP_DERIVE_KEY	Key derivation
JWK_KEY_OP_DERIVE_BITS	Bits derivation
JWK_KEY_OP_INVALID	Invalid key_ops in JWK

jwk_key_type_t

enum jwk_key_type_t

JWK Key Types.

Corresponds to the "kty" attribute of the JWK.

RFC-7517 Sec 4.1 RFC-7518 Sec 6.1

Since

3.0.0

Enumerator
JWK_KEY_TYPE_NONE	Unused on valid keys
JWK_KEY_TYPE_EC	Elliptic Curve keys
JWK_KEY_TYPE_RSA	RSA keys (RSA and RSA-PSS)
JWK_KEY_TYPE_OKP	Octet Key Pair (e.g. EdDSA)
JWK_KEY_TYPE_OCT	Octet sequence (e.g. HS256)
JWK_KEY_TYPE_AKP	Algorithm Key Pair (e.g. ML-DSA) RFC-9964 Sec 3 Since 3.5.0

jwk_pub_key_use_t

enum jwk_pub_key_use_t

Usage types for JWK public keys.

Corresponds to the "use" attribute in a JWK the represents a public key.

RFC-7517 Sec 4.2

Since

3.0.0

Enumerator
JWK_PUB_KEY_USE_NONE	No usable attribute was set
JWK_PUB_KEY_USE_SIG	Signature key (JWS)
JWK_PUB_KEY_USE_ENC	Encryption key (JWE)

Function Documentation

jwks_export()

char * jwks_export	(	const jwk_set_t *	jwk_set,
		int	priv )

Serialize a whole keyring to a JWKS JSON string.

Produces a JWK Set (an object with a "keys" array) containing every item in the set.

Parameters

jwk_set	An existing jwk_set_t
priv	If non-zero, include private key parameters for private keys. If zero, only public parameters are emitted.

Returns

A newly allocated, nil-terminated JSON string the caller must free with free(), or NULL on error.

Since

3.4.0

jwks_find_bykid()

jwk_item_t * jwks_find_bykid	(	jwk_set_t *	jwk_set,
		const char *	kid )

Find a jwk_item_t with a specific kid (Key ID).

LibJWT does not ensure that kid's are unique in a given keyring, so care must be taken. This will return the first match.

Parameters

jwk_set	An existing jwk_set_t
kid	String representing a kid to find

Returns

A jwk_item_t object or NULL if none found

Since

3.2.0

jwks_find_bythumbprint()

jwk_item_t * jwks_find_bythumbprint	(	jwk_set_t *	jwk_set,
		jwk_thumbprint_alg_t	alg,
		const char *	thumbprint )

Find a key in a set by its JWK Thumbprint.

📄 RFC-7638

Returns the first item in jwk_set whose thumbprint (for the given hash) equals thumbprint. Unlike jwks_find_bykid(), this matches on the key's canonical, deterministic identity rather than the advisory "kid", so it works even when keys carry no (or an inconsistent) "kid" — e.g. matching a proof-of-possession "cnf"/"jkt" value against a set of known keys.

Parameters

jwk_set	An existing jwk_set_t
alg	The hash used to produce thumbprint (see jwk_thumbprint_alg_t)
thumbprint	A base64url JWK thumbprint, as from jwks_item_thumbprint()

Returns

The matching jwk_item_t, or NULL if none matches or on bad input

Since

3.6.0

jwks_find_bythumbprint_uri()

jwk_item_t * jwks_find_bythumbprint_uri	(	jwk_set_t *	jwk_set,
		const char *	uri )

Find a key in a set by its JWK Thumbprint URI.

📄 RFC-9278

As jwks_find_bythumbprint(), but takes the RFC 9278 URI form ("urn:ietf:params:oauth:jwk-thumbprint:sha-256:<thumbprint>"); the hash is taken from the URI's sha-NNN label.

Parameters

jwk_set	An existing jwk_set_t
uri	A JWK Thumbprint URI, as from jwks_item_thumbprint_uri()

Returns

The matching jwk_item_t, or NULL if none matches or on bad input

Since

3.6.0

jwks_item_alg()

jwt_alg_t jwks_item_alg

(

const jwk_item_t *

item

)

The algorithm for this JWK.

It is perfectly valid for this to be JWT_ALG_NONE.

Parameters

item	A JWK Item

Returns

A jwt_alg_t type of this key

Since

3.0.0

jwks_item_count()

size_t jwks_item_count

(

const jwk_set_t *

jwk_set

)

Return the number of keys in a jwk_set_t.

Parameters

jwk_set

Pointer to a JWKS object

Returns

The number of items in the set

Since

3.1.0

jwks_item_curve()

const char * jwks_item_curve

(

const jwk_item_t *

item

)

A curve name, if applicable, for this key.

Mainly applies to EC and OKP (EdDSA) type keys.

Parameters

item	A JWK Item

Returns

A string of the curve name if one exists. NULL otherwise.

Since

3.0.0

jwks_item_error()

int jwks_item_error

(

const jwk_item_t *

item

)

Check the error condition for this JWK.

Parameters

item	A JWK Item

Returns

1 for true, 0 for false

Since

3.0.0

jwks_item_error_msg()

const char * jwks_item_error_msg

(

const jwk_item_t *

item

)

Check the error message for a JWK Item.

Parameters

item	A JWK Item

Returns

A string message. Empty string if no error.

Since

3.0.0

jwks_item_export()

char * jwks_item_export	(	const jwk_item_t *	item,
		int	priv )

Serialize a single JWK item to a JWK JSON string.

Produces the JSON Web Key representation of this item. This is the serialization counterpart to the jwks_load_fromkey() import path.

Parameters

item	A JWK Item
priv	If non-zero, include private key parameters when the item is a private key. If zero, only public parameters are emitted.

Returns

A newly allocated, nil-terminated JSON string the caller must free with free(), or NULL on error.

Since

3.4.0

jwks_item_free()

int jwks_item_free	(	jwk_set_t *	jwk_set,
		size_t	index )

Free remove and free the nth jwk_item_t in a jwk_set.

Parameters

jwk_set	Pointer to a JWKS object
index	the position of the item in the index

Returns

0 if no item was was deleted (found), 1 if it was

Since

3.0.0

jwks_item_free_all()

int jwks_item_free_all

(

jwk_set_t *

jwk_set

)

Remove and free all jwk_item_t in a jwk_set_t.

The jwk_set_t becomes an empty set.

Parameters

jwk_set

Pointer to a JWKS object

Returns

The number of items deleted

Since

3.0.0

jwks_item_free_bad()

int jwks_item_free_bad

(

jwk_set_t *

jwk_set

)

Free all keys marked with an error in a jwk_set_t.

The jwk_set_t becomes an empty set.

Parameters

jwk_set

Pointer to a JWKS object

Returns

The number of items with an error that were deleted

Since

3.1.0

jwks_item_get()

const jwk_item_t * jwks_item_get	(	const jwk_set_t *	jwk_set,
		size_t	index )

Return the index'th jwk_item in the jwk_set.

Allows you to obtain the raw jwk_item. NOTE, this is not a copy of the item, which means if the jwk_set is freed, then this data is freed and cannot be used.

Parameters

jwk_set	An existing jwk_set_t
index	Index of the jwk_set

Returns

A valid jwk_item_t or NULL if it doesn't exist

Warning

The index of an item in a keyring can change if items are deleted. Effort is made to add new JWK to the end of the set, so this should not affect the index of previous items.

Since

3.0.0

jwks_item_is_private()

int jwks_item_is_private

(

const jwk_item_t *

item

)

Whether this key is private (or public).

Parameters

item	A JWK Item

Returns

1 for true, 0 for false

Since

3.0.0

jwks_item_key_bits()

int jwks_item_key_bits

(

const jwk_item_t *

item

)

The number of bits in this JWK.

This is relevant to the key type (kty). E.g. an RSA key would have at least 2048 bits, and an EC key would be 256, 384, or 521 bits, etc.

Parameters

item	A JWK Item

Returns

The number of bits for the key

Since

3.0.0

jwks_item_key_oct()

int jwks_item_key_oct	(	const jwk_item_t *	item,
		const unsigned char **	buf,
		size_t *	len )

Retrieve binary octet data of a key.

Only valid for JWT_KEY_TYPE_OCT.

Parameters

item	A JWK Item
buf	Pointer to a pointer buffer
len	Pointer to a length

Returns

0 on success. buf will point to data of len length. Non-zero on error.

Since

3.0.0

jwks_item_key_ops()

jwk_key_op_t jwks_item_key_ops

(

const jwk_item_t *

item

)

The "key_ops" field for this JWK.

Parameters

item	A JWK Item

Returns

A jwk_key_op_t type for this key which represents all of the "key_ops" supported as a bit field.

Since

3.0.0

jwks_item_kid()

const char * jwks_item_kid

(

const jwk_item_t *

item

)

A kid (Key ID) for this JWK.

Parameters

item	A JWK Item

Returns

A string of the kid if one exists. NULL otherwise.

Since

3.0.0

jwks_item_kty()

jwk_key_type_t jwks_item_kty

(

const jwk_item_t *

item

)

The Key Type of this JWK.

Parameters

item	A JWK Item

Returns

A jwk_key_type_t type for this key

Since

3.0.0

jwks_item_pem()

const char * jwks_item_pem

(

const jwk_item_t *

item

)

The PEM generated for the JWK.

This is an optional field that may or may not be supported depending on which crypto backend is in use. It is provided as a courtesy.

Parameters

item	A JWK Item

Returns

A string of the PEM file for this key or NULL if none exists

Since

3.0.0

jwks_item_thumbprint()

char * jwks_item_thumbprint	(	const jwk_item_t *	item,
		jwk_thumbprint_alg_t	alg )

Compute the JWK Thumbprint of a key.

RFC-7638 Sec 3

Produces the base64url-encoded SHA-2 digest of the key's canonical JWK form: a JSON object containing only the members required for the key type, with no whitespace and the member names in lexicographic order. The result is a stable, deterministic fingerprint of the (public) key parameters, commonly used as a key id ("kid") or as the "jkt" confirmation value.

The thumbprint is computed over public parameters and is identical whether the item was loaded from a JWK or from a PEM/DER key.

Parameters

item	A JWK Item
alg	The thumbprint hash algorithm (see jwk_thumbprint_alg_t); JWK_THUMBPRINT_SHA256 is the default.

Returns

A newly allocated, nil-terminated base64url string the caller must free with free(), or NULL on error (an unusable key, a missing required member, or an invalid alg).

Since

3.6.0

jwks_item_thumbprint_uri()

char * jwks_item_thumbprint_uri	(	const jwk_item_t *	item,
		jwk_thumbprint_alg_t	alg )

Compute the JWK Thumbprint URI of a key.

📄 RFC-9278

As jwks_item_thumbprint(), but returns the RFC 9278 URI form: "urn:ietf:params:oauth:jwk-thumbprint:sha-256:<thumbprint>" (or sha-384 / sha-512 to match alg).

Parameters

item	A JWK Item
alg	The thumbprint hash algorithm (see jwk_thumbprint_alg_t); JWK_THUMBPRINT_SHA256 is the default.

Returns

A newly allocated, nil-terminated URI string the caller must free with free(), or NULL on error.

Since

3.6.0

jwks_item_use()

jwk_pub_key_use_t jwks_item_use

(

const jwk_item_t *

item

)

The "use" field for this JWK.

Parameters

item	A JWK Item

Returns

A jwk_pub_key_use_t type for this key

Since

3.0.0

jwks_item_x5c()

const unsigned char * jwks_item_x5c	(	const jwk_item_t *	item,
		size_t	index,
		size_t *	len )

Get a certificate from the JWK x5c chain (DER).

Returns the raw DER bytes of the certificate at index in the x5c chain (index 0 is the leaf, which holds the public key matching the JWK). The bytes are owned by the JWK item and remain valid until it is freed; the caller must not free them. Certificate-chain validation is the caller's responsibility (libjwt does not build or verify the trust chain).

Parameters

item	A JWK Item
index	The certificate index (0 is the leaf)
len	If not NULL, set to the length of the DER in bytes

Returns

The DER bytes, or NULL if index is out of range

Since

3.6.0

jwks_item_x5c_count()

size_t jwks_item_x5c_count

(

const jwk_item_t *

item

)

Number of certificates in the JWK x5c chain.

Parameters

item	A JWK Item

Returns

The number of X.509 certificates in the x5c chain, or 0 if the JWK has none (RFC 7517 §4.7).

Since

3.6.0

jwks_item_x5t()

const char * jwks_item_x5t

(

const jwk_item_t *

item

)

The JWK x5t (SHA-1 certificate thumbprint).

Parameters

item	A JWK Item

Returns

The base64url x5t value (RFC 7517 §4.8), or NULL if absent. The legacy SHA-1 thumbprint is exposed as-is and not recomputed.

Since

3.6.0

jwks_item_x5t_s256()

const char * jwks_item_x5t_s256

(

const jwk_item_t *

item

)

The JWK x5t#S256 (SHA-256 certificate thumbprint).

If the JWK also carries an x5c chain, this value was verified at parse time to equal base64url(SHA-256(DER(leaf))) (RFC 7517 §4.9); a JWK whose x5t#S256 disagrees with its x5c leaf is rejected (the item carries an error).

Parameters

item	A JWK Item

Returns

The base64url x5t#S256 value, or NULL if absent

Since

3.6.0