JWK Management

Create and manage keyrings of JWK and JWKS keys. More...

Collaboration diagram for JWK Management:

Data Structures
struct	jwks_url_config_t
	Configuration for a cached remote JWKS source. More...

Macros
#define	jwk_set_auto_t   jwk_set_t __attribute__((cleanup(jwks_freep)))
	A jwk_set_t pointer that is freed automatically at scope exit.

Typedefs
typedef struct jwk_set	jwk_set_t
	Opaque JWKS object.

Enumerations
enum	jwk_key_flags_t { JWK_KEY_NONE = 0x0000 , JWK_KEY_GEN_KID = 0x0001 , JWK_KEY_TRY_HMAC = 0x0002 }
	Flags controlling how a native key is imported into a keyring. More...

Functions
jwk_set_t *	jwks_load (jwk_set_t *jwk_set, const char *jwk_json_str)
	Create or add to a keyring from a null terminated string.
jwk_set_t *	jwks_load_strn (jwk_set_t *jwk_set, const char *jwk_json_str, const size_t len)
	Create or add to a keyring from a string of known length.
jwk_set_t *	jwks_load_fromfile (jwk_set_t *jwk_set, const char *file_name)
	Create or add to a keyring from a file.
jwk_set_t *	jwks_load_fromfp (jwk_set_t *jwk_set, FILE *input)
	Create or add to a keyring from a FILE pointer.
jwk_set_t *	jwks_load_fromurl (jwk_set_t *jwk_set, const char *url, int verify)
	Create or add to a keyring from a URL.
jwk_set_t *	jwks_create (const char *jwk_json_str)
	Wrapper around jwks_load() that explicitly creates a new keyring.
jwk_set_t *	jwks_create_strn (const char *jwk_json_str, const size_t len)
	Wrapper around jwks_load_strn() that explicitly creates a new keyring.
jwk_set_t *	jwks_create_fromfile (const char *file_name)
	Wrapper around jwks_load_fromfile() that explicitly creates a new keyring.
jwk_set_t *	jwks_create_fromfp (FILE *input)
	Wrapper around jwks_load_fromfp() that explicitly creates a new keyring.
jwk_set_t *	jwks_create_fromurl (const char *url, int verify)
	Wrapper around jwks_load_fromurl() that explicitly creates a new keyring.
jwk_set_t *	jwks_load_fromurl_cached (jwk_set_t *jwk_set, const char *url, const jwks_url_config_t *config)
	Load a JWKS from a URL with caching, TTL, and conditional refresh.
jwk_set_t *	jwks_refresh_fromurl (jwk_set_t *jwk_set)
	Force a refresh of a cached JWKS source (key rotation).
jwk_set_t *	jwks_load_fromkey (jwk_set_t *jwk_set, const char *key, const size_t len, unsigned int flags)
	Create or add to a keyring by importing a native key.
jwk_set_t *	jwks_load_fromkey_file (jwk_set_t *jwk_set, const char *file_name, unsigned int flags)
	Create or add to a keyring by importing a native key from a file.
jwk_set_t *	jwks_create_fromkey (const char *key, const size_t len, unsigned int flags)
	Wrapper around jwks_load_fromkey() that explicitly creates a new keyring.
jwk_set_t *	jwks_create_fromkey_file (const char *file_name, unsigned int flags)
	Wrapper around jwks_load_fromkey_file() that explicitly creates a new keyring.
jwk_set_t *	jwks_generate (jwk_set_t *jwk_set, jwk_key_type_t kty, const char *param, jwt_alg_t alg, unsigned int flags)
	Generate a new key and add it to a keyring as a JWK.
jwk_set_t *	jwks_create_generate (jwk_key_type_t kty, const char *param, jwt_alg_t alg, unsigned int flags)
	Wrapper around jwks_generate() that explicitly creates a new keyring.
int	jwks_error (const jwk_set_t *jwk_set)
	Check if there is an error with a jwk_set.
