jwks_core_grp(3)

NAME
jwks_core_grp - JWK Management

SYNOPSIS

  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

  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

  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_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_create_strn (const char * jwk_json_str, const size_t len)

Wrapper around jwks_load_strn() 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. 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.

  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

  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

  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.

  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

  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.

  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.

  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.

  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.

  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.

Author

Generated automatically by Doxygen for LibJWT from the source code.