JWT validation functions

These functions allow you to define requirements for JWT validation. More...

Functions
unsigned int	jwt_validate (jwt_t *jwt, jwt_valid_t *jwt_valid)
	Validate a JWT object with a validation object.
int	jwt_valid_new (jwt_valid_t **jwt_valid, jwt_alg_t alg)
	Allocate a new, JWT validation object.
void	jwt_valid_free (jwt_valid_t *jwt_valid)
	Free a JWT validation object and any other resources it is using.
unsigned int	jwt_valid_get_status (jwt_valid_t *jwt_valid)
	Return the status string for the validation object.
time_t	jwt_valid_get_nbf_leeway (jwt_valid_t *jwt_valid)
	Return the nbf_leeway value set.
time_t	jwt_valid_get_exp_leeway (jwt_valid_t *jwt_valid)
	Return the exp_leeway value set.
int	jwt_valid_add_grant (jwt_valid_t *jwt_valid, const char *grant, const char *val)
	Add a new string grant requirement to this JWT validation object.
const char *	jwt_valid_get_grant (jwt_valid_t *jwt_valid, const char *grant)
	Return the value of a string required grant.
int	jwt_valid_add_grant_int (jwt_valid_t *jwt_valid, const char *grant, long val)
	Add a new integer grant requirement to this JWT validation object.
long	jwt_valid_get_grant_int (jwt_valid_t *jwt_valid, const char *grant)
	Return the value of an integer required grant.
int	jwt_valid_add_grant_bool (jwt_valid_t *jwt_valid, const char *grant, int val)
	Add a new boolean required grant to this JWT validation object.
int	jwt_valid_get_grant_bool (jwt_valid_t *jwt_valid, const char *grant)
	Return the value of an boolean required grant.
int	jwt_valid_add_grants_json (jwt_valid_t *jwt_valid, const char *json)
	Add required grants from a JSON encoded object string.
char *	jwt_valid_get_grants_json (jwt_valid_t *jwt_valid, const char *grant)
	Return the value of a grant as JSON encoded object string.
int	jwt_valid_del_grants (jwt_valid_t *jwt_valid, const char *grant)
	Delete a grant from this JWT object.
int	jwt_valid_set_now (jwt_valid_t *jwt_valid, const time_t now)
	Set the time for which expires and not-before claims should be evaluated.
int	jwt_valid_set_nbf_leeway (jwt_valid_t *jwt_valid, const time_t nbf_leeway)
	Set the nbf_leeway value as defined in: https://www.rfc-editor.org/rfc/rfc7519#section-4.1.5.
int	jwt_valid_set_exp_leeway (jwt_valid_t *jwt_valid, const time_t exp_leeway)
	Set the exp_leeway value as defined in: https://www.rfc-editor.org/rfc/rfc7519#section-4.1.4.
int	jwt_valid_set_headers (jwt_valid_t *jwt_valid, int hdr)
	Set validation for replicated claims in headers.
char *	jwt_exception_str (unsigned int exceptions)
	Parses exceptions and returns a comma delimited and human-readable string.

Detailed Description

These functions allow you to define requirements for JWT validation.

The most basic validation is that the JWT uses the expected algorithm.

When replicating claims in header (usually for encrypted JWT), validation tests that they match claims in the body (iss, sub, aud).

Time-based claims can also be validated (nbf, exp).

Finally, validation can test that claims be present and have certain value.

Function Documentation

jwt_exception_str()

char * jwt_exception_str

(

unsigned int

exceptions

)

Parses exceptions and returns a comma delimited and human-readable string.

The returned string must be freed by the caller. If you changed the allocation method using jwt_set_alloc, then you must use jwt_free_str() to free the memory.

Note: This string is currently en-US ASCII only. Language support will come in the future.

Parameters

exceptions

Integer containing the exception flags.

Returns

A null terminated string on success, NULL on error with errno set appropriately.

jwt_valid_add_grant()

int jwt_valid_add_grant	(	jwt_valid_t *	jwt_valid,
		const char *	grant,
		const char *	val )

Add a new string grant requirement to this JWT validation object.

Parameters

jwt_valid	Pointer to a JWT validation object.
grant	String containing the name of the grant to add.
val	String containing the value to be saved for grant. Can be an empty string, but cannot be NULL.

Returns

Returns 0 on success, valid errno otherwise.

Note, this only allows for string based grants. If you wish to add integer grants, then use jwt_valid_add_grant_int(). If you wish to add more complex grants (e.g. an array), then use jwt_valid_add_grants_json().