int	jwks_error_any (const jwk_set_t *jwk_set)
	Check if there is an error within the jwk_set and any of the jwk_item_t in the set.
const char *	jwks_error_msg (const jwk_set_t *jwk_set)
	Retrieve an error message from a jwk_set.
void	jwks_error_clear (jwk_set_t *jwk_set)
	Clear an error condition in a jwk_set.
void	jwks_free (jwk_set_t *jwk_set)

Detailed Description

Create and manage keyrings of JWK and JWKS keys.

Functions to handle JSON that represents JWK and JWKS for use in validating or signing JWT objects.

Note

The jwks_create functions are convenience wrappers around the same-named jwks_load functions. They explicitly create a keyring.

If you want to create an empty keyring, simply call jwks_create(NULL)

Macro Definition Documentation

jwk_set_auto_t

#define jwk_set_auto_t   jwk_set_t __attribute__((cleanup(jwks_freep)))

A jwk_set_t pointer that is freed automatically at scope exit.

Declares a jwk_set_t pointer carrying the GCC/Clang cleanup attribute so jwks_free() is invoked on it automatically when the variable goes out of scope. Initialize it where you declare it.

Since

3.0.0

Typedef Documentation

jwk_set_t

typedef struct jwk_set jwk_set_t

Opaque JWKS object.

Used for working with JSON Web Keys and JWK Sets (JWKS).

Remarks

All JWK operations require that you import your JWK into a jwk_set_t first. Internal, LibJWT creates a jwk_set_t even for single keys. This makes code pretty much the same whether working with one JWK or a set of them.

Since

3.0.0

Enumeration Type Documentation

jwk_key_flags_t

enum jwk_key_flags_t

Flags controlling how a native key is imported into a keyring.

Used with the jwks_load_fromkey() and jwks_create_fromkey() family. The input to those functions may be a PEM file, a DER file, or (with JWK_KEY_TRY_HMAC) raw bytes treated as an HMAC key, so these flags are named JWK_KEY_* rather than anything PEM-specific.

Since

3.4.0

Enumerator
JWK_KEY_NONE	No options
JWK_KEY_GEN_KID	Generate a deterministic "kid" (the 📄 RFC-7638 JWK SHA-256 thumbprint) for each imported key
JWK_KEY_TRY_HMAC	If the input does not parse as a PEM/DER key, treat the raw bytes as an "oct" (HMAC) key

Function Documentation

jwks_create()

jwk_set_t * jwks_create

(

const char *

jwk_json_str

)

Wrapper around jwks_load() that explicitly creates a new keyring.

Since

3.0.0

jwks_create_fromfile()

jwk_set_t * jwks_create_fromfile

(

const char *

file_name

)

Wrapper around jwks_load_fromfile() that explicitly creates a new keyring.

Since

3.0.0

jwks_create_fromfp()

jwk_set_t * jwks_create_fromfp

(

FILE *

input

)

Wrapper around jwks_load_fromfp() that explicitly creates a new keyring.

Since

3.0.0

jwks_create_fromkey()

jwk_set_t * jwks_create_fromkey	(	const char *	key,
		const size_t	len,
		unsigned int	flags )

Wrapper around jwks_load_fromkey() that explicitly creates a new keyring.

Since

3.4.0

jwks_create_fromkey_file()

jwk_set_t * jwks_create_fromkey_file	(	const char *	file_name,
		unsigned int	flags )

Wrapper around jwks_load_fromkey_file() that explicitly creates a new keyring.

Since

3.4.0

jwks_create_fromurl()

jwk_set_t * jwks_create_fromurl	(	const char *	url,
		int	verify )

Wrapper around jwks_load_fromurl() that explicitly creates a new keyring.

Since

3.2.0

jwks_create_generate()

jwk_set_t * jwks_create_generate	(	jwk_key_type_t	kty,
		const char *	param,
		jwt_alg_t	alg,
		unsigned int	flags )

