Browse code

TLS Documentation updates

Olle E. Johansson authored on 21/10/2012 16:30:32
Showing 6 changed files
... ...
@@ -56,10 +56,10 @@ Andrei Pelinescu-Onciul
56 56
 
57 57
 1.1. Overview
58 58
 
59
-   This module implements the TLS transport for SIP-router using the
60
-   OpenSSL library (http://www.openssl.org). To enable the TLS support
61
-   this module must be loaded and enable_tls=yes must be added to the
62
-   SIP-router config file
59
+   This module implements the TLS transport for Kamailio using the OpenSSL
60
+   library (http://www.openssl.org). To enable the TLS support this module
61
+   must be loaded and enable_tls=yes must be added to the SIP-router
62
+   config file
63 63
 
64 64
 1.2. Quick Start
65 65
 
... ...
@@ -291,32 +291,33 @@ te.
291 291
 2. sign it with the ca certificate
292 292
         openssl ca -in ser1_cert_req.pem -out ser1_cert.pem
293 293
 
294
-3. copy ser1_cert.pem to your ser config. dir
294
+3. copy ser1_cert.pem to your Kamailio config. dir
295 295
 
296 296
 
297
-Setting sip-router to use the certificate
297
+Setting Kamailio to use the certificate
298 298
 -----------------------------------------
299 299
 1. create the ca list file:
300 300
         for each of your ca certificates that you intend to use do:
301 301
                 cat cacert.pem >>calist.pem
302 302
 
303
-2. copy your sip-router certificate, private key and ca list file to your
303
+2. copy your Kamailio certificate, private key and ca list file to your
304 304
         intended machine (preferably in your sip-router configuration directory,
305
-         this is the default place sip-router searches for).
305
+         this is the default place Kamailio searches for).
306 306
 
307
-3. set up sip-router.cfg to use the certificate
308
-        if your ser certificate name is different from cert.pem or it is not
309
-        placed in sip-router cfg. directory, add to your sip-router.cfg:
307
+3. set up Kamailio.cfg to use the certificate
308
+        if your Kamailio certificate name is different from cert.pem or it is no
309
+t
310
+        placed in Kamailio cfg. directory, add to your kamailio.cfg:
310 311
                 modparam("tls", "certificate", "/path/cert_file_name")
311 312
 
312
-4. set up sip-router to use the private key
313
+4. set up Kamailio to use the private key
313 314
         if your private key is not contained in the same file as the certificate
314 315
         (or the certificate name is not the default cert.pem), add to your
315
-         sip-router.cfg:
316
+         Kamailio.cfg:
316 317
                 modparam("tls", "private_key", "/path/private_key_file")
317 318
 
318
-5. set up sip-router to use the ca list (optional)
319
-        add to your sip-router.cfg:
319
+5. set up Kamailio to use the ca list (optional)
320
+        add to your Kamailio.cfg:
320 321
                 modparam("tls", "ca_list", "/path/ca_list_file")
321 322
 
322 323
 6. set up tls authentication options:
... ...
@@ -333,9 +334,9 @@ Revoking a certificate and using a CRL
333 334
 2. generate/update the certificate revocation list:
334 335
         openssl ca -gencrl -out my_crl.pem
335 336
 
336
-3. copy my_crl.pem to your ser config. dir
337
+3. copy my_crl.pem to your Kamailio config. dir
337 338
 
338
-4. set up sip-router to use the CRL:
339
+4. set up Kamailio to use the CRL:
339 340
                 modparam("tls", "crl", "path/my_crl.pem")
340 341
 
341 342
 1.9. Parameters
... ...
@@ -372,7 +373,7 @@ modparam("tls", "tls_method", "TLSv1")
372 373
    working directory (at runtime). If it starts with a '/' it will be an
373 374
    absolute path and if it starts with anything else the path will be
374 375
    relative to the main config file directory (e.g.: for ser -f
375
-   /etc/ser/ser.cfg it will be relative to /etc/ser/).
376
+   /etc/kamailio/kamailio.cfg it will be relative to /etc/ser/).
376 377
 
377 378
    Warning: try not to use certificate with keys longer then 1024 bytes.
378 379
    Longer keys will severely impact performance, in particular the TLS