jwt_valid_add_grant_bool()

int jwt_valid_add_grant_bool	(	jwt_valid_t *	jwt_valid,
		const char *	grant,
		int	val )

Add a new boolean required grant to this JWT validation object.

Creates a new grant for this object. The string for grant is copied internally, so do not require that the pointer or string remain valid for the lifetime of this object. It is an error if you try to add a grant that already exists.

Parameters

jwt_valid	Pointer to a JWT validation object.
grant	String containing the name of the grant to add.
val	boolean containing the value to be saved for grant.

Returns

Returns 0 on success, valid errno otherwise.

Note, this only allows for boolean based grants. If you wish to add string grants, then use jwt_valid_add_grant(). If you wish to add more complex grants (e.g. an array), then use jwt_valid_add_grants_json().

jwt_valid_add_grant_int()

int jwt_valid_add_grant_int	(	jwt_valid_t *	jwt_valid,
		const char *	grant,
		long	val )

Add a new integer grant requirement to this JWT validation object.

Parameters

jwt_valid	Pointer to a JWT validation object.
grant	String containing the name of the grant to add.
val	int containing the value to be saved for grant.

Returns

Returns 0 on success, valid errno otherwise.

Note, this only allows for integer based grants. If you wish to add string grants, then use jwt_valid_add_grant(). If you wish to add more complex grants (e.g. an array), then use jwt_valid_add_grants_json().

jwt_valid_add_grants_json()

int jwt_valid_add_grants_json	(	jwt_valid_t *	jwt_valid,
		const char *	json )

Add required grants from a JSON encoded object string.

Loads a grant from an existing JSON encoded object string. Overwrites existing grant.

Parameters

jwt_valid	Pointer to a JWT validation object.
json	String containing a JSON encoded object of grants.

Returns

Returns 0 on success, valid errno otherwise.

jwt_valid_del_grants()

int jwt_valid_del_grants	(	jwt_valid_t *	jwt_valid,
		const char *	grant )

Delete a grant from this JWT object.

Deletes the named grant from this object. It is not an error if there is no grant matching the passed name. If grant is NULL, then all grants are deleted from this JWT.

Parameters

jwt_valid	Pointer to a JWT validation object.
grant	String containing the name of the grant to delete. If this is NULL, then all grants are deleted.

Returns

Returns 0 on success, valid errno otherwise.

jwt_valid_free()

void jwt_valid_free

(

jwt_valid_t *

jwt_valid

)

Free a JWT validation object and any other resources it is using.

After calling, the JWT validation object referenced will no longer be valid and its memory will be freed.

Parameters

jwt_valid

Pointer to a JWT validation object previously created with jwt_valid_new().

jwt_valid_get_exp_leeway()

time_t jwt_valid_get_exp_leeway

(

jwt_valid_t *

jwt_valid

)

Return the exp_leeway value set.

Parameters

jwt_valid

Pointer to a JWT validation object.

Returns

Returns current exp_leeway value

jwt_valid_get_grant()

const char * jwt_valid_get_grant	(	jwt_valid_t *	jwt_valid,
		const char *	grant )

Return the value of a string required grant.

Returns the string value for a grant (e.g. "iss"). If it does not exist, NULL will be returned.

Parameters

jwt_valid	Pointer to a JWT validation object.
grant	String containing the name of the grant to return a value for.

Returns

Returns a string for the value, or NULL when not found.

Note, this will only return grants with JSON string values. Use jwt_valid_get_grants_json() to get the JSON representation of more complex values (e.g. arrays) or use jwt_valid_get_grant_int() to get simple integer values.

jwt_valid_get_grant_bool()

int jwt_valid_get_grant_bool	(	jwt_valid_t *	jwt_valid,
		const char *	grant )

Return the value of an boolean required grant.

Returns the int value for a grant (e.g. "exp"). If it does not exist, 0 will be returned.

Parameters

jwt_valid	Pointer to a JWT validation object.
grant	String containing the name of the grant to return a value for.

Returns

Returns a boolean for the value. Sets errno to ENOENT when not found.

Note, this will only return grants with JSON boolean values. Use jwt_valid_get_grants_json() to get the JSON representation of more complex values (e.g. arrays) or use jwt_valid_get_grant() to get string values.

jwt_valid_get_grant_int()

long jwt_valid_get_grant_int	(	jwt_valid_t *	jwt_valid,
		const char *	grant )