Wrapper around jwks_generate() that explicitly creates a new keyring.

Since

3.6.0

jwks_create_strn()

jwk_set_t * jwks_create_strn	(	const char *	jwk_json_str,
		const size_t	len )

Wrapper around jwks_load_strn() that explicitly creates a new keyring.

Since

3.0.0

jwks_error()

int jwks_error

(

const jwk_set_t *

jwk_set

)

Check if there is an error with a jwk_set.

An Error in a jwk_set is usually passive and generally means there was an issue loading the JWK(S) data.

To get a string describing the error, use jwks_error_msg(). You can clear the error with jwks_error_clear().

Parameters

jwk_set

An existing jwk_set_t

Returns

0 if no error exists, 1 if it does exists.

Since

3.0.0

jwks_error_any()

int jwks_error_any

(

const jwk_set_t *

jwk_set

)

Check if there is an error within the jwk_set and any of the jwk_item_t in the set.

Parameters

jwk_set

An existing jwk_set_t

Returns

0 if no error exists, or the number of errors in the set

Since

3.0.0

jwks_error_clear()

void jwks_error_clear

(

jwk_set_t *

jwk_set

)

Clear an error condition in a jwk_set.

Parameters

jwk_set

An existing jwk_set_t

Since

3.0.0

jwks_error_msg()

const char * jwks_error_msg

(

const jwk_set_t *

jwk_set

)

Retrieve an error message from a jwk_set.

Note

A zero length string is valid even if jwks_error() returns non-zero.

Parameters

jwk_set

An existing jwk_set_t

Returns

A string message. The string may be empty.

Since

3.0.0

jwks_free()

void jwks_free

(

jwk_set_t *

jwk_set

)

Free all memory associated with a jwt_set_t, including any jwk_item_t in the set.

Parameters

jwk_set

An existing jwk_set_t

Since

3.0.0

jwks_generate()

jwk_set_t * jwks_generate	(	jwk_set_t *	jwk_set,
		jwk_key_type_t	kty,
		const char *	param,
		jwt_alg_t	alg,
		unsigned int	flags )

Generate a new key and add it to a keyring as a JWK.

Generates a fresh key of type kty and appends it to jwk_set as a new jwk_item_t (a private JWK), returning the set. Pass NULL for jwk_set to create a new keyring. The generated key is bound to the active crypto backend, so it can be used directly for signing/verifying or JWE.

param selects the key geometry, interpreted by kty (NULL or "" picks a sensible default):

• EC: the curve — "P-256" (default), "P-384", "P-521", "secp256k1"
• OKP: the curve — "Ed25519" (default), "Ed448", "X25519", "X448"
• RSA: the modulus size in bits — "2048" (default), "3072", "4096"
• oct: the key size in bits — "256" (default), "384", "512"
• AKP (ML-DSA): ignored (the variant comes from alg)

alg is the JWA discriminator. It is optional for EC/OKP/oct (it stamps the JWK "alg"), distinguishes RSA (RS*) from RSA-PSS (PS*) for kty=RSA, and is REQUIRED for AKP to pin the ML-DSA variant (JWT_ALG_ML_DSA_44/65/87). Pass JWT_ALG_NONE for none. It must be compatible with kty.

flags is a bitwise OR of jwk_key_flags_t; JWK_KEY_GEN_KID stamps the RFC 7638 thumbprint as the "kid".

A backend that cannot generate the requested key (e.g. MbedTLS has no EdDSA) does not crash: the appended item carries an error (jwks_item_error()).

Parameters

jwk_set	A keyring to append to, or NULL to create a new one
kty	The key type to generate
param	The key geometry selector (see above), or NULL for the default
alg	The JWA algorithm discriminator, or JWT_ALG_NONE
flags	A bitwise OR of jwk_key_flags_t values (or JWK_KEY_NONE)

