name mode size
..
doc 040000
Makefile 100644 200B
README 100644 9.11kB
secsipid_mod.c 100644 18.19kB
secsipid_papi.h 100644 1.92kB
README
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(pubkeyVal) 4.3. secsipid_get_url(url, ovar) 4.4. 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. 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_get_url usage 1.10. secsipid_add_identity usage 1.11. 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(pubkeyVal) 4.3. secsipid_get_url(url, ovar) 4.4. 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), 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 pyblic 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(pubkeyVal) 4.3. secsipid_get_url(url, ovar) 4.4. 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.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(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_get_url(url, ovar) Get the content of a URL and store the result in a variable. The url parameters can contain pseudo-variables and ovar has to be the name of a writtable pseudo-variable. This function can be used from ANY_ROUTE. Example 1.9. secsipid_get_url usage ... request_route { ... if(secsipid_get_url("https://$fd/stirshaken/cert.pem", "$var(pubkey)")) { ... } ... } ... 4.4. 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.10. 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 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. Until the libsecsipid is going to be packaged in OS distributions, the secsipid_proc 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.11. Libsecsipid Usage ... export GO111MODULE=off 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_proc/ 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.