Return the value of an integer required grant.

Returns the int value for a grant (e.g. "exp"). If it does not exist, 0 will be returned.

Parameters

jwt_valid	Pointer to a JWT validation object.
grant	String containing the name of the grant to return a value for.

Returns

Returns an int for the value. Sets errno to ENOENT when not found.

Note, this will only return grants with JSON integer values. Use jwt_valid_get_grants_json() to get the JSON representation of more complex values (e.g. arrays) or use jwt_valid_get_grant() to get string values.

jwt_valid_get_grants_json()

char * jwt_valid_get_grants_json	(	jwt_valid_t *	jwt_valid,
		const char *	grant )

Return the value of a grant as JSON encoded object string.

Returns the JSON encoded string value for a grant (e.g. "iss"). If it does not exist, NULL will be returned.

Parameters

jwt_valid	Pointer to a JWT validation object.
grant	String containing the name of the grant to return a value for.

Returns

Returns a string for the value, or NULL when not found. The returned string must be freed by the caller.

jwt_valid_get_nbf_leeway()

time_t jwt_valid_get_nbf_leeway

(

jwt_valid_t *

jwt_valid

)

Return the nbf_leeway value set.

Parameters

jwt_valid

Pointer to a JWT validation object.

Returns

Returns current nbf_leeway value

jwt_valid_get_status()

unsigned int jwt_valid_get_status

(

jwt_valid_t *

jwt_valid

)

Return the status string for the validation object.

The status of validation object is primarily for describing the reason jwt_validate() failed.

Parameters

jwt_valid

Pointer to a JWT validation object.

Returns

Returns current validation status as a bitwise OR of possible errors, or 0 if validation is currently successful.

jwt_valid_new()

int jwt_valid_new	(	jwt_valid_t **	jwt_valid,
		jwt_alg_t	alg )

Allocate a new, JWT validation object.

This is used to create a new object for a JWT validation. After you have finished with the object, use jwt_valid_free() to clean up the memory used by it.

Parameters

jwt_valid	Pointer to a JWT validation object pointer. Will be allocated on success.
alg	A valid jwt_alg_t specifier.

Returns

0 on success, valid errno otherwise.

jwt_valid_set_exp_leeway()

int jwt_valid_set_exp_leeway	(	jwt_valid_t *	jwt_valid,
		const time_t	exp_leeway )

Set the exp_leeway value as defined in: https://www.rfc-editor.org/rfc/rfc7519#section-4.1.4.

Parameters

jwt_valid	Pointer to a JWT validation object.
exp_leeway	leeway for exp value.

Returns

Returns 0 on success, valid errno otherwise.

jwt_valid_set_headers()

int jwt_valid_set_headers	(	jwt_valid_t *	jwt_valid,
		int	hdr )

Set validation for replicated claims in headers.

When set, validation tests for presence of iss, sub, aud in jwt headers and tests match for same claims in body.

Parameters

jwt_valid	Pointer to a JWT validation object.
hdr	When true, test header claims

Returns

Returns 0 on success, valid errno otherwise.

Remarks

jwt_validate() will not fail if iss, sub, aud are not present in JWT header or body.

jwt_valid_set_nbf_leeway()

int jwt_valid_set_nbf_leeway	(	jwt_valid_t *	jwt_valid,
		const time_t	nbf_leeway )

Set the nbf_leeway value as defined in: https://www.rfc-editor.org/rfc/rfc7519#section-4.1.5.

Parameters

jwt_valid	Pointer to a JWT validation object.
nbf_leeway	leeway for nbf value.

Returns

Returns 0 on success, valid errno otherwise.

jwt_valid_set_now()

int jwt_valid_set_now	(	jwt_valid_t *	jwt_valid,
		const time_t	now )

Set the time for which expires and not-before claims should be evaluated.

Parameters

jwt_valid	Pointer to a JWT validation object.
now	Time to use when considering nbf and exp claims.

Returns

Returns 0 on success, valid errno otherwise.

Remarks

jwt_validate() will not fail based on time if no expires or not-before claims exist in a JWT object.

jwt_validate()

unsigned int jwt_validate	(	jwt_t *	jwt,
		jwt_valid_t *	jwt_valid )

Validate a JWT object with a validation object.

Parameters

jwt	Pointer to a JWT object.
jwt_valid	Pointer to a JWT validation object.

Returns

bitwide OR if possible validation errors or 0 on success