From 3f9f1620fd6d621863d6df92eb17039a956474d8 Mon Sep 17 00:00:00 2001 From: Daniel-Constantin Mierla Date: Mon, 27 Jan 2020 11:25:09 +0100 Subject: [PATCH] secsipid: new module implementing STIR and SKAKEN IETF extensions - for more see RFC 8224 and RFC 8588 --- src/modules/secsipid/Makefile | 17 ++ src/modules/secsipid/README | 204 ++++++++++++++++++++ src/modules/secsipid/doc/Makefile | 4 + src/modules/secsipid/doc/secsipid.xml | 42 ++++ src/modules/secsipid/doc/secsipid_admin.xml | 203 +++++++++++++++++++ src/modules/secsipid/libsecsipid.h | 90 +++++++++ src/modules/secsipid/secsipid.h | 8 + 7 files changed, 568 insertions(+) create mode 100644 src/modules/secsipid/Makefile create mode 100644 src/modules/secsipid/README create mode 100644 src/modules/secsipid/doc/Makefile create mode 100644 src/modules/secsipid/doc/secsipid.xml create mode 100644 src/modules/secsipid/doc/secsipid_admin.xml create mode 100644 src/modules/secsipid/libsecsipid.h create mode 100644 src/modules/secsipid/secsipid.h diff --git a/src/modules/secsipid/Makefile b/src/modules/secsipid/Makefile new file mode 100644 index 00000000000..ec8ad07980b --- /dev/null +++ b/src/modules/secsipid/Makefile @@ -0,0 +1,17 @@ +# +# secsipid module makefile +# +# WARNING: do not run this directly, it should be run by the master Makefile + +include ../../Makefile.defs +auto_gen= +NAME=secsipid.so + +DEFS+= -I. +LIBS+= -L. -lsecsipid + +ifeq ($(OS), darwin) +LIBS+= -framework CoreFoundation -framework Security -lpthread +endif + +include ../../Makefile.modules diff --git a/src/modules/secsipid/README b/src/modules/secsipid/README new file mode 100644 index 00000000000..8ad57e5a31f --- /dev/null +++ b/src/modules/secsipid/README @@ -0,0 +1,204 @@ +SecSIPId Module + +Daniel-Constantin Mierla + + asipto.com + + +Edited by + +Daniel-Constantin Mierla + + + + 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 expire parameter + 1.3. secsipid_check_identity usage + 1.4. secsipid_add_identity usage + 1.5. + +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 and + SHAKEN IETF extensions for SIP (RFC8224, RFC 8588). + + It exports the functions to check and generate 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 expire parameter +... +modparam("secsipid", "expire", 600) +... + +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 + checjed 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", "", "http://kamailio.org/stir/$rd/c +ert.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. +... +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/ +... diff --git a/src/modules/secsipid/doc/Makefile b/src/modules/secsipid/doc/Makefile new file mode 100644 index 00000000000..087eefd20ed --- /dev/null +++ b/src/modules/secsipid/doc/Makefile @@ -0,0 +1,4 @@ +docs = secsipid.xml + +docbook_dir = ../../../../doc/docbook +include $(docbook_dir)/Makefile.module diff --git a/src/modules/secsipid/doc/secsipid.xml b/src/modules/secsipid/doc/secsipid.xml new file mode 100644 index 00000000000..bdd3126c2e0 --- /dev/null +++ b/src/modules/secsipid/doc/secsipid.xml @@ -0,0 +1,42 @@ + + + +%docentities; + +]> + + + + SecSIPId Module + &kamailioname; + + + Daniel-Constantin + Mierla + asipto.com + miconda@gmail.com +
+ + http://www.asipto.com + +
+ + + Daniel-Constantin + Mierla + miconda@gmail.com + + + + 2020 + http://www.asipto.com + + + + + + + diff --git a/src/modules/secsipid/doc/secsipid_admin.xml b/src/modules/secsipid/doc/secsipid_admin.xml new file mode 100644 index 00000000000..945293fb1bd --- /dev/null +++ b/src/modules/secsipid/doc/secsipid_admin.xml @@ -0,0 +1,203 @@ + + + +%docentities; + +]> + + + + + &adminguide; + +
+ Overview + + The module implements secure SIP identity specifications - STIR and SHAKEN + IETF extensions for SIP (RFC8224, RFC 8588). + + + It exports the functions to check and generate 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 +
+ <varname>expire</varname> (int) + + The interval in seconds after which the Identity header JWT is considered + to be expired. + + + + Default value is 300. + + + + Set <varname>expire</varname> parameter + +... +modparam("secsipid", "expire", 600) +... + + +
+
+ <varname>timeout</varname> (int) + + The interval in seconds after which the HTTP GET operation to download + the public key times out. + + + + Default value is 5. + + + + Set <varname>expire</varname> parameter + +... +modparam("secsipid", "expire", 600) +... + + +
+ +
+ +
+ Functions +
+ + <function moreinfo="none">secsipid_check_identity(keyPath)</function> + + + 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 checjed against the "expire" + parameter. + + + The parameters can contain pseudo-variables. + + + This function can be used from ANY_ROUTE. + + + <function>secsipid_check_identity</function> 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. + +
+
+ + <function moreinfo="none">secsipid_add_identity(origTN, destTN, attest, origID, x5u, keyPath)</function> + + + 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. + + + <function>secsipid_add_identity</function> usage + +... +request_route { + ... + secsipid_add_identity("$fU", "$rU", "A", "", "http://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: + + + +... +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/ +... + + +
+ + + diff --git a/src/modules/secsipid/libsecsipid.h b/src/modules/secsipid/libsecsipid.h new file mode 100644 index 00000000000..77cddcb5afa --- /dev/null +++ b/src/modules/secsipid/libsecsipid.h @@ -0,0 +1,90 @@ +/* Code generated by cmd/cgo; DO NOT EDIT. */ + +/* package command-line-arguments */ + + +#line 1 "cgo-builtin-export-prolog" + +#include /* for ptrdiff_t below */ + +#ifndef GO_CGO_EXPORT_PROLOGUE_H +#define GO_CGO_EXPORT_PROLOGUE_H + +#ifndef GO_CGO_GOSTRING_TYPEDEF +typedef struct { const char *p; ptrdiff_t n; } _GoString_; +#endif + +#endif + +/* Start of preamble from import "C" comments. */ + + + + +/* End of preamble from import "C" comments. */ + + +/* Start of boilerplate cgo prologue. */ +#line 1 "cgo-gcc-export-header-prolog" + +#ifndef GO_CGO_PROLOGUE_H +#define GO_CGO_PROLOGUE_H + +typedef signed char GoInt8; +typedef unsigned char GoUint8; +typedef short GoInt16; +typedef unsigned short GoUint16; +typedef int GoInt32; +typedef unsigned int GoUint32; +typedef long long GoInt64; +typedef unsigned long long GoUint64; +typedef GoInt64 GoInt; +typedef GoUint64 GoUint; +typedef __SIZE_TYPE__ GoUintptr; +typedef float GoFloat32; +typedef double GoFloat64; +typedef float _Complex GoComplex64; +typedef double _Complex GoComplex128; + +/* + static assertion to make sure the file is being used on architecture + at least with matching size of GoInt. +*/ +typedef char _check_for_64_bit_pointer_matching_GoInt[sizeof(void*)==64/8 ? 1:-1]; + +#ifndef GO_CGO_GOSTRING_TYPEDEF +typedef _GoString_ GoString; +#endif +typedef void *GoMap; +typedef void *GoChan; +typedef struct { void *t; void *v; } GoInterface; +typedef struct { void *data; GoInt len; GoInt cap; } GoSlice; + +#endif + +/* End of boilerplate cgo prologue. */ + +#ifdef __cplusplus +extern "C" { +#endif + + +// SecSIPIDSignJSONHP -- + +extern int SecSIPIDSignJSONHP(char* p0, char* p1, char* p2, char** p3); + +// SecSIPIDGetIdentity -- + +extern int SecSIPIDGetIdentity(char* p0, char* p1, char* p2, char* p3, char* p4, char* p5, char** p6); + +// SecSIPIDCheck -- + +extern int SecSIPIDCheck(char* p0, int p1, int p2, char* p3, int p4); + +// SecSIPIDCheckFull -- + +extern int SecSIPIDCheckFull(char* p0, int p1, int p2, char* p3, int p4); + +#ifdef __cplusplus +} +#endif diff --git a/src/modules/secsipid/secsipid.h b/src/modules/secsipid/secsipid.h new file mode 100644 index 00000000000..050bfe97d99 --- /dev/null +++ b/src/modules/secsipid/secsipid.h @@ -0,0 +1,8 @@ +/* header file for secsipid library */ + +#ifndef __SECSIPID_H__ +#define __SECSIPID_H__ + +#include "libsecsipid.h" + +#endif