SecSIPId Module

Daniel-Constantin Mierla

   asipto.com
   <miconda@gmail.com>

Edited by

Daniel-Constantin Mierla

   <miconda@gmail.com>

   Copyright © 2020 http://www.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. expire (int)
              3.2. timeout (int)

        4. Functions

              4.1. secsipid_check_identity(keyPath)
              4.2. secsipid_add_identity(origTN, destTN, attest, origID,
                      x5u, keyPath)

        5. Installation

   List of Examples

   1.1. Set expire parameter
   1.2. Set timeout parameter
   1.3. secsipid_check_identity usage
   1.4. secsipid_add_identity usage
   1.5. Libsecsipid 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. expire (int)
        3.2. timeout (int)

   4. Functions

        4.1. secsipid_check_identity(keyPath)
        4.2. secsipid_add_identity(origTN, destTN, attest, origID, x5u,
                keyPath)

   5. Installation

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

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:
     * No dependencies on other Kamailio modules.

2.2. 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/.

3. Parameters

   3.1. expire (int)
   3.2. timeout (int)

3.1. expire (int)

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

   Default value is 300.

   Example 1.1. Set expire parameter
...
modparam("secsipid", "expire", 600)
...

3.2. timeout (int)

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

   Default value is 5.

   Example 1.2. Set timeout parameter
...
modparam("secsipid", "timeout", 2)
...

4. Functions

   4.1. secsipid_check_identity(keyPath)
   4.2. secsipid_add_identity(origTN, destTN, attest, origID, x5u,
          keyPath)

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

   Example 1.3. 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.

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

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

5. 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:

   Example 1.5. 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/
...