💡 Usage Examples

This page walks through common end-to-end tasks with LibJWT, starting from the simplest possible case and gradually layering in more advanced concepts. Each example introduces only one or two new ideas, so they are meant to be read in order.

Almost everything in LibJWT is built around two pairs of objects:

Purpose	Create / sign	Consume / verify
Signed tokens (JWS)	jwt_builder_t	jwt_checker_t
Encrypted tokens (JWE)	jwe_builder_t	jwe_checker_t

The pattern is always the same: create the object, configure it (a key, some claims, perhaps a callback), then call a single function to produce or consume a token.

Note

To keep them readable, the examples below check only the most important return values. Real applications should check every return code (using jwt_builder_error_msg() and friends to report failures) and are encouraged to use the jwt_builder_auto_t / jwt_checker_auto_t / jwe_builder_auto_t / jwe_checker_auto_t / jwk_set_auto_t cleanup types (on GCC and Clang) so objects are freed automatically when they go out of scope.

✏ Signing and Verifying (JWS)

These examples cover creating and consuming signed tokens with the Builder and Checker.

Signing your first token

The simplest token is signed with HS256, an HMAC over a shared secret. The secret is just a JWK with "kty":"oct". Loading a key is always a two-step process: read the JSON into a keyring (jwk_set_t) with one of the jwks_create_* functions, then pull the individual key (jwk_item_t) out of it with jwks_item_get.

#include <stdio.h>
#include <stdlib.h>
#include <jwt.h>
 
int main(void)
{
    jwt_builder_t *builder = NULL;
    jwk_set_t *keys = NULL;
    const jwk_item_t *key = NULL;
    char *token = NULL;
 
    /* Load the signing key (a JWK with "kty":"oct"). */
    keys = jwks_create_fromfile("oct_key_256.json");
    key = jwks_item_get(keys, 0);
 
    /* Create the builder and give it the key + algorithm. */
    builder = jwt_builder_new();
    jwt_builder_setkey(builder, JWT_ALG_HS256, key);
 
    /* Generate the token. The caller owns the returned string. */
    token = jwt_builder_generate(builder);
    if (token == NULL)
        fprintf(stderr, "generate failed: %s\n", jwt_builder_error_msg(builder));
    else
        printf("%s\n", token);
 
    free(token);
    jwt_builder_free(builder);
    jwks_free(keys);
    return 0;
}

By default the builder adds an iat (Issued At) claim. You can turn that off with jwt_builder_enable_iat.

Verifying a token

Verifying mirrors signing: load the same key, set it on a jwt_checker_t with the algorithm you expect, then call jwt_checker_verify. A return of 0 means the signature (and any configured claim checks) passed.

jwt_checker_t *checker = NULL;
jwk_set_t *keys = NULL;
const jwk_item_t *key = NULL;
 
keys = jwks_create_fromfile("oct_key_256.json");
key = jwks_item_get(keys, 0);
 
checker = jwt_checker_new();
jwt_checker_setkey(checker, JWT_ALG_HS256, key);
 
if (jwt_checker_verify(checker, token) == 0)
    printf("token is valid\n");
else
    printf("rejected: %s\n", jwt_checker_error_msg(checker));
 
jwt_checker_free(checker);
jwks_free(keys);

Note

Pinning the algorithm with jwt_checker_setkey is a security feature: the checker will reject a token whose alg header does not match the algorithm you configured. This prevents algorithm-confusion attacks.

Adding and validating claims

Claims and headers are set through a small helper struct, jwt_value_t. You fill it in with one of the jwt_set_SET_* macros, then hand it to jwt_builder_claim_set. Anything you set on the builder is copied into every token it generates.

jwt_value_t jval;
 
/* "sub": "user@example.com" */
jwt_set_SET_STR(&jval, "sub", "user@example.com");
jwt_builder_claim_set(builder, &jval);
 
/* "iss": "myapp" */
jwt_set_SET_STR(&jval, "iss", "myapp");
jwt_builder_claim_set(builder, &jval);
 
