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

Collaboration diagram for Validation Functions:

Typedefs
typedef struct jwt_valid	jwt_valid_t
	Opaque JWT Validation object.

Enumerations
enum	jwt_valid_exception_t { JWT_VALIDATION_SUCCESS , JWT_VALIDATION_ERROR , JWT_VALIDATION_ALG_MISMATCH , JWT_VALIDATION_EXPIRED , JWT_VALIDATION_TOO_NEW , JWT_VALIDATION_ISS_MISMATCH , JWT_VALIDATION_SUB_MISMATCH , JWT_VALIDATION_AUD_MISMATCH , JWT_VALIDATION_GRANT_MISSING , JWT_VALIDATION_GRANT_MISMATCH }
	Validation exception types for jwt_t objects. More...

Functions
jwt_valid_exception_t	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.

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

Typedef Documentation

◆ jwt_valid_t

typedef struct jwt_valid jwt_valid_t

Opaque JWT Validation object.

Used in the JWT validation functions.

Definition at line 70 of file jwt.h.

Enumeration Type Documentation

◆ jwt_valid_exception_t

enum jwt_valid_exception_t

Validation exception types for jwt_t objects.

These are bitwise values that allow you to check for exceptions when using the jwt_valid_t

Todo

RFC-7519 Sec 4.1.6 "iat" Issued At

RFC-7519 Sec 4.1.7 "jti" JWT ID

Enumerator
JWT_VALIDATION_SUCCESS	Validation succeeded
JWT_VALIDATION_ERROR	General failures
JWT_VALIDATION_ALG_MISMATCH	RFC-7518 Sec 3.1 `"alg"` Algorithm
JWT_VALIDATION_EXPIRED	RFC-7519 Sec 4.1.4 `"exp"` Expired
JWT_VALIDATION_TOO_NEW	RFC-7519 Sec 4.1.5 `"nbf"` Not Before
JWT_VALIDATION_ISS_MISMATCH	RFC-7519 Sec 4.1.1 `"iss"` Issuer
JWT_VALIDATION_SUB_MISMATCH	RFC-7519 Sec 4.1.2 `"sub"` Subject
JWT_VALIDATION_AUD_MISMATCH	RFC-7519 Sec 4.1.3 `"aud"` Audience
JWT_VALIDATION_GRANT_MISSING	User-defined Grant missing
JWT_VALIDATION_GRANT_MISMATCH	User-defined Grant mismatch

Definition at line 230 of file jwt.h.

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.

Remarks: 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.

Remarks: 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.

Remarks: 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.

Remarks: 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.

Remarks: 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()

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

jwt_valid_exception_t 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

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ jwt_valid_t

Enumeration Type Documentation

◆ jwt_valid_exception_t

Function Documentation

◆ jwt_exception_str()

◆ jwt_valid_add_grant()

◆ jwt_valid_add_grant_bool()

◆ jwt_valid_add_grant_int()

◆ jwt_valid_add_grants_json()

◆ jwt_valid_del_grants()

◆ jwt_valid_free()

◆ jwt_valid_get_exp_leeway()

◆ jwt_valid_get_grant()

◆ jwt_valid_get_grant_bool()

◆ jwt_valid_get_grant_int()

◆ jwt_valid_get_grants_json()

◆ jwt_valid_get_nbf_leeway()

◆ jwt_valid_get_status()

◆ jwt_valid_new()

◆ jwt_valid_set_exp_leeway()

◆ jwt_valid_set_headers()

◆ jwt_valid_set_nbf_leeway()

◆ jwt_valid_set_now()

◆ jwt_validate()