Returns

The keyring with the new key appended, or NULL on allocation failure

Since

3.6.0

jwks_load()

jwk_set_t * jwks_load	(	jwk_set_t *	jwk_set,
		const char *	jwk_json_str )

Create or add to a keyring from a null terminated string.

This function, and the utility versions, allow you to create a keyring used to verify and/or create JSON Web Tokens. It accepts either single JWK or a JWKS (JSON Web Token Set).

If you want to create a new set, then pass NULL as the first argument. If you want to add to an existing keyring, then pass that as the first argument.

If non-NULL is returned, you should then check to make sure there is no error with jwks_error(). There may be errors on individual JWK items in the set. You can check if there are any with jwks_error_any().

Parameters

jwk_set	Either NULL to create a new set, or an existing jwt_set to add new keys to it.
jwk_json_str	JSON string representation of a single key or array of "keys".

Returns

A valid jwt_set_t on success. On failure, either NULL or a jwt_set_t with error set. NULL generally means ENOMEM.

Since

3.0.0

jwks_load_fromfile()

jwk_set_t * jwks_load_fromfile	(	jwk_set_t *	jwk_set,
		const char *	file_name )

Create or add to a keyring from a file.

The JSON will be read from a file on the system. Must be readable by the running process. The end result of this function is the same as jwks_load.

Parameters

jwk_set	Either NULL to create a new set, or an existing jwt_set to add new keys to it.
file_name	A file containing a JSON representation of a single key or array of "keys".

Returns

A valid jwt_set_t on success. On failure, either NULL or a jwt_set_t with error set. NULL generally means ENOMEM.

Since

3.0.0

jwks_load_fromfp()

jwk_set_t * jwks_load_fromfp	(	jwk_set_t *	jwk_set,
		FILE *	input )

Create or add to a keyring from a FILE pointer.

The JSON will be read from a FILE pointer. The end result of this function is the same as jwks_load. The FILE pointer must be set to the starting position of the JWK data. This function will read until it reaches EOF or invalid JSON data.

Parameters

jwk_set	Either NULL to create a new set, or an existing jwt_set to add new keys to it.
input	A FILE pointer where the JSON representation of a single key or array of "keys" can be fread() from.

Returns

A valid jwt_set_t on success. On failure, either NULL or a jwt_set_t with error set. NULL generally means ENOMEM.

Since

3.0.0

jwks_load_fromkey()

jwk_set_t * jwks_load_fromkey	(	jwk_set_t *	jwk_set,
		const char *	key,
		const size_t	len,
		unsigned int	flags )

Create or add to a keyring by importing a native key.

Import a key that is NOT already in JWK form — a PEM or DER encoded public or private key (RSA, RSA-PSS, EC, or EdDSA), or (with JWK_KEY_TRY_HMAC) raw bytes treated as an HMAC key — and convert it into a JWK in the keyring. This is the inverse of jwks_item_pem().

As with jwks_load(), pass NULL as jwk_set to create a new keyring, or an existing one to add to it. On success you should check jwks_error() and jwks_error_any() as with any other loader.

Parameters

jwk_set	Either NULL to create a new set, or an existing jwk_set_t to add the imported key to.
key	A buffer holding a single PEM, DER, or raw key.
len	The length of key in bytes.
flags	A bitwise OR of jwk_key_flags_t values (or JWK_KEY_NONE).

Returns

A valid jwk_set_t on success. On failure, either NULL or a jwk_set_t with error set. NULL generally means ENOMEM or that the key could not be parsed.

Since

3.4.0

jwks_load_fromkey_file()

jwk_set_t * jwks_load_fromkey_file	(	jwk_set_t *	jwk_set,
		const char *	file_name,
		unsigned int	flags )

Create or add to a keyring by importing a native key from a file.

Like jwks_load_fromkey(), but reads the key from a file (PEM or DER).

Parameters

