LibJWT: JWK Management

| LibJWT 3.3.2 The C JSON Web Token Library +JWK +JWKS

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_set | An 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_set | An 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_set | An 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_set | An 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_set | An 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_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.

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

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

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