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)
              3.3. cache_dir (str)
              3.4. cache_expire (int)
              3.5. modproc (str)
              3.6. libopt (str)

        4. Functions

              4.1. secsipid_check_identity(keyPath)
              4.2. secsipid_check_identity_pubkey(pubkeyVal)
              4.3. secsipid_check(sIdentity, keyPath)
              4.4. secsipid_verify(sIdentity, keyVal, opts)
              4.5. secsipid_get_url(url, ovar)
              4.6. secsipid_add_identity(origTN, destTN, attest, origID,
                      x5u, keyPath)

              4.7. secsipid_build_identity(origTN, destTN, attest, origID,
                      x5u, keyPath)

              4.8. secsipid_build_identity_prvkey(origTN, destTN, attest,
                      origID, x5u, keyData)

              4.9. secsipid_sign(sheaders, spaypload, keyPath)
              4.10. secsipid_sign_prvkey(sheaders, spaypload, keyData)

        5. Installation

   List of Examples

   1.1. Set expire parameter
   1.2. Set timeout parameter
   1.3. Set cache_dir parameter
   1.4. Set cache_expire parameter
   1.5. Set modproc parameter
   1.6. Set libopt parameter
   1.7. secsipid_check_identity usage
   1.8. secsipid_check_identity_pubkey usage
   1.9. secsipid_check usage
   1.10. secsipid_verify usage
   1.11. secsipid_get_url usage
   1.12. secsipid_add_identity usage
   1.13. secsipid_build_identity usage
   1.14. secsipid_build_identity_prvkey usage
   1.15. secsipid_sign usage
   1.16. secsipid_sign_prvkey usage
   1.17. 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)
        3.3. cache_dir (str)
        3.4. cache_expire (int)
        3.5. modproc (str)
        3.6. libopt (str)

   4. Functions

        4.1. secsipid_check_identity(keyPath)
        4.2. secsipid_check_identity_pubkey(pubkeyVal)
        4.3. secsipid_check(sIdentity, keyPath)
        4.4. secsipid_verify(sIdentity, keyVal, opts)
        4.5. secsipid_get_url(url, ovar)
        4.6. secsipid_add_identity(origTN, destTN, attest, origID, x5u,
                keyPath)

        4.7. secsipid_build_identity(origTN, destTN, attest, origID, x5u,
                keyPath)

        4.8. secsipid_build_identity_prvkey(origTN, destTN, attest,
                origID, x5u, keyData)

        4.9. secsipid_sign(sheaders, spaypload, keyPath)
        4.10. secsipid_sign_prvkey(sheaders, spaypload, keyData)

   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), known together as STIR/SHAKEN.

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

   Note that this module needs "secsipid_proc.so" module to be installed,
   but without loading the "secsipid_proc.so" via "loadmodule". This
   module loads "secsipid_proc.so" in child init callback in order to
   initialize the "libsecsipid" per child process.

   The libsecsipid is provided by secsipidx project:
   https://github.com/asipto/secsipidx.

   In case of failure, the functions in this module return error codes
   (the negative values) listed in the code of libsecsipid, pretty much at
   the top of:
   https://github.com/asipto/secsipidx/blob/main/secsipid/secsipid.go.

2. Dependencies

   2.1. Kamailio Modules
   2.2. External Libraries or Applications

2.1. Kamailio Modules

   The following modules must be installed (but not loaded) to use this
   module:
     * secsipid_proc.

2.2. External Libraries or Applications

   The following libraries or applications must be installed before
   running Kamailio with this module loaded:
     * none.

3. Parameters

   3.1. expire (int)
   3.2. timeout (int)
   3.3. cache_dir (str)
   3.4. cache_expire (int)
   3.5. modproc (str)
   3.6. libopt (str)

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

3.3. cache_dir (str)

   The path to the directory where to save cached public keys. If set, it
   activates the public key file caching in the libsecsipid library.

   Default value is "".

   Example 1.3. Set cache_dir parameter
...
modparam("secsipid", "cache_dir", "/tmp/kamailio/secsipid")
...

