Builder
JSON Web Token
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);
jwt_builder_t
struct jwt_builder jwt_builder_t
Opaque Builder Object.
Definition jwt.h:275
jwt_builder_new
jwt_builder_t * jwt_builder_new(void)
Function to create a new builder instance.
jwt_builder_generate
char * jwt_builder_generate(jwt_builder_t *builder)
Generate a token.
jwt_builder_free
void jwt_builder_free(jwt_builder_t *builder)
Frees a previously created builder object.

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