/* A custom integer claim. */
jwt_set_SET_INT(&jval, "login_count", 42);
jwt_builder_claim_set(builder, &jval);

On the verifying side, the checker can validate a handful of registered claims for you with a simple comparison. Use jwt_checker_claim_set with the claim you care about; verification then fails if the token's value does not match.

/* Only accept tokens issued by "myapp" for the "billing" audience. */
jwt_checker_claim_set(checker, JWT_CLAIM_ISS, "myapp");
jwt_checker_claim_set(checker, JWT_CLAIM_AUD, "billing");
 
if (jwt_checker_verify(checker, token) == 0)
    printf("issuer and audience accepted\n");

The checker validates iss, aud, and sub by string comparison, and exp/nbf by time (see below). For anything more involved — multiple acceptable issuers, custom claims, business rules — use a callback (Dynamic tokens with a callback).

Expiration and not-before

The exp (Expiration) and nbf (Not Before) claims are time-based, so LibJWT manages them as offsets from "now". On the builder, set the offset in seconds with jwt_builder_time_offset.

/* Token is valid for one hour. */
jwt_builder_time_offset(builder, JWT_CLAIM_EXP, 3600);
 
/* ...and not valid until 30 seconds from now. */
jwt_builder_time_offset(builder, JWT_CLAIM_NBF, 30);

The checker validates exp and nbf automatically whenever they are present. To tolerate small clock differences between machines, give it some leeway (in seconds) with jwt_checker_time_leeway.

/* Allow 60 seconds of clock skew on both exp and nbf. */
jwt_checker_time_leeway(checker, JWT_CLAIM_EXP, 60);
jwt_checker_time_leeway(checker, JWT_CLAIM_NBF, 60);

Critical headers

Sometimes a token carries a custom header that the recipient must understand. RFC-7515 Sec 4.1.11 handles this with the crit (Critical) header, which lists header names that cannot be ignored. On the builder, register each critical name with jwt_builder_setcrit; the header itself is added in a callback (see Dynamic tokens with a callback).

/* Mark our custom "myhdr" header as critical. */
jwt_builder_setcrit(builder, "myhdr");

A checker rejects any token whose crit header lists a name it has not been told to expect. Declare the names your application understands with jwt_checker_understands.

/* We know how to process "myhdr"; without this, verify() would fail. */
jwt_checker_understands(checker, "myhdr");

Dynamic tokens with a callback

Everything above is static — the same configuration applies to every token. When something must change per token (a different sub for each user, a key chosen at runtime, a unique jti), use a callback. The builder invokes it during jwt_builder_generate, after the token object is created but before it is signed, giving you a jwt_t to modify and a jwt_config_t to set the key and algorithm.

/* Set a per-token claim and choose the signing key at generation time. */
static int on_generate(jwt_t *jwt, jwt_config_t *config)
{
    jwt_value_t jval;
    const char *user = config->ctx; /* the ctx we registered below */
 
    jwt_set_SET_STR(&jval, "sub", user);
    jwt_claim_set(jwt, &jval);
 
    config->alg = JWT_ALG_HS256;
    config->key = my_lookup_key(user); /* application-provided */
 
    return 0; /* non-zero aborts generation */
}
 
/* Register it, passing a context pointer through to the callback. */
jwt_builder_setcb(builder, on_generate, "user@example.com");
 
token = jwt_builder_generate(builder);

The checker has the mirror-image hook, jwt_checker_setcb — it runs during verification so you can inspect the header and claims, or select the verification key, before the signature is checked. (A checker callback should only read the jwt_t — changes to it do not affect verification.)

Note

For the very common case of a unique token id, the builder offers a dedicated jwt_builder_setjti hook to generate the jti claim, paired with jwt_checker_setjti on the checker for replay protection.

🔒 Encrypting and Decrypting (JWE)

Encrypted tokens use the Builder and Checker. The main difference from JWS is that JWE needs two algorithms: a key management algorithm (the "alg" header, jwe_key_alg_t) that establishes the Content Encryption Key (CEK), and a content encryption algorithm (the "enc" header, jwe_enc_t) that actually encrypts the payload.

