jwks_core_grp(3)

📦
version 3.3.3 · 2 versions
, in ubuntu stonking

💖 jwks_core_grp — JWK Management 💖

okay bestie, so this is jwks_core_grp(3), a page from the Library Functions Manual, and it's basically the whole JWK keyring saga for LibJWT. if you're signing or validating JWTs and you need to wrangle JSON Web Keys, you're in the right place. grab a strawberry 🍓 and let's go.

✨ SYNOPSIS ✨

Typedefs 📚

  • typedef struct jwk_set jwk_set_t — the Opaque JWKS object. she's mysterious, she's opaque, she holds everything.

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)

(the synopsis gives you literally nothing else, but don't worry, the full glow-up is below 🫶)

👑 Detailed Description 👑

these are the functions that handle JSON representing JWK and JWKS, so you can validate or sign JWT objects. it's giving "the entire plumbing department, but make it cute."

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. she's used for working with JSON Web Keys and JWK Sets (JWKS). no cap, that's her whole job.

Remarks 💅

All JWK operations require that you import your JWK into a jwk_set_t first. Internally, 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. so yeah — one key, forty keys, same vibe, same code. iconic.

🦋 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 — like, she's not screaming, she's just quietly side-eyeing you 😭.

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. (yes, periodt. that's the whole scale.)

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. so this is the group-chat version — she checks the main character and all her friends.

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. emotional reset, cleanse era, we love to see it 🧚

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. (empty string but valid? the duality 💀)

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. the full clean-out-your-closet moment. you gotta do it, bestie. don't leak.

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. (yes, "by by", we're quoting the source, it's staying 💀)

Example: https://example.com/.well-known/jwks.json

Warning 🚨 You should not have private keys available on public web sites. like girl. please. i'm begging. 🔥

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. (not a human girlie, just a robot doing her best 🫶)

and that's the whole page bestie!! ✨ this was LibJWT, Version 3.3.3, straight from the jwks_core_grp(3) files — now go build that keyring, handle your errors, and jwks_free() when you're done. main character energy only. 💅💖🌈

📦 where this page comes from