Provided by: libjwt14-doc_3.2.2-1_all 
NAME
jwt_builder_grp - Builder
SYNOPSIS
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
typedef struct jwt_builder jwt_builder_t
Opaque Builder Object.
Function Documentation
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
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
void jwt_builder_error_clear (jwt_builder_t * builder)
Clear error state in a builder object.
Parameters
builder Pointer to a builder object
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.
void jwt_builder_free (jwt_builder_t * builder)
Frees a previously created builder object.
Parameters
builder Pointer to a builder object
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.
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_t * jwt_builder_new (void)
Function to create a new builder instance.
Returns
Pointer to a builder object on success, NULL on failure
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
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
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
Author
Generated automatically by Doxygen for LibJWT from the source code.
LibJWT Version 3.2.2 jwt_builder_grp(3)