JSON Web Key and Sets

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

Data Structures
struct	jwk_item_t
	Structural representation of a JWK. More...

Typedefs
typedef struct jwk_set	jwk_set_t
	Opaque JWKS object.

Enumerations
enum	jwk_key_type_t { JWK_KEY_TYPE_NONE , JWK_KEY_TYPE_EC , JWK_KEY_TYPE_RSA , JWK_KEY_TYPE_OKP }
	JWK Key Types. More...
enum	jwk_pub_key_use_t { JWK_PUB_KEY_USE_NONE , 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 , JWK_KEY_OP_SIGN , JWK_KEY_OP_VERIFY , JWK_KEY_OP_ENCRYPT ,   JWK_KEY_OP_DECRYPT , JWK_KEY_OP_WRAP , JWK_KEY_OP_UNWRAP , JWK_KEY_OP_DERIVE_KEY ,   JWK_KEY_OP_DERIVE_BITS , JWK_KEY_OP_INVALID }
	Allowed key operations for JWK private keys. More...

Functions
jwk_set_t *	jwks_create (const char *jwk_json_str)
	Create a new JWKS object for later use in validating JWTs.
int	jwks_item_add (jwk_set_t *jwk_set, jwk_item_t *item)
	Add a jwk_item_t to an existing jwk_set_t.
int	jwks_error (jwk_set_t *jwk_set)
	Check if there is an error within the jwk_set.
int	jwks_error_any (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 (jwk_set_t *jwk_set)
	Retrieve an error message from a jwk_set.
jwk_item_t *	jwks_item_get (jwk_set_t *jwk_set, size_t index)
	Return the index'th jwk_item in the jwk_set.
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.
int	jwks_item_free (jwk_set_t *jwk_set, size_t index)
	Free all memory associated with the nth jwt_item_t in a jwk_set.
int	jwks_item_free_all (jwk_set_t *jwk_set)
	Free all memory associated with alljwt_item_t in a jwk_set.

Detailed Description

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

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.

Definition at line 82 of file jwt.h.

Enumeration Type Documentation

jwk_key_op_t

enum jwk_key_op_t

Allowed key operations for JWK private keys.

A JWK can support one or more of these bitwise flag operations. The names correspond with the RFC.

if (@ref jwt_item_t.key_ops & (JWK_KEY_OP_SIGN | JWK_KEY_OP_ENCRYPT)) {
    ...
}

RFC-7517 Sec 4.3

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.

Definition at line 177 of file jwt.h.

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

Enumerator
JWK_KEY_TYPE_NONE	Unused on valid keys.
JWK_KEY_TYPE_EC	Eliptic Curve keys.
JWK_KEY_TYPE_RSA	RSA keys (RSA and RSA-PSS)
JWK_KEY_TYPE_OKP	Octet Key Pair (e.g. EDDSA)

Definition at line 143 of file jwt.h.

jwk_pub_key_use_t

enum jwk_pub_key_use_t

Usage types for JWK public keys.

Corresponds to the "use" attribute in a valid JWK.

RFC-7517 Sec 4.2

Enumerator
JWK_PUB_KEY_USE_NONE	No usable attribute was set.
JWK_PUB_KEY_USE_SIG	Signature validation (JWS)
JWK_PUB_KEY_USE_ENC	Decryption key (JWE)

Definition at line 157 of file jwt.h.

Function Documentation

jwks_create()

jwk_set_t * jwks_create

(

const char *

jwk_json_str

)

Create a new JWKS object for later use in validating JWTs.

This function expects a JSON string either as a single object for one JWK or as an array of objects under a key of "keys" (as defined in JWKS specifications).

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_json_str

JSON string representation of a single key or array of "keys". If NULL is passed, an empty jwk_set_t is created.

Returns

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

jwks_error()

int jwks_error

(

jwk_set_t *

jwk_set

)

Check if there is an error within the jwk_set.

To get a string describing the error, use jwks_error_str.

Parameters

jwk_set

An existing jwk_set_t

Returns

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

jwks_error_any()

int jwks_error_any

(

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, 1 if any exists.

jwks_error_msg()

const char * jwks_error_msg

(

jwk_set_t *

jwk_set

)

Retrieve an error message from a jwk_set.

Note, a zero length string is valid if jwos_error() returns non-zero.

Parameters

jwk_set

An existing jwk_set_t

Returns

NULL on error, valid string otherwise

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

jwks_item_add()

int jwks_item_add	(	jwk_set_t *	jwk_set,
		jwk_item_t *	item )

Add a jwk_item_t to an existing jwk_set_t.

Parameters

jwk_set	An existing jwk_set_t
item	A JWK item to add to the set

Returns

0 on success, valid errno otherwise.

jwks_item_free()

int jwks_item_free	(	jwk_set_t *	jwk_set,
		size_t	index )

Free all memory associated with the nth jwt_item_t in a jwk_set.

Parameters

jwk_set	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

jwks_item_free_all()

int jwks_item_free_all

(

jwk_set_t *

jwk_set

)

Free all memory associated with alljwt_item_t in a jwk_set.

The jwk_set becomes an empty set.

Parameters

jwk_set

A JWKS object

Returns

The numbner of items deleted

jwks_item_get()

jwk_item_t * jwks_item_get	(	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, so any changes to it will be reflected to it in the jwk_set. This also 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

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

Remarks

It's also worth pointing out that the index of a specific jwk_item in a jwk_set can and will change if items are added or removed. from the jwk_set.