Browse code

secsipid: docs for secsipid_build_identity_prvkey()

Daniel-Constantin Mierla authored on 30/08/2021 09:05:52
Showing 1 changed files
... ...
@@ -397,6 +397,36 @@ request_route {
397 397
     ...
398 398
 }
399 399
 ...
400
+</programlisting>
401
+		</example>
402
+	</section>
403
+	<section id="secsipid.f.secsipid_build_identity_prvkey">
404
+		<title>
405
+		<function moreinfo="none">secsipid_build_identity_prvkey(origTN, destTN, attest, origID, x5u, keyData)</function>
406
+		</title>
407
+		<para>
408
+			Similar to secsipid_build_identity(), but the private key data is
409
+			provided as parameter instead to the file path.
410
+		</para>
411
+		<para>
412
+		The parameters can contain pseudo-variables.
413
+		</para>
414
+		<para>
415
+		This function can be used from ANY_ROUTE.
416
+		</para>
417
+		<example>
418
+		<title><function>secsipid_build_identity_prvkey</function> usage</title>
419
+		<programlisting format="linespecific">
420
+...
421
+request_route {
422
+    ...
423
+    if(secsipid_build_identity_prvkey("$fU", "$rU", "A", "",
424
+            "https://kamailio.org/stir/$rd/cert.pem", "$var(prvkey)")) {
425
+        xinfo("Identity value: $secsipid(val)\n");
426
+    }
427
+    ...
428
+}
429
+...
400 430
 </programlisting>
401 431
 		</example>
402 432
 	</section>
Browse code

secsipid: fix documentation example for secsipid_check() function

