Provided by: libjwt14-doc_3.2.2-1_all 
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.
LibJWT Version 3.2.2 jwks_core_grp(3)