libjwt-2.1.0
|
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. | |
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.
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.
exceptions | Integer containing the exception flags. |
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.
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. |
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().
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.
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. |
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().
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.
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. |
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().
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.
jwt_valid | Pointer to a JWT validation object. |
json | String containing a JSON encoded object of 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.
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. |
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.
jwt_valid | Pointer to a JWT validation object previously created with jwt_valid_new(). |
time_t jwt_valid_get_exp_leeway | ( | jwt_valid_t * | jwt_valid | ) |
Return the exp_leeway value set.
jwt_valid | Pointer to a 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.
Returns the string value for a grant (e.g. "iss"). If it does not exist, NULL will be returned.
jwt_valid | Pointer to a JWT validation object. |
grant | String containing the name of the grant to return a value for. |
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.
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.
jwt_valid | Pointer to a JWT validation object. |
grant | String containing the name of the grant to return a value for. |
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.
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.
jwt_valid | Pointer to a JWT validation object. |
grant | String containing the name of the grant to return a value for. |
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.
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.
jwt_valid | Pointer to a JWT validation object. |
grant | String containing the name of the grant to return a value for. |
time_t jwt_valid_get_nbf_leeway | ( | jwt_valid_t * | jwt_valid | ) |
Return the nbf_leeway value set.
jwt_valid | Pointer to a JWT validation object. |
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.
jwt_valid | Pointer to a JWT validation object. |
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.
jwt_valid | Pointer to a JWT validation object pointer. Will be allocated on success. |
alg | A valid jwt_alg_t specifier. |
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.
jwt_valid | Pointer to a JWT validation object. |
exp_leeway | leeway for exp value. |
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.
jwt_valid | Pointer to a JWT validation object. |
hdr | When true, test header claims |
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.
jwt_valid | Pointer to a JWT validation object. |
nbf_leeway | leeway for nbf value. |
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.
jwt_valid | Pointer to a JWT validation object. |
now | Time to use when considering nbf and exp claims. |
unsigned int jwt_validate | ( | jwt_t * | jwt, |
jwt_valid_t * | jwt_valid ) |
Validate a JWT object with a validation object.
jwt | Pointer to a JWT object. |
jwt_valid | Pointer to a JWT validation object. |