LibJWT: Checker

| LibJWT 3.3.2 The C JSON Web Token Library +JWK +JWKS

Checker
JSON Web Token
Collaboration diagram for Checker:

## Typedefs
typedef struct jwt_checker | jwt_checker_t
| Opaque Checker object.

## Functions
jwt_checker_t * | jwt_checker_new (void)
| Function to create a new checker instance.
void | jwt_checker_free (jwt_checker_t *checker)
| Frees a previously created checker object.
int | jwt_checker_error (const jwt_checker_t *checker)
| Checks error state of checker object.
const char * | jwt_checker_error_msg (const jwt_checker_t *checker)
| Get the error message contained in a checker object.
void | jwt_checker_error_clear (jwt_checker_t *checker)
| Clear error state in a checker object.
int | jwt_checker_setkey (jwt_checker_t *checker, const jwt_alg_t alg, const jwk_item_t *key)
| Sets a key and algorithm for a checker.
int | jwt_checker_setcb (jwt_checker_t *checker, jwt_callback_t cb, void *ctx)
| Set a callback for generating tokens.
void * | jwt_checker_getctx (jwt_checker_t *checker)
| Retrieve the callback context that was previously set.
int | jwt_checker_verify (jwt_checker_t *checker, const char *token)
| Verify a token.

## Detailed Description

Validating a JWT involves decoding the Base64url parts of the JWT then verifying claims and the signature hash. The checker object allows you to configure how you want to perform these steps so you can easily process tokens with one simple call.

## Typedef Documentation

## ◆ jwt_checker_t

typedef struct jwt_checker jwt_checker_t

Opaque Checker object.

## Function Documentation

## ◆ jwt_checker_error()

int jwt_checker_error | ( | const jwt_checker_t * | checker | ) |

Checks error state of checker object.

Parameters

  checker | Pointer to a checker object

Returns
  0 if no errors exist, non-zero otherwise

## ◆ jwt_checker_error_clear()

void jwt_checker_error_clear | ( | jwt_checker_t * | checker | ) |

Clear error state in a checker object.

Parameters

  checker | Pointer to a checker object

## ◆ jwt_checker_error_msg()

const char * jwt_checker_error_msg | ( | const jwt_checker_t * | checker | ) |

Get the error message contained in a checker object.

Parameters

  checker | Pointer to a checker object

Returns
  Pointer to a string with the error message. Can be an empty string if there is no error. Never returns NULL.

## ◆ jwt_checker_free()

void jwt_checker_free | ( | jwt_checker_t * | checker | ) |

Frees a previously created checker object.

Parameters

  checker | Pointer to a checker object

## ◆ jwt_checker_getctx()

void * jwt_checker_getctx | ( | jwt_checker_t * | checker | ) |

Retrieve the callback context that was previously set.

This is useful for accessing the context that was previously passed in the setcb function.

Parameters

  checker | Pointer to a checker object

Returns
  Pointer to the context or NULL

## ◆ jwt_checker_new()

jwt_checker_t * jwt_checker_new | ( | void |  | ) |

Function to create a new checker instance.

Returns
  Pointer to a checker object on success, NULL on failure

## ◆ jwt_checker_setcb()

int jwt_checker_setcb | ( | jwt_checker_t * | checker,
|  | jwt_callback_t | cb,
|  | void * | ctx )

Set a callback for generating tokens.

When verifying a token, this callback will be run after jwt_t has been parsed, but before the token is verified (including signature verification). During this, the callback should only inspect the header or claims in the JWT. Any attempts to make changes to the jwt_t object will not change the rest of the process.

The callback can also set the key and algorithm used to verify the signature. If the callback returns non-zero, then processing will stop and return an error.

The ctx value is also passed to the callback as part of the jwt_value_t struct.

Note
  Calling this with a NULL cb param and a new ctx param after already setting the callback will allow updating the ctx passed to the callback. Calling with both values as NULL will disable the callback completely.

Parameters

  checker | Pointer to a checker object
  cb | Pointer to a callback function
  ctx | Pointer to data to pass to the callback function

Returns
  0 on success, non-zero otherwise with error set in the checker

## ◆ jwt_checker_setkey()

int jwt_checker_setkey | ( | jwt_checker_t * | checker,
|  | const jwt_alg_t | alg,
|  | const jwk_item_t * | key )

Sets a key and algorithm for a checker.

See jwt_builder_setkey for detailed information.

Parameters

  checker | Pointer to a checker object
  alg | A valid jwt_alg_t type
  key | A JWK key object

Returns
  0 on success, non-zero otherwise with error set in the checker

## ◆ jwt_checker_verify()

int jwt_checker_verify | ( | jwt_checker_t * | checker,
|  | const char * | token )

Verify a token.

Note
  If you set a callback for this checker, this is when it will be called.

Parameters

  checker | Pointer to a checker object
  token | A string containing a token to be verified

Returns
  0 on success, non-zero otherwise with error set in the checker