3.4. cache_expire (int)

   The interval in seconds after which a cached public key is considered
   expired. This value is passed to the libsecsipid library.

   Default value is 3600.

   Example 1.4. Set cache_expire parameter
...
modparam("secsipid", "cache_expire", 7200)
...

3.5. modproc (str)

   The name of or the path to the required per-process API module.

   Default value is "secsipid_proc.so".

   Example 1.5. Set modproc parameter
...
modparam("secsipid", "modproc", "secsipid_proc2.so")
...

3.6. libopt (str)

   Set a libsecsipid option. The value has to be name=value. The parameter
   can be set many times.

   Default value is "" (not set).

   Example 1.6. Set libopt parameter
...
modparam("secsipid", "libopt", "CacheExpires=0")
...

4. Functions

   4.1. secsipid_check_identity(keyPath)
   4.2. secsipid_check_identity_pubkey(pubkeyVal)
   4.3. secsipid_check(sIdentity, keyPath)
   4.4. secsipid_verify(sIdentity, keyVal, opts)
   4.5. secsipid_get_url(url, ovar)
   4.6. secsipid_add_identity(origTN, destTN, attest, origID, x5u,
          keyPath)

   4.7. secsipid_build_identity(origTN, destTN, attest, origID, x5u,
          keyPath)

   4.8. secsipid_build_identity_prvkey(origTN, destTN, attest, origID,
          x5u, keyData)

   4.9. secsipid_sign(sheaders, spaypload, keyPath)
   4.10. secsipid_sign_prvkey(sheaders, spaypload, keyData)

4.1.  secsipid_check_identity(keyPath)

   Check the validity of the Identity header using the public keys stored
   in the file specified by "keyPath". If the parameter is empty, the
   function is downloading the public key using the URL from "info"
   parameter of the Identity header, using the value of "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.7. 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_check_identity_pubkey(pubkeyVal)

   Similar to secsipid_check_identity() with the public key value provided
   in the parameter.

   The parameters can contain pseudo-variables.

   This function can be used from ANY_ROUTE.

   Example 1.8. secsipid_check_identity_pubkey usage
...
request_route {
  ...
  http_client_query("https://provider.com/stir-shaken/cert.pem", "$var(pubkey)")
;
  ...
  if(secsipid_check_identity_pubkey("$var(pubkey)")) { ... }
  ...
}
...

4.3.  secsipid_check(sIdentity, keyPath)

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

   The parameters can contain pseudo-variables.

   This function can be used from ANY_ROUTE.

   Example 1.9. secsipid_check usage
...
request_route {
    ...
        if(secsipid_check("...", "/secsipid/$si/cert.pem")) { ... }
    ...
        if(secsipid_check("...", "")) { ... }
    ...
}
...

   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.4.  secsipid_verify(sIdentity, keyVal, opts)

   Check the validity of the "sIdentity" parameter using the key value
   given in the parameter "keyVal". The validity of the JWT in the
   sIdentity value is also checked against the "expire" parameter.

   The "opts" parameter provides the verify options:
     * A (uppercase) - skip verifying the attributes in the JWT header.

   The parameters can contain pseudo-variables.

   This function can be used from ANY_ROUTE.

   Example 1.10. secsipid_verify usage
...
request_route {
    ...
    secsipid_get_url("https://provider.com/stir-shaken/cert.pem", "$var(pubkey)"
);
    if(secsipid_verify("$hdr(Identity)", "$var(pubkey)", "A")) { ... }
    ...
}
...

   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.5.  secsipid_get_url(url, ovar)

   Get the content of a URL and store the result in a variable. The result
   is cached by libsecsipid, if caching is enabled.

   The url parameters can contain pseudo-variables and ovar has to be the
   name of a writable pseudo-variable.

   This function can be used from ANY_ROUTE.

   Example 1.11. secsipid_get_url usage
...
request_route {
  ...
  if(secsipid_get_url("https://$fd/stirshaken/cert.pem", "$var(pubkey)")) { ...
}
  ...
}
...