... ...
@@ -382,7 +383,7 @@ modparam("tls", "tls_method", "TLSv1")
382 383
 
383 384
    Example 4. Set certificate parameter
384 385
 ...
385
-modparam("tls", "certificate", "/usr/local/etc/ser/my_certificate.pem")
386
+modparam("tls", "certificate", "/usr/local/etc/kamailio/my_certificate.pem")
386 387
 ...
387 388
 
388 389
 1.9.3. private_key (string)
... ...
@@ -392,7 +393,7 @@ modparam("tls", "certificate", "/usr/local/etc/ser/my_certificate.pem")
392 393
    If the file name starts with a '.' the path will be relative to the
393 394
    working directory (at runtime). If it starts with a '/' it will be an
394 395
    absolute path and if it starts with anything else the path will be
395
-   relative to the main config file directory (e.g.: for ser -f
396
+   relative to the main config file directory (e.g.: for kamailio -f
396 397
    /etc/ser/ser.cfg it will be relative to /etc/ser/).
397 398
 
398 399
    Note: the private key can be contained in the same file as the
... ...
@@ -415,7 +416,7 @@ modparam("tls", "private", "/usr/local/etc/ser/my_pkey.pem")
415 416
    If the file name starts with a '.' the path will be relative to the
416 417
    working directory (at runtime). If it starts with a '/' it will be an
417 418
    absolute path and if it starts with anything else the path will be
418
-   relative to the main config file directory (e.g.: for ser -f
419
+   relative to the main config file directory (e.g.: for kamailio -f
419 420
    /etc/ser/ser.cfg it will be relative to /etc/ser/).
420 421
 
421 422
    By default the CA file is not set.
... ...
@@ -442,7 +443,7 @@ modparam("tls", "ca_list", "/usr/local/etc/ser/ca_list.pem")
442 443
    If the file name starts with a '.' the path will be relative to the
443 444
    working directory (at runtime). If it starts with a '/' it will be an
444 445
    absolute path and if it starts with anything else the path will be
445
-   relative to the main config file directory (e.g.: for ser -f
446
+   relative to the main config file directory (e.g.: for kamailio -f
446 447
    /etc/ser/ser.cfg it will be relative to /etc/ser/).
447 448
 
448 449
 Note
... ...
@@ -452,9 +453,9 @@ Note
452 453
 
453 454
    By default the crl file is not set.
454 455
 
455
-   To update the crl in a running ser, make sure you configure tls via a
456
-   separate tls config file (the config modparam) and issue a tls.reload
457
-   RPC call, e.g.:
456
+   To update the crl in a running Kamailio, make sure you configure tls
457
+   via a separate tls config file (the config modparam) and issue a
458
+   tls.reload RPC call, e.g.:
458 459
  $ sercmd tls.reload
459 460
 
460 461
    A quick way to create the CRL in PEM format, using openssl is:
... ...
@@ -539,13 +540,13 @@ modparam("tls", "cipher_list", "HIGH")
539 540
 1.9.10. send_timeout (int)
540 541
 
541 542
    This parameter is obsolete and cannot be used in newer TLS versions (>
542
-   sip-router 3.0). In these versions the send_timeout is replaced by
543
+   Kamailio 3.0). In these versions the send_timeout is replaced by
543 544
    tcp_send_timeout (common with all the tcp connections).
544 545
 
545 546
 1.9.11. handshake_timeout (int)
546 547
 
547 548
    This parameter is obsolete and cannot be used in newer TLS versions (>
548
-   sip-router 3.0). In these versions the handshake_timeout is replaced by
549
+   Kamailio 3.0). In these versions the handshake_timeout is replaced by
549 550
    tcp_connect_timeout (common with all the tcp connections).
550 551
 
551 552
 1.9.12. connection_timeout (int)
... ...
@@ -637,7 +638,7 @@ modparam("tls", "ssl_freelist_max_len", 0)
637 638
    succesfull handshake (try minimum 1024).
638 639
 
639 640
    Lower values would lead to less memory usage, but values lower then the
640
-   typical ser/sip-router write size would incur a slight performance
641
+   typical ser/Kamailio write size would incur a slight performance
641 642
    penalty. Good values are bigger then the size of the biggest SIP packet
642 643
    one normally expects to forward. For example in most setups 2048 would
643 644
    be a good value.
... ...
@@ -1027,9 +1028,9 @@ modparam("tls", "config", "/usr/local/etc/ser/tls.cfg")
1027 1028
    multiple domains, a tls specific config, config reloading and a tls
1028 1029
    specific select framework.
1029 1030
 
1030
-   For ser/sr 3.1 most of the TLS specific code was completely re-written
1031
-   to add support for asynchrounous TLS and fix several long standing
1032
-   bugs.
1031
+   For Kamailio 3.1 most of the TLS specific code was completely
1032
+   re-written to add support for asynchrounous TLS and fix several long
1033
+   standing bugs.
1033 1034
 
1034 1035
    The code is currently maintained by Andrei Pelinescu-Onciul
1035 1036
    <andrei@iptel.org>.
... ...
@@ -1,6 +1,12 @@
1
-<?xml version="1.0" encoding="UTF-8"?>
2
-<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
3
-   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
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 "../../../docbook/entities.xml">
7
+%docentities;
8
+
9
+]>
4 10
 
