secsipid: docs - small typo
[kamailio] / src / modules / secsipid / doc / secsipid_admin.xml
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>timeout</varname> parameter</title>
91                 <programlisting format="linespecific">
92 ...
93 modparam("secsipid", "timeout", 2)
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 checked 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", "",
167         "http://kamailio.org/stir/$rd/cert.pem", "/secsipid/$rd/key.pem");
168     ...
169 }
170 ...
171 </programlisting>
172                 </example>
173         </section>
174         </section>
175         <section>
176         <title>Installation</title>
177         <para>
178                 The module depends on "libsecsipid", which is a component of "sipsecidx"
179                 project from https://github.com/asipto/secsipidx/. The library is
180                 implemented in Go language, with generated C API and library. Until the
181                 libsecsipid is going to be packaged in OS distributions, the secsipid
182                 module can be compiled by copying secsipid.h libsecsipid.h and libsecsipid.a
183                 files in the folder of the module.
184         </para>
185         <para>
186                 To generate the libsecsipid.a file, it requires to have Go language
187                 installed and its environment configured, then run the following commands:
188         </para>
189                 <example>
190                 <title>Libsecsipid usage</title>
191                 <programlisting format="linespecific">
192 ...
193 go get https://github.com/asipto/secsipidx
194 cd $GOPATH/src/github.com/asipto/secsipidx/csecsipid/
195 make liba
196 cp secsipid.h libsecsipid.h libsecsipid.a \
197     /path/to/kamailio/src/modules/secsipid/
198 cd /path/to/kamailio/
199 make modules modules=src/modules/secsipid/
200 ...
201 </programlisting>
202                 </example>
203         </section>
204
205 </chapter>
206