jwt_builder_grp(3)

📦
version 3.3.3 · 2 versions
, in ubuntu stonking

💅 jwt_builder_grp(3) — the Builder, bestie

okay so this whole page lives in the Library Functions Manual, and it's all about jwt_builder_grp, aka the Builder. no cap. let's get into it 💖

🌸 NAME

jwt_builder_grp — Builder. that's the whole name section, she's brief and she's iconic. 👑

✨ SYNOPSIS

🎀 Typedefs

  • typedef struct jwt_builder jwt_builder_t — Opaque Builder Object.

🦋 Functions

  • jwt_builder_t * jwt_builder_new (void) — the function that spawns a fresh new builder instance ✨
  • void jwt_builder_free (jwt_builder_t *builder) — frees a builder object you made earlier 🧹
  • int jwt_builder_error (const jwt_builder_t *builder) — checks the error state of a builder object
  • const char * jwt_builder_error_msg (const jwt_builder_t *builder) — grabs the error message hanging out inside a builder object
  • void jwt_builder_error_clear (jwt_builder_t *builder) — clears the 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 an algorithm for a builder 🔑
  • int jwt_builder_enable_iat (jwt_builder_t *builder, int enable) — sets whether the IssuedAt claim gets used on the builder
  • int jwt_builder_setcb (jwt_builder_t *builder, jwt_callback_t cb, void *ctx) — sets a callback for generating tokens
  • void * jwt_builder_getctx (jwt_builder_t *builder) — retrieves the callback context you set earlier
  • char * jwt_builder_generate (jwt_builder_t *builder) — generates a token 🪄

💜 Detailed Description

So making a JWT token is a whole multi-step thing, bestie, it's giving process. First up you create a jwt_builder_t object — think of it as a JWT factory 🏭. Once it's configured, you use it to make tokens with pre-defined claims. that's the whole vibe.

⭐ Typedef Documentation

typedef struct jwt_builder jwt_builder_t

Opaque Builder Object. she's opaque, she's mysterious, we don't peek inside. 🫶

🔥 Function Documentation

int jwt_builder_enable_iat (jwt_builder_t * builder, int enable)

Set IssuedAt usage on builder. By default, the builder sets the iat claim on all the tokens it makes. You can flip that on or off with this function, whenever you feel like it. ✨

Parameters

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

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. the little vibe check of the builder world 💅

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. fresh start, clean slate, new me 🧚

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. It can be an empty string if there's no error. It never returns NULL, so you're safe, don't stress. 🌈

void jwt_builder_free (jwt_builder_t * builder)

Frees a previously created builder object. let her rest, she's done her job 💀

Parameters

  • builder — Pointer to a builder object

char * jwt_builder_generate (jwt_builder_t * builder)

Generate a token. What this function does is spit out a string containing a JWT. A token is represented by 3 parts: header.payload.sig. Each part is Base64url Encoded. An example would be, and yes this is literally it:

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 depend 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. The caller is responsible for freeing the memory for this string. On error, NULL is returned and the 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. lowkey handy 🫶

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. newborn builder, so precious 🎀

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 a token is being generated, this callback runs after jwt_t has been created, but before the token is encoded. During that window 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. she's got range 💅

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 let you update the ctx passed to the callback. Calling with both values as NULL disables 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, bestie, we're not doing chaos today. This is what will or won't pass as far as algorithm matching between the alg param and the alg inside jwk_item_t. Where alg-A means one specific algorithm (not none) and alg-B represents another one (also not none). The none is used to mean no algorithm is set. NULL means the 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 ⚠️ — That warning row means an insecure token. Insecure tokens are not very useful and are strongly discouraged. do not do it, i am begging 🙈

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.

and that's the whole page, bestie, you ate it 💖 this was LibJWT, Version 3.3.3, page jwt_builder_grp(3) — go forth and build tokens, main character energy only 🌟

📦 where this page comes from