JWK Management

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

Collaboration diagram for JWK Management:

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_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.
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)

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 random (uuidv4) "kid" 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_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_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_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