jwks_item_grp(3)

📦
version 3.3.3 · 2 versions
, in ubuntu stonking

✨ NAME ✨

jwks_item_grp — your whole JSON Web Key usage era, bestie. This is the <pink>jwks_item_grp(3)</pink> manual, from the Library Functions Manual, and it's literally the group chat of every type, enum and function you need to actually use a JWK. 💖

🎀 SYNOPSIS 🎀

🦋 Typedefs

  • typedef struct jwk_item jwk_item_t — the object representation of a JWK, bestie.

🌸 Enumerations

  • enum jwk_key_type_t { JWK_KEY_TYPE_NONE = 0, JWK_KEY_TYPE_EC, JWK_KEY_TYPE_RSA, JWK_KEY_TYPE_OKP, JWK_KEY_TYPE_OCT } — JWK Key Types.
  • enum jwk_pub_key_use_t { JWK_PUB_KEY_USE_NONE = 0, JWK_PUB_KEY_USE_SIG, JWK_PUB_KEY_USE_ENC } — usage types for JWK public keys.
  • enum jwk_key_op_t { JWK_KEY_OP_NONE = 0x0000, JWK_KEY_OP_SIGN = 0x0001, JWK_KEY_OP_VERIFY = 0x0002, JWK_KEY_OP_ENCRYPT = 0x0004, JWK_KEY_OP_DECRYPT = 0x0008, JWK_KEY_OP_WRAP = 0x0010, JWK_KEY_OP_UNWRAP = 0x0020, JWK_KEY_OP_DERIVE_KEY = 0x0040, JWK_KEY_OP_DERIVE_BITS = 0x0080, JWK_KEY_OP_INVALID = 0xffff } — allowed key operations for JWK private keys.

💜 Functions

  • const jwk_item_t * jwks_item_get (const jwk_set_t *jwk_set, size_t index) — hands you the index'th jwk_item out of the jwk_set.
  • jwk_item_t * jwks_find_bykid (jwk_set_t *jwk_set, const char *kid) — sniff out a jwk_item_t by its specific kid (Key ID).
  • int jwks_item_is_private (const jwk_item_t *item) — is this key private, or is it public? the vibe check.
  • int jwks_item_error (const jwk_item_t *item) — checks the error condition for this JWK.
  • const char * jwks_item_error_msg (const jwk_item_t *item) — checks the error message for a JWK Item.
  • const char * jwks_item_curve (const jwk_item_t *item) — the curve name for this key, if that's applicable.
  • const char * jwks_item_kid (const jwk_item_t *item) — a kid (Key ID) for this JWK.
  • jwt_alg_t jwks_item_alg (const jwk_item_t *item) — the algorithm for this JWK.
  • jwk_key_type_t jwks_item_kty (const jwk_item_t *item) — the Key Type of this JWK.
  • jwk_pub_key_use_t jwks_item_use (const jwk_item_t *item) — the "use" field for this JWK.
  • jwk_key_op_t jwks_item_key_ops (const jwk_item_t *item) — the "key_ops" field for this JWK.
  • const char * jwks_item_pem (const jwk_item_t *item) — the PEM generated for the JWK.
  • int jwks_item_key_oct (const jwk_item_t *item, const unsigned char **buf, size_t *len) — retrieves the binary octet data of a key.
  • int jwks_item_key_bits (const jwk_item_t *item) — the number of bits in this JWK.
  • int jwks_item_free (jwk_set_t *jwk_set, size_t index) — removes and frees the *n*th jwk_item_t in a jwk_set.
  • int jwks_item_free_all (jwk_set_t *jwk_set) — removes and frees every jwk_item_t in a jwk_set_t.
  • int jwks_item_free_bad (jwk_set_t *jwk_set) — frees every key marked with an error in a jwk_set_t.
  • size_t jwks_item_count (const jwk_set_t *jwk_set) — returns how many keys live in a jwk_set_t.

🌈 Detailed Description 🌈

It's functionality for using a JWK — which is represented as a jwk_item_t — to sign and validate JWT objects. That's the whole assignment. 💅

