LibJWT 3.7.0
The C JSON Web Token Library +JWK +JWKS
Checker Functions

Get, set, and delete the claims a checker validates. More...

Collaboration diagram for Checker Functions:

Functions

const char * jwt_checker_claim_get (jwt_checker_t *checker, jwt_claims_t type)
 Get the value of a validation claim.
int jwt_checker_claim_set (jwt_checker_t *checker, jwt_claims_t type, const char *value)
 Set the value of a validation claim.
int jwt_checker_claim_del (jwt_checker_t *checker, jwt_claims_t type)
 Delete the value of a validation claim.
int jwt_checker_time_leeway (jwt_checker_t *checker, jwt_claims_t claim, time_t secs)
 Setup the exp or nbf claim leeway values.

Detailed Description

Get, set, and delete the claims a checker validates.

For a checker object, claims will be used to verify the token. This verification is very simplistic and only supports standards-defined claims like nbf, iss, etc. Even for some of these, LibJWT can only perform simple time or string comparison. For example, if you wanted to accept tokens from multiple issuers, you would need to handle that yourself, most likely in a callback.

This is a list of the claims that LibJWT can check on its own, and the method that is used to decide success:

Claim Type Comparison for Validation
exp Timestamp exp > (now + leeway)
nbf Timestamp nbf <= (now - leeway)
iss String !strcmp(iss, userval)
aud String or Array userval equals aud, or is among its elements
sub String !strcmp(sub, userval)
Note
exp and nbf are "validate if present": the check only fails a token when the claim is present and does not satisfy the comparison above. A token that omits it passes, so enabling JWT_CLAIM_EXP does not by itself require that a token carry an exp. One whose value is not an integer is present and fails, a JSON null included (before 3.8.0, json-c read a null one as absent and passed it). A value pinned with jwt_checker_claim_set() (iss, aud or sub) is different: the claim must be present and match, so a token that omits it fails. To reject tokens lacking any other claim, use jwt_checker_require().
An 📄 RFC-7797 unencoded ("b64":false) payload carries no claims (RFC-7797 Sec 7) and is checked as an empty set: it passes exp and nbf, but fails any pinned value, required claim or jti check (see jwt_checker_verify()).
Per RFC-7519 Sec 4.1.3, aud may be a single string or an array of strings; the token is accepted when your configured audience matches the string or appears among the array elements.
Besides alg, the checker object itself evaluates only the crit and b64 header parameters and, when configured to, typ (jwt_checker_expect_typ()), kid (keyring lookup) and an embedded jwk. Anything else you need to do there can be done in a callback with the jwt_t.

Function Documentation

◆ jwt_checker_claim_del()

int jwt_checker_claim_del ( jwt_checker_t * checker,
jwt_claims_t type )

Delete the value of a validation claim.

Parameters
checkerPointer to a checker object
typeOne of JWT_CLAIM_ISS, JWT_CLAIM_AUD, or JWT_CLAIM_SUB
Returns
0 on success, any other value is an error
Since
3.0.0

◆ jwt_checker_claim_get()

const char * jwt_checker_claim_get ( jwt_checker_t * checker,
jwt_claims_t type )

Get the value of a validation claim.

Parameters
checkerPointer to a checker object
typeOne of JWT_CLAIM_ISS, JWT_CLAIM_AUD, or JWT_CLAIM_SUB
Returns
A string representation of the claim, or NULL if it isn't set
Since
3.0.0

◆ jwt_checker_claim_set()

int jwt_checker_claim_set ( jwt_checker_t * checker,
jwt_claims_t type,
const char * value )

Set the value of a validation claim.

Parameters
checkerPointer to a checker object
typeOne of JWT_CLAIM_ISS, JWT_CLAIM_AUD, or JWT_CLAIM_SUB
valueA string to set as the new value of the validation
Returns
0 on success, any other value is an error
Since
3.0.0

◆ jwt_checker_time_leeway()

int jwt_checker_time_leeway ( jwt_checker_t * checker,
jwt_claims_t claim,
time_t secs )

Setup the exp or nbf claim leeway values.

This allows you to set a leeway for exp and nbf claims to account for any skew. The value is in seconds.

To disable either one, set the secs to -1.

Parameters
checkerPointer to a checker object
claimOne of JWT_CLAIM_NBF or JWT_CLAIM_EXP
secsThe number of seconds of leeway to account for being valid
Returns
0 on success, any other value is an error
Since
3.0.0