Typedefs¶

typedef struct jwt_builder jwt_builder_t
Opaque Builder Object.

Functions¶

jwt_builder_t * jwt_builder_new (void)
Function to create a new builder instance. void jwt_builder_free (jwt_builder_t *builder)
Frees a previously created builder object. int jwt_builder_error (const jwt_builder_t *builder)
Checks error state of builder object. const char * jwt_builder_error_msg (const jwt_builder_t *builder)
Get the error message contained in a builder object. void jwt_builder_error_clear (jwt_builder_t *builder)
Clear error state in a builder object. int jwt_builder_setkey (jwt_builder_t *builder, const jwt_alg_t alg, const jwk_item_t *key)
Sets a key and algorithm for a builder. int jwt_builder_enable_iat (jwt_builder_t *builder, int enable)
Set IssuedAt usage on builder. int jwt_builder_setcb (jwt_builder_t *builder, jwt_callback_t cb, void *ctx)
Set a callback for generating tokens. void * jwt_builder_getctx (jwt_builder_t *builder)
Retrieve the callback context that was previously set. char * jwt_builder_generate (jwt_builder_t *builder)
Generate a token.

typedef struct jwt_builder jwt_builder_t¶

Opaque Builder Object.

int jwt_builder_enable_iat (jwt_builder_t * builder, int enable)¶

Set IssuedAt usage on builder. By default, the builder will set the iat claim to all tokens. You can enable or disable this using this function.

Parameters

Returns

int jwt_builder_error (const jwt_builder_t * builder)¶

Checks error state of builder object.

Parameters

Returns

void jwt_builder_error_clear (jwt_builder_t * builder)¶

Clear error state in a builder object.

Parameters

const char * jwt_builder_error_msg (const jwt_builder_t * builder)¶

Get the error message contained in a builder object.

Parameters

Returns

void jwt_builder_free (jwt_builder_t * builder)¶

Frees a previously created builder object.

Parameters

char * jwt_builder_generate (jwt_builder_t * builder)¶

Generate a token. The result of this function is to generate a string containing a JWT. A token is represetned by 3 parts: header.payload.sig. Each part is Base64url Encoded. An example would be:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3MzY0MzI0MzR9.iDn6N9JsAdUPF11ow0skIfc9eJc2wGRIq30RSRZ8_68

When decoded, the header and payload would look like this (excluding the signature block)::

{"alg":"HS256","typ":"JWT"}.{"iat":1736432434}

If pretty printed:

{


   "alg": "HS256",


   "typ": "JWT"
}
.
{


   "iat": 1736432434
}

The signature block is a cryptographic hash. Its length and format is dependent on the algorithm being used.

A simple usage with no signature or payload would be:

jwt_builder_t *builder = NULL;
builder = jwt_builder_new();
if (builder) {


    char *out = jwt_builder_generate(builder);


    if (out) {


        printf("%s\n", out);


        free(out);


    }
}
jwt_builder_free(builder);

Note

Parameters

Returns

void * jwt_builder_getctx (jwt_builder_t * builder)¶

Retrieve the callback context that was previously set. This is useful for accessing the context that was previously passed in the setcb function.

Parameters

Returns

jwt_builder_t * jwt_builder_new (void)¶

Function to create a new builder instance.

Returns

int jwt_builder_setcb (jwt_builder_t * builder, jwt_callback_t cb, void * ctx)¶

Set a callback for generating tokens. When generating a token, this callback will be run after jwt_t has been created, but before the token is encoded. During this, the callback can set, change, or remove claims and header attributes. It can also use the jwt_value_t structure to set a key and alg to use when signing the token.

The ctx value is also passed to the callback as part of the jwt_value_t struct.

Note

Parameters

Returns

int jwt_builder_setkey (jwt_builder_t * builder, const jwt_alg_t alg, const jwk_item_t * key)¶

Sets a key and algorithm for a builder. The values here must make sense. This table shows what will or won't pass as far as algorithm matching between the alg param and the alg in jwk_item_t. Where alg-A means one specific algorithm (not none) and alg-B represents another (also not none). The none is used to represent no algorithm being set. NULL represents that jwk_item_t pointer is NULL.

alg jwt_item_t Result alg-A alg-A :white_check_mark: none alg-A :white_check_mark: alg-A none :white_check_mark: none NULL :warning: alg-A alg-B :x: alg-A NULL :x:

Warning

Parameters

Returns