LibJWT 3.2.0
The C JSON Web Token Library +JWK +JWKS
Typedefs | Functions
JWK Management
JSON Web Keys
Collaboration diagram for JWK Management:

Typedefs

typedef struct jwk_set jwk_set_t
 Opaque JWKS object.
 

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

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.

Function Documentation

◆ jwks_create()

jwk_set_t * jwks_create ( const char * jwk_json_str)

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

◆ jwks_create_fromfile()

jwk_set_t * jwks_create_fromfile ( const char * file_name)

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

◆ jwks_create_fromfp()

jwk_set_t * jwks_create_fromfp ( FILE * input)

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

◆ 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.

◆ 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.

◆ 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_setAn existing jwk_set_t
Returns
0 if no error exists, 1 if it does exists.

◆ 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_setAn existing jwk_set_t
Returns
0 if no error exists, or the number of errors in the set

◆ jwks_error_clear()

void jwks_error_clear ( jwk_set_t * jwk_set)

Clear an error condition in a jwk_set.

Parameters
jwk_setAn existing jwk_set_t

◆ 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_setAn existing jwk_set_t
Returns
A string message. The string may be empty.

◆ 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_setAn existing jwk_set_t

◆ 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_setEither NULL to create a new set, or an existing jwt_set to add new keys to it.
jwk_json_strJSON 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.

◆ 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_setEither NULL to create a new set, or an existing jwt_set to add new keys to it.
file_nameA 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.

◆ 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_setEither NULL to create a new set, or an existing jwt_set to add new keys to it.
inputA 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.

◆ 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_setEither NULL to create a new set, or an existing jwt_set to add new keys to it.
urlA string URL to where the JSON representation of a single key or array of "keys" can be retrieved from. Generally a json file.
verifySet to 1 to verify the Host, 2 to verify Host and Peer. 2 is recommended unless you really need to disable with 0.
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_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_setEither NULL to create a new set, or an existing jwt_set to add new keys to it.
jwk_json_strJSON string representation of a single key or array of "keys".
lenThe 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.