Encrypting your first token

The simplest JWE uses dir (Direct Encryption): a shared symmetric key is the CEK, so there is no key wrapping. Here it is paired with A256GCM content encryption. The key is a JWK with "kty":"oct". Because the plaintext can be arbitrary bytes, jwe_builder_generate takes an explicit length.

#include <stdlib.h>
#include <string.h>
#include <jwt.h>
 
jwe_builder_t *builder = NULL;
jwk_set_t *keys = NULL;
const jwk_item_t *key = NULL;
const char *message = "the launch code is 0000";
char *token = NULL;
 
keys = jwks_create_fromfile("oct_dir_256.json");
key = jwks_item_get(keys, 0);
 
builder = jwe_builder_new();
jwe_builder_setkey(builder, JWE_ALG_DIR, JWE_ENC_A256GCM, key);
 
token = jwe_builder_generate(builder, (const unsigned char *)message,
                             strlen(message));
if (token == NULL)
    fprintf(stderr, "encrypt failed: %s\n", jwe_builder_error_msg(builder));
else
    printf("%s\n", token); /* a five-part compact JWE */
 
free(token);
jwe_builder_free(builder);
jwks_free(keys);

Decrypting a token

To decrypt, configure a jwe_checker_t with the same key and the algorithms you expect, then call jwe_checker_decrypt. It returns a newly allocated buffer and, through its out-parameter, the true plaintext length. The buffer is also nil-terminated for convenience.

jwe_checker_t *checker = NULL;
unsigned char *plaintext = NULL;
size_t len = 0;
 
keys = jwks_create_fromfile("oct_dir_256.json");
key = jwks_item_get(keys, 0);
 
checker = jwe_checker_new();
jwe_checker_setkey(checker, JWE_ALG_DIR, JWE_ENC_A256GCM, key);
 
plaintext = jwe_checker_decrypt(checker, token, &len);
if (plaintext == NULL)
    fprintf(stderr, "decrypt failed: %s\n", jwe_checker_error_msg(checker));
else
    printf("recovered %zu bytes: %s\n", len, plaintext);
 
free(plaintext);
jwe_checker_free(checker);
jwks_free(keys);

Note

Decryption with an authenticated mode like A256GCM also verifies the token. If the ciphertext, IV, or tag has been altered, decryption fails and returns NULL — there is no separate "verify" step.

Encrypting to a recipient's public key

dir requires both sides to share a secret in advance. More often you want to encrypt to someone's public key so that only their private key can decrypt. That is what the asymmetric key management algorithms are for. Here we use RSA-OAEP-256: only the alg changes — the rest of the flow is identical.

/* The sender needs only the recipient's public RSA JWK. */
keys = jwks_create_fromfile("rsa_key_2048_enc.json");
key = jwks_item_get(keys, 0);
 
builder = jwe_builder_new();
jwe_builder_setkey(builder, JWE_ALG_RSA_OAEP_256, JWE_ENC_A256GCM, key);
 
token = jwe_builder_generate(builder, (const unsigned char *)message,
                             strlen(message));

The recipient decrypts exactly as in Decrypting a token, but using their RSA private key and the matching JWE_ALG_RSA_OAEP_256.

JSON serialization and AAD

Every example so far produced the RFC-7516 Sec 7.1 Compact Serialization — the five-part a.b.c.d.e string. The RFC-7516 Sec 7.2 JSON Serialization is a JSON object instead, and it can carry things the compact form cannot, such as Additional Authenticated Data (AAD): bytes that are authenticated (bound into the tag) but not encrypted. Select the JSON form with jwe_builder_set_format and attach AAD with jwe_builder_set_aad.

static const unsigned char aad[] = "context-id:42";
 
builder = jwe_builder_new();
jwe_builder_setkey(builder, JWE_ALG_DIR, JWE_ENC_A256GCM, key);
 
/* Produce the Flattened JSON Serialization with AAD. */
jwe_builder_set_format(builder, JWE_FORMAT_JSON_FLAT);
jwe_builder_set_aad(builder, aad, sizeof(aad) - 1);
 
