JSON Web Key Usage
JSON Web Keys
Collaboration diagram for JSON Web Key Usage:

## Typedefs

typedef struct jwk_item | jwk_item_t
| Object representation of a JWK.

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

## Functions

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.
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).
int | jwks_item_is_private (const jwk_item_t *item)
| Whether this key is private (or public).
int | jwks_item_error (const jwk_item_t *item)
| Check the error condition for this JWK.
const char * | jwks_item_error_msg (const jwk_item_t *item)
| Check the error message for a JWK Item.
const char * | jwks_item_curve (const jwk_item_t *item)
| A curve name, if applicable, for this key.
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)
| Retrieve 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)
| Free remove and free the nth jwk_item_t in a jwk_set.
int | jwks_item_free_all (jwk_set_t *jwk_set)
| Remove and free all jwk_item_t in a jwk_set_t.
int | jwks_item_free_bad (jwk_set_t *jwk_set)
| Free all keys marked with an error in a jwk_set_t.
size_t | jwks_item_count (const jwk_set_t *jwk_set)
| Return the number of keys in a jwk_set_t.

## Detailed Description

Functionality for using a JWK (represented as a jwk_item_t) to sign and validate JWT objects.

## Typedef Documentation

## jwk_item_t

typedef struct jwk_item jwk_item_t

Object representation of a JWK.

This object is produced by importing a JWK or JWKS into a jwk_set_t object. It represents single key and is used when generating or verifying JWT.

## Enumeration Type Documentation

## jwk_key_op_t

enum jwk_key_op_t

Allowed key operations for JWK private keys.

Corresponds to the "key_ops" attribute in a JWK that represents a private key. These can be bitwise compares to the key_ops attribute of a jwk_item_t. These flags are used internally to decide if a JWK can be used for certain operations.

if (jwk_item_t.key_ops & (JWK_KEY_OP_SIGN | JWK_KEY_OP_ENCRYPT)) {
...
}
jwk_item_t
struct jwk_item jwk_item_t
Object representation of a JWK.
Definition jwt.h:208
JWK_KEY_OP_ENCRYPT
@ JWK_KEY_OP_ENCRYPT
Definition jwt.h:144
JWK_KEY_OP_SIGN
@ JWK_KEY_OP_SIGN
Definition jwt.h:142

RFC-7517 Sec 4.3

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

## jwk_key_type_t

enum jwk_key_type_t

JWK Key Types.

Corresponds to the "kty" attribute of the JWK.

RFC-7517 Sec 4.1 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)

## jwk_pub_key_use_t

enum jwk_pub_key_use_t

Usage types for JWK public keys.

Corresponds to the "use" attribute in a JWK the represents a public key.

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

## jwks_find_bykid()

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).

LibJWT does not ensure that kid's 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

## jwks_item_alg()

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.

Parameters

  item | A JWK Item

Returns
  A jwt_alg_t type of this key

## jwks_item_count()

size_t jwks_item_count | ( | const jwk_set_t * | jwk_set | ) |

Return the number of keys in a jwk_set_t.

Parameters

  jwk_set | Pointer to a JWKS object

Returns
  The number of items in the set

## jwks_item_curve()

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.

## jwks_item_error()

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

## jwks_item_error_msg()

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 no error.

## jwks_item_free()

int jwks_item_free | ( | jwk_set_t * | jwk_set,
|  | size_t | index )

Free remove and free the nth 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 was deleted (found), 1 if it was

## jwks_item_free_all()

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.

Parameters

  jwk_set | Pointer to a JWKS object

Returns
  The number of items deleted

## jwks_item_free_bad()

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

## jwks_item_get()

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.

Allows you to obtain the raw jwk_item. NOTE, this is not a copy of the item, which means if the jwk_set is freed, then this data is freed and cannot be used.

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.

## jwks_item_is_private()

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

## jwks_item_key_bits()

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.

Parameters

  item | A JWK Item

Returns
  The number of bits for the key

## jwks_item_key_oct()

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.

## jwks_item_key_ops()

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.

## jwks_item_kid()

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.

## jwks_item_kty()

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

## jwks_item_pem()

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

## jwks_item_use()

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