5 11
 <section id="tls.certs_howto" xmlns:xi="http://www.w3.org/2001/XInclude">
6 12
     <sectioninfo>
... ...
@@ -85,32 +91,32 @@ Creating a server/client certificate
85 91
 2. sign it with the ca certificate
86 92
 	openssl ca -in ser1_cert_req.pem -out ser1_cert.pem
87 93
 	
88
-3. copy ser1_cert.pem to your ser config. dir
94
+3. copy ser1_cert.pem to your &kamailio; config. dir
89 95
 
90 96
 
91
-Setting sip-router to use the certificate
97
+Setting &kamailio; to use the certificate
92 98
 -----------------------------------------
93 99
 1. create the ca list file:
94 100
 	for each of your ca certificates that you intend to use do:
95 101
 		cat cacert.pem >>calist.pem
96 102
 	
97
-2. copy your sip-router certificate, private key and ca list file to your 
103
+2. copy your &kamailio; certificate, private key and ca list file to your 
98 104
 	intended machine (preferably in your sip-router configuration directory,
99
-	 this is the default place sip-router searches for).
105
+	 this is the default place &kamailio; searches for).
100 106
 	
101
-3. set up sip-router.cfg to use the certificate
102
-	if your ser certificate name is different from cert.pem or it is not
103
-	placed in sip-router cfg. directory, add to your sip-router.cfg:
107
+3. set up &kamailio;.cfg to use the certificate
108
+	if your &kamailio; certificate name is different from cert.pem or it is not
109
+	placed in &kamailio; cfg. directory, add to your kamailio.cfg:
104 110
 		modparam("tls", "certificate", "/path/cert_file_name")
105 111
 	
106
-4. set up sip-router to use the private key
112
+4. set up &kamailio; to use the private key
107 113
 	if your private key is not contained in the same file as the certificate
108 114
 	(or the certificate name is not the default cert.pem), add to your
109
-	 sip-router.cfg:
115
+	 &kamailio;.cfg:
110 116
 		modparam("tls", "private_key", "/path/private_key_file")
111 117
 	
112
-5. set up sip-router to use the ca list (optional)
113
-	add to your sip-router.cfg:
118
+5. set up &kamailio; to use the ca list (optional)
119
+	add to your &kamailio;.cfg:
114 120
 		modparam("tls", "ca_list", "/path/ca_list_file")
115 121
 	
116 122
 6. set up tls authentication options:
... ...
@@ -127,9 +133,9 @@ Revoking a certificate and using a CRL
127 133
 2. generate/update the certificate revocation list:
128 134
 	openssl ca -gencrl -out my_crl.pem
129 135
 	
130
-3. copy my_crl.pem to your ser config. dir
136
+3. copy my_crl.pem to your &kamailio; config. dir
131 137
 	
132
-4. set up sip-router to use the CRL:
138
+4. set up &kamailio; to use the CRL:
133 139
 		modparam("tls", "crl", "path/my_crl.pem")
134 140
 
135 141
 
