 |
LibJWT 3.5.0
The C JSON Web Token Library +JWK +JWKS
|
|
LibJWT 3.5.0
The C JSON Web Token Library +JWK +JWKS
|
Get and set claims and headers on a jwt_t during a callback. More...
Data Structures | |
| struct | jwt_config_t |
| Structure used to pass state with a user callback. More... | |
Typedefs | |
| typedef struct jwt | jwt_t |
| Opaque JWT object. | |
| typedef int(* | jwt_callback_t) (jwt_t *, jwt_config_t *) |
| General callback for generation and verification of JWT. | |
| typedef char *(* | jwt_jti_gen_cb_t) (const jwt_t *, jwt_config_t *) |
| Callback to generate a jti (JWT ID) when building a token. | |
| typedef int(* | jwt_jti_check_cb_t) (const jwt_t *, jwt_config_t *, const char *) |
| Callback to verify a jti (JWT ID) when checking a token. | |
Functions | |
| jwt_value_error_t | jwt_header_set (jwt_t *jwt, jwt_value_t *value) |
| Set a value in the header of a JWT. | |
| jwt_value_error_t | jwt_header_get (jwt_t *jwt, jwt_value_t *value) |
| Get a value from the header of a JWT. | |
| jwt_value_error_t | jwt_header_del (jwt_t *jwt, const char *header) |
| Delete a value from the header of a JWT. | |
| jwt_value_error_t | jwt_claim_set (jwt_t *jwt, jwt_value_t *value) |
| Set a value in the claims of a JWT. | |
| jwt_value_error_t | jwt_claim_get (jwt_t *jwt, jwt_value_t *value) |
| Get a value from the claims of a JWT. | |
| jwt_value_error_t | jwt_claim_del (jwt_t *jwt, const char *claim) |
| Delete a value from the claims of a JWT. | |
| int | jwt_builder_setcnf_jkt (jwt_builder_t *builder, const jwk_item_t *key) |
| Set the "cnf" (confirmation) claim to a key thumbprint. | |
| int | jwt_builder_setcnf_jwk (jwt_builder_t *builder, const jwk_item_t *key) |
| Set the "cnf" (confirmation) claim to an embedded JWK. | |
| int | jwt_builder_setcnf (jwt_builder_t *builder, const char *member, const char *value) |
| Set the "cnf" (confirmation) claim to a single string member. | |
| char * | jwt_get_cnf (const jwt_t *jwt, const char *member) |
| Read a string-valued "cnf" (confirmation) member from a token. | |
| char * | jwt_token_hash (const char *value, jwk_thumbprint_alg_t alg) |
| Compute a base64url token hash (full digest). | |
| char * | jwt_token_hash_half (const char *value, jwt_alg_t alg) |
| Compute a base64url token hash (left half of the digest). | |
Get and set claims and headers on a jwt_t during a callback.
For most usage, setting values in the builder object is enough to provide all the information you would like set in a JWT token. However, if some information is dynamic, meaning it is only known at the time the token is created, then you can provide this during the builder callback on the jwt_t object.
When verifying a token, the checker callback should not modify the jwt_t object at all. Access to the jwt_t is provided only to allow additional validation beyond LibJWT's internal checks.
| typedef int(* jwt_callback_t) (jwt_t *, jwt_config_t *) |
General callback for generation and verification of JWT.
| typedef int(* jwt_jti_check_cb_t) (const jwt_t *, jwt_config_t *, const char *) |
Callback to verify a jti (JWT ID) when checking a token.
📄 RFC-7519 Sec 4.1.7 Receives the "jti" claim from the token. Return 0 to accept the token or non-zero to reject it (e.g. an unknown or already-consumed id). This is where an application implements replay protection against its own id pool.
| typedef char *(* jwt_jti_gen_cb_t) (const jwt_t *, jwt_config_t *) |
Callback to generate a jti (JWT ID) when building a token.
📄 RFC-7519 Sec 4.1.7 The returned string is set as the "jti" claim and then freed by LibJWT, so it must be allocated with whatever allocator LibJWT is currently using: plain malloc() if jwt_set_alloc() was never called, otherwise the allocator passed to jwt_set_alloc(). Returning NULL aborts token generation. The application is responsible for ensuring the id is unique.
| typedef struct jwt jwt_t |
Opaque JWT object.
Used in callbacks when generating or verifying a JWT
| int jwt_builder_setcnf | ( | jwt_builder_t * | builder, |
| const char * | member, | ||
| const char * | value ) |
Set the "cnf" (confirmation) claim to a single string member.
📄 RFC-7800
Sets "cnf" to a single member named member with string value value – e.g. "kid" (RFC 7800), "x5t#S256" (RFC 8705 mTLS), or "jku". Any existing "cnf" is replaced, so the object always carries exactly one confirmation member.
| builder | Pointer to a builder object |
| member | The confirmation member name (e.g. "kid", "x5t#S256") |
| value | The member's string value |
| int jwt_builder_setcnf_jkt | ( | jwt_builder_t * | builder, |
| const jwk_item_t * | key ) |
Set the "cnf" (confirmation) claim to a key thumbprint.
Sets "cnf" to a single "jkt" member holding the RFC 7638 SHA-256 JWK thumbprint of key (the DPoP confirmation method). Any existing "cnf" is replaced, so the object always carries exactly one confirmation member.
| builder | Pointer to a builder object |
| key | The proof-of-possession public key to bind the token to |
| int jwt_builder_setcnf_jwk | ( | jwt_builder_t * | builder, |
| const jwk_item_t * | key ) |
Set the "cnf" (confirmation) claim to an embedded JWK.
Sets "cnf" to a single "jwk" member holding the public JWK of key. Only public parameters are embedded. Any existing "cnf" is replaced.
| builder | Pointer to a builder object |
| key | The proof-of-possession public key to embed |
| jwt_value_error_t jwt_claim_del | ( | jwt_t * | jwt, |
| const char * | claim ) |
Delete a value from the claims of a JWT.
| jwt | Pointer to a jwt_t token, previously created with jwt_create() |
| claim | The name of the claim to delete, or NULL to clear all claims |
| jwt_value_error_t jwt_claim_get | ( | jwt_t * | jwt, |
| jwt_value_t * | value ) |
Get a value from the claims of a JWT.
| jwt | Pointer to a jwt_t token, previously created with jwt_create() |
| value | A jwt_value_t structure with relevant actions filled in |
| jwt_value_error_t jwt_claim_set | ( | jwt_t * | jwt, |
| jwt_value_t * | value ) |
Set a value in the claims of a JWT.
| jwt | Pointer to a jwt_t token, previously created with jwt_create() |
| value | A jwt_value_t structure with relevant actions filled in |
| char * jwt_get_cnf | ( | const jwt_t * | jwt, |
| const char * | member ) |
Read a string-valued "cnf" (confirmation) member from a token.
📄 RFC-7800
Returns the value of cnf.member (e.g. "jkt", "kid", "x5t#S256") for a verified token. Because a verifier obtains the jwt_t inside its jwt_checker_setcb() callback, this is where you call it to confirm a presented proof-of-possession key.
| jwt | Pointer to a jwt_t token |
| member | The confirmation member name to read |
cnf or the member is absent or not a string | jwt_value_error_t jwt_header_del | ( | jwt_t * | jwt, |
| const char * | header ) |
Delete a value from the header of a JWT.
| jwt | Pointer to a jwt_t token, previously created with jwt_create() |
| header | The name of the header to delete, or NULL to clear the entire header |
| jwt_value_error_t jwt_header_get | ( | jwt_t * | jwt, |
| jwt_value_t * | value ) |
Get a value from the header of a JWT.
| jwt | Pointer to a jwt_t token, previously created with jwt_create() |
| value | A jwt_value_t structure with relevant actions filled in |
| jwt_value_error_t jwt_header_set | ( | jwt_t * | jwt, |
| jwt_value_t * | value ) |
Set a value in the header of a JWT.
| jwt | Pointer to a jwt_t token, previously created with jwt_create() |
| value | A jwt_value_t structure with relevant actions filled in |
| char * jwt_token_hash | ( | const char * | value, |
| jwk_thumbprint_alg_t | alg ) |
Compute a base64url token hash (full digest).
Returns base64url(SHA-x(value)) over the full digest. This is the DPoP "ath" (access token hash): bind a DPoP proof to an access token with jwt_token_hash(access_token, ::JWK_THUMBPRINT_SHA256) and set the result as the proof's "ath" claim (RFC 9449 pins SHA-256). It is also the generic "hash this string and base64url it" helper.
| value | The string to hash (e.g. the access token), nil-terminated |
| alg | The digest to use (see jwk_thumbprint_alg_t); RFC 9449 ath uses JWK_THUMBPRINT_SHA256 |
| char * jwt_token_hash_half | ( | const char * | value, |
| jwt_alg_t | alg ) |
Compute a base64url token hash (left half of the digest).
Returns base64url(left-half(SHA-x(value))), where the digest width is the one the JWS algorithm alg signs with (HS/RS/ES/PS-256 -> SHA-256, -384 -> SHA-384, -512 and EdDSA -> SHA-512). This is the OpenID Connect "at_hash" and "c_hash" construction (OIDC Core 3.1.3.6 / 3.3.2.11): take the left-most half of the hash bytes before base64url. Distinct from jwt_token_hash(), which uses the full digest and is keyed to a hash selector.
| value | The string to hash (an access token or authorization code) |
| alg | The signing jwt_alg_t whose hash width is used |
alg with no SHA-2 width) 