# &adminguide;

## 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.

## Dependencies

### &kamailio; Modules

The following modules must be loaded before this module:

- none.

### 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.

## Parameters

### `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.

#### Set `key_mode` parameter

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

## Functions

### `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.

#### `jwt_generate` usage

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

### `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.

#### `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");
      }
    ...

### `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.

#### `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");
      }
    ...

## Variables

### `$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().

#### `$jwt(name)` usage

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