💖 Typedef Documentation 💖

typedef struct jwk_item jwk_item_t

Object representation of a JWK. This object gets produced when you import a JWK or a JWKS into a jwk_set_t object. It represents a single key and it's what gets used when generating or verifying a JWT. One key, one little icon. ✨

🧚 Enumeration Type Documentation 🧚

enum jwk_key_op_t

Allowed key operations for JWK private keys. It corresponds to the "key_ops" attribute in a JWK that represents a private key. These can be bitwise compared to the key_ops attribute of a jwk_item_t. These flags get used internally to decide whether a JWK can be used for certain operations, like so:

if (jwk_item_t.key_ops & (JWK_KEY_OP_SIGN | JWK_KEY_OP_ENCRYPT)) {
    ...
}

See also RFC-7517 Sec 4.3, bestie. 📚

Enumerator

  • JWK_KEY_OP_NONE — no key_op set.
  • JWK_KEY_OP_SIGN — signing.
  • JWK_KEY_OP_VERIFY — signature verification.
  • JWK_KEY_OP_ENCRYPT — used for encryption.
  • JWK_KEY_OP_DECRYPT — used for decrypting.
  • JWK_KEY_OP_WRAP — for wrapping other keys.
  • JWK_KEY_OP_UNWRAP — for unwrappng other keys.
  • JWK_KEY_OP_DERIVE_KEY — key derivation.
  • JWK_KEY_OP_DERIVE_BITS — bits derivation.
  • JWK_KEY_OP_INVALID — invalid key_ops in JWK.

enum jwk_key_type_t

JWK Key Types. It corresponds to the "kty" attribute of the JWK.

See also RFC-7517 Sec 4.1 and RFC-7518 Sec 6.1. 📚

Enumerator

  • JWK_KEY_TYPE_NONE — unused on valid keys.
  • JWK_KEY_TYPE_EC — Elliptic Curve keys.
  • JWK_KEY_TYPE_RSA — RSA keys (RSA and RSA-PSS).
  • JWK_KEY_TYPE_OKP — Octet Key Pair (e.g. EdDSA).
  • JWK_KEY_TYPE_OCT — Octet sequence (e.g. HS256).

enum jwk_pub_key_use_t

Usage types for JWK public keys. It corresponds to the "use" attribute in a JWK that represents a public key.

See also RFC-7517 Sec 4.2. 📚

Enumerator

  • JWK_PUB_KEY_USE_NONE — no usable attribute was set.
  • JWK_PUB_KEY_USE_SIG — signature key (JWS).
  • JWK_PUB_KEY_USE_ENC — encryption key (JWE).

👑 Function Documentation 👑

jwk_item_t * jwks_find_bykid (jwk_set_t * jwk_set, const char * kid)

Find a jwk_item_t with a specific kid (Key ID). Heads up: LibJWT does not ensure that kids are unique in a given keyring, so care must be taken. This will return the first match.

Parameters

  • jwk_set — an existing jwk_set_t
  • kid — string representing a kid to find

Returns

A jwk_item_t object, or NULL if none found.

jwt_alg_t jwks_item_alg (const jwk_item_t * item)

The algorithm for this JWK. It is perfectly valid for this to be JWT_ALG_NONE — no drama there. 💅

Parameters

  • item — a JWK Item

Returns

A jwt_alg_t type of this key.

size_t jwks_item_count (const jwk_set_t * jwk_set)

Return the number of keys in a jwk_set_t. Count 'em up. 🔢

Parameters

  • jwk_set — pointer to a JWKS object

Returns

The number of items in the set.

const char * jwks_item_curve (const jwk_item_t * item)

A curve name, if applicable, for this key. Mainly applies to EC and OKP (EdDSA) type keys.

Parameters

  • item — a JWK Item

Returns

A string of the curve name if one exists, NULL otherwise.

int jwks_item_error (const jwk_item_t * item)

Check the error condition for this JWK.

Parameters

  • item — a JWK Item

Returns

1 for true, 0 for false.

const char * jwks_item_error_msg (const jwk_item_t * item)

