Browse code

auth_identity: removed auth_identity.xml from source folder

- there is one in doc/ subfolder

(cherry picked from commit 9155a53bccd090e51b274802d140f363aca6d4b7)

Daniel-Constantin Mierla authored on 24/05/2022 10:19:38
Showing 1 changed files
1 1
deleted file mode 100644
... ...
@@ -1,629 +0,0 @@
1
-<?xml version='1.0'?>
2
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3
-  "http://www.oasis-open.org/docbookid/id/g/4.5/docbookx.dtd">
4
-
5
-
6
-<refentry xml:id="module.auth_identity"
7
-          xmlns:xi="http://www.w3.org/2001/XInclude"
8
-          xmlns:serdoc="http://sip-router.org/xml/serdoc">
9
-  <refmeta>
10
-    <refentrytitle>auth_identity</refentrytitle>
11
-    <manvolnum>7</manvolnum>
12
-  </refmeta>
13
-  <refnamediv>
14
-    <refname>auth_identity</refname>
15
-    <refpurpose>Securely identify originator of SIP messages.</refpurpose>
16
-  </refnamediv>
17
-
18
-  <refsect1>
19
-    <title>Description</title>
20
-    <para>
21
-      The <command>auth_identity</command> SER module provides
22
-      functionalities for securely identifying originators of SIP
23
-      messages by implementing the mechanism described in RFC 4474
24
-      and known as SIP Identity framework.
25
-    </para>
26
-    <para>
27
-      The module provides two services:
28
-      The <emphasis>authorizer</emphasis> authorizes a message and adds
29
-      Identity and Identity-Info headers to forwarded requests.
30
-      The <emphasis>verifier</emphasis> verifies the identity of a
31
-      received message.
32
-    </para>
33
-    <para>
34
-      In order to use the <command>auth_identity</command> module you
35
-      have to provide a certificate. More information can be found in
36
-      the section
37
-      <serdoc:link linkend="module.auth_identity.certificates">Certificates
38
-      </serdoc:link> below.
39
-    </para>
40
-  </refsect1>
41
-
42
-  <refsect1 xml:id="module.auth_identity.functions">
43
-    <title>Functions</title>
44
-
45
-    <refsect2 xml:id="function.auth_add_identity">
46
-      <title>
47
-        <function>auth_add_identity</function>
48
-        ()
49
-      </title>
50
-      <para>
51
-        Allowed in request processing only.
52
-      </para>
53
-      <para>
54
-        The <function>auth_add_identity()</function> function authorizes
55
-        a request by adding identity information to it.
56
-      </para>
57
-      <para>
58
-        It calculates a SHA1 hash over certain components of the message
59
-        and encrypts it using the private key given through the
60
-        <serdoc:modparam
61
-          module="auth_identity">privatekey_path</serdoc:modparam>
62
-        parameter. The resulting cyphertext is appended to the message
63
-        as the content of the Identity header field.
64
-      </para>
65
-      <para>
66
-        To allow the receiver to decypher the identity information, it adds
67
-        the URL where the receiver may find the certificate in the
68
-        Indentity-Info header field. This URL is set through the
69
-        <serdoc:modparam
70
-          module="auth_identity">certificate_url</serdoc:modparam>
71
-        parameter.
72
-      </para>
73
-      <para>
74
-        <emphasis>Note:</emphasis> After the function has been called,
75
-        the following header fields must not be modified:
76
-        From, To, Call-ID, CSeq, Date, Contact. Additionally, the
77
-        message body must remain unmodified, too.
78
-      </para>
79
-    </refsect2>
80
-
81
-    <refsect2 xml:id="function.auth_date_proc">
82
-      <title>
83
-        <function>auth_date_proc</function>
84
-        ()
85
-      </title>
86
-      <para>
87
-        Allowed in request processing only.
88
-      </para>
89
-      <para>
90
-        The <function>auth_date_proc()</function> checks the age of a
91
-        request to be authroized. If the time given in the Date header
92
-        field of the request differs by more than the amount of seconds
93
-        given by the
94
-        <serdoc:modparam module="auth_identity">msg_timeout</serdoc:modparam>
95
-        parameter, the function returns <literal>false</literal>. It also
96
-        returns <literal>false</literal> if the certificate used by the
97
-        authorizer has expired.
98
-      </para>
99
-    </refsect2>
100
-
101
-    <refsect2 xml:id="function.vrfy_check_callid">
102
-      <title>
103
-        <function>vrfy_check_callid</function>
104
-        ()
105
-      </title>
106
-      <para>
107
-        Allowed in request processing only.
108
-      </para>
109
-      <para>
110
-        The <function>vrfy_check_callid()</function> checks whether a
111
-        request for this call has been processed within the
112
-        time given by the
113
-        <serdoc:modparam
114
-          module="auth_identity">auth_validity_time</serdoc:modparam>
115
-        parameter.
116
-      </para>
117
-      <para>
118
-        The function generates a call identifier from the Call-ID and CSqe
119
-        header fields and the Tag parameter of the From header field and
120
-        compares it with the values stored in the Call-ID cache.
121
-      </para>
122
-      <para>
123
-        It returns <literal>false</literal> if the value is found and thus
124
-        the request is replayed or <literal>true</literal> otherwise.
125
-      </para>
126
-    </refsect2>
127
-
128
-    <refsect2 xml:id="function.vrfy_check_certificate">
129
-      <title>
130
-        <function>vrfy_check_certificate</function>
131
-        ()
132
-      </title>
133
-      <para>
134
-        Allowed in request processing only.
135
-      </para>
136
-      <para>
137
-        The <function>vrfy_check_certificate()</function> function
138
-        checks the downloaded certificate and returns <literal>true</literal>
139
-        if it is valid or <literal>false</literal> otherwise.
140
-      </para>
141
-      <para>
142
-        A certificate is considered valid if it has not yet expired and
143
-        if its subject is identical to the domain part of the URL.
144
-      </para>
145
-      <!-- XXX Er, which URL? -->
146
-      <para>
147
-        Before <function>vrfy_check_certificate()</function> can be called,
148
-        the function <function>vrfy_check_date()</function> must have been
149
-        called and returned <literal>true</literal>.
150
-      </para>
151
-    </refsect2>
152
-
153
-    <refsect2 xml:id="function.vrfy_check_date">
154
-      <title>
155
-        <function>vrfy_check_date</function>
156
-        ()
157
-      </title>
158
-      <para>
159
-        Allowed in request processing only.
160
-      </para>
161
-      <para>
162
-        The <function>vrfy_check_date()</function> function checks
163
-        the date of the request currently being processed. It returns
164
-        <literal>false</literal> if the time in the Date header field
165
-        of the request differs from the current system time by more than
166
-        the number of seconds given by the
167
-        <serdoc:modparam
168
-          module="auth_identity">auth_validity_time</serdoc:modparam>
169
-        parameter.
170
-      </para>
171
-    </refsect2>
172
-
173
-    <refsect2 xml:id="function.vrfy_check_msgvalidity">
174
-      <title>
175
-        <function>vrfy_check_msgvalidity</function>
176
-        ()
177
-      </title>
178
-      <para>
179
-        Allowed in request processing only.
180
-      </para>
181
-      <para>
182
-        The <function>vrfy_check_msgvalidity()</function> function
183
-        checks the integrity of the request currently being processed.
184
-      </para>
185
-      <para>
186
-        It does so by calculating a SHA1 hash over certain parts of the
187
-        message and comparing it with the hash value that results from
188
-        decrypting the content of the Identity header field using the
189
-        certificate previously retrieved using the
190
-        <function>vrfy_get_certificate()</function> function.
191
-      </para>
192
-      <para>
193
-        The function returns <literal>true</literal> if the two hashes
194
-        match.
195
-      </para>
196
-    </refsect2>
197
-
198
-    <refsect2 xml:id="function.vrfy_get_certificate">
199
-      <title>
200
-        <function>vrfy_get_certificate</function>
201
-        ()
202
-      </title>
203
-      <para>
204
-        Allowed in request processing only.
205
-      </para>
206
-      <para>
207
-        The <function>vrfy_get_certificate()</function> tries to get
208
-        the certificate from the URL given in the Identity-Info header
209
-        field of the currently processed request.
210
-      </para>
211
-      <para>
212
-        It returns <literal>true</literal> if the certifcate was
213
-        successfully loaded in a format that the module can process or
214
-        <literal>false</literal> otherwise.
215
-      </para>
216
-    </refsect2>
217
-
218
-  </refsect1>
219
-
220
-
221
-  <refsect1 xml:id="module.auth_identity.parameters">
222
-    <title>Module Parameters</title>
223
-
224
-    <refsect2 xml:id="module.auth_identity.accept_pem_certs">
225
-      <title><parameter>accept_pem_certs</parameter></title>
226
-      <serdoc:paraminfo>
227
-        <serdoc:paramtype>boolean</serdoc:paramtype>
228
-        <serdoc:paramdefault>no</serdoc:paramdefault>
229
-      </serdoc:paraminfo>
230
-      <para>
231
-        The <parameter>accept_pem_certs</parameter> parameter defines,
232
-        whether the verifier should process certificates in PEM format.
233
-      </para>
234
-    </refsect2>
235
-
236
-    <refsect2 xml:id="module.auth_identity.auth_validity_time">
237
-      <title><parameter>auth_validity_time</parameter></title>
238
-      <serdoc:paraminfo>
239
-        <serdoc:paramtype>integer</serdoc:paramtype>
240
-        <serdoc:paramdefault>3600</serdoc:paramdefault>
241
-      </serdoc:paraminfo>
242
-      <para>
243
-        The <parameter>auth_validity_time</parameter> parameter
244
-        sets the maximum age of a verified message.
245
-      </para>
246
-    </refsect2>
247
-
248
-    <refsect2 xml:id="module.auth_identity.cainfo_path">
249
-      <title><parameter>cainfo_path</parameter></title>
250
-      <serdoc:paraminfo>
251
-        <serdoc:paramtype>string</serdoc:paramtype>
252
-        <serdoc:paramdefault>""</serdoc:paramdefault>
253
-      </serdoc:paraminfo>
254
-      <para>
255
-        The <parameter>cainfo_path</parameter> paramter contains the
256
-        path and name of a file that contains trusted certificates.
257
-      </para>
258
-      <para>
259
-        The file should contain one or more certificates in PEM format
260
-        concatenated together. It is necessary if the verifier should
261
-        accept self-signed certifcates.
262
-      </para>
263
-    </refsect2>
264
-
265
-    <refsect2 xml:id="module.auth_identity.callid_cache_limit">
266
-      <title><parameter>callid_cache_limit</parameter></title>
267
-      <serdoc:paraminfo>
268
-        <serdoc:paramtype>integer</serdoc:paramtype>
269
-        <serdoc:paramdefault>262144</serdoc:paramdefault>
270
-      </serdoc:paraminfo>
271
-      <para>
272
-        The <parameter>callid_cache_limit</parameter> parameter
273
-        limits the number of entries in the Call-ID cache.
274
-      </para>
275
-      <para>
276
-        The Call-IDs of previously verified messages are stored in the
277
-        Call-ID cache for some time in order to recognize call
278
-        replay attacks. The cache uses shared memory. Each entry is
279
-        about 100 bytes in size.
280
-      </para>
281
-    </refsect2>
282
-
283
-    <refsect2 xml:id="module.auth_identity.certificate_cache_limit">
284
-      <title><parameter>certificate_cache_limit</parameter></title>
285
-      <serdoc:paraminfo>
286
-        <serdoc:paramtype>integer</serdoc:paramtype>
287
-        <serdoc:paramdefault>32768</serdoc:paramdefault>
288
-      </serdoc:paraminfo>
289
-      <para>
290
-        The <parameter>certificate_cache_limit</parameter> parameter
291
-        limits the number of entries stored in the certificate cache.
292
-      </para>
293
-      <para>
294
-        Each retrieved certificate is placed in the certificate cache
295
-        to speed up processing should it be needed again.
296
-      </para>
297
-      <para>
298
-        The cahce uses shared memory. Each entry is approximately 600
299
-        bytes in size.
300
-      </para>
301
-    </refsect2>
302
-
303
-    <refsect2 xml:id="module.auth_identity.certificate_path">
304
-      <title><parameter>certificate_path</parameter></title>
305
-      <serdoc:paraminfo>
306
-        <serdoc:paramtype>string</serdoc:paramtype>
307
-        <serdoc:paramdefault>""</serdoc:paramdefault>
308
-      </serdoc:paraminfo>
309
-      <para>
310
-        The <parameter>certificate_path</parameter> parameter must be
311
-        set to path and name of the file that contains the certificate
312
-        of the authentication service in PEM format.
313
-      </para>
314
-      <para>
315
-        The parameter is required for the authentication service to work.
316
-      </para>
317
-    </refsect2>
318
-
319
-    <refsect2 xml:id="module.auth_identity.certificate_url">
320
-      <title><parameter>certificate_url</parameter></title>
321
-      <serdoc:paraminfo>
322
-        <serdoc:paramtype>string</serdoc:paramtype>
323
-        <serdoc:paramdefault>""</serdoc:paramdefault>
324
-      </serdoc:paraminfo>
325
-      <para>
326
-        The <parameter>certificate_url</parameter> parameter must be
327
-        set to the URL where a verifier can retrieve the certificate.
328
-        The URL will be stored in the Identity-Info header of any
329
-        authorized request.
330
-      </para>
331
-      <para>
332
-        The certificate must be available at the given URL in DER
333
-        format.
334
-      </para>
335
-      <para>
336
-        The parameter is required for the authentication service to work.
337
-      </para>
338
-    </refsect2>
339
-
340
-    <refsect2 xml:id="module.auth_identity.msg_timeout">
341
-      <title><parameter>msg_timeout</parameter></title>
342
-      <serdoc:paraminfo>
343
-        <serdoc:paramtype>int</serdoc:paramtype>
344
-        <serdoc:paramdefault>600</serdoc:paramdefault>
345
-      </serdoc:paraminfo>
346
-      <para>
347
-        The <parameter>msg_timeout</parameter> parameter contains the
348
-        maximum age of a request to be authorized in seconds.
349
-      </para>
350
-      <para>
351
-        The authorizer will compare the time given in the Date header field
352
-        of the request with its own current time.
353
-      </para>
354
-    </refsect2>
355
-
356
-    <refsect2 xml:id="module.auth_identity.privatekey_path">
357
-      <title><parameter>privatekey_path</parameter></title>
358
-      <serdoc:paraminfo>
359
-        <serdoc:paramtype>string</serdoc:paramtype>
360
-        <serdoc:paramdefault>""</serdoc:paramdefault>
361
-      </serdoc:paraminfo>
362
-      <para>
363
-        The <parameter>privatekey_path</parameter> must be set to the paht
364
-        and name of the file that contains the private key of the
365
-        authentication service in PEM format.
366
-      </para>
367
-      <para>
368
-        The parameter is required for the authentication service to work.
369
-      </para>
370
-    </refsect2>
371
-
372
-  </refsect1>
373
-
374
-  <refsect1 id="modules.auth_identity.examples">
375
-    <title>Examples</title>
376
-    <para>
377
-      The <emphasis>authentifier</emphasis> is typically included in the
378
-      part of the routing
379
-      logic that sends a request to a foreign domain. In the
380
-      <filename>ser-oob.cfg</filename> configuration, this is the
381
-      <varname>route[OUTBOUND]</varname>. With an authentifier included,
382
-      it looks like this:
383
-    </para>
384
-    <programlisting><![CDATA[
385
-route[OUTBOUND]
386
-{
387
-	if ($f.did && !$t.did) {
388
-		# Authentication service
389
-		if (method=="INVITE" || method=="OPTION") {
390
-			# Identity and Identity-info headers must not exist
391
-			if (@identity) {
392
-				sl_reply("403", "Invalid Identity header");
393
-				drop;
394
-			}
395
-			if (@identity_info) {
396
-				sl_reply("403", "Invalid Identity-info header");
397
-				drop;
398
-			}
399
-
400
-			if (!auth_date_proc()) {
401
-				sl_reply("403", "Invalid Date value");
402
-				drop;
403
-			}
404
-
405
-			if (!auth_add_identity()) {
406
-				sl_reply("480", "Authentication error");
407
-				drop;
408
-			}
409
-		}
410
-		route(FORWARD);
411
-	}
412
-}
413
-]]></programlisting>
414
-    <para>
415
-      The <emphasis>verifier</emphasis> should be run after you discovered
416
-      that a request originates from a foreign domain (for your own domains,
417
-      you should be doing digest authentication instead).
418
-    </para>
419
-    <para>
420
-      While you should reject any request that does contain an Identity
421
-      header but does not verify, it is up to your local policy, what to
422
-      do with messages that do not contain an Identity header at all.
423
-      You could reject them or divert them to voice mail or any of a number
424
-      of other options.
425
-    </para>
426
-    <para>
427
-      The following config snippet rejects any message that does not have
428
-      an Identity header.
429
-    </para>
430
-    <programlisting><![CDATA[
431
-	if (method=="INVITE" || method=="OPTIONS") {
432
-		if (!@identity) {
433
-			sl_reply("428", "Use Identity Header");
434
-			drop;
435
-		}
436
-		if (!@identity_info) {
437
-			sl_reply("436", "Bad Identity-Info");
438
-			drop;
439
-		}
440
-
441
-		if (!vrfy_check_date()) {
442
-			sl_reply("403", "Outdated Date header value");
443
-			drop;
444
-		}
445
-
446
-		if (!vrfy_get_certificate()) {
447
-			sl_reply("436", "Bad Identity-Info");
448
-			drop;
449
-		}
450
-
451
-		if (!vrfy_check_certificate()) {
452
-			sl_reply("437", "Unsupported Certificate");
453
-			drop;
454
-		}
455
-
456
-		if (!vrfy_check_msgvalidity()) {
457
-			sl_reply("438", "Invalid Identity Header");
458
-			drop;
459
-		}
460
-
461
-		if (!vrfy_check_callid()) {
462
-			sl_reply("403", "Message is replayed");
463
-			drop;
464
-		}
465
-	}
466
-]]></programlisting>
467
-  </refsect1>
468
-
469
-  <refsect1 id="mdoule.auth_identity.how-it-works">
470
-    <title>The SIP Identity Mechanism</title>
471
-    <para>
472
-      The SIP Identity Mechanism is defined in RFC 4474 "Enhancements for
473
-      Authenticated Identity Management in the Session Initiation Protocol
474
-      (SIP)". Its main purpose is to affirm the identity of the originator
475
-      of a request as stated in the From header field of the request.
476
-      While basic SIP provides a mechanism for a user agent to proof its
477
-      authenticity to the proxy serving the domain of the address used
478
-      by the user agent, no such mechanism exists to proof the authenticity
479
-      to other proxies or end points. The SIP Identity Mechanism mends this
480
-      oversight.
481
-    </para>
482
-    <para>
483
-      The mechanism allows a proxy to cryptographically sign a message as
484
-      authentic before sending it to another proxy. It does so after
485
-      making sure the sender actually is who he claims and is allowed to
486
-      use the address in the context of the message.
487
-    </para>
488
-    <para>
489
-      If the proxy is satisfied, it creates two header fields: Identity and
490
-      Identity-Info. The Identity header field contains a signed hash over
491
-      the following components of the message:
492
-    </para>
493
-    <itemizedlist>
494
-      <listitem>
495
-        the address given in the From header field,
496
-      </listitem>
497
-      <listitem>
498
-        the address given in the To header field,
499
-      </listitem>
500
-      <listitem>
501
-        the Call-ID,
502
-      </listitem>
503
-      <listitem>
504
-        the content of the CSeq header field,
505
-      </listitem>
506
-      <listitem>
507
-        the content of the Date header field,
508
-      </listitem>
509
-      <listitem>
510
-        the address given in the Contact header field if present, and
511
-      </listitem>
512
-      <listitem>
513
-        the body of the message.
514
-      </listitem>
515
-    </itemizedlist>
516
-    <para>
517
-      The hash is signed with a certificate for the domain. A URL pointing
518
-      to a place where an interested party can download a copy of the
519
-      certificate is placed into the Identity-Info header field.
520
-    </para>
521
-    <para>
522
-      If the message arrives at a proxy or user agent that wishes to verify
523
-      the authenticity, this device downloads the certificate and itself
524
-      forms the hash over the above components. If both hashes match, the
525
-      message has been authenticated by the proxy of the domain of the
526
-      certificate and has not been tempered with on the way.
527
-    </para>
528
-  </refsect1>
529
-
530
-  <refsect1 id="modules.auth_identity.credentials">
531
-    <title>Certificates</title>
532
-    <para>
533
-      In order to use the <command>auth_identity</command> module, you need a
534
-      certificate for your domain. There is two options, how to get one: you
535
-      buy one from a certification authority or you create your own
536
-      certification authority and use a self-signed certificate.  If you plan
537
-      to provide real  inter-domain calls for your domain, you should pick the
538
-      first option. Although it is more expensive, it guarantees proper
539
-      interaction between domains.
540
-    </para>
541
-    <para>
542
-      Either way, you will end up with a private key and a certificate which
543
-      includes the public key for that private key. You can use the same key
544
-      and certificate as for the TLS encrypted SIP transport. Because of
545
-      this, details on the process of acquiring them can be found in 
546
-      <serdoc:module>tls</serdoc:module>.
547
-    </para>
548
-    <para>
549
-      Once you have the certificate and private key, you set the module
550
-      parameter
551
-      <serdoc:modparam module="auth_identity">certificate_path</serdoc:modparam>
552
-      to point to the file containing the certificate and
553
-      <serdoc:modparam module="auth_identity">privatekey_path</serdoc:modparam>
554
-      to point to the file with the private key.
555
-    </para>
556
-    <para>
557
-      Finally, you have to put a public version of your certificate onto
558
-      a web server somewhere. This version must be DER encoded and,
559
-      obviously, must not contain the private key. You can create this
560
-      by issuing
561
-    </para>
562
-    <programlisting><![CDATA[
563
-# openssl x509 -in your_certificate.crt -outform der -out your_certificate.der
564
-]]></programlisting>
565
-    <para>
566
-      You then place the DER encoded certificate into a publicly
567
-      available directory on your webserver and state the URL to the
568
-      file in the parameter
569
-      <serdoc:modparam module="auth_identity">certificate_url</serdoc:modparam>.
570
-    </para>
571
-  </refsect1>
572
-
573
-  <!--
574
-    Compilation sections only go into the Admin Guide since we assume
575
-    that if you read a manpage you already have installed the module.
576
-  --> 
577
-  <refsect1 role="admin-guide">
578
-    <title>Compilation</title>
579
-    <para>
580
-      This <command>auth_identity</command> module needs the following
581
-      headers and libraries:
582
-    </para>
583
-    <itemizedlist>
584
-      <listitem>
585
-        <emphasis>OpenSSL</emphasis> (version 0.9.8 or higher) for
586
-        cryptographic functions,
587
-      </listitem>
588
-      <listitem>
589
-        <emphasis>libcURL</emphasis> for HTTP, HTTPS functions.
590
-      </listitem>
591
-    </itemizedlist>
592
-    <para>
593
-      If you'd like to use the <emphasis>TLS</emphasis> module, too,
594
-      you will have to change <varname>LIB</varname> variable in the
595
-      Makefile to the value that is by default commented out.
596
-    </para>
597
-  </refsect1>
598
-
599
-  <refsect1>
600
-    <title>Known Limitations</title>
601
-    <para>
602
-      Both authorizer and verifier currently only support SIP requests
603
-      except for responses to CANCEL and REGISTER requests.
604
-    </para>
605
-    <para>
606
-      The verifier does not support the subjectAltName extension of
607
-      certificates.
608
-    </para>
609
-  </refsect1>
610
-
611
-  <refsect1 role="manpage">
612
-    <title>Authors</title>
613
-    <para>
614
-      Written by Gergely Kovacs and Martin Hoffmann.
615
-    </para>
616
-  </refsect1>
617
-
618
-  <refsect1 role="manpage">
619
-    <title>See Also</title>
620
-    <simplelist type="inline">
621
-      <member><serdoc:sbin>ser</serdoc:sbin></member>
622
-      <member><serdoc:file>ser.cfg</serdoc:file></member>
623
-    </simplelist>
624
-  </refsect1>
625
-
626
-</refentry>
627
-
628
-<!-- vim:sw=2 sta et sts=2 ai
629
-  -->