JWT Module

Daniel-Constantin Mierla

Edited by

Daniel-Constantin Mierla

Copyright © 2021 asipto.com

Table of Contents

1. Admin Guide
1. Overview
2. Dependencies
2.1. Kamailio Modules
2.2. External Libraries or Applications
3. Parameters
3.1. key_mode (int)
4. Functions
4.1. jwt_generate(prvkey, alg, claims[, headers])
4.2. jwt_verify(pubkeypath, alg, claims, jwtval)
4.3. jwt_verify_key(pubkeyval, alg, claims, jwtval)
5. Variables
5.1. $jwt(key)

List of Examples

1.1. Set key_mode parameter
1.2. jwt_generate usage
1.3. jwt_verify usage
1.4. jwt_verify_key usage
1.5. $jwt(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. key_mode (int)
4. Functions
4.1. jwt_generate(prvkey, alg, claims[, headers])
4.2. jwt_verify(pubkeypath, alg, claims, jwtval)
4.3. jwt_verify_key(pubkeyval, alg, claims, jwtval)
5. Variables
5.1. $jwt(key)

1. Overview

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

It relies on libjwt (at least v1.12.0) library (https://github.com/benmcollins/libjwt), but it is not working with the new libjwt3.

2. Dependencies

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 - minimum version 1.12.0, but less than libjwt 3.0.

3. Parameters

3.1. key_mode (int)

Mode to use the private and public keys. If set to 0, they are read always from the disk. If set to 1, they are cached in memory with the first use (no reload support yet).

Default value is 0.

Example 1.1. Set key_mode parameter 

...
modparam("jwt", "key_mode", 1)
...

4. Functions

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

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

The parameters are:

  • prvkey - path to private key

  • 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. jwt_generate usage 

...
  jwt_generate("/path/to/prvkey.pem", "RS256",
        "caller='$fU';callee='$tU';callid='$ci';index=100");
...

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

Verify the JWT.

The parameters are:

  • pubkeypath - path to public key file

  • 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 jwt_generate()).

  • jwtval - the value of the JWT to verify

This function can be used from ANY_ROUTE.

Example 1.3. jwt_verify usage 

...
  if(!jwt_verify("/path/to/pubkey.pem", "RS256",
         "caller='$fU';callee='$tU';callid='$ci';index=100",
        "$var(jwt)") {
    xwarn("failed to verify jwt\n");
  }
...

4.3.  jwt_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 jwt_generate()).

  • jwtval - the value of the JWT to verify

This function can be used from ANY_ROUTE.

Example 1.4. jwt_verify_key usage 

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

5. Variables

5.1.  $jwt(key)

Get the values and attributes after using JWT functions.

The key can be:

  • val - the value of JWT after a successful jwt_generate().

  • status - the status of verification after a failed jwt_verify().

Example 1.5. $jwt(name) usage 

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