# &adminguide;

## Overview

The module implements secure SIP identity specifications - STIR (Secure Telephony Identity Revisited) and SHAKEN (Signature-based Handling of Asserted information using toKENs) IETF extensions for SIP (RFC8224, RFC8588).

It exports the functions to check and generate SIP Identity header.

## Dependencies

### &kamailio; Modules

The following modules must be loaded before this module:

- No dependencies on other &kamailio; modules.

### External Libraries or Applications

The following libraries or applications must be installed before running &kamailio; with this module loaded:

- libsecsipid - https://github.com/asipto/secsipidx/.

## Parameters

### `expire` (int)

The interval in seconds after which the Identity header JWT is considered to be expired.

Default value is 300.

#### Set `expire` parameter

    ...
    modparam("secsipid", "expire", 600)
    ...

### `timeout` (int)

The interval in seconds after which the HTTP GET operation to download the public key times out.

Default value is 5.

#### Set `timeout` parameter

    ...
    modparam("secsipid", "timeout", 2)
    ...

## Functions

### `secsipid_check_identity(keyPath)`

Check the validity of the Identity header using the keys stored in the file specified by "keyPath". If the parameter is empty, the function is downloading the key using the URL from "info" parameter of the Identity header, using the value od "timeout" parameter to limit the download time. The validity of the JWT body in the Identity header is also checked against the "expire" parameter.

The parameters can contain pseudo-variables.

This function can be used from ANY_ROUTE.

#### `secsipid_check_identity` usage

    ...
    request_route {
        ...
    	if(secsipid_check_identity("/secsipid/$si/cert.pem")) { ... }
        ...
    	if(secsipid_check_identity("")) { ... }
        ...
    }
    ...

Further checks can be done with config operations, decoding the JWT header and payload using {s.select} and {s.decode.base64t} transformations together with jansson module.

### `secsipid_add_identity(origTN, destTN, attest, origID, x5u, keyPath)`

Add Identity header using the key specified by "keyPath" to sign the JWT body. If origID is empty, a UUID string is generated to fill the field. The origTN represents the origination telephone number; destTN represents the destination telephone number; x5u is the HTTP URL referencing to the public key that should be used to verify the signature; attest represents the attestation level (should be "A", "B" or "C").

The parameters can contain pseudo-variables.

This function can be used from ANY_ROUTE.

#### `secsipid_add_identity` usage

    ...
    request_route {
        ...
        secsipid_add_identity("$fU", "$rU", "A", "",
            "https://kamailio.org/stir/$rd/cert.pem", "/secsipid/$rd/key.pem");
        ...
    }
    ...

## Installation

The module depends on "libsecsipid", which is a component of "sipsecidx" project from https://github.com/asipto/secsipidx/. The library is implemented in Go language, with generated C API and library. Until the libsecsipid is going to be packaged in OS distributions, the secsipid module can be compiled by copying secsipid.h libsecsipid.h and libsecsipid.a files in the folder of the module.

To generate the libsecsipid.a file, it requires to have Go language installed and its environment configured, then run the following commands:

### Libsecsipid usage

    ...
    go get https://github.com/asipto/secsipidx
    cd $GOPATH/src/github.com/asipto/secsipidx/csecsipid/
    make liba
    cp secsipid.h libsecsipid.h libsecsipid.a \
        /path/to/kamailio/src/modules/secsipid/
    cd /path/to/kamailio/
    make modules modules=src/modules/secsipid/
    ...