4.6.  secsipid_add_identity(origTN, destTN, attest, origID, x5u, keyPath)

   Add Identity header using the private 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.12. secsipid_add_identity usage
...
request_route {
    ...
    secsipid_add_identity("$fU", "$rU", "A", "",
        "https://kamailio.org/stir/$rd/cert.pem", "/secsipid/$rd/key.pem");
    ...
}
...

4.7.  secsipid_build_identity(origTN, destTN, attest, origID, x5u, keyPath)

   Build Identity value using the key specified by private "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"). On success, the Indentity value is stored in variable
   $secsipid(val). It also sets $secsipid(ret) to the return value of the
   libsecsipid functions.

   The parameters can contain pseudo-variables.

   This function can be used from ANY_ROUTE.

   Example 1.13. secsipid_build_identity usage
...
request_route {
    ...
    if(secsipid_build_identity("$fU", "$rU", "A", "",
            "https://kamailio.org/stir/$rd/cert.pem", "/secsipid/$rd/key.pem"))
{
        xinfo("Identity value: $secsipid(val)\n");
    }
    ...
}
...

4.8.  secsipid_build_identity_prvkey(origTN, destTN, attest, origID, x5u,
keyData)

   Similar to secsipid_build_identity(), but the private key data is
   provided as parameter instead to the file path.

   The parameters can contain pseudo-variables.

   This function can be used from ANY_ROUTE.

   Example 1.14. secsipid_build_identity_prvkey usage
...
request_route {
    ...
    if(secsipid_build_identity_prvkey("$fU", "$rU", "A", "",
            "https://kamailio.org/stir/$rd/cert.pem", "$var(prvkey)")) {
        xinfo("Identity value: $secsipid(val)\n");
    }
    ...
}
...

4.9.  secsipid_sign(sheaders, spaypload, keyPath)

   Build Identity value using the private key specified by "keyPath" to
   sign the JWT body. The sheaders and spayload have to be string
   representation of JSON headers and payload to be signed. On success,
   the Indentity value is stored in variable $secsipid(val). It also sets
   $secsipid(ret) to the return value of the libsecsipid functions.

   The parameters can contain pseudo-variables.

   This function can be used from ANY_ROUTE.

   Example 1.15. secsipid_sign usage
...
request_route {
    ...
    if(secsipid_sign("_JSON_HEADERS_", "_JSON_PAYLOAD_",
            "/secsipid/$rd/key.pem")) {
        xinfo("Identity value: $secsipid(val)\n");
    }
    ...
}
...

4.10.  secsipid_sign_prvkey(sheaders, spaypload, keyData)

   Build Identity value using the private key given by "keyData" to sign
   the JWT body. The sheaders and spayload have to be string
   representation of JSON headers and payload to be signed. On success,
   the Indentity value is stored in variable $secsipid(val). It also sets
   $secsipid(ret) to the return value of the libsecsipid functions.

   The parameters can contain pseudo-variables.

   This function can be used from ANY_ROUTE.

   Example 1.16. secsipid_sign_prvkey usage
...
request_route {
    ...
    if(secsipid_sign_prvkey("_JSON_HEADERS_", "_JSON_PAYLOAD_",
            "_PRIVATE_KEY_")) {
        xinfo("Identity value: $secsipid(val)\n");
    }
    ...
}
...

5. Installation

   The module needs "secsipdi_proc.so" module that 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.

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

   Example 1.17. Libsecsipid Usage
...
export GO111MODULE=off
go get https://github.com/asipto/secsipidx
cd $GOPATH/src/github.com/asipto/secsipidx/csecsipid/
make all
make install

cd /path/to/kamailio/
make include_modules="secsipid secsipid_proc ..." cfg
make all
make install

## or compiling individual modules for use inside source tree
# make modules modules=src/modules/secsipid_proc
# make modules modules=src/modules/secsipid
...

   For more details about compilation and installation of libsecsipid,
   see: https://github.com/asipto/secsipidx.