... ...
@@ -1,6 +1,12 @@
1
-<?xml version="1.0" encoding="UTF-8"?>
2
-<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3
-   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
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 "../../../docbook/entities.xml">
7
+%docentities;
8
+
9
+]>
4 10
 
5 11
 <section id="textops.functions">
6 12
 	<sectioninfo>
... ...
@@ -1,6 +1,12 @@
1
-<?xml version="1.0" encoding="UTF-8"?>
2
-<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
3
-   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
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 "../../../docbook/entities.xml">
7
+%docentities;
8
+
9
+]>
4 10
 
5 11
 <section id="tls.history">
6 12
     <sectioninfo>
... ...
@@ -11,7 +17,7 @@
11 17
 			This module was put together by Jan Janak <email>jan@iptel.org</email> from code  from the experimental tls core addon (<ulink url="http://cvs.berlios.de/cgi-bin/viewcvs.cgi/ser/experimental/tls/">http://cvs.berlios.de/cgi-bin/viewcvs.cgi/ser/experimental/tls/</ulink>), code originally written by Peter Griffiths and later maintained by Cesc Santasusana and from an iptelorg tls code addon, written by Andrei Pelinescu-Onciul <email>andrei@iptel.org</email>. Jan also added support for multiple domains, a tls specific config, config reloading and a tls specific select framework.
12 18
 		</para>
13 19
 		<para>
14
-			For ser/sr 3.1 most of the TLS specific code was completely
20
+			For &kamailio; 3.1 most of the TLS specific code was completely
15 21
 			re-written to add support for asynchrounous TLS and fix several
16 22
 			long standing bugs.
17 23
 		</para>
... ...
@@ -64,7 +64,7 @@ modparam("tls", "tls_method", "TLSv1")
64 64
 		working directory (<emphasis>at runtime</emphasis>). If it starts
65 65
 		with a '/' it will be an absolute path and if it starts with anything
66 66
 		else the path will be relative to the main config file directory
67
-		(e.g.: for ser -f /etc/ser/ser.cfg it will be relative to /etc/ser/).
67
+		(e.g.: for ser -f /etc/kamailio/kamailio.cfg it will be relative to /etc/ser/).
68 68
 	</para>
69 69
 	<para>
70 70
 		<emphasis>Warning:</emphasis> try not to use certificate with keys
... ...
@@ -78,7 +78,7 @@ modparam("tls", "tls_method", "TLSv1")
78 78
 	    <title>Set <varname>certificate</varname> parameter</title>
79 79
 	    <programlisting>
80 80
 ...
81
-modparam("tls", "certificate", "/usr/local/etc/ser/my_certificate.pem")
81
+modparam("tls", "certificate", "/usr/local/etc/kamailio/my_certificate.pem")
82 82
 ...
83 83
 	    </programlisting>
84 84
 	</example>
... ...
@@ -94,7 +94,7 @@ modparam("tls", "certificate", "/usr/local/etc/ser/my_certificate.pem")
94 94
 		working directory (<emphasis>at runtime</emphasis>). If it starts
95 95
 		with a '/' it will be an absolute path and if it starts with anything
96 96
 		else the path will be relative to the main config file directory
97
-		(e.g.: for ser -f /etc/ser/ser.cfg it will be relative to /etc/ser/).
97
+		(e.g.: for kamailio -f /etc/ser/ser.cfg it will be relative to /etc/ser/).
98 98
 	</para>
99 99
 	<para>
100 100
 		Note: the private key can be contained in the same file as the
... ...
@@ -126,7 +126,7 @@ modparam("tls", "private", "/usr/local/etc/ser/my_pkey.pem")
126 126
 		working directory (<emphasis>at runtime</emphasis>). If it starts
127 127
 		with a '/' it will be an absolute path and if it starts with anything
128 128
 		else the path will be relative to the main config file directory
129
-		(e.g.: for ser -f /etc/ser/ser.cfg it will be relative to /etc/ser/).
129
+		(e.g.: for kamailio -f /etc/ser/ser.cfg it will be relative to /etc/ser/).
130 130
 	</para>
131 131
 	<para>
132 132
 		By default the CA file is not set.
... ...
@@ -168,7 +168,7 @@ modparam("tls", "ca_list", "/usr/local/etc/ser/ca_list.pem")
168 168
 		working directory (<emphasis>at runtime</emphasis>). If it starts
169 169
 		with a '/' it will be an absolute path and if it starts with anything
170 170
 		else the path will be relative to the main config file directory
171
-		(e.g.: for ser -f /etc/ser/ser.cfg it will be relative to /etc/ser/).
171
+		(e.g.: for kamailio -f /etc/ser/ser.cfg it will be relative to /etc/ser/).
172 172
 	</para>
173 173
 	<note><para>
174 174
 		If set, <varname>require_certificate</varname> should also be set
... ...
@@ -178,7 +178,7 @@ modparam("tls", "ca_list", "/usr/local/etc/ser/ca_list.pem")
178 178
 		By default the crl file is not set.
179 179
 	</para>
180 180
 	<para>
181
-		To update the crl in a running ser, make sure you configure tls
181
+		To update the crl in a running &kamailio;, make sure you configure tls
182 182
 		via a separate tls config file
183 183
 		(the <varname>config</varname> modparam) and issue a tls.reload
184 184
 		RPC call, e.g.:
... ...
@@ -308,7 +308,7 @@ modparam("tls", "cipher_list", "HIGH")
308 308
 	<title><varname>send_timeout</varname> (int)</title>
309 309
 	<para>
310 310
 		This parameter is <emphasis>obsolete</emphasis> and cannot be used
311
-		in newer TLS versions (&gt; sip-router 3.0). In these versions the
311
+		in newer TLS versions (&gt; &kamailio; 3.0). In these versions the
312 312
 		send_timeout is replaced by <varname>tcp_send_timeout</varname>
313 313
 		(common with all the tcp connections).
314 314
 	</para>
... ...
@@ -318,7 +318,7 @@ modparam("tls", "cipher_list", "HIGH")
318 318
 	<title><varname>handshake_timeout</varname> (int)</title>
319 319
 	<para>
320 320
 		This parameter is <emphasis>obsolete</emphasis> and cannot be used
321
-		in newer TLS versions (&gt; sip-router 3.0). In these versions the
321
+		in newer TLS versions (&gt; &kamailio; 3.0). In these versions the
322 322
 		handshake_timeout is replaced by <varname>tcp_connect_timeout</varname>
323 323
 		(common with all the tcp connections).
324 324
 	</para>
... ...
@@ -461,7 +461,7 @@ modparam("tls", "ssl_freelist_max_len", 0)
461 461
 	</para>
462 462
 	<para>
463 463
 		Lower values would lead to less memory usage, but values lower then
464
-		the typical ser/sip-router write size would incur a slight performance
464
+		the typical ser/&kamailio; write size would incur a slight performance
465 465
 		penalty. Good values are bigger then the  size of the biggest
466 466
 		SIP packet one normally expects to forward. For example in most
467 467
 		setups 2048 would be a good value.
... ...
@@ -2,8 +2,11 @@
2 2
 <!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 3
 	"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
4 4
 	[ <!ENTITY % local.common.attrib
5
-	 "xmlns:xi CDATA #FIXED 'http://www.w3.org/2001/XInclude'"> ]
6
->
5
+	 "xmlns:xi CDATA #FIXED 'http://www.w3.org/2001/XInclude'"> 
6
+<!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
7
+%docentities;
8
+
9
+]>
7 10
 
8 11
 <section id="tls" xmlns:xi="http://www.w3.org/2001/XInclude">
9 12
 	<sectioninfo>
... ...
@@ -28,7 +31,7 @@
28 31
 		<section id="tls.overview">
29 32
 		<title>Overview</title>
30 33
 		<para>
31
-			This module implements the TLS transport for SIP-router using the <ulink url="http://www.openssl.org">OpenSSL library</ulink> (http://www.openssl.org). To enable the TLS support this module must be loaded and <emphasis>enable_tls=yes</emphasis> must be added to the SIP-router config file 
34
+			This module implements the TLS transport for &kamailio; using the <ulink url="http://www.openssl.org">OpenSSL library</ulink> (http://www.openssl.org). To enable the TLS support this module must be loaded and <emphasis>enable_tls=yes</emphasis> must be added to the SIP-router config file 
32 35
 		</para>
33 36
 		</section>
34 37
 		<section id="tls.quick_start">