token = jwe_builder_generate(builder, (const unsigned char *)message,
                             strlen(message));

A JSON token may be compact or JSON, so on the consuming side use jwe_checker_decrypt_all, which auto-detects the serialization. After a successful decrypt you can recover the authenticated AAD with jwe_checker_get_aad.

size_t aad_len = 0;
const unsigned char *got = NULL;
 
plaintext = jwe_checker_decrypt_all(checker, token, &len);
 
got = jwe_checker_get_aad(checker, &aad_len);
if (got != NULL)
    printf("authenticated AAD: %.*s\n", (int)aad_len, got);

Multiple recipients

The General JSON Serialization can address several recipients at once: the payload is encrypted a single time with one CEK, and that CEK is then wrapped independently for each recipient. Any one recipient can decrypt the token with their own key. Configure the first recipient with jwe_builder_setkey as usual, then add each additional one with jwe_builder_add_recipient. Adding a second recipient automatically switches output to JWE_FORMAT_JSON_GENERAL.

const jwk_item_t *rsa_key = NULL, *ec_key = NULL;
jwk_set_t *rsa_keys = NULL, *ec_keys = NULL;
 
rsa_keys = jwks_create_fromfile("rsa_key_2048_enc.json");
rsa_key  = jwks_item_get(rsa_keys, 0);
ec_keys  = jwks_create_fromfile("ec_key_prime256v1_enc.json");
ec_key   = jwks_item_get(ec_keys, 0);
 
builder = jwe_builder_new();
 
/* First recipient: RSA. The shared "enc" is set here. */
jwe_builder_setkey(builder, JWE_ALG_RSA_OAEP_256, JWE_ENC_A256GCM, rsa_key);
 
/* Second recipient: an EC key via ECDH-ES + A128KW. */
jwe_builder_add_recipient(builder, JWE_ALG_ECDH_ES_A128KW, ec_key);
 
/* Produces the General JSON Serialization with a "recipients" array. */
token = jwe_builder_generate(builder, (const unsigned char *)message,
                             strlen(message));

Each recipient decrypts with their own key. The checker is configured with that recipient's key and algorithm, and jwe_checker_decrypt_all finds the matching entry in the recipients array.

/* The EC recipient decrypts with its own key and algorithm. */
checker = jwe_checker_new();
jwe_checker_setkey(checker, JWE_ALG_ECDH_ES_A128KW, JWE_ENC_A256GCM, ec_key);
 
plaintext = jwe_checker_decrypt_all(checker, token, &len);

Note

dir and ECDH-ES Direct (JWE_ALG_ECDH_ES) derive the CEK directly from a single key, so they cannot be combined with other recipients.

ECDH-ES and PartyInfo

ECDH-ES derives the CEK from an (ephemeral) Diffie-Hellman exchange against the recipient's EC key. The derivation (a Concat KDF, RFC-7518 Sec 4.6) can optionally mix in two application-supplied octet strings, PartyUInfo and PartyVInfo, which are also emitted as the apu and apv headers. Set them with jwe_builder_set_partyinfo.

keys = jwks_create_fromfile("ec_key_prime256v1_enc.json");
key = jwks_item_get(keys, 0);
 
builder = jwe_builder_new();
jwe_builder_setkey(builder, JWE_ALG_ECDH_ES, JWE_ENC_A256GCM, key);
 
/* Optional context bound into the key derivation. */
jwe_builder_set_partyinfo(builder,
                          (const unsigned char *)"Alice", 5,  /* apu */
                          (const unsigned char *)"Bob", 3);   /* apv */
 
token = jwe_builder_generate(builder, (const unsigned char *)message,
                             strlen(message));

The decrypting side sets the same algorithms and uses its EC private key; the apu/apv values travel in the token, so the checker reproduces the same derivation automatically.

Note

For per-recipient PartyInfo or per-recipient headers in a General JSON token, use the recipient handle returned by jwe_builder_add_recipient with jwe_recipient_set_partyinfo and jwe_recipient_add_header_json.