Check the error message for a JWK Item.

Parameters

  • item — a JWK Item

Returns

A string message. Empty string if there's no error.

int jwks_item_free (jwk_set_t * jwk_set, size_t index)

Remove and free the *n*th jwk_item_t in a jwk_set.

Parameters

  • jwk_set — pointer to a JWKS object
  • index — the position of the item in the index

Returns

0 if no item was deleted (found), 1 if it was.

int jwks_item_free_all (jwk_set_t * jwk_set)

Remove and free all jwk_item_t in a jwk_set_t. The jwk_set_t becomes an empty set — like, fully cleared, ghost town. 🫥

Parameters

  • jwk_set — pointer to a JWKS object

Returns

The number of items deleted.

int jwks_item_free_bad (jwk_set_t * jwk_set)

Free all keys marked with an error in a jwk_set_t. The jwk_set_t becomes an empty set.

Parameters

  • jwk_set — pointer to a JWKS object

Returns

The number of items with an error that were deleted.

const jwk_item_t * jwks_item_get (const jwk_set_t * jwk_set, size_t index)

Return the index'th jwk_item in the jwk_set. This lets you obtain the raw jwk_item. NOTE: this is not a copy of the item, which means that if the jwk_set gets freed, then this data is freed too and cannot be used anymore. 🔥

Parameters

  • jwk_set — an existing jwk_set_t
  • index — index of the jwk_set

Returns

A valid jwk_item_t, or NULL if it doesn't exist.

Warning

The index of an item in a keyring can change if items are deleted. Effort is made to add new JWK to the end of the set, so this should not affect the index of previous items. 🙈

int jwks_item_is_private (const jwk_item_t * item)

Whether this key is private (or public).

Parameters

  • item — a JWK Item

Returns

1 for true, 0 for false.

int jwks_item_key_bits (const jwk_item_t * item)

The number of bits in this JWK. This is relevant to the key type (kty). E.g. an RSA key would have at least 2048 bits, and an EC key would be 256, 384, or 521 bits, etc. Big keys, big energy. 💪

Parameters

  • item — a JWK Item

Returns

The number of bits for the key.

int jwks_item_key_oct (const jwk_item_t * item, const unsigned char ** buf, size_t * len)

Retrieve binary octet data of a key. Only valid for JWT_KEY_TYPE_OCT.

Parameters

  • item — a JWK Item
  • buf — pointer to a pointer buffer
  • len — pointer to a length

Returns

0 on success. buf will point to data of len length. Non-zero on error.

jwk_key_op_t jwks_item_key_ops (const jwk_item_t * item)

The "key_ops" field for this JWK.

Parameters

  • item — a JWK Item

Returns

A jwk_key_op_t type for this key, which represents all of the "key_ops" supported as a bit field.

const char * jwks_item_kid (const jwk_item_t * item)

A kid (Key ID) for this JWK.

Parameters

  • item — a JWK Item

Returns

A string of the kid if one exists, NULL otherwise.

jwk_key_type_t jwks_item_kty (const jwk_item_t * item)

The Key Type of this JWK.

Parameters

  • item — a JWK Item

Returns

A jwk_key_type_t type for this key.

const char * jwks_item_pem (const jwk_item_t * item)

The PEM generated for the JWK. This is an optional field that may or may not be supported depending on which crypto backend is in use. It is provided as a courtesy. 🎀

Parameters

  • item — a JWK Item

Returns

A string of the PEM file for this key, or NULL if none exists.

jwk_pub_key_use_t jwks_item_use (const jwk_item_t * item)

The "use" field for this JWK.

Parameters

  • item — a JWK Item

Returns

A jwk_pub_key_use_t type for this key.

🩷 Author 🩷

Generated automatically by Doxygen for LibJWT from the source code. Not a human's handwriting, it's the robot's. 🤖

okay bestie that's the whole page, no cap — and it was all brought to you by LibJWT, Version 3.3.3, living in the jwks_item_grp(3) page of the Library Functions Manual. go sign some JWTs, you ate. 💅✨🦋

📦 where this page comes from