Browse code

- added tls module documentation (not yet complete, still missing select, rpc and better tls.cfg description).

Test case: try to read the generated README and see if it makes sense and you uderstand at least 88,73% from it. Prerequisites: well rested and a blood alcohol level within legal driving limits. WARNING: known to induce strong drowsiness.

Andrei Pelinescu-Onciul authored on 21/02/2007 00:54:44
Showing 8 changed files
1 1
new file mode 100644
... ...
@@ -0,0 +1,483 @@
1
+
2
+TLS Module
3
+
4
+Andrei Pelinescu-Onciul
5
+
6
+   iptelorg GmbH
7
+
8
+   Copyright � 2007 iptelorg GmbH
9
+   Revision History
10
+   Revision $Revision$ $Date$
11
+     _________________________________________________________________
12
+
13
+Overview
14
+
15
+   This module implements the TLS transport for ser using the openssl
16
+   library (http://www.openssl.org). To enable the TLS support this
17
+   module must be loaded and enable_tls=yes must be added to the ser
18
+   config file
19
+
20
+Quick Start
21
+
22
+   Make sure you have a proper certificate and private key and either use
23
+   the certificate and private_key module parameters, or make sure the
24
+   certificate and key are in the same PEM file, named cert.pem an placed
25
+   in [your-cfg-install-prefix]/etc/ser/. Don't forget to load the tls
26
+   module and to enable tls (add enable_tls=yes to your config).
27
+
28
+   Example 1. quick start config
29
+#...
30
+loadmodule "modules/tls/tls.so"
31
+
32
+modparam("tls", "private_key", "./andrei-test.pem")
33
+modparam("tls", "certificate", "./andrei-test.pem")
34
+modparam("tls", "ca_list", "./calist.pem")
35
+
36
+enable_tls=yes
37
+
38
+route{
39
+        # ....
40
+}
41
+
42
+Important Notes
43
+
44
+   The tls module needs some special options enabled when compiling ser.
45
+   These options are enabled by default, however in case you're using a
46
+   modified ser version or Makefile, make sure that you enable -DUSE_TLS
47
+   and -DTLS_HOOKS (or compile with make TLS_HOOKS=1 which will take care
48
+   of both options). To quickly check if your ser version was compiled
49
+   with these options, run ser -V and look for USE_TLS and TLS_HOOKS
50
+   among the flags.
51
+
52
+   This module includes several workarounds for various openssl bugs
53
+   (like compression and kerberos using the wrong memory allocations
54
+   functions, low memory problems a.s.o). On startup it will try to
55
+   enable the needed workarounds based on the openssl library version.
56
+   Each time a known problem is detected and a workaround is enabled, a
57
+   message will be logged. In general it is recommended to compile this
58
+   module on the same machine or a similar machine to where ser will be
59
+   run or to link it statically with libssl. For example if on the
60
+   compile machine openssl does not have the kerberos support enabled,
61
+   but on the target machine a kerberos enabled openssl library is
62
+   installed, ser cannot apply the needed workarounds and will refuse to
63
+   start. The same thing will happen if the openssl versions are too
64
+   different (to force ser startup anyway, see the tls_force_run module
65
+   parameter).
66
+
67
+   Try to avoid using keys larger then 1024 bytes. Large keys
68
+   significantly slow down the TLS connection handshake, thus limiting
69
+   the maximum ser TLS connection rate.
70
+
71
+   Compression is fully supported and used by default, if you have a new
72
+   enough openssl version (starting with 0.9.8). Although there are some
73
+   problems with zlib compression in currently deployed openssl versions
74
+   (up to and including 0.9.8d, see openssl bug #1468), the tls module
75
+   will automatically switch to its own fixed version. There's no need to
76
+   force-disable the compression.
77
+
78
+   The tls module includes workarounds for the following known openssl
79
+   bugs: openssl #1204 (disable SS_OP_TLS_BLOCK_PADDING_BUG if
80
+   compression is enabled, for versions between 0.9.8 and 0.9.8c),
81
+   openssl #1468 (fix zlib compression memory allocation) and openssl
82
+   #1467 (kerberos support will be disabled if openssl version less than
83
+   0.9.8e-beta1). The bug reports can be viewed at
84
+   http://rt.openssl.org/.
85
+
86
+Known Limitations
87
+
88
+   The private key must not encrypted (ser cannot ask you for a password
89
+   on startup).
90
+
91
+   The tls certificate verifications ignores the certificate name,
92
+   altname and ip extensions, it just checks if the certificate is signed
93
+   by a recognized CA. One can use the select framework to try to
94
+   overcome this limitation (check in the script for the contents of
95
+   various certificate fields), but this is not only slow, but also not
96
+   exactly standard conforming (the verification should happen during TLS
97
+   connection establishment and not after).
98
+
99
+   TLS specific config reloading is not safe, so for now better don't use
100
+   it, especially under heavy traffic.
101
+
102
+   This documentation is incomplete. The select framework and rpc
103
+   sections are completely missing.
104
+
105
+Quick Certificate Howto
106
+
107
+   Revision History
108
+   Revision $Revision$ $Date$
109
+
110
+   There are various ways to create, sign certificates and manage small
111
+   CAs (Certificate Authorities). If you want a GUI, try tinyca
112
+   (http://tinyca.sm-zone.net/), a very nice and small CA management
113
+   application. If you are in a hurry and everything you have are the
114
+   installed openssl libraries and utilities, read on.
115
+
116
+   Assumptions: we run our own CA.
117
+
118
+   Warning: in this example no key is encrypted. The client and server
119
+   private keys must not be encrypted (ser doesn't support encrypted
120
+   keys), so make sure the corresponding files are readable only by
121
+   trusted people. You should use a password for your CA private key.
122
+
123
+Creating CA certificate
124
+-----------------------
125
+1. create CA dir
126
+        mkdir ca
127
+        cd ca
128
+
129
+2. create ca dir structure and files  (see ca(1))
130
+        mkdir demoCA #default CA name, edit /etc/ss/openssl.cnf
131
+        mkdir  demoCA/private
132
+        mkdir demoCA/newcerts
133
+        touch demoCA/index.txt
134
+        echo 01 >demoCA/serial
135
+
136
+2. create CA private key
137
+        openssl genrsa -out demoCA/private/cakey.pem 2048
138
+        chmod 600 demoCA/private/cakey.pem
139
+
140
+3. create CA self-signed certificate
141
+        openssl req -out demoCA/cacert.pem   -x509 -new -key demoCA/private/cak
142
+ey.pem
143
+
144
+
145
+Creating a server/client certificate
146
+------------------------------------
147
+1. create a certificate request (and its private key in privkey.pem)
148
+        openssl req -out ser1_cert_req.pem -new -nodes
149
+   WARNING: the organization name should be the same as in the ca certificate.
150
+
151
+2. sign it with the ca certificate
152
+        openssl ca -in ser1_cert_req.pem -out ser1_cert.pem
153
+
154
+3. copy ser1_cert.pem to your ser config. dir
155
+
156
+
157
+Setting ser to use the certificate
158
+----------------------------------
159
+1. create the ca list file:
160
+        for each of your ca certificates that you intend to use do:
161
+                cat cacert.pem >>calist.pem
162
+
163
+2. copy your ser certificate, private key and ca list file to your
164
+        intended machine (preferably in your ser cfg. directory, this is the
165
+        default place ser searches for)
166
+
167
+3. set up ser.cfg to use the certificate
168
+        if your ser certificate name is different from cert.pem or it is not
169
+        placed in ser cfg. directory, add to your ser.cfg:
170
+                modparam("tls", "certificate", "/path/cert_file_name")
171
+
172
+4. set up ser to use the private key
173
+        if your private key is not contained in the certificate (or the
174
+         certificate name is not the default cert.pem), add to your ser.cfg:
175
+                modparam("tls", "private_key", "/path/private_key_file")
176
+
177
+5. set up ser to use the ca list (optional)
178
+        add to your ser.cfg:
179
+                modparam("tls", "ca_list", "/path/ca_list_file")
180
+
181
+6. set up tls authentication options:
182
+                modparam("tls", "verify_certificate", 1)
183
+                modparam("tls", "require_certificate", 1)
184
+        (for more information see the module parameters documentation)
185
+
186
+Parameters
187
+
188
+   Revision History
189
+   Revision $Revision$ $Date$
190
+
191
+tls_method (string)
192
+
193
+   Sets the SSL protocol method. Possible values are:
194
+     * TLSv1 - only TLSv1 connections are accepted. This is the default
195
+       and recommended method (if you want to be rfc3261 conformant don't
196
+       change it).
197
+     * SSLv3 - only SSLv3 connections are accepted
198
+     * SSLv2 - only SSLv2 connections, for old clients. Note: you
199
+       shouldn't use SSLv2 for anything which should be highly secure.
200
+     * SSLv23 - any of the above methods will be accepted, with the
201
+       following limitation: the initial SSL hello message must be V2 (in
202
+       the initial hello all the supported protocols are advertised
203
+       enabling switching to a higher and more secure version). This
204
+       means connections from SSLv3 or TLSv1 clients will not be
205
+       accepted.
206
+
207
+   If rfc3261 conformance is desired, TLSv1 must be used. For
208
+   compatibility with older clients SSLv23 is a good option.
209
+
210
+   Example 2. Set tls_method parameter
211
+...
212
+modparam("tls", "tls_method", "TLSv1")
213
+...
214
+
215
+certificate (string)
216
+
217
+   Sets the certificate file name. The certificate file can also contain
218
+   the private key.
219
+
220
+   Warning: try not to use certificate with keys longer then 1024 bytes.
221
+   Longer keys will severely impact performance, in particular the tls
222
+   connection rate.
223
+
224
+   The default value is [SER_CFG_DIR]/cert.pem.
225
+
226
+   Example 3. Set certificate parameter
227
+...
228
+modparam("tls", "certificate", "/usr/local/etc/ser/my_certificate.pem")
229
+...
230
+
231
+private_key (string)
232
+
233
+   Sets the private key file name.
234
+
235
+   Note: the private key can be contained in the same file as the
236
+   certificate (just append it to the certificate file, e.g.: cat
237
+   pkey.pem >> cert.pem)
238
+
239
+   The default value is [SER_CFG_DIR]/cert.pem.
240
+
241
+   Example 4. Set private_key parameter
242
+...
243
+modparam("tls", "private", "/usr/local/etc/ser/my_pkey.pem")
244
+...
245
+
246
+ca_list (string)
247
+
248
+   Sets the CA list file name. This file contains a list of all the
249
+   trusted CAs certificates. If a signature in a certificate chain
250
+   belongs to one of the listed CAs, the authentication will succeed. See
251
+   also verify_certificate, verify_depth and require_certificate.
252
+
253
+   By default the CA file is not set.
254
+
255
+   An easy way to create the CA list is to append each trusted trusted CA
256
+   certificate in the PEM format to one file, e.g.: for f in
257
+   trusted_cas/*.pem ; do cat "$f" >> ca_list.pem ; done .
258
+
259
+   Example 5. Set ca_list parameter
260
+...
261
+modparam("tls", "ca_list", "/usr/local/etc/ser/ca_list.pem")
262
+...
263
+
264
+verify_certificate (boolean)
265
+
266
+   If enabled it will force certificate verification. For more
267
+   information see the verify(1) openssl man page.
268
+
269
+   Note: the certificate verification will always fail if the ca_list is
270
+   empty.
271
+
272
+   See also: ca_list, require_certificate, verify_depth.
273
+
274
+   By default the certificate verification is off.
275
+
276
+   Example 6. Set verify_certificate parameter
277
+...
278
+modparam("tls", "verify_certificate", 1)
279
+...
280
+
281
+verify_depth (integer)
282
+
283
+   Sets how far up the certificate chain will the certificate
284
+   verification go in the search for a trusted CA.
285
+
286
+   See also: ca_list, require_certificate, verify_certificate,
287
+
288
+   The default value is 9.
289
+
290
+   Example 7. Set verify_depth parameter
291
+...
292
+modparam("tls", "verify_depth", 9)
293
+...
294
+
295
+require_certificate (boolean)
296
+
297
+   When enabled it will require a certificate from a client. If the
298
+   client does not offer a certificate and verify_certificate is on, the
299
+   certificate verification will fail.
300
+
301
+   The default value is off.
302
+
303
+   Example 8. Set require_certificate parameter
304
+...
305
+modparam("tls", "require_certificate", 1)
306
+...
307
+
308
+cipher_list (string)
309
+
310
+   Sets the list of accepted ciphers. The list consists of cipher strings
311
+   separated by colons. For more information on the cipher list format
312
+   see the cipher(1) openssl man page.
313
+
314
+   The default value is not set (all the openssl supported ciphers are
315
+   enabled).
316
+
317
+   Example 9. Set cipher_list parameter
318
+...
319
+modparam("tls", "cipher_list", "HIGH")
320
+...
321
+
322
+send_timeout (int)
323
+
324
+   Sets the maximum interval of time after which ser will give up trying
325
+   to send a message over tls (time after a tls send will be aborted and
326
+   the corresponding tls connection closed). The value is in seconds.
327
+
328
+   The default value is 120 s.
329
+
330
+   Example 10. Set send_timeout parameter
331
+...
332
+modparam("tls", "send_timeout", 1)
333
+...
334
+
335
+handshake_timeout (int)
336
+
337
+   Sets the maximum interval of time after which ser will give up trying
338
+   to accept a tls connection or connect to a tls peer. The value is in
339
+   seconds.
340
+
341
+   The default value is 120 s.
342
+
343
+   Example 11. Set handshake_timeout parameter
344
+...
345
+modparam("tls", "handshake_timeout", 1)
346
+...
347
+
348
+connection_timeout (int)
349
+
350
+   Sets the amount of time after which an idle tls connection will be
351
+   closed. This is similar to tcp_connection_lifetime. The value is
352
+   expressed in seconds.
353
+
354
+   The default value is 10 min.
355
+
356
+   If the value set is -1, the connection will never be close on idle.
357
+
358
+   Example 12. Set connection_timeout parameter
359
+...
360
+modparam("tls", "connection_timeout", 60)
361
+...
362
+
363
+tls_disable_compression (boolean)
364
+
365
+   If set compression over SSL/TLS will be disabled.
366
+
367
+   By default compression is enabled.
368
+
369
+   Example 13. Set tls_disable_compression parameter
370
+...
371
+modparam("tls", "tls_disable_compression", 1)
372
+...
373
+
374
+tls_log (int)
375
+
376
+   Sets the log level at which tls related messages will be logged.
377
+
378
+   The default value is 3.
379
+
380
+   Example 14. Set tls_log parameter
381
+...
382
+# ignore tls messages if ser is started with debug less than 10
383
+modparam("tls", "tls_log", 10)
384
+...
385
+
386
+tls_force_run (boolean)
387
+
388
+   If enabled ser will start even if some of the openssl sanity checks
389
+   fail (turn it on at your own risk).
390
+
391
+   Currently failing any of the following sanity checks will not allow
392
+   ser to start:
393
+     * the version of the library the tls module was compiled with is
394
+       "too different" from the library used at runtime. The versions
395
+       should have the same major, minor and fix level (e.g.: 0.9.8a and
396
+       0.9.8c are ok, but 0.9.8 and 0.9.9 are not)
397
+     * the openssl library used at compile time and the one used at
398
+       runtime have different kerberos options
399
+
400
+   By default tls_force_run is disabled.
401
+
402
+   Example 15. Set tls_force_run parameter
403
+...
404
+modparam("tls", "tls_force_run", 11)
405
+...
406
+
407
+config (string)
408
+
409
+   Sets the name of the TLS specific config file.
410
+
411
+   If set the tls module will load a special config file, in which
412
+   different tls parameters can be specified on a per role (server or
413
+   client) and domain basis (for now only IPs). The corresponding module
414
+   parameters will be ignored.
415
+
416
+   By default no config file is specified.
417
+
418
+   The following parameters can be set in the config file, for each
419
+   domain:
420
+     * tls_method
421
+     * verify_certificate
422
+     * require_certificate
423
+     * private_key
424
+     * certificate
425
+     * verify_depth
426
+     * ca_list
427
+     * cipher_list
428
+
429
+   ser acts as a server when it accepts a connection and as a client when
430
+   it initiates a new connection by itself (it connects to something).
431
+
432
+   Example 16. Short config file
433
+[server:default]
434
+method = TLSv1
435
+verify_certificate = no
436
+require_certificate = no
437
+private_key = default_key.pem
438
+certificate = default_cert.pem
439
+ca_list = default_ca.pem
440
+
441
+[client:default]
442
+verify_certificate = yes
443
+require_certificate = yes
444
+
445
+#more relaxed for connection on the loopback interface
446
+[server:127.0.0.1:5061]
447
+method = SSLv23
448
+verify_certificate = yes
449
+require_certificate = no
450
+private_key = local_key.pem
451
+certificate = local_cert.pem
452
+verify_depth = 3
453
+ca_list = local_ca.pem
454
+
455
+   For a more complete example check the tls.cfg distributed with the ser
456
+   source (sip_router/modules/tls/tls.cfg).
457
+
458
+   Example 17. Set config parameter
459
+...
460
+modparam("tls", "config", "/usr/local/etc/ser/tls.cfg")
461
+...
462
+
463
+Functions
464
+
465
+   Revision History
466
+   Revision $Revision$ $Date$
467
+
468
+History
469
+
470
+   Revision History
471
+   Revision $Revision$ $Date$
472
+
473
+   This module was put together by Jan Janak <jan@iptel.org> from code
474
+   from the experimental tls core addon
475
+   (http://cvs.berlios.de/cgi-bin/viewcvs.cgi/ser/experimental/tls/),
476
+   code originally written by Peter Griffiths and later maintained by
477
+   Cesc Santasusana and from an iptelorg tls code addon, written by
478
+   Andrei Pelinescu-Onciul <andrei@iptel.org>. Jan also added support for
479
+   multiple domains, a tls specific config, config reloading and a tls
480
+   specific select framework.
481
+
482
+   The code is currently maintained by Andrei Pelinescu-Onciul
483
+   <andrei@iptel.org>.
... ...
@@ -1,3 +1,5 @@
1
+[NOTE: this file is obsolete, use README instead]
2
+
1 3
 
2 4
 free-TLS core module
3 5
 
4 6
new file mode 100644
... ...
@@ -0,0 +1,29 @@
1
+#
2
+# The list of documents to build (without extensions)
3
+#
4
+DOCUMENTS = tls
5
+
6
+#
7
+# The root directory containing Makefile.doc
8
+#
9
+ROOT_DIR=../../..
10
+
11
+#
12
+# Validate docbook documents before generating output
13
+# (may be slow)
14
+#
15
+#VALIDATE=1
16
+
17
+#
18
+# You can override the stylesheet used to generate
19
+# xhtml documents here
20
+#
21
+#XHTML_XSL=$(ROOT_DIR)/doc/stylesheets/xhtml.xsl
22
+
23
+#
24
+# You can override the stylesheet used to generate
25
+# plain text documents here
26
+#
27
+#TXT_XSL=$(XHTML_XSL)
28
+
29
+include $(ROOT_DIR)/Makefile.doc
0 30
new file mode 100644
... ...
@@ -0,0 +1,94 @@
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">
4
+
5
+<section id="tls.certs_howto" xmlns:xi="http://www.w3.org/2001/XInclude">
6
+    <sectioninfo>
7
+	<revhistory>
8
+	    <revision>
9
+		<revnumber>$Revision$</revnumber>
10
+		<date>$Date$</date>
11
+	    </revision>
12
+	</revhistory>
13
+    </sectioninfo>
14
+
15
+	<title>Quick Certificate Howto</title>
16
+		<para>
17
+			There are various ways to create, sign certificates and manage small CAs (Certificate Authorities). If you want a GUI, try <ulink url="http://tinyca.sm-zone.net/">tinyca (http://tinyca.sm-zone.net/)</ulink>, a very nice and small CA management application. If you are in a hurry and everything you have are the installed openssl libraries and utilities, read on.
18
+		</para>
19
+		<para>
20
+			Assumptions: we run our own CA.
21
+		</para>
22
+		<para>
23
+			Warning: in this example no key is encrypted. The client and server private keys must not be encrypted (ser doesn't support encrypted keys), so make sure the corresponding files are readable only by trusted people. You should use a password for your CA private key.
24
+		</para>
25
+		<para>
26
+		<programlisting>
27
+
28
+Creating CA certificate
29
+-----------------------
30
+1. create CA dir
31
+	mkdir ca
32
+	cd ca
33
+	
34
+2. create ca dir structure and files  (see ca(1))
35
+	mkdir demoCA #default CA name, edit /etc/ss/openssl.cnf
36
+	mkdir  demoCA/private
37
+	mkdir demoCA/newcerts
38
+	touch demoCA/index.txt
39
+	echo 01 >demoCA/serial
40
+	
41
+2. create CA private key
42
+	openssl genrsa -out demoCA/private/cakey.pem 2048
43
+	chmod 600 demoCA/private/cakey.pem
44
+	
45
+3. create CA self-signed certificate
46
+	openssl req -out demoCA/cacert.pem   -x509 -new -key demoCA/private/cakey.pem
47
+
48
+
49
+Creating a server/client certificate
50
+------------------------------------
51
+1. create a certificate request (and its private key in privkey.pem)
52
+	openssl req -out ser1_cert_req.pem -new -nodes
53
+   WARNING: the organization name should be the same as in the ca certificate.
54
+	
55
+2. sign it with the ca certificate
56
+	openssl ca -in ser1_cert_req.pem -out ser1_cert.pem
57
+	
58
+3. copy ser1_cert.pem to your ser config. dir
59
+
60
+
61
+Setting ser to use the certificate
62
+----------------------------------
63
+1. create the ca list file:
64
+	for each of your ca certificates that you intend to use do:
65
+		cat cacert.pem >>calist.pem
66
+	
67
+2. copy your ser certificate, private key and ca list file to your 
68
+	intended machine (preferably in your ser cfg. directory, this is the 
69
+	default place ser searches for)
70
+	
71
+3. set up ser.cfg to use the certificate
72
+	if your ser certificate name is different from cert.pem or it is not
73
+	placed in ser cfg. directory, add to your ser.cfg:
74
+		modparam("tls", "certificate", "/path/cert_file_name")
75
+	
76
+4. set up ser to use the private key
77
+	if your private key is not contained in the certificate (or the
78
+	 certificate name is not the default cert.pem), add to your ser.cfg:
79
+		modparam("tls", "private_key", "/path/private_key_file")
80
+	
81
+5. set up ser to use the ca list (optional)
82
+	add to your ser.cfg:
83
+		modparam("tls", "ca_list", "/path/ca_list_file")
84
+	
85
+6. set up tls authentication options:
86
+		modparam("tls", "verify_certificate", 1)
87
+		modparam("tls", "require_certificate", 1) 
88
+	(for more information see the module parameters documentation)
89
+
90
+		</programlisting>
91
+		</para>
92
+
93
+
94
+</section>
0 95
new file mode 100644
... ...
@@ -0,0 +1,17 @@
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">
4
+
5
+<section id="textops.functions" xmlns:xi="http://www.w3.org/2001/XInclude">
6
+    <sectioninfo>
7
+	<revhistory>
8
+	    <revision>
9
+		<revnumber>$Revision$</revnumber>
10
+		<date>$Date$</date>
11
+	    </revision>
12
+	</revhistory>
13
+    </sectioninfo>
14
+
15
+    <title>Functions</title>
16
+
17
+</section>
0 18
new file mode 100644
... ...
@@ -0,0 +1,22 @@
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">
4
+
5
+<section id="tls.certs_howto" xmlns:xi="http://www.w3.org/2001/XInclude">
6
+    <sectioninfo>
7
+	<revhistory>
8
+	    <revision>
9
+		<revnumber>$Revision$</revnumber>
10
+		<date>$Date$</date>
11
+	    </revision>
12
+	</revhistory>
13
+    </sectioninfo>
14
+
15
+	<title>History</title>
16
+		<para>
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.
18
+		</para>
19
+		<para>
20
+			The code is currently maintained by Andrei Pelinescu-Onciul <email>andrei@iptel.org</email>.
21
+		</para>
22
+</section>
0 23
new file mode 100644
... ...
@@ -0,0 +1,395 @@
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">
4
+
5
+<section id="tm.parameters" xmlns:xi="http://www.w3.org/2001/XInclude">
6
+    <sectioninfo>
7
+	<revhistory>
8
+	    <revision>
9
+		<revnumber>$Revision$</revnumber>
10
+		<date>$Date$</date>
11
+	    </revision>
12
+	</revhistory>
13
+    </sectioninfo>
14
+
15
+    <title>Parameters</title>
16
+
17
+	<section id="tls_method">
18
+	<title><varname>tls_method</varname> (string)</title>
19
+	<para>
20
+		Sets the SSL protocol method. Possible values are:
21
+	</para>
22
+	<itemizedlist>
23
+			<listitem>
24
+				<para>
25
+				<emphasis>TLSv1</emphasis> - only TLSv1 connections are accepted. This is the default and recommended method (if you want to be rfc3261  conformant don't change it).
26
+				</para>
27
+			</listitem>
28
+			<listitem>
29
+				<para>
30
+				<emphasis>SSLv3</emphasis> - only SSLv3 connections are accepted
31
+				</para>
32
+			</listitem>
33
+			<listitem>
34
+				<para>
35
+				<emphasis>SSLv2</emphasis> - only SSLv2 connections, for old clients. Note: you shouldn't use SSLv2 for anything which should be highly secure.
36
+				</para>
37
+			</listitem>
38
+			<listitem>
39
+				<para>
40
+				<emphasis>SSLv23</emphasis> - any of the above methods will be accepted, with the following limitation: the initial SSL hello message must be V2 (in the initial hello all the supported protocols are advertised enabling switching to a higher and more secure version). This means connections from SSLv3 or TLSv1 clients will not be accepted.
41
+				</para>
42
+			</listitem>
43
+	</itemizedlist>
44
+	<para>
45
+		If rfc3261 conformance is desired,  TLSv1 must be used. For compatibility with older clients SSLv23 is a good option.
46
+	</para>
47
+	<example>
48
+	    <title>Set <varname>tls_method</varname> parameter</title>
49
+	    <programlisting>
50
+...
51
+modparam("tls", "tls_method", "TLSv1")
52
+...
53
+	    </programlisting>
54
+	</example>
55
+	</section>
56
+
57
+	<section id="certificate">
58
+	<title><varname>certificate</varname> (string)</title>
59
+	<para>
60
+		Sets the certificate file name. The certificate file can also contain the private key.
61
+	</para>
62
+	<para>
63
+		<emphasis>Warning:</emphasis> try not to use certificate with keys longer then 1024 bytes. Longer keys will severely impact performance, in particular the tls connection rate.
64
+	</para>
65
+	<para>
66
+		The default value is [SER_CFG_DIR]/cert.pem.
67
+	</para>
68
+	<example>
69
+	    <title>Set <varname>certificate</varname> parameter</title>
70
+	    <programlisting>
71
+...
72
+modparam("tls", "certificate", "/usr/local/etc/ser/my_certificate.pem")
73
+...
74
+	    </programlisting>
75
+	</example>
76
+	</section>
77
+
78
+	<section id="private_key">
79
+	<title><varname>private_key</varname> (string)</title>
80
+	<para>
81
+		Sets the private key file name.
82
+	</para>
83
+	<para>
84
+		Note: the private key can be contained in the same file as the certificate (just append it to the certificate file, e.g.: cat pkey.pem >> cert.pem)
85
+	</para>
86
+	<para>
87
+		The default value is [SER_CFG_DIR]/cert.pem.
88
+	</para>
89
+	<example>
90
+	    <title>Set <varname>private_key</varname> parameter</title>
91
+	    <programlisting>
92
+...
93
+modparam("tls", "private", "/usr/local/etc/ser/my_pkey.pem")
94
+...
95
+	    </programlisting>
96
+	</example>
97
+	</section>
98
+
99
+<section id="ca_list">
100
+	<title><varname>ca_list</varname> (string)</title>
101
+	<para>
102
+		Sets the CA list file name. This file contains a list of all the trusted CAs certificates. If a signature in a certificate chain belongs to one of the listed CAs, the authentication will succeed. See also <emphasis>verify_certificate</emphasis>, <emphasis>verify_depth</emphasis> and <emphasis>require_certificate</emphasis>.
103
+	</para>
104
+	<para>
105
+		By default the CA file is not set.
106
+	</para>
107
+	<para>
108
+		An easy way to create the CA list is to append each trusted trusted CA certificate in the PEM format to one file, e.g.: for f in trusted_cas/*.pem ; do cat "$f" >> ca_list.pem ; done .
109
+	</para>
110
+	<example>
111
+	    <title>Set <varname>ca_list</varname> parameter</title>
112
+	    <programlisting>
113
+...
114
+modparam("tls", "ca_list", "/usr/local/etc/ser/ca_list.pem")
115
+...
116
+	    </programlisting>
117
+	</example>
118
+	</section>
119
+
120
+<section id="verify_certificate">
121
+	<title><varname>verify_certificate</varname> (boolean)</title>
122
+	<para>
123
+		If enabled it will force certificate verification. For more information see the <ulink url="http://www.openssl.org/docs/apps/verify.html">verify(1)</ulink> openssl man page.
124
+	</para>
125
+	<para>
126
+		Note: the certificate verification will always fail if the ca_list is empty.
127
+	</para>
128
+	<para>
129
+		See also: <varname>ca_list</varname>, <varname>require_certificate</varname>, <varname>verify_depth</varname>.
130
+	</para>
131
+	<para>
132
+		By default the certificate verification is off.
133
+	</para>
134
+	<example>
135
+	    <title>Set <varname>verify_certificate</varname> parameter</title>
136
+	    <programlisting>
137
+...
138
+modparam("tls", "verify_certificate", 1)
139
+...
140
+	    </programlisting>
141
+	</example>
142
+	</section>
143
+
144
+<section id="verify_depth">
145
+	<title><varname>verify_depth</varname> (integer)</title>
146
+	<para>
147
+		Sets how far up the certificate chain will the certificate verification go in the search for a trusted CA.
148
+	</para>
149
+	<para>
150
+		See also: <varname>ca_list</varname>, <varname>require_certificate</varname>, <varname>verify_certificate</varname>,
151
+	</para>
152
+	<para>
153
+		The default value is 9.
154
+	</para>
155
+	<example>
156
+	    <title>Set <varname>verify_depth</varname> parameter</title>
157
+	    <programlisting>
158
+...
159
+modparam("tls", "verify_depth", 9)
160
+...
161
+	    </programlisting>
162
+	</example>
163
+	</section>
164
+
165
+<section id="require_certificate">
166
+	<title><varname>require_certificate</varname> (boolean)</title>
167
+	<para>
168
+		When enabled it will require a certificate from a client. If the client does not offer a certificate and <varname>verify_certificate</varname> is on, the certificate verification will fail.
169
+	</para>
170
+	<para>
171
+		The default value is off.
172
+	</para>
173
+	<example>
174
+	    <title>Set <varname>require_certificate</varname> parameter</title>
175
+	    <programlisting>
176
+...
177
+modparam("tls", "require_certificate", 1)
178
+...
179
+	    </programlisting>
180
+	</example>
181
+	</section>
182
+
183
+<section id="cipher_list">
184
+	<title><varname>cipher_list</varname> (string)</title>
185
+	<para>
186
+		Sets the list of accepted ciphers. The list consists of cipher strings separated by colons. For more information on the cipher list format see the <ulink url="http://www.openssl.org/docs/apps/ciphers.html">cipher(1)</ulink> openssl man page.
187
+	</para>
188
+	<para>
189
+		The default value is not set (all the openssl supported ciphers are enabled).
190
+	</para>
191
+	<example>
192
+	    <title>Set <varname>cipher_list</varname> parameter</title>
193
+	    <programlisting>
194
+...
195
+modparam("tls", "cipher_list", "HIGH")
196
+...
197
+	    </programlisting>
198
+	</example>
199
+	</section>
200
+
201
+	<section id="send_timeout">
202
+	<title><varname>send_timeout</varname> (int)</title>
203
+	<para>
204
+		Sets the maximum interval of time after which ser will give up trying to send a message over tls (time after a tls send will be aborted and the corresponding tls connection closed). The value is in seconds.
205
+	</para>
206
+	<para>
207
+		The default value is 120 s.
208
+	</para>
209
+	<example>
210
+	    <title>Set <varname>send_timeout</varname> parameter</title>
211
+	    <programlisting>
212
+...
213
+modparam("tls", "send_timeout", 1)
214
+...
215
+	    </programlisting>
216
+	</example>
217
+	</section>
218
+
219
+	<section id="handshake_timeout">
220
+	<title><varname>handshake_timeout</varname> (int)</title>
221
+	<para>
222
+		Sets the maximum interval of time after which ser will give up trying to accept a tls connection or connect to a tls peer. The value is in seconds.
223
+	</para>
224
+	<para>
225
+		The default value is 120 s.
226
+	</para>
227
+	<example>
228
+	    <title>Set <varname>handshake_timeout</varname> parameter</title>
229
+	    <programlisting>
230
+...
231
+modparam("tls", "handshake_timeout", 1)
232
+...
233
+	    </programlisting>
234
+	</example>
235
+	</section>
236
+
237
+	<section id="connection_timeout">
238
+	<title><varname>connection_timeout</varname> (int)</title>
239
+	<para>
240
+		Sets the amount of time after which an idle tls connection will be closed. This is similar to tcp_connection_lifetime. The value is expressed in seconds.
241
+	</para>
242
+	<para>
243
+		The default value is 10 min.
244
+	</para>
245
+	<para>
246
+		If the value set is -1, the connection will never be close on idle.
247
+	</para>
248
+	<example>
249
+	    <title>Set <varname>connection_timeout</varname> parameter</title>
250
+	    <programlisting>
251
+...
252
+modparam("tls", "connection_timeout", 60)
253
+...
254
+	    </programlisting>
255
+	</example>
256
+	</section>
257
+
258
+	<section id="tls_disable_compression">
259
+	<title><varname>tls_disable_compression</varname> (boolean)</title>
260
+	<para>
261
+		If set compression over SSL/TLS will be disabled.
262
+	</para>
263
+	<para>
264
+		By default compression is enabled.
265
+	</para>
266
+	<example>
267
+	    <title>Set <varname>tls_disable_compression</varname> parameter</title>
268
+	    <programlisting>
269
+...
270
+modparam("tls", "tls_disable_compression", 1)
271
+...
272
+	    </programlisting>
273
+	</example>
274
+	</section>
275
+
276
+	<section id="tls_log">
277
+	<title><varname>tls_log</varname> (int)</title>
278
+	<para>
279
+		Sets the log level at which tls related messages will be logged.
280
+	</para>
281
+	<para>
282
+		The default value is 3.
283
+	</para>
284
+	<example>
285
+		<title>Set <varname>tls_log</varname> parameter</title>
286
+		<programlisting>
287
+...
288
+# ignore tls messages if ser is started with debug less than 10
289
+modparam("tls", "tls_log", 10)
290
+...
291
+		</programlisting>
292
+	</example>
293
+	</section>
294
+
295
+	<section id="tls_force_run">
296
+	<title><varname>tls_force_run</varname> (boolean)</title>
297
+	<para>
298
+		If enabled ser will start even if some of the openssl sanity checks fail (turn it on at your own risk).
299
+	</para>
300
+	<para>
301
+		Currently failing any of the following sanity checks will not allow ser to start:
302
+	</para>
303
+	<itemizedlist>
304
+			<listitem>
305
+				<para>
306
+					the version of the library the tls module was compiled with is "too different" from the library used at runtime. The versions should have the same major, minor and fix level (e.g.: 0.9.8a and 0.9.8c are ok, but 0.9.8 and 0.9.9 are not)
307
+				</para>
308
+			</listitem>
309
+			<listitem>
310
+				<para>
311
+					the openssl library used at compile time and the one used at runtime have different kerberos options 
312
+				</para>
313
+			</listitem>
314
+	</itemizedlist>
315
+	<para>
316
+		By default tls_force_run is disabled.
317
+	</para>
318
+	<example>
319
+		<title>Set <varname>tls_force_run</varname> parameter</title>
320
+		<programlisting>
321
+...
322
+modparam("tls", "tls_force_run", 11)
323
+...
324
+	</programlisting>
325
+	</example>
326
+	</section>
327
+
328
+	<section id="config">
329
+	<title><varname>config</varname> (string)</title>
330
+	<para>
331
+		Sets the name of the TLS specific config file.
332
+	</para>
333
+	<para>
334
+		If set the tls module will load a special config file, in which different tls parameters can be specified on a per role (server or client) and domain basis (for now only IPs). The corresponding module parameters will be ignored.
335
+	</para>
336
+	<para>
337
+		By default no config file is specified.
338
+	</para>
339
+	<para>
340
+		The following parameters can be set in the config file, for each domain:
341
+	</para>
342
+	<itemizedlist>
343
+			<listitem><para>tls_method</para></listitem>
344
+			<listitem><para>verify_certificate</para></listitem>
345
+			<listitem><para>require_certificate</para></listitem>
346
+			<listitem><para>private_key</para></listitem>
347
+			<listitem><para>certificate</para></listitem>
348
+			<listitem><para>verify_depth</para></listitem>
349
+			<listitem><para>ca_list</para></listitem>
350
+			<listitem><para>cipher_list</para></listitem>
351
+	</itemizedlist>
352
+	<para>
353
+		ser acts as a server when it accepts a connection and as a client when it initiates a new connection by itself (it connects to something).
354
+	</para>
355
+	<example>
356
+		<title>Short config file</title>
357
+	<programlisting>
358
+[server:default]
359
+method = TLSv1
360
+verify_certificate = no
361
+require_certificate = no
362
+private_key = default_key.pem
363
+certificate = default_cert.pem
364
+ca_list = default_ca.pem
365
+
366
+[client:default]
367
+verify_certificate = yes
368
+require_certificate = yes
369
+
370
+#more relaxed for connection on the loopback interface
371
+[server:127.0.0.1:5061]
372
+method = SSLv23
373
+verify_certificate = yes
374
+require_certificate = no
375
+private_key = local_key.pem
376
+certificate = local_cert.pem
377
+verify_depth = 3
378
+ca_list = local_ca.pem
379
+
380
+	</programlisting>
381
+	</example>
382
+	<para>
383
+		For a more complete example check the <emphasis>tls.cfg</emphasis> distributed with the ser source (sip_router/modules/tls/tls.cfg).
384
+	</para>
385
+	<example>
386
+		<title>Set <varname>config</varname> parameter</title>
387
+		<programlisting>
388
+...
389
+modparam("tls", "config", "/usr/local/etc/ser/tls.cfg")
390
+...
391
+	</programlisting>
392
+	</example>
393
+	</section>
394
+
395
+</section>
0 396
new file mode 100644
... ...
@@ -0,0 +1,103 @@
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">
4
+
5
+<section id="tls" xmlns:xi="http://www.w3.org/2001/XInclude">
6
+	<sectioninfo>
7
+	<authorgroup>
8
+		<author>
9
+		<firstname>Andrei</firstname>
10
+		<surname>Pelinescu-Onciul</surname>
11
+		<affiliation><orgname>iptelorg GmbH</orgname></affiliation>
12
+		<address>
13
+			<email>andrei@iptel.org</email>
14
+		</address>
15
+		</author>
16
+	</authorgroup>
17
+	<copyright>
18
+		<year>2007</year>
19
+		<holder>iptelorg GmbH</holder>
20
+	</copyright>
21
+	<revhistory>
22
+		<revision>
23
+		<revnumber>$Revision$</revnumber>
24
+		<date>$Date$</date>
25
+		</revision>
26
+	</revhistory>
27
+	</sectioninfo>
28
+
29
+	<title>TLS Module</title>
30
+
31
+		<section id="tls.overview">
32
+		<title>Overview</title>
33
+		<para>
34
+			This module implements the TLS transport for ser 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 ser config file 
35
+		</para>
36
+		</section>
37
+		<section id="tls.quick_start">
38
+		<title>Quick Start</title>
39
+		<para>
40
+			Make sure you have a proper certificate and private key and either use the certificate and private_key module parameters, or make sure the certificate and key are in the same PEM file, named cert.pem an placed in [your-cfg-install-prefix]/etc/ser/. Don't forget to load the tls module and to enable tls (add <emphasis>enable_tls=yes</emphasis> to your config).
41
+		</para>
42
+		<example>
43
+		<title>quick start config</title>
44
+		<programlisting>
45
+#...
46
+loadmodule "modules/tls/tls.so"
47
+
48
+modparam("tls", "private_key", "./andrei-test.pem")
49
+modparam("tls", "certificate", "./andrei-test.pem")
50
+modparam("tls", "ca_list", "./calist.pem")
51
+
52
+enable_tls=yes
53
+
54
+route{
55
+	# ....
56
+}
57
+		</programlisting>
58
+		</example>
59
+		</section>
60
+
61
+		<section id="tls.notes">
62
+		<title>Important Notes</title>
63
+		<para>
64
+			The tls module needs some special options enabled when compiling ser. These options are enabled by default, however in case you're using a modified ser version or Makefile, make sure that you enable -DUSE_TLS and -DTLS_HOOKS (or compile with make TLS_HOOKS=1 which will take care of both options). To quickly check if your ser version was compiled with these options, run ser -V and look for USE_TLS and TLS_HOOKS among the flags.
65
+		</para>
66
+		<para>
67
+			This module includes several workarounds for various openssl bugs (like compression and kerberos using the wrong memory allocations functions, low memory problems a.s.o). On startup it will try to enable the needed workarounds based on the openssl library version. Each time a known problem is detected and a workaround is enabled, a message will be logged. In general it is recommended to compile this module on the same machine or a similar machine to where ser will be run or to link it statically with libssl. For example if on the compile machine openssl does not have the kerberos support enabled, but on the target machine a kerberos enabled openssl library is installed, ser cannot apply the needed workarounds and will refuse to start. The same thing will happen if the openssl versions are too different (to force ser startup anyway, see the <varname>tls_force_run</varname> module parameter).
68
+		</para>
69
+		<para>
70
+			Try to avoid using keys larger then 1024 bytes. Large keys significantly slow down the TLS connection handshake, thus limiting the maximum ser TLS connection rate.
71
+		</para>
72
+		<para>
73
+			Compression is fully supported and used by default, if you have a new enough openssl version (starting with 0.9.8). Although there are some problems with zlib compression in currently deployed openssl versions (up to and including 0.9.8d, see openssl bug #1468), the tls module will automatically switch to its own fixed version. There's no need to force-disable the compression.
74
+		</para>
75
+		<para>
76
+			The tls module includes workarounds for the following known openssl bugs:  openssl #1204 (disable SS_OP_TLS_BLOCK_PADDING_BUG if compression is enabled, for versions between 0.9.8 and 0.9.8c), openssl #1468 (fix zlib compression memory allocation) and openssl #1467 (kerberos support will be disabled if
77
+ openssl version less than 0.9.8e-beta1). The bug reports can be viewed at
78
+  <ulink url="http://rt.openssl.org/">http://rt.openssl.org/</ulink>.
79
+		</para>
80
+		</section>
81
+		<section id="tls.known_limitations">
82
+		<title>Known Limitations</title>
83
+		<para>
84
+			The private key must not encrypted (ser cannot ask you for a password on startup).
85
+		</para>
86
+		<para>
87
+			The tls certificate verifications ignores the certificate name, altname and ip extensions, it just checks if the certificate is signed by a recognized CA. One can use the select framework to try to overcome this limitation (check in the script for the contents of various certificate fields), but this is not only slow, but also not exactly standard conforming (the verification should happen during TLS connection establishment and not after).
88
+		</para>
89
+		<para>
90
+			TLS specific config reloading is not safe, so for now better don't use it, especially under heavy traffic.
91
+		</para>
92
+		<para>
93
+			This documentation is incomplete. The select framework and rpc sections are completely missing.
94
+		</para>
95
+		</section>
96
+
97
+	<xi:include href="certs_howto.xml"/>
98
+	<xi:include href="params.xml"/>
99
+	<xi:include href="functions.xml"/>
100
+	<xi:include href="history.xml"/>
101
+
102
+</section>
103
+