Builder

Collaboration diagram for Builder:

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.

Detailed Description

Creating a JWT token involves several steps. First is creating a jwt_builder_t object, which can be thought of as a JWT factory. Once configured, you can use it to create tokens with pre-defined claims.

Typedef Documentation

jwt_builder_t

typedef struct jwt_builder jwt_builder_t

Opaque Builder Object.

Function Documentation

jwt_builder_enable_iat()

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

builder	Pointer to a builder object
enable	0 to disable, any other value to enable

Returns

Previous value (0 or 1), or -1 on error

jwt_builder_error()

int jwt_builder_error

(

const jwt_builder_t *

builder

)

Checks error state of builder object.

Parameters

builder

Pointer to a builder object

Returns

0 if no errors exist, non-zero otherwise

jwt_builder_error_clear()

void jwt_builder_error_clear

(

jwt_builder_t *

builder

)

Clear error state in a builder object.

Parameters

builder

Pointer to a builder object

jwt_builder_error_msg()

const char * jwt_builder_error_msg

(

const jwt_builder_t *

builder

)

Get the error message contained in a builder object.

Parameters

builder

Pointer to a builder object

Returns

Pointer to a string with the error message. Can be an empty string if there is no error. Never returns NULL.

jwt_builder_free()

void jwt_builder_free

(

jwt_builder_t *

builder

)

Frees a previously created builder object.

Parameters

builder

Pointer to a builder object

jwt_builder_generate()

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

If you set a callback for this builder, this is when it will be called.

Parameters

builder

Pointer to a builder object

Returns

A string containing a JWT. Caller is respondible for freeing the memory for this string. On error, NULL is returned and error is set in the builder object.

jwt_builder_getctx()

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

builder

Pointer to a builder object

Returns

Pointer to the context or NULL

jwt_builder_new()

jwt_builder_t * jwt_builder_new

(

void

)

Function to create a new builder instance.

Returns

Pointer to a builder object on success, NULL on failure

jwt_builder_setcb()

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

Calling this with a NULL cb param and a new ctx param after already setting the callback will allow updating the ctx passed to the callback. Calling with both values as NULL will disable the callback completely.

Parameters

builder	Pointer to a builder object
cb	Pointer to a callback function
ctx	Pointer to data to pass to the callback function

Returns

0 on success, non-zero otherwise with error set in the builder

jwt_builder_setkey()

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	✅
none	alg-A	✅
alg-A	none	✅
none	NULL	⚠
alg-A	alg-B	❌
alg-A	NULL	❌

Warning

The warning represents an insecure token. Using insecure tokens is not very useful and strongly discouraged.

Parameters

builder	Pointer to a builder object
alg	A valid jwt_alg_t type
key	A JWK key object

Returns

0 on success, non-zero otherwise with error set in the builder