JWT3 Module

Wolfgang Kampichler

Daniel-Constantin Mierla

   <miconda@gmail.com>

Edited by

Daniel-Constantin Mierla

   <miconda@gmail.com>

   Copyright © 2021 asipto.com

   Copyright © 2026 Wolfgang Kampichler, Frequentis AG
     __________________________________________________________________

   Table of Contents

   1. Admin Guide

        1. Overview
        2. Dependencies

              2.1. Kamailio Modules
              2.2. External Libraries or Applications

        3. Parameters

              3.1. leeway_sec (int)

        4. Functions

              4.1. jwt3_generate(prvkey, alg, claims[, headers])
              4.2. jwt3_verify(pubkeypath, alg, claims, jwtval)
              4.3. jwt3_verify_key(pubkeyval, alg, claims, jwtval)

        5. Variables

              5.1. $jwt3(key)

   List of Examples

   1.1. Set leeway_sec parameter
   1.2. jwt3_generate usage
   1.3. jwt3_verify usage
   1.4. jwt3_verify_key usage
   1.5. $jwt3(name) usage

Chapter 1. Admin Guide

   Table of Contents

   1. Overview
   2. Dependencies

        2.1. Kamailio Modules
        2.2. External Libraries or Applications

   3. Parameters

        3.1. leeway_sec (int)

   4. Functions

        4.1. jwt3_generate(prvkey, alg, claims[, headers])
        4.2. jwt3_verify(pubkeypath, alg, claims, jwtval)
        4.3. jwt3_verify_key(pubkeyval, alg, claims, jwtval)

   5. Variables

        5.1. $jwt3(key)

1. Overview

   This module provides JWT (JSON Web Token) functions to be used in
   Kamailio configuration file.

   It relies on libjwt (at least v3.2.0) library
   (https://github.com/benmcollins/libjwt).

2. Dependencies

   2.1. Kamailio Modules
   2.2. External Libraries or Applications

2.1. Kamailio Modules

   The following modules must be loaded before this module:
     * none.

2.2. External Libraries or Applications

   The following libraries or applications must be installed before
   running Kamailio with this module loaded:
     * libjwt - version 3.2.0 or higher.

3. Parameters

   3.1. leeway_sec (int)

3.1. leeway_sec (int)

   This parameter defines the time tolerance in seconds used to account
   for clock skew when validating the exp (expiration) and nbf (not
   before) claims. A value of -1 disables nbf/exp claim validation, while
   any positive integer sets the allowable leeway window.

   Default value is -1.

   Example 1.1. Set leeway_sec parameter
...
modparam("jwt", "leeway_sec", 30)
...

4. Functions

   4.1. jwt3_generate(prvkey, alg, claims[, headers])
   4.2. jwt3_verify(pubkeypath, alg, claims, jwtval)
   4.3. jwt3_verify_key(pubkeyval, alg, claims, jwtval)

4.1. jwt3_generate(prvkey, alg, claims[, headers])

   Generate the JWT, its value can be retrieved in the variable
   $jwt3(val).

   The parameters are:
     * prvkey - path to private key (PEM or JWKS)
     * alg - the algorithm to build the signature, as supported by the
       libjwt (e.g., RS256, HS256, ES256, ...)
     * claims - the list of claims to be added to JWT, in the format
       "name1=value1;name2=value2;..." (same as the SIP parameters
       format). The string values can be enclosed in single or double
       quotes. If a value is not eclosed in between quotes, it is added as
       numeric value if it is successfully converted to a long value,
       otherwise is added as string value.
     * headers - the list of headers to be added to JWT, in the format
       "name1=value1;name2=value2;..." (same as the SIP parameters
       format). The string values can be enclosed in single or double
       quotes. If a value is not eclosed in between quotes, it is added as
       numeric value if it is successfully converted to a long value,
       otherwise is added as string value.

   This function can be used from ANY_ROUTE.

   Example 1.2. jwt3_generate usage
...
  jwt3_generate("/path/to/prvkey.json", "ES256",
        "caller='$fU';callee='$tU';callid='$ci';index=100");
...

4.2. jwt3_verify(pubkeypath, alg, claims, jwtval)

   Verify the JWT.

   The parameters are:
     * pubkeypath - path to public key file (PEM or JWKS)
     * alg - the algorithm to build the signature, as supported by the
       libjwt (e.g., RS256, HS256, ES256, ...)
     * claims - the list of claims to be checked they are in the JWT, in
       the format "name1=value1;name2=value2;..." (same as the SIP
       parameters format, see also the description of claims parameter for
       jwt3_generate()).
     * jwtval - the value of the JWT to verify

   This function can be used from ANY_ROUTE.

   Example 1.3. jwt3_verify usage
...
  if(!jwt3_verify("/path/to/pubkey.json", "ES256",
         "caller='$fU';callee='$tU';callid='$ci';index=100",
        "$var(jwt)") {
    xwarn("failed to verify jwt\n");
  }
...

4.3. jwt3_verify_key(pubkeyval, alg, claims, jwtval)

   Verify the JWT.

   The parameters are:
     * pubkeyval - public key value
     * alg - the algorithm to build the signature, as supported by the
       libjwt (e.g., RS256, HS256, ES256, ...)
     * claims - the list of claims to be checked they are in the JWT, in
       the format "name1=value1;name2=value2;..." (same as the SIP
       parameters format, see also the description of claims parameter for
       jwt3_generate()).
     * jwtval - the value of the JWT to verify

   This function can be used from ANY_ROUTE.

   Example 1.4. jwt3_verify_key usage
...
  if(!jwt3_verify_key("...", "RS256",
         "caller='$fU';callee='$tU';callid='$ci';index=100",
        "$var(jwt)") {
    xwarn("failed to verify jwt\n");
  }
...

5. Variables

   5.1. $jwt3(key)

5.1. $jwt3(key)

   Get the values and attributes after using JWT functions.

   The key can be:
     * val - the value of JWT after a successful jwt3_generate().
     * status - the status of verification after a failed jwt3_verify().

   Example 1.5. $jwt3(name) usage
...
  jwt3_generate("/path/to/prvkey.pem", "RS256",
        "caller='$fU';callee='$tU';callid='$ci';index=100");
  xinfo("jwt is: $jwt3(val)");
...