jwk_set	Either NULL to create a new set, or an existing jwk_set_t to add the imported key to.
file_name	Path to a file holding a single PEM, DER, or raw key.
flags	A bitwise OR of jwk_key_flags_t values (or JWK_KEY_NONE).

Returns

A valid jwk_set_t on success. On failure, either NULL or a jwk_set_t with error set.

Since

3.4.0

jwks_load_fromurl()

jwk_set_t * jwks_load_fromurl	(	jwk_set_t *	jwk_set,
		const char *	url,
		int	verify )

Create or add to a keyring from a URL.

The JSON will be retrieved from a URL. This can be any URL understood by by Libcurl.

Example: https://example.com/.well-known/jwks.json

Warning

You should not have private keys available on public web sites.

Parameters

jwk_set	Either NULL to create a new set, or an existing jwt_set to add new keys to it.
url	A string URL to where the JSON representation of a single key or array of "keys" can be retrieved from. Generally a json file.
verify	Set to non-zero to fully verify the TLS connection (certificate chain/peer and hostname); set to 0 to disable verification entirely. Non-zero is strongly recommended: hostname verification on its own is meaningless, so any value >= 1 enables both peer and host verification. 0 disables all verification and is insecure (use only for testing).

Returns

A valid jwt_set_t on success. On failure, either NULL or a jwt_set_t with error set. NULL generally means ENOMEM.

Since

3.2.0

jwks_load_fromurl_cached()

jwk_set_t * jwks_load_fromurl_cached	(	jwk_set_t *	jwk_set,
		const char *	url,
		const jwks_url_config_t *	config )

Load a JWKS from a URL with caching, TTL, and conditional refresh.

A caching wrapper around the network fetch (only with libcurl). The keyring jwk_set holds the cache: on the first call it is fetched and stored; on a later call with the same jwk_set and url the cached keys are returned without a network request while they are still fresh. Freshness comes from the response Cache-Control: max-age if present, otherwise jwks_url_config_t::ttl. Once stale, a conditional GET (If-None-Match with the stored ETag) refreshes the cache; a 304 Not Modified keeps the existing keys.

Only http and https URLs are accepted (an SSRF guard; unlike jwks_load_fromurl(), which also allows file://). On a refresh failure the previously cached keys are retained and the error is set on the keyring.

Parameters

jwk_set	An existing cached keyring to reuse, or NULL to create one
url	The JWKS URL (http/https)
config	Cache configuration, or NULL for the defaults

Returns

The keyring (cached or refreshed), or NULL on allocation failure or when built without libcurl

Since

3.6.0

jwks_load_strn()

jwk_set_t * jwks_load_strn	(	jwk_set_t *	jwk_set,
		const char *	jwk_json_str,
		const size_t	len )

Create or add to a keyring from a string of known length.

Useful if the string is not null terminated. Otherwise, it works the same as jwks_load().

Parameters

jwk_set	Either NULL to create a new set, or an existing jwt_set to add new keys to it.
jwk_json_str	JSON string representation of a single key or array of "keys".
len	The length of jwk_json_str that represents the key(s) being read.

Returns

A valid jwt_set_t on success. On failure, either NULL or a jwt_set_t with error set. NULL generally means ENOMEM.

Since

3.0.0

jwks_refresh_fromurl()

jwk_set_t * jwks_refresh_fromurl

(

jwk_set_t *

jwk_set

)

Force a refresh of a cached JWKS source (key rotation).

Intended for an unknown-kid (key rotation) miss: re-fetch the JWKS even if the cache is still fresh. The refresh is rate-limited by the cooldown configured in jwks_load_fromurl_cached() — within the cooldown window this is a no-op, which bounds outbound requests an attacker could trigger by presenting random kid values.

Parameters

jwk_set

A keyring previously populated by jwks_load_fromurl_cached()

Returns

The keyring (possibly refreshed); a keyring with no cache is returned unchanged

Since

3.6.0