jwt_builder_grp(3)

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.