Checker

Verify and validate JWT tokens. More...

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.
int	jwt_checker_setjti (jwt_checker_t *checker, jwt_jti_check_cb_t cb, void *ctx)
	Set a callback to verify the jti (JWT ID) claim (RFC-7519 Sec 4.1.7).
void *	jwt_checker_getctx (jwt_checker_t *checker)
	Retrieve the callback context that was previously set.
int	jwt_checker_understands (jwt_checker_t *checker, const char *header)
	Declare a critical header parameter as understood (RFC-7515 Sec 4.1.11).
int	jwt_checker_verify (jwt_checker_t *checker, const char *token)
	Verify a token.

Detailed Description

Verify and validate JWT tokens.

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_setjti()

int jwt_checker_setjti	(	jwt_checker_t *	checker,
		jwt_jti_check_cb_t	cb,
		void *	ctx )

Set a callback to verify the jti (JWT ID) claim (RFC-7519 Sec 4.1.7).

When set, verification reads the token's "jti" claim and passes it to the callback, which returns 0 to accept or non-zero to reject the token. This is where an application implements replay protection against its own id pool (look the id up and consume it). When this callback is set, a token that has no "jti" claim is rejected.

The ctx is passed to the callback via the jwt_config_t structure.

Note

Calling this with a NULL cb and a new ctx updates the ctx. Calling with both NULL disables the callback.

Parameters

checker	Pointer to a checker object
cb	Pointer to a jti verification callback
ctx	Pointer to data to pass to the callback

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_understands()

int jwt_checker_understands	(	jwt_checker_t *	checker,
		const char *	header )

Declare a critical header parameter as understood (RFC-7515 Sec 4.1.11).

Per RFC 7515, if a token's crit (Critical) header parameter lists a header name, the recipient MUST understand and process that header or else reject the token. LibJWT understands no extension header parameters on its own, so by default any token carrying a crit header will fail verification.

Use this function to declare each extension header parameter that your application is prepared to handle (typically inspected in your verify callback). During verification, every name listed in crit must both be present in the header and have been declared here; otherwise the token is rejected.

Parameters

checker	Pointer to a checker object
header	Name of the critical header parameter the application understands

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