1SecSIPId Module 2 3Daniel-Constantin Mierla 4 5 asipto.com 6 <miconda@gmail.com> 7 8Edited by 9 10Daniel-Constantin Mierla 11 12 <miconda@gmail.com> 13 14 Copyright © 2020 http://www.asipto.com 15 __________________________________________________________________ 16 17 Table of Contents 18 19 1. Admin Guide 20 21 1. Overview 22 2. Dependencies 23 24 2.1. Kamailio Modules 25 2.2. External Libraries or Applications 26 27 3. Parameters 28 29 3.1. expire (int) 30 3.2. timeout (int) 31 32 4. Functions 33 34 4.1. secsipid_check_identity(keyPath) 35 4.2. secsipid_add_identity(origTN, destTN, attest, origID, 36 x5u, keyPath) 37 38 5. Installation 39 40 List of Examples 41 42 1.1. Set expire parameter 43 1.2. Set timeout parameter 44 1.3. secsipid_check_identity usage 45 1.4. secsipid_add_identity usage 46 1.5. Libsecsipid usage 47 48Chapter 1. Admin Guide 49 50 Table of Contents 51 52 1. Overview 53 2. Dependencies 54 55 2.1. Kamailio Modules 56 2.2. External Libraries or Applications 57 58 3. Parameters 59 60 3.1. expire (int) 61 3.2. timeout (int) 62 63 4. Functions 64 65 4.1. secsipid_check_identity(keyPath) 66 4.2. secsipid_add_identity(origTN, destTN, attest, origID, x5u, 67 keyPath) 68 69 5. Installation 70 711. Overview 72 73 The module implements secure SIP identity specifications - STIR (Secure 74 Telephony Identity Revisited) and SHAKEN (Signature-based Handling of 75 Asserted information using toKENs) IETF extensions for SIP (RFC8224, 76 RFC8588). 77 78 It exports the functions to check and generate SIP Identity header. 79 802. Dependencies 81 82 2.1. Kamailio Modules 83 2.2. External Libraries or Applications 84 852.1. Kamailio Modules 86 87 The following modules must be loaded before this module: 88 * No dependencies on other Kamailio modules. 89 902.2. External Libraries or Applications 91 92 The following libraries or applications must be installed before 93 running Kamailio with this module loaded: 94 * libsecsipid - https://github.com/asipto/secsipidx/. 95 963. Parameters 97 98 3.1. expire (int) 99 3.2. timeout (int) 100 1013.1. expire (int) 102 103 The interval in seconds after which the Identity header JWT is 104 considered to be expired. 105 106 Default value is 300. 107 108 Example 1.1. Set expire parameter 109... 110modparam("secsipid", "expire", 600) 111... 112 1133.2. timeout (int) 114 115 The interval in seconds after which the HTTP GET operation to download 116 the public key times out. 117 118 Default value is 5. 119 120 Example 1.2. Set timeout parameter 121... 122modparam("secsipid", "timeout", 2) 123... 124 1254. Functions 126 127 4.1. secsipid_check_identity(keyPath) 128 4.2. secsipid_add_identity(origTN, destTN, attest, origID, x5u, 129 keyPath) 130 1314.1. secsipid_check_identity(keyPath) 132 133 Check the validity of the Identity header using the keys stored in the 134 file specified by "keyPath". If the parameter is empty, the function is 135 downloading the key using the URL from "info" parameter of the Identity 136 header, using the value od "timeout" parameter to limit the download 137 time. The validity of the JWT body in the Identity header is also 138 checked against the "expire" parameter. 139 140 The parameters can contain pseudo-variables. 141 142 This function can be used from ANY_ROUTE. 143 144 Example 1.3. secsipid_check_identity usage 145... 146request_route { 147 ... 148 if(secsipid_check_identity("/secsipid/$si/cert.pem")) { ... } 149 ... 150 if(secsipid_check_identity("")) { ... } 151 ... 152} 153... 154 155 Further checks can be done with config operations, decoding the JWT 156 header and payload using {s.select} and {s.decode.base64t} 157 transformations together with jansson module. 158 1594.2. secsipid_add_identity(origTN, destTN, attest, origID, x5u, keyPath) 160 161 Add Identity header using the key specified by "keyPath" to sign the 162 JWT body. If origID is empty, a UUID string is generated to fill the 163 field. The origTN represents the origination telephone number; destTN 164 represents the destination telephone number; x5u is the HTTP URL 165 referencing to the public key that should be used to verify the 166 signature; attest represents the attestation level (should be "A", "B" 167 or "C"). 168 169 The parameters can contain pseudo-variables. 170 171 This function can be used from ANY_ROUTE. 172 173 Example 1.4. secsipid_add_identity usage 174... 175request_route { 176 ... 177 secsipid_add_identity("$fU", "$rU", "A", "", 178 "https://kamailio.org/stir/$rd/cert.pem", "/secsipid/$rd/key.pem"); 179 ... 180} 181... 182 1835. Installation 184 185 The module depends on "libsecsipid", which is a component of 186 "sipsecidx" project from https://github.com/asipto/secsipidx/. The 187 library is implemented in Go language, with generated C API and 188 library. Until the libsecsipid is going to be packaged in OS 189 distributions, the secsipid module can be compiled by copying 190 secsipid.h libsecsipid.h and libsecsipid.a files in the folder of the 191 module. 192 193 To generate the libsecsipid.a file, it requires to have Go language 194 installed and its environment configured, then run the following 195 commands: 196 197 Example 1.5. Libsecsipid usage 198... 199go get https://github.com/asipto/secsipidx 200cd $GOPATH/src/github.com/asipto/secsipidx/csecsipid/ 201make liba 202cp secsipid.h libsecsipid.h libsecsipid.a \ 203 /path/to/kamailio/src/modules/secsipid/ 204cd /path/to/kamailio/ 205make modules modules=src/modules/secsipid/ 206... 207