Ovidiu Sas authored on 01/07/2021 14:09:24
Showing 1 changed files
... ...
@@ -291,9 +291,9 @@ request_route {
291 291
 ...
292 292
 request_route {
293 293
     ...
294
-	if(secsipid_check_identity("...", "/secsipid/$si/cert.pem")) { ... }
294
+	if(secsipid_check("...", "/secsipid/$si/cert.pem")) { ... }
295 295
     ...
296
-	if(secsipid_check_identity("...", "")) { ... }
296
+	if(secsipid_check("...", "")) { ... }
297 297
     ...
298 298
 }
299 299
 ...
Browse code

secsipid: fix documentation for secsipid_check_identity_pubkey

Ovidiu Sas authored on 01/07/2021 14:04:10
Showing 1 changed files
... ...
@@ -239,7 +239,7 @@ request_route {
239 239
 	</section>
240 240
 	<section id="secsipid.f.secsipid_check_identity_pubkey">
241 241
 		<title>
242
-		<function moreinfo="none">secsipid_check_identity(pubkeyVal)</function>
242
+		<function moreinfo="none">secsipid_check_identity_pubkey(pubkeyVal)</function>
243 243
 		</title>
244 244
 		<para>
245 245
 			Similar to secsipid_check_identity() with the public key value
Browse code

secsipid: docs for secsipid_sign()

Daniel-Constantin Mierla authored on 21/06/2021 06:12:15
Showing 1 changed files
... ...
@@ -397,6 +397,39 @@ request_route {
397 397
     ...
398 398
 }
399 399
 ...
400
+</programlisting>
401
+		</example>
402
+	</section>
403
+	<section id="secsipid.f.secsipid_sign">
404
+		<title>
405
+		<function moreinfo="none">secsipid_sign(sheaders, spaypload, keyPath)</function>
406
+		</title>
407
+		<para>
408
+			Build Identity value using the key specified by "keyPath" to sign the JWT body.
409
+			The sheaders and spayload have to be string representation of JSON
410
+			headers and payload to be signed. On success, the Indentity value is
411
+			stored in variable $secsipid(val). It also sets $secsipid(ret) to
412
+			the return value of the libsecsipid functions.
413
+		</para>
414
+		<para>
415
+		The parameters can contain pseudo-variables.
416
+		</para>
417
+		<para>
418
+		This function can be used from ANY_ROUTE.
419
+		</para>
420
+		<example>
421
+		<title><function>secsipid_sign</function> usage</title>
422
+		<programlisting format="linespecific">
423
+...
424
+request_route {
425
+    ...
426
+    if(secsipid_sign("_JSON_HEADERS_", "_JSON_PAYLOAD_",
427
+            "/secsipid/$rd/key.pem")) {
428
+        xinfo("Identity value: $secsipid(val)\n");
429
+    }
430
+    ...
431
+}
432
+...
400 433
 </programlisting>
401 434
 		</example>
402 435
 	</section>
Browse code

secsipid: docs for secsipid_check(...) function

Daniel-Constantin Mierla authored on 18/06/2021 12:06:42
Showing 1 changed files
... ...
@@ -266,6 +266,45 @@ request_route {
266 266
 </programlisting>
267 267
 		</example>
268 268
 	</section>
269
+	<section id="secsipid.f.secsipid_check">
270
+		<title>
271
+		<function moreinfo="none">secsipid_check(sIdentity, keyPath)</function>
272
+		</title>
273
+		<para>
274
+			Check the validity of the "sIdentity" parameter using the keys stored
275
+			in the file specified by "keyPath". If the keyPath parameter is empty,
276
+			the function is downloading the key using the URL from "info"
277
+			parameter of the sIdentity, using the value of "timeout"
278
+			parameter to limit the download time. The validity of the JWT
279
+			in the sIdentity value is also checked against the "expire"
280
+			parameter.
281
+		</para>
282
+		<para>
283
+		The parameters can contain pseudo-variables.
284
+		</para>
285
+		<para>
286
+		This function can be used from ANY_ROUTE.
287
+		</para>
288
+		<example>
289
+		<title><function>secsipid_check</function> usage</title>
290
+		<programlisting format="linespecific">
291
+...
292
+request_route {
293
+    ...
294
+	if(secsipid_check_identity("...", "/secsipid/$si/cert.pem")) { ... }
295
+    ...
296
+	if(secsipid_check_identity("...", "")) { ... }
297
+    ...
298
+}
299
+...
300
+</programlisting>
301
+		</example>
302
+		<para>
303
+			Further checks can be done with config operations, decoding the JWT header
304
+			and payload using {s.select} and {s.decode.base64t} transformations
305
+			together with jansson module.
306
+		</para>
307
+	</section>
269 308
 	<section id="secsipid.f.secsipid_get_url">
270 309
 		<title>
271 310
 		<function moreinfo="none">secsipid_get_url(url, ovar)</function>
Browse code

secsipid: docs for secsipid_build_identity(...) function

Daniel-Constantin Mierla authored on 17/06/2021 14:35:55
Showing 1 changed files
... ...
@@ -322,6 +322,42 @@ request_route {
322 322
     ...
323 323
 }
324 324
 ...
325
+</programlisting>
326
+		</example>
327
+	</section>
328
+	<section id="secsipid.f.secsipid_build_identity">
329
+		<title>
330
+		<function moreinfo="none">secsipid_build_identity(origTN, destTN, attest, origID, x5u, keyPath)</function>
331
+		</title>
332
+		<para>
333
+			Build Identity value using the key specified by "keyPath" to sign the JWT body.
334
+			If origID is empty, a UUID string is generated to fill the field. The origTN
335
+			represents the origination telephone number; destTN represents the destination
336
+			telephone number; x5u is the HTTP URL referencing to the public key that
337
+			should be used to verify the signature; attest represents the attestation
338
+			level (should be "A", "B" or "C"). On success, the Indentity value is
339
+			stored in variable $secsipid(val). It also sets $secsipid(ret) to
340
+			the return value of the libsecsipid functions.
341
+		</para>
342
+		<para>
343
+		The parameters can contain pseudo-variables.
344
+		</para>
345
+		<para>
346
+		This function can be used from ANY_ROUTE.
347
+		</para>
348
+		<example>
349
+		<title><function>secsipid_build_identity</function> usage</title>
350
+		<programlisting format="linespecific">
351
+...
352
+request_route {
353
+    ...
354
+    if(secsipid_build_identity("$fU", "$rU", "A", "",
355
+            "https://kamailio.org/stir/$rd/cert.pem", "/secsipid/$rd/key.pem")) {
356
+        xinfo("Identity value: $secsipid(val)\n");
357
+    }
358
+    ...
359
+}
360
+...
325 361
 </programlisting>
326 362
 		</example>
327 363
 	</section>
Browse code

secsipid: explicit STIR/SHAKEN reference

- help matching on search terms

Daniel-Constantin Mierla authored on 14/06/2021 14:56:21
Showing 1 changed files
... ...
@@ -19,7 +19,7 @@
19 19
 		The module implements secure SIP identity specifications - STIR
20 20
 		(Secure Telephony Identity Revisited) and SHAKEN
21 21
 		(Signature-based Handling of Asserted information using toKENs)
22
-		IETF extensions for SIP (RFC8224, RFC8588).
22
+		IETF extensions for SIP (RFC8224, RFC8588), known together as STIR/SHAKEN.
23 23
 	</para>
24 24
 	<para>
25 25
 		It exports the functions to check and generate SIP Identity header.
Browse code

secsipid: note about libsecsipid location and failure return codes

Daniel-Constantin Mierla authored on 01/06/2021 07:50:31
Showing 1 changed files
... ...
@@ -30,6 +30,17 @@
30 30
 		loads "secsipid_proc.so" in child init callback in order to initialize
31 31
 		the "libsecsipid" per child process.
32 32
 	</para>
33
+	<para>
34
+		The libsecsipid is provided by secsipidx project:
35
+		<ulink url="https://github.com/asipto/secsipidx">https://github.com/asipto/secsipidx</ulink>.
36
+	</para>
37
+	<para>
38
+		In case of failure, the functions in this module return error codes
39
+		(the negative values) listed in the code of libsecsipid, pretty much
40
+		at the top of:
41
+		<ulink url="https://github.com/asipto/secsipidx/blob/main/secsipid/secsipid.go"
42
+			>https://github.com/asipto/secsipidx/blob/main/secsipid/secsipid.go</ulink>.
43
+	</para>
33 44
 	</section>
34 45
 	<section>
35 46
 	<title>Dependencies</title>
Browse code

secsipid: docs - set GO111MODULE=off in installation example

Daniel-Constantin Mierla authored on 12/05/2021 06:32:37
Showing 1 changed files
... ...
@@ -318,7 +318,7 @@ request_route {
318 318
 	<section id="secsipid.s.installation">
319 319
 	<title>Installation</title>
320 320
 	<para>
321
-		The module needs "secsipdi_proc.so" module thatdepends on "libsecsipid",
321
+		The module needs "secsipdi_proc.so" module that depends on "libsecsipid",
322 322
 		which is a component of "sipsecidx" project from
323 323
 		https://github.com/asipto/secsipidx/. The library is
324 324
 		implemented in Go language, with generated C API and library. Until the
... ...
@@ -334,6 +334,7 @@ request_route {
334 334
 		<title>Libsecsipid Usage</title>
335 335
 		<programlisting format="linespecific">
336 336
 ...
337
+export GO111MODULE=off
337 338
 go get https://github.com/asipto/secsipidx
338 339
 cd $GOPATH/src/github.com/asipto/secsipidx/csecsipid/
339 340
 make liba
... ...
@@ -351,6 +352,10 @@ make install
351 352
 ...
352 353
 </programlisting>
353 354
 		</example>
355
+	<para>
356
+		For more details about compilation and installation of libsecsipid, see:
357
+		<ulink url="https://github.com/asipto/secsipidx">https://github.com/asipto/secsipidx</ulink>.
358
+	</para>
354 359
 	</section>
355 360
 
356 361
 </chapter>
Browse code

secsipid: docs - updates to installation section with secsipid_proc

Daniel-Constantin Mierla authored on 12/04/2021 16:39:25
Showing 1 changed files
... ...
@@ -318,10 +318,11 @@ request_route {
318 318
 	<section id="secsipid.s.installation">
319 319
 	<title>Installation</title>
320 320
 	<para>
321
-		The module depends on "libsecsipid", which is a component of "sipsecidx"
322
-		project from https://github.com/asipto/secsipidx/. The library is
321
+		The module needs "secsipdi_proc.so" module thatdepends on "libsecsipid",
322
+		which is a component of "sipsecidx" project from
323
+		https://github.com/asipto/secsipidx/. The library is
323 324
 		implemented in Go language, with generated C API and library. Until the
324
-		libsecsipid is going to be packaged in OS distributions, the secsipid
325
+		libsecsipid is going to be packaged in OS distributions, the secsipid_proc
325 326
 		module can be compiled by copying secsipid.h libsecsipid.h and libsecsipid.a
326 327
 		files in the folder of the module.
327 328
 	</para>
... ...
@@ -330,16 +331,23 @@ request_route {
330 331
 		installed and its environment configured, then run the following commands:
331 332
 	</para>
332 333
 		<example>
333
-		<title>Libsecsipid usage</title>
334
+		<title>Libsecsipid Usage</title>
334 335
 		<programlisting format="linespecific">
335 336
 ...
336 337
 go get https://github.com/asipto/secsipidx
337 338
 cd $GOPATH/src/github.com/asipto/secsipidx/csecsipid/
338 339
 make liba
339 340
 cp secsipid.h libsecsipid.h libsecsipid.a \
340
-    /path/to/kamailio/src/modules/secsipid/
341
+    /path/to/kamailio/src/modules/secsipid_proc/
342
+
341 343
 cd /path/to/kamailio/
342
-make modules modules=src/modules/secsipid/
344
+make include_modules="secsipid secsipid_proc ..." cfg
345
+make all
346
+make install
347
+
348
+## or compiling individual modules for use inside source tree
349
+# make modules modules=src/modules/secsipid_proc
350
+# make modules modules=src/modules/secsipid
343 351
 ...
344 352
 </programlisting>
345 353
 		</example>
Browse code

secsipid: docs for libopt

Daniel-Constantin Mierla authored on 12/04/2021 05:56:54
Showing 1 changed files
... ...
@@ -162,6 +162,27 @@ modparam("secsipid", "modproc", "secsipid_proc2.so")
162 162
 </programlisting>
163 163
 		</example>
164 164
 	</section>
165
+	<section id="secsipid.p.libopt">
166
+		<title><varname>libopt</varname> (str)</title>
167
+		<para>
168
+			Set a libsecsipid option. The value has to be name=value. The
169
+			parameter can be set many times.
170
+		</para>
171
+		<para>
172
+		<emphasis>
173
+			Default value is "" (not set).
174
+		</emphasis>
175
+		</para>
176
+		<example>
177
+		<title>Set <varname>libopt</varname> parameter</title>
178
+		<programlisting format="linespecific">
179
+...
180
+modparam("secsipid", "libopt", "CacheExpires=0")
181
+...
182
+</programlisting>
183
+		</example>
184
+	</section>
185
+
165 186
 	</section>
166 187
 
167 188
 	<section>
Browse code

secsipid: redesign to use per-process API functions

- needed to initialize the multi-threaded libsecsipid library per child
process
- per-process API functions to be offered by secsipid_proc module

Daniel-Constantin Mierla authored on 15/02/2021 07:34:05
Showing 1 changed files
... ...
@@ -24,17 +24,23 @@
24 24
 	<para>
25 25
 		It exports the functions to check and generate SIP Identity header.
26 26
 	</para>
27
+	<para>
28
+		Note that this module needs "secsipid_proc.so" module to be installed,
29
+		but without loading the "secsipid_proc.so" via "loadmodule". This module
30
+		loads "secsipid_proc.so" in child init callback in order to initialize
31
+		the "libsecsipid" per child process.
32
+	</para>
27 33
 	</section>
28 34
 	<section>
29 35
 	<title>Dependencies</title>
30 36
 	<section>
31 37
 		<title>&kamailio; Modules</title>
32 38
 		<para>
33
-		The following modules must be loaded before this module:
39
+		The following modules must be installed (but not loaded) to use this module:
34 40
 			<itemizedlist>
35 41
 			<listitem>
36 42
 			<para>
37
-				<emphasis>No dependencies on other &kamailio; modules</emphasis>.
43
+				<emphasis>secsipid_proc</emphasis>.
38 44
 			</para>
39 45
 			</listitem>
40 46
 			</itemizedlist>
... ...
@@ -48,7 +54,7 @@
48 54
 			<itemizedlist>
49 55
 			<listitem>
50 56
 			<para>
51
-				<emphasis>libsecsipid</emphasis> - https://github.com/asipto/secsipidx/.
57
+				<emphasis>none</emphasis>.
52 58
 			</para>
53 59
 			</listitem>
54 60
 			</itemizedlist>
... ...
@@ -137,7 +143,25 @@ modparam("secsipid", "cache_expire", 7200)
137 143
 </programlisting>
138 144
 		</example>
139 145
 	</section>
140
-
146
+	<section id="secsipid.p.modproc">
147
+		<title><varname>modproc</varname> (str)</title>
148
+		<para>
149
+		The name of or the path to the required per-process API module.
150
+		</para>
151
+		<para>
152
+		<emphasis>
153
+			Default value is "secsipid_proc.so".
154
+		</emphasis>
155
+		</para>
156
+		<example>
157
+		<title>Set <varname>modproc</varname> parameter</title>
158
+		<programlisting format="linespecific">
159
+...
160
+modparam("secsipid", "modproc", "secsipid_proc2.so")
161
+...
162
+</programlisting>
163
+		</example>
164
+	</section>
141 165
 	</section>
142 166
 
143 167
 	<section>
Browse code

secsipid: docs - details of the acronyms

Daniel-Constantin Mierla authored on 24/12/2020 09:09:02
Showing 1 changed files
... ...
@@ -16,11 +16,13 @@
16 16
 	<section>
17 17
 	<title>Overview</title>
18 18
 	<para>
19
-		The module implements secure SIP identity specifications - STIR and SHAKEN
20
-		IETF extensions for SIP (RFC8224, RFC 8588).
19
+		The module implements secure SIP identity specifications - STIR
20
+		(Secure Telephony Identity Revisited) and SHAKEN
21
+		(Signature-based Handling of Asserted information using toKENs)
22
+		IETF extensions for SIP (RFC8224, RFC8588).
21 23
 	</para>
22 24
 	<para>
23
-		It exports the functions to check and generate Identity header.
25
+		It exports the functions to check and generate SIP Identity header.
24 26
 	</para>
25 27
 	</section>
26 28
 	<section>
... ...
@@ -260,7 +262,7 @@ request_route {
260 262
 request_route {
261 263
     ...
262 264
     secsipid_add_identity("$fU", "$rU", "A", "",
263
-        "http://kamailio.org/stir/$rd/cert.pem", "/secsipid/$rd/key.pem");
265
+        "https://kamailio.org/stir/$rd/cert.pem", "/secsipid/$rd/key.pem");
264 266
     ...
265 267
 }
266 268
 ...
Browse code

secsipid: docs for secsipid_get_url()

Daniel-Constantin Mierla authored on 17/11/2020 10:44:44
Showing 1 changed files
... ...
@@ -207,11 +207,33 @@ request_route {
207 207
 ...
208 208
 </programlisting>
209 209
 		</example>
210
+	</section>
211
+	<section id="secsipid.f.secsipid_get_url">
212
+		<title>
213
+		<function moreinfo="none">secsipid_get_url(url, ovar)</function>
214
+		</title>
210 215
 		<para>
211
-			Further checks can be done with config operations, decoding the JWT header
212
-			and payload using {s.select} and {s.decode.base64t} transformations
213
-			together with jansson module.
216
+			Get the content of a URL and store the result in a variable.
217
+		</para>
218
+		<para>
219
+		The url parameters can contain pseudo-variables and ovar has to be
220
+		the name of a writtable pseudo-variable.
221
+		</para>
222
+		<para>
223
+		This function can be used from ANY_ROUTE.
214 224
 		</para>
225
+		<example>
226
+		<title><function>secsipid_get_url</function> usage</title>
227
+		<programlisting format="linespecific">
228
+...
229
+request_route {
230
+  ...
231
+  if(secsipid_get_url("https://$fd/stirshaken/cert.pem", "$var(pubkey)")) { ... }
232
+  ...
233
+}
234
+...
235
+</programlisting>
236
+		</example>
215 237
 	</section>
216 238
 	<section id="secsipid.f.secsipid_add_identity">
217 239
 		<title>
Browse code

secsipid: docs for secsipid_check_identity_pubkey()

Daniel-Constantin Mierla authored on 17/11/2020 09:16:55
Showing 1 changed files
... ...
@@ -171,6 +171,40 @@ request_route {
171 171
     ...
172 172
 }
173 173
 ...
174
+</programlisting>
175
+		</example>
176
+		<para>
177
+			Further checks can be done with config operations, decoding the JWT header
178
+			and payload using {s.select} and {s.decode.base64t} transformations
179
+			together with jansson module.
180
+		</para>
181
+	</section>
182
+	<section id="secsipid.f.secsipid_check_identity_pubkey">
183
+		<title>
184
+		<function moreinfo="none">secsipid_check_identity(pubkeyVal)</function>
185
+		</title>
186
+		<para>
187
+			Similar to secsipid_check_identity() with the public key value
188
+			provided in the parameter.
189
+		</para>
190
+		<para>
191
+		The parameters can contain pseudo-variables.
192
+		</para>
193
+		<para>
194
+		This function can be used from ANY_ROUTE.
195
+		</para>
196
+		<example>
197
+		<title><function>secsipid_check_identity_pubkey</function> usage</title>
198
+		<programlisting format="linespecific">
199
+...
200
+request_route {
201
+  ...
202
+  http_client_query("https://provider.com/stir-shaken/cert.pem", "$var(pubkey)");
203
+  ...
204
+  if(secsipid_check_identity_pubkey("$var(pubkey)")) { ... }
205
+  ...
206
+}
207
+...
174 208
 </programlisting>
175 209
 		</example>
176 210
 		<para>
Browse code

sipsecid: docs - fix sections id prefix

Daniel-Constantin Mierla authored on 12/11/2020 16:38:08
Showing 1 changed files
... ...
@@ -140,7 +140,7 @@ modparam("secsipid", "cache_expire", 7200)
140 140
 
141 141
 	<section>
142 142
 	<title>Functions</title>
143
-	<section id="async.f.secsipid_check_identity">
143
+	<section id="secsipid.f.secsipid_check_identity">
144 144
 		<title>
145 145
 		<function moreinfo="none">secsipid_check_identity(keyPath)</function>
146 146
 		</title>
... ...
@@ -179,7 +179,7 @@ request_route {
179 179
 			together with jansson module.
180 180
 		</para>
181 181
 	</section>
182
-	<section id="async.f.secsipid_add_identity">
182
+	<section id="secsipid.f.secsipid_add_identity">
183 183
 		<title>
184 184
 		<function moreinfo="none">secsipid_add_identity(origTN, destTN, attest, origID, x5u, keyPath)</function>
185 185
 		</title>
... ...
@@ -212,7 +212,7 @@ request_route {
212 212
 		</example>
213 213
 	</section>
214 214
 	</section>
215
-	<section>
215
+	<section id="secsipid.s.installation">
216 216
 	<title>Installation</title>
217 217
 	<para>
218 218
 		The module depends on "libsecsipid", which is a component of "sipsecidx"
Browse code

secsipid: docs for cache parameters

Daniel-Constantin Mierla authored on 12/11/2020 13:39:05
Showing 1 changed files
... ...
@@ -92,6 +92,46 @@ modparam("secsipid", "expire", 600)
92 92
 ...
93 93
 modparam("secsipid", "timeout", 2)
94 94
 ...
95
+</programlisting>
96
+		</example>
97
+	</section>
98
+	<section>
99
+		<title><varname>cache_dir</varname> (str)</title>
100
+		<para>
101
+		The path to the directory where to save cached pyblic keys. If set,
102
+		it activates the public key file caching in the libsecsipid library.
103
+		</para>
104
+		<para>
105
+		<emphasis>
106
+			Default value is "".
107
+		</emphasis>
108
+		</para>
109
+		<example>
110
+		<title>Set <varname>cache_dir</varname> parameter</title>
111
+		<programlisting format="linespecific">
112
+...
113
+modparam("secsipid", "cache_dir", "/tmp/kamailio/secsipid")
114
+...
115
+</programlisting>
116
+		</example>
117
+	</section>
118
+	<section>
119
+		<title><varname>cache_expire</varname> (int)</title>
120
+		<para>
121
+		The interval in seconds after which a cached public key is considered
122
+		expired. This value is passed to the libsecsipid library.
123
+		</para>
124
+		<para>
125
+		<emphasis>
126
+			Default value is 3600.
127
+		</emphasis>
128
+		</para>
129
+		<example>
130
+		<title>Set <varname>cache_expire</varname> parameter</title>
131
+		<programlisting format="linespecific">
132
+...
133
+modparam("secsipid", "cache_expire", 7200)
134
+...
95 135
 </programlisting>
96 136
 		</example>
97 137
 	</section>
Browse code

secsipid: docs - small typo

Daniel-Constantin Mierla authored on 16/10/2020 06:49:12
Showing 1 changed files
... ...
@@ -110,7 +110,7 @@ modparam("secsipid", "timeout", 2)
110 110
 			the function is downloading the key using the URL from "info"
111 111
 			parameter of the Identity header, using the value od "timeout"
112 112
 			parameter to limit the download time. The validity of the JWT
113
-			body in the Identity header is also checjed against the "expire"
113
+			body in the Identity header is also checked against the "expire"
114 114
 			parameter.
115 115
 		</para>
116 116
 		<para>
Browse code

secsipid: docs - removed extra parentheses in example

Daniel-Constantin Mierla authored on 13/04/2020 15:33:10
Showing 1 changed files
... ...
@@ -164,7 +164,7 @@ request_route {
164 164
 request_route {
165 165
     ...
166 166
     secsipid_add_identity("$fU", "$rU", "A", "",
167
-        "http://kamailio.org/stir/$rd/cert.pem", "/secsipid/$rd/key.pem"));
167
+        "http://kamailio.org/stir/$rd/cert.pem", "/secsipid/$rd/key.pem");
168 168
     ...
169 169
 }
170 170
 ...
Browse code

secsipid: reformatted long lines in examples to fit properly in README

Daniel-Constantin Mierla authored on 13/04/2020 15:29:33
Showing 1 changed files
... ...
@@ -163,7 +163,8 @@ request_route {
163 163
 ...
164 164
 request_route {
165 165
     ...
166
-    secsipid_add_identity("$fU", "$rU", "A", "", "http://kamailio.org/stir/$rd/cert.pem", "/secsipid/$rd/key.pem"));
166
+    secsipid_add_identity("$fU", "$rU", "A", "",
167
+        "http://kamailio.org/stir/$rd/cert.pem", "/secsipid/$rd/key.pem"));
167 168
     ...
168 169
 }
169 170
 ...
... ...
@@ -192,7 +193,8 @@ request_route {
192 193
 go get https://github.com/asipto/secsipidx
193 194
 cd $GOPATH/src/github.com/asipto/secsipidx/csecsipid/
194 195
 make liba
195
-cp secsipid.h libsecsipid.h libsecsipid.a /path/to/kamailio/src/modules/secsipid/
196
+cp secsipid.h libsecsipid.h libsecsipid.a \
197
+    /path/to/kamailio/src/modules/secsipid/
196 198
 cd /path/to/kamailio/
197 199
 make modules modules=src/modules/secsipid/
198 200
 ...
Browse code

secsipid: docs - fixed example for timeout parameter

Daniel-Constantin Mierla authored on 06/03/2020 06:17:21
Showing 1 changed files
... ...
@@ -87,10 +87,10 @@ modparam("secsipid", "expire", 600)
87 87
 		</emphasis>
88 88
 		</para>
89 89
 		<example>
90
-		<title>Set <varname>expire</varname> parameter</title>
90
+		<title>Set <varname>timeout</varname> parameter</title>
91 91
 		<programlisting format="linespecific">
92 92
 ...
93
-modparam("secsipid", "expire", 600)
93
+modparam("secsipid", "timeout", 2)
94 94
 ...
95 95
 </programlisting>
96 96
 		</example>
Browse code

secsipid: docs - added title to installation example

Daniel-Constantin Mierla authored on 27/01/2020 16:05:29
Showing 1 changed files
... ...
@@ -186,6 +186,7 @@ request_route {
186 186
 		installed and its environment configured, then run the following commands:
187 187
 	</para>
188 188
 		<example>
189
+		<title>Libsecsipid usage</title>
189 190
 		<programlisting format="linespecific">
190 191
 ...
191 192
 go get https://github.com/asipto/secsipidx
Browse code

secsipid: new module implementing STIR and SKAKEN IETF extensions

- for more see RFC 8224 and RFC 8588

Daniel-Constantin Mierla authored on 27/01/2020 10:25:09
Showing 1 changed files
1 1
new file mode 100644
... ...
@@ -0,0 +1,203 @@
1
+<?xml version="1.0" encoding='ISO-8859-1'?>
2
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
4
+
5
+<!-- Include general documentation entities -->
6
+<!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
7
+%docentities;
8
+
9
+]>
10
+<!-- Module User's Guide -->
11
+
12
+<chapter>
13
+
14
+	<title>&adminguide;</title>
15
+
16
+	<section>
17
+	<title>Overview</title>
18
+	<para>
19
+		The module implements secure SIP identity specifications - STIR and SHAKEN
20
+		IETF extensions for SIP (RFC8224, RFC 8588).
21
+	</para>
22
+	<para>
23
+		It exports the functions to check and generate Identity header.
24
+	</para>
25
+	</section>
26
+	<section>
27
+	<title>Dependencies</title>
28
+	<section>
29
+		<title>&kamailio; Modules</title>
30
+		<para>
31
+		The following modules must be loaded before this module:
32
+			<itemizedlist>
33
+			<listitem>
34
+			<para>
35
+				<emphasis>No dependencies on other &kamailio; modules</emphasis>.
36
+			</para>
37
+			</listitem>
38
+			</itemizedlist>
39
+		</para>
40
+	</section>
41
+	<section>
42
+		<title>External Libraries or Applications</title>
43
+		<para>
44
+		The following libraries or applications must be installed before running
45
+		&kamailio; with this module loaded:
46
+			<itemizedlist>
47
+			<listitem>
48
+			<para>
49
+				<emphasis>libsecsipid</emphasis> - https://github.com/asipto/secsipidx/.
50
+			</para>
51
+			</listitem>
52
+			</itemizedlist>
53
+		</para>
54
+	</section>
55
+	</section>
56
+	<section>
57
+	<title>Parameters</title>
58
+	<section>
59
+		<title><varname>expire</varname> (int)</title>
60
+		<para>
61
+		The interval in seconds after which the Identity header JWT is considered
62
+		to be expired.
63
+		</para>
64
+		<para>
65
+		<emphasis>
66
+			Default value is 300.
67
+		</emphasis>
68
+		</para>
69
+		<example>
70
+		<title>Set <varname>expire</varname> parameter</title>
71
+		<programlisting format="linespecific">
72
+...
73
+modparam("secsipid", "expire", 600)
74
+...
75
+</programlisting>
76
+		</example>
77
+	</section>
78
+	<section>
79
+		<title><varname>timeout</varname> (int)</title>
80
+		<para>
81
+		The interval in seconds after which the HTTP GET operation to download
82
+		the public key times out.
83
+		</para>
84
+		<para>
85
+		<emphasis>
86
+			Default value is 5.
87
+		</emphasis>
88
+		</para>
89
+		<example>
90
+		<title>Set <varname>expire</varname> parameter</title>
91
+		<programlisting format="linespecific">
92
+...
93
+modparam("secsipid", "expire", 600)
94
+...
95
+</programlisting>
96
+		</example>
97
+	</section>
98
+
99
+	</section>
100
+
101
+	<section>
102
+	<title>Functions</title>
103
+	<section id="async.f.secsipid_check_identity">
104
+		<title>
105
+		<function moreinfo="none">secsipid_check_identity(keyPath)</function>
106
+		</title>
107
+		<para>
108
+			Check the validity of the Identity header using the keys stored
109
+			in the file specified by "keyPath". If the parameter is empty,
110
+			the function is downloading the key using the URL from "info"
111
+			parameter of the Identity header, using the value od "timeout"
112
+			parameter to limit the download time. The validity of the JWT
113
+			body in the Identity header is also checjed against the "expire"
114
+			parameter.
115
+		</para>
116
+		<para>
117
+		The parameters can contain pseudo-variables.
118
+		</para>
119
+		<para>
120
+		This function can be used from ANY_ROUTE.
121
+		</para>
122
+		<example>
123
+		<title><function>secsipid_check_identity</function> usage</title>
124
+		<programlisting format="linespecific">
125
+...
126
+request_route {
127
+    ...
128
+	if(secsipid_check_identity("/secsipid/$si/cert.pem")) { ... }
129
+    ...
130
+	if(secsipid_check_identity("")) { ... }
131
+    ...
132
+}
133
+...
134
+</programlisting>
135
+		</example>
136
+		<para>
137
+			Further checks can be done with config operations, decoding the JWT header
138
+			and payload using {s.select} and {s.decode.base64t} transformations
139
+			together with jansson module.
140
+		</para>
141
+	</section>
142
+	<section id="async.f.secsipid_add_identity">
143
+		<title>
144
+		<function moreinfo="none">secsipid_add_identity(origTN, destTN, attest, origID, x5u, keyPath)</function>
145
+		</title>
146
+		<para>
147
+			Add Identity header using the key specified by "keyPath" to sign the JWT body.
148
+			If origID is empty, a UUID string is generated to fill the field. The origTN
149
+			represents the origination telephone number; destTN represents the destination
150
+			telephone number; x5u is the HTTP URL referencing to the public key that
151
+			should be used to verify the signature; attest represents the attestation
152
+			level (should be "A", "B" or "C").
153
+		</para>
154
+		<para>
155
+		The parameters can contain pseudo-variables.
156
+		</para>
157
+		<para>
158
+		This function can be used from ANY_ROUTE.
159
+		</para>
160
+		<example>
161
+		<title><function>secsipid_add_identity</function> usage</title>
162
+		<programlisting format="linespecific">
163
+...
164
+request_route {
165
+    ...
166
+    secsipid_add_identity("$fU", "$rU", "A", "", "http://kamailio.org/stir/$rd/cert.pem", "/secsipid/$rd/key.pem"));
167
+    ...
168
+}
169
+...
170
+</programlisting>
171
+		</example>
172
+	</section>
173
+	</section>
174
+	<section>
175
+	<title>Installation</title>
176
+	<para>
177
+		The module depends on "libsecsipid", which is a component of "sipsecidx"
178
+		project from https://github.com/asipto/secsipidx/. The library is
179
+		implemented in Go language, with generated C API and library. Until the
180
+		libsecsipid is going to be packaged in OS distributions, the secsipid
181
+		module can be compiled by copying secsipid.h libsecsipid.h and libsecsipid.a
182
+		files in the folder of the module.
183
+	</para>
184
+	<para>
185
+		To generate the libsecsipid.a file, it requires to have Go language
186
+		installed and its environment configured, then run the following commands:
187
+	</para>
188
+		<example>
189
+		<programlisting format="linespecific">
190
+...
191
+go get https://github.com/asipto/secsipidx
192
+cd $GOPATH/src/github.com/asipto/secsipidx/csecsipid/
193
+make liba
194
+cp secsipid.h libsecsipid.h libsecsipid.a /path/to/kamailio/src/modules/secsipid/
195
+cd /path/to/kamailio/
196
+make modules modules=src/modules/secsipid/
197
+...
198
+</programlisting>
199
+		</example>
200
+	</section>
201
+
202
+</chapter>
203
+