Browse code

Merge pull request #3144 from space88man/wolfssl

tls_wolfssl: new module TLS stack based on wolfSSL

Daniel-Constantin Mierla authored on 16/06/2022 06:39:02 • GitHub committed on 16/06/2022 06:39:02
Showing 46 changed files
1 1
new file mode 100644
... ...
@@ -0,0 +1,81 @@
1
+#
2
+# TLS module makefile
3
+#
4
+#
5
+# WARNING: do not run this directly, it should be run by the main Makefile
6
+
7
+include ../../Makefile.defs
8
+auto_gen=
9
+NAME=tls_wolfssl.so
10
+
11
+# set to yes when wanting to link with static libraries
12
+LIBSSL_STATIC ?= no
13
+# set to yes when wanting to link with static libraries compiled from source
14
+LIBSSL_STATIC_SRCLIB ?= no
15
+# set to the path of the folder with static libraries compiled from source
16
+LIBSSL_STATIC_SRCPATH ?= /usr/local/src/openssl
17
+
18
+ifeq ($(CROSS_COMPILE),)
19
+WOLFSSL_BUILDER=$(shell \
20
+	if pkg-config --exists wolfssl; then \
21
+		echo 'pkg-config wolfssl'; \
22
+	fi)
23
+endif
24
+
25
+ifneq ($(WOLFSSL_BUILDER),)
26
+
27
+ifneq ($(WOLFSSL_STATIC),yes)
28
+	DEFS += $(shell $(WOLFSSL_BUILDER) --cflags)
29
+	LIBS += $(shell $(WOLFSSL_BUILDER) --libs)
30
+
31
+else # $(WOLFSSL_STATIC),yes)
32
+
33
+	DEFS += -DKSR_WOLFSSL_STATIC
34
+
35
+ifneq ($(WOLFSSL_STATIC_SRCLIB),yes)
36
+	## when static libs (*.a) from packages are compiled with -fPIC
37
+	DEFS += $(shell $(WOLFSSL_BUILDER) --cflags)
38
+	LIBS += $(shell $(WOLFSSL_BUILDER) --libs-only-L)
39
+	# TODO: explore use of LIBS += -Wl,-Bstatic $(shell $(SSL_BUILDER) --libs-only-l)
40
+	LIBS += -l:libwolfssl.a -l:libz.a -l:libdl.a
41
+else
42
+	## when linking against static libs compiled from sources
43
+	DEFS += -I$(WOLFSSL_STATIC_SRCPATH)/include
44
+	LIBS += $(WOLFSSL_STATIC_SRCPATH)/libwolfssl.a
45
+endif # ifneq ($(WOLFSSL_STATIC_SRCLIB),yes)
46
+
47
+endif # ifneq ($(WOLFSSL_STATIC),yes)
48
+
49
+else # ifneq ($(SSL_BUILDER),)
50
+
51
+	DEFS += -I$(LOCALBASE)/wolfssl/include
52
+	LIBS += -L$(LOCALBASE)/lib \
53
+			-L$(LOCALBASE)/lib64  \
54
+			-lwolfssl
55
+endif # ifneq ($(SSL_BUILDER),)
56
+
57
+LIBS+= $(TLS_EXTRA_LIBS)
58
+
59
+# dcm: tls.cfg installed via local 'install-cfg' to update paths
60
+#MOD_INSTALL_CFGS=tls.cfg
61
+
62
+include ../../Makefile.modules
63
+
64
+install-tls-cert: $(cfg_prefix)/$(cfg_dir)
65
+	MAIN_NAME=$(MAIN_NAME) ./tls_cert.sh -d $(cfg_prefix)/$(cfg_dir)
66
+
67
+install-cfg:
68
+	@if ! [ -d $(cfg_prefix)/$(cfg_dir) ]; then \
69
+		mkdir -p "$(cfg_prefix)/$(cfg_dir)" ; \
70
+	fi
71
+	@$(call try_err, $(INSTALL_TOUCH) \
72
+			"$(cfg_prefix)/$(cfg_dir)tls.cfg.sample" )
73
+	@sed -e "s#\/usr/local/etc/kamailio/#$(cfg_target)#g" \
74
+			-e "s#kamailio-selfsigned#$(MAIN_NAME)-selfsigned#g" \
75
+				< ./tls.cfg > "$(cfg_prefix)/$(cfg_dir)tls.cfg.sample"
76
+	@if [ -z "${skip_cfg_install}" -a \
77
+			! -f "$(cfg_prefix)/$(cfg_dir)tls.cfg" ]; then \
78
+		mv -f "$(cfg_prefix)/$(cfg_dir)tls.cfg.sample" \
79
+						"$(cfg_prefix)/$(cfg_dir)tls.cfg" ; \
80
+	fi
81
+
0 82
new file mode 100644
... ...
@@ -0,0 +1,1713 @@
1
+TLS Module
2
+
3
+Andrei Pelinescu-Onciul
4
+
5
+   iptelorg GmbH
6
+
7
+Carsten Bock
8
+
9
+   ng-voice GmbH
10
+
11
+Olle E. Johansson
12
+
13
+   Edvina AB
14
+
15
+   Copyright © 2007 iptelorg GmbH
16
+
17
+   Copyright © 2014 ng-voice GmbH
18
+     __________________________________________________________________
19
+
20
+   Table of Contents
21
+
22
+   1. Admin Guide
23
+
24
+        1. Overview
25
+        2. Quick Start
26
+        3. Important Notes
27
+        4. Compiling the TLS Module
28
+        5. TLS and Low Memory
29
+        6. TLS Debugging
30
+        7. Known Limitations
31
+        8. Quick Certificate Howto
32
+        9. HSM Howto
33
+        10. Parameters
34
+
35
+              10.1. tls_method (string)
36
+              10.2. certificate (string)
37
+              10.3. private_key (string)
38
+              10.4. ca_list (string)
39
+              10.5. ca_path (str)
40
+              10.6. crl (string)
41
+              10.7. verify_certificate (boolean)
42
+              10.8. verify_depth (integer)
43
+              10.9. require_certificate (boolean)
44
+              10.10. cipher_list (string)
45
+              10.11. server_name (string)
46
+              10.12. connection_timeout (int)
47
+              10.13. tls_disable_compression (boolean)
48
+              10.14. ssl_release_buffers (integer)
49
+              10.15. ssl_freelist_max_len (integer)
50
+              10.16. ssl_max_send_fragment (integer)
51
+              10.17. ssl_read_ahead (boolean)
52
+              10.18. send_close_notify (boolean)
53
+              10.19. con_ct_wq_max (integer)
54
+              10.20. ct_wq_max (integer)
55
+              10.21. ct_wq_blk_size (integer)
56
+              10.22. tls_log (int)
57
+              10.23. tls_debug (int)
58
+              10.24. low_mem_threshold1 (integer)
59
+              10.25. low_mem_threshold2 (integer)
60
+              10.26. tls_force_run (boolean)
61
+              10.27. session_cache (boolean)
62
+              10.28. session_id (str)
63
+              10.29. renegotiation (boolean)
64
+              10.30. config (string)
65
+              10.31. xavp_cfg (string)
66
+              10.32. event_callback (str)
67
+              10.33. rand_engine (str)
68
+              10.34. engine (string)
69
+              10.35. engine_config (string)
70
+              10.36. engine_algorithms (string)
71
+              10.37. verify_client (string)
72
+
73
+        11. Functions
74
+
75
+              11.1. is_peer_verified()
76
+              11.2. tls_set_connect_server_id(srvid)
77
+
78
+        12. RPC Commands
79
+
80
+              12.1. tls.info
81
+              12.2. tls.list
82
+              12.3. tls.options
83
+              12.4. tls.reload
84
+
85
+        13. Status
86
+
87
+              13.1. License
88
+              13.2. History
89
+
90
+        14. Event Routes
91
+
92
+              14.1. event_route[tls:connection-out]
93
+
94
+        15. TLS With Database Backend
95
+
96
+   List of Examples
97
+
98
+   1.1. Quick Start Basic Config
99
+   1.2. Compiling TLS with Debug Messages
100
+   1.3. Set tls_method parameter
101
+   1.4. Set certificate parameter
102
+   1.5. Set private_key parameter
103
+   1.6. Set ca_list parameter
104
+   1.7. Set ca_path parameter
105
+   1.8. Set crl parameter
106
+   1.9. Set verify_certificate parameter
107
+   1.10. Set verify_depth parameter
108
+   1.11. Set require_certificate parameter
109
+   1.12. Set cipher_list parameter
110
+   1.13. Set server_name parameter
111
+   1.14. Set connection_timeout parameter
112
+   1.15. Set tls.connection_timeout at runtime
113
+   1.16. Set tls_disable_compression parameter
114
+   1.17. Set ssl_release_buffers parameter
115
+   1.18. Set ssl_freelist_max_len parameter
116
+   1.19. Set ssl_max_send_fragment parameter
117
+   1.20. Set ssl_read_ahead parameter
118
+   1.21. Set send_close_notify parameter
119
+   1.22. Set tls.send_close_notify at runtime
120
+   1.23. Set con_ct_wq_max parameter
121
+   1.24. Set tls.con_ct_wq_max at runtime
122
+   1.25. Set ct_wq_max parameter
123
+   1.26. Set tls.ct_wq_max at runtime
124
+   1.27. Set ct_wq_blk_size parameter
125
+   1.28. Set tls.ct_wq_max at runtime
126
+   1.29. Set tls_log parameter
127
+   1.30. Set tls.log at runtime
128
+   1.31. Set tls_debug parameter
129
+   1.32. Set tls.debug at runtime
130
+   1.33. Set low_mem_threshold1 parameter
131
+   1.34. Set tls.low_mem_threshold1 at runtime
132
+   1.35. Set tls.low_mem_threshold2 parameter
133
+   1.36. Set tls.low_mem_threshold2 at runtime
134
+   1.37. Set tls_force_run parameter
135
+   1.38. Set session_cache parameter
136
+   1.39. Set session_id parameter
137
+   1.40. Set renegotiation parameter
138
+   1.41. Sample TLS Config File
139
+   1.42. Set config parameter
140
+   1.43. Change and reload the TLS configuration at runtime
141
+   1.44. Set xavp_cfg parameter
142
+   1.45. Set event_callback parameter
143
+   1.46. Set rand_engine parameter
144
+   1.47. Set verify_client modparam parameter
145
+   1.48. Set verify_client tls.cfg parameter
146
+   1.49. is_peer_verified usage
147
+   1.50. tls_set_connect_server_id usage
148
+   1.51. Use of event_route[tls:connection-out]
149
+
150
+Chapter 1. Admin Guide
151
+
152
+   Table of Contents
153
+
154
+   1. Overview
155
+   2. Quick Start
156
+   3. Important Notes
157
+   4. Compiling the TLS Module
158
+   5. TLS and Low Memory
159
+   6. TLS Debugging
160
+   7. Known Limitations
161
+   8. Quick Certificate Howto
162
+   9. HSM Howto
163
+   10. Parameters
164
+
165
+        10.1. tls_method (string)
166
+        10.2. certificate (string)
167
+        10.3. private_key (string)
168
+        10.4. ca_list (string)
169
+        10.5. ca_path (str)
170
+        10.6. crl (string)
171
+        10.7. verify_certificate (boolean)
172
+        10.8. verify_depth (integer)
173
+        10.9. require_certificate (boolean)
174
+        10.10. cipher_list (string)
175
+        10.11. server_name (string)
176
+        10.12. connection_timeout (int)
177
+        10.13. tls_disable_compression (boolean)
178
+        10.14. ssl_release_buffers (integer)
179
+        10.15. ssl_freelist_max_len (integer)
180
+        10.16. ssl_max_send_fragment (integer)
181
+        10.17. ssl_read_ahead (boolean)
182
+        10.18. send_close_notify (boolean)
183
+        10.19. con_ct_wq_max (integer)
184
+        10.20. ct_wq_max (integer)
185
+        10.21. ct_wq_blk_size (integer)
186
+        10.22. tls_log (int)
187
+        10.23. tls_debug (int)
188
+        10.24. low_mem_threshold1 (integer)
189
+        10.25. low_mem_threshold2 (integer)
190
+        10.26. tls_force_run (boolean)
191
+        10.27. session_cache (boolean)
192
+        10.28. session_id (str)
193
+        10.29. renegotiation (boolean)
194
+        10.30. config (string)
195
+        10.31. xavp_cfg (string)
196
+        10.32. event_callback (str)
197
+        10.33. rand_engine (str)
198
+        10.34. engine (string)
199
+        10.35. engine_config (string)
200
+        10.36. engine_algorithms (string)
201
+        10.37. verify_client (string)
202
+
203
+   11. Functions
204
+
205
+        11.1. is_peer_verified()
206
+        11.2. tls_set_connect_server_id(srvid)
207
+
208
+   12. RPC Commands
209
+
210
+        12.1. tls.info
211
+        12.2. tls.list
212
+        12.3. tls.options
213
+        12.4. tls.reload
214
+
215
+   13. Status
216
+
217
+        13.1. License
218
+        13.2. History
219
+
220
+   14. Event Routes
221
+
222
+        14.1. event_route[tls:connection-out]
223
+
224
+   15. TLS With Database Backend
225
+
226
+1. Overview
227
+
228
+   This module implements the TLS transport for Kamailio using the OpenSSL
229
+   library (http://www.openssl.org). To enable the Kamailio TLS support
230
+   this module must be loaded and enable_tls=yes core setting must be
231
+   added to the Kamailio config file.
232
+
233
+   IMPORTANT: the tls module must be loaded before any other Kamailio
234
+   module that uses libssl (OpenSSL library). A safe option is to have the
235
+   tls module loaded first (be in the first "loadmodule" in Kamailio.cfg).
236
+
237
+   IMPORTANT: using this module compiled with newer versions of libssl
238
+   (e.g., v1.1+) may require Kamailio to be started with --atexit=no
239
+   command line parameters to avoid calling C atexit callbacks inside the
240
+   process ending during daemonize procedure as well as during shut down,
241
+   which can lead to crashes because it destroys and then accesses shared
242
+   memory. For example, such case has been reported for Ubuntu 20.04 or
243
+   RedHat 8.
244
+
245
+2. Quick Start
246
+
247
+   The default kamailio.cfg file has basic tls support included, it has to
248
+   be enabled with "#!define WITH_TLS" directive.
249
+
250
+   The most important parameters to set the path to the public certificate
251
+   and private key files. You can either have them in different file or in
252
+   the same file in PEM format. The parameters for them are certificate
253
+   and private_key. They can be given as modparam or or provided in the
254
+   profiles of tls.cfg file.
255
+
256
+   When installing tls module of kamailio, a sample 'tls.cfg' file is
257
+   deployed in the same folder with 'kamailio.cfg', along with freshly
258
+   generated self signed certificates.
259
+
260
+   HINT: be sure you have enable_tls=yes to your kamailio.cfg.
261
+
262
+   Example 1.1. Quick Start Basic Config
263
+#...
264
+loadmodule "sl.so"
265
+loadmodule "tls.so"
266
+
267
+modparam("tls", "private_key", "./server-test.pem")
268
+modparam("tls", "certificate", "./server-test.pem")
269
+modparam("tls", "ca_list", "./calist.pem")
270
+
271
+enable_tls=yes
272
+
273
+request_route {
274
+        if(proto != TLS) {
275
+                sl_send_reply("403", "Accepting TLS Only");
276
+                exit;
277
+        }
278
+        ...
279
+}
280
+
281
+3. Important Notes
282
+
283
+   The TLS module needs some special options enabled when compiling
284
+   Kamailio. These options are enabled by default, however in case you're
285
+   using a modified Kamailio version or Makefile, make sure that you
286
+   enable -DUSE_TLS and -DTLS_HOOKS (or compile with make TLS_HOOKS=1
287
+   which will take care of both options).
288
+
289
+   To quickly check if your Kamailio version was compiled with these
290
+   options, run kamailio -V and look for USE_TLS and TLS_HOOKS among the
291
+   flags.
292
+
293
+   For OpenSSL (libssl) v1.1.x, it is required to preload
294
+   'openssl_mutex_shared' library shipped by Kamailio. For more details
295
+   see 'src/modules/tls/openssl_mutex_shared/README.md'.
296
+
297
+   This module includes several workarounds for various Openssl bugs (like
298
+   compression and Kerberos using the wrong memory allocations functions,
299
+   low memory problems a.s.o). On startup it will try to enable the needed
300
+   workarounds based on the OpenSSL library version. Each time a known
301
+   problem is detected and a workaround is enabled, a message will be
302
+   logged. In general it is recommended to compile this module on the same
303
+   machine or a similar machine to where kamailio will be run or to link
304
+   it statically with libssl. For example if on the compile machine
305
+   OpenSSL does not have the Kerberos support enabled, but on the target
306
+   machine a Kerberos enabled OpenSSL library is installed, Kamailio
307
+   cannot apply the needed workarounds and will refuse to start. The same
308
+   thing will happen if the OpenSSL versions are too different (to force
309
+   Kamailio startup anyway, see the tls_force_run module parameter).
310
+
311
+   Compression is fully supported if you have a new enough OpenSSL version
312
+   (starting with 0.9.8). Although there are some problems with zlib
313
+   compression in currently deployed OpenSSL versions (up to and including
314
+   0.9.8d, see openssl bug #1468), the TLS module will automatically
315
+   switch to its own fixed version. Note however that starting with
316
+   Kamailio 3.1 compression is not enabled by default, due to the huge
317
+   extra memory consumption that it causes (about 10x more memory). To
318
+   enable it use modparam("tls", "tls_disable_compression", 0) (see
319
+   tls_disable_compression).
320
+
321
+   The TLS module includes workarounds for the following known openssl
322
+   bugs:
323
+     * openssl #1204 (disable SS_OP_TLS_BLOCK_PADDING_BUG if compression
324
+       is enabled, for versions between 0.9.8 and 0.9.8c),
325
+     * openssl #1468 (fix zlib compression memory allocation),
326
+     * openssl #1467 (kerberos support will be disabled if the openssl
327
+       version is less than 0.9.8e-beta1)
328
+     * openssl #1491 (stop using tls in low memory situations due to the
329
+       very high risk of openssl crashing or leaking memory).
330
+
331
+   The bug reports can be viewed at http://rt.openssl.org/.
332
+
333
+4. Compiling the TLS Module
334
+
335
+   In most case compiling the TLS module is as simple as:
336
+make -C modules/tls
337
+
338
+   or
339
+make modules modules=modules/tls
340
+
341
+   or (compiling whole Kamailio and the tls module)
342
+make all include_modules=tls
343
+
344
+   .
345
+
346
+   However in some cases the OpenSSL library requires linking with other
347
+   libraries. For example compiling the OpenSSL library with Kerberos and
348
+   zlib-shared support will require linking the TLS module with libkrb5
349
+   and libz. In this case just add TLS_EXTRA_LIBS="library list" to make's
350
+   command line. E.g.:
351
+make TLS_EXTRA_LIBS="-lkrb5 -lz" all include_modules=tls
352
+
353
+   In general, if Kamailio fails to start with a symbol not found error
354
+   when trying to load the TLS module (check the log), it means some
355
+   needed library was not linked and it must be added to TLS_EXTRA_LIBS
356
+
357
+   Elliptic Curve Diffie-Hellman (EDCH)-Ciphers are only supported in
358
+   OpenSSL 1.0.0e and later.
359
+
360
+5. TLS and Low Memory
361
+
362
+   The Openssl library doesn't handle low memory situations very well. If
363
+   memory allocations start to fail (due to memory shortage), Openssl can
364
+   crash or cause memory leaks (making the memory shortage even worse). As
365
+   of this writing all Openssl versions were affected (including 0.9.8e),
366
+   see Openssl bug #1491. The TLS module has some workarounds for
367
+   preventing this problem (see low_mem_treshold1 and low_mem_threshold2),
368
+   however starting Kamailio with enough shared memory is higly
369
+   recommended. When this is not possible a quick way to significantly
370
+   reduce Openssl memory usage it to disable compression (see
371
+   tls_disable_compression).
372
+
373
+6. TLS Debugging
374
+
375
+   Debugging messages can be selectively enabled by recompiling the TLS
376
+   module with a combination of the following defines:
377
+     * TLS_WR_DEBUG - debug messages for the write/send part.
378
+     * TLS_RD_DEBUG - debug messages for the read/receive part.
379
+     * TLS_BIO_DEBUG - debug messages for the custom BIO.
380
+
381
+   Example 1.2. Compiling TLS with Debug Messages
382
+make -C modules/tls extra_defs="-DTLS_WR_DEBUG -DTLS_RD_DEBUG"
383
+
384
+   To change the level at which the debug messages are logged, change the
385
+   tls_debug module parameter.
386
+
387
+7. Known Limitations
388
+
389
+   The private key must not be encrypted (Kamailio cannot ask you for a
390
+   password on startup).
391
+
392
+   The TLS certificate verifications ignores the certificate name, Subject
393
+   Altname and IP extensions, it just checks if the certificate is signed
394
+   by a recognized CA. One can use the select framework to try to overcome
395
+   this limitation (check in the script for the contents of various
396
+   certificate fields), but this is not only slow, but also not exactly
397
+   standard conforming (the verification should happen during TLS
398
+   connection establishment and not after).
399
+
400
+   TLS specific config reloading is not safe, so for now better don't use
401
+   it, especially under heavy traffic.
402
+
403
+   This documentation is incomplete. The provided selects are not
404
+   documented in this file. A list with all the ones implemented by the
405
+   TLS module can be found in the Cookbook https://www.kamailio.org/wiki/
406
+   in the section Selects for the respective version of Kamailio.
407
+
408
+8. Quick Certificate Howto
409
+
410
+   There are various ways to create, sign certificates and manage small
411
+   CAs (Certificate Authorities). If you are in a hurry and everything you
412
+   have are the installed OpenSSL libraries and utilities, read on.
413
+
414
+   Assumptions: we run our own CA.
415
+
416
+   Warning: in this example no key is encrypted. The client and server
417
+   private keys must not be encrypted (Kamailio doesn't support encrypted
418
+   keys), so make sure the corresponding files are readable only by
419
+   trusted people. You should use a password to protect your CA private
420
+   key.
421
+
422
+Assumptions
423
+------------
424
+
425
+The default openssl configuration (usually /etc/ssl/openssl.cnf)
426
+default_ca section is the one distributed with openssl and uses the default
427
+directories:
428
+
429
+...
430
+
431
+default_ca      = CA_default            # The default ca section
432
+
433
+[ CA_default ]
434
+
435
+dir             = ./demoCA              # Where everything is kept
436
+certs           = $dir/certs            # Where the issued certs are kept
437
+crl_dir         = $dir/crl              # Where the issued crl are kept
438
+database        = $dir/index.txt        # database index file.
439
+#unique_subject = no                    # Set to 'no' to allow creation of
440
+                                        # several certificates with same subject
441
+.
442
+new_certs_dir   = $dir/newcerts         # default place for new certs.
443
+
444
+certificate     = $dir/cacert.pem       # The CA certificate
445
+serial          = $dir/serial           # The current serial number
446
+crlnumber       = $dir/crlnumber        # the current CRL number
447
+crl             = $dir/crl.pem          # The current CRL
448
+private_key     = $dir/private/cakey.pem# The private key
449
+RANDFILE        = $dir/private/.rand    # private random number file
450
+
451
+...
452
+
453
+If this is not the case create a new OpenSSL config file that uses the above
454
+paths for the default CA and add to all the openssl commands:
455
+ -config filename. E.g.:
456
+        openssl ca -config my_openssl.cnf -in kamailio1_cert_req.pem -out kamail
457
+io1_cert.pem
458
+
459
+
460
+Creating the CA certificate
461
+---------------------------
462
+1. Create the CA directory
463
+        mkdir ca
464
+        cd ca
465
+
466
+2. Create the CA directory structure and files  (see ca(1))
467
+        mkdir demoCA            #default CA name, edit /etc/ssl/openssl.cnf
468
+        mkdir  demoCA/private
469
+        mkdir demoCA/newcerts
470
+        touch demoCA/index.txt
471
+        echo 01 >demoCA/serial
472
+        echo 01 >demoCA/crlnumber
473
+
474
+2. Create CA private key
475
+        openssl genrsa -out demoCA/private/cakey.pem 2048
476
+        chmod 600 demoCA/private/cakey.pem
477
+
478
+3. Create CA self-signed certificate
479
+        openssl req -out demoCA/cacert.pem   -x509 -new -key demoCA/private/cake
480
+y.pem
481
+
482
+
483
+Creating a server/client TLS certificate
484
+----------------------------------------
485
+1. Create a certificate request (and its private key in privkey.pem)
486
+
487
+        openssl req -out kamailio1_cert_req.pem -new -nodes
488
+
489
+        WARNING: the organization name should be the same as in the CA certifica
490
+te.
491
+
492
+2. Sign it with the CA certificate
493
+        openssl ca -in kamailio1_cert_req.pem -out kamailio1_cert.pem
494
+
495
+3. Copy kamailio1_cert.pem to your Kamailio configuration dir
496
+
497
+
498
+Setting Kamailio to use the TLS certificate
499
+---------------------------------------------
500
+1. Create the CA list file:
501
+        for each of your CA certificates that you intend to use do:
502
+                cat cacert.pem >>calist.pem
503
+
504
+2. Copy your Kamailio certificate, private key and ca list file to your
505
+        intended machine (preferably in your Kamailio configuration directory,
506
+         this is the default place Kamailio searches for).
507
+
508
+3. Set up Kamailio.cfg to use the certificate
509
+        if your Kamailio certificate name is different from cert.pem or it is no
510
+t
511
+        placed in Kamailio cfg. directory, add to your kamailio.cfg:
512
+                modparam("tls", "certificate", "/path/cert_file_name")
513
+
514
+4. Set up Kamailio to use the private key
515
+        if your private key is not contained in the same file as the certificate
516
+        (or the certificate name is not the default cert.pem), add to your
517
+         Kamailio.cfg:
518
+                modparam("tls", "private_key", "/path/private_key_file")
519
+
520
+5. Set up Kamailio to use the CA list (optional)
521
+   The CA list is not used for your server certificate - it's used to approve ot
522
+her servers
523
+   and clients connecting to your server with a client certificate or for approv
524
+ing
525
+   a certificate used by a server your server connects to.
526
+        add to your Kamailio.cfg:
527
+                modparam("tls", "ca_list", "/path/ca_list_file")
528
+
529
+6. Set up TLS authentication options:
530
+                modparam("tls", "verify_certificate", 1)
531
+                modparam("tls", "require_certificate", 1)
532
+        (for more information see the module parameters documentation)
533
+
534
+
535
+Revoking a certificate and using a CRL
536
+--------------------------------------
537
+1. Revoking a certificate:
538
+        openssl ca -revoke bad_cert.pem
539
+
540
+2. Generate/update the certificate revocation list:
541
+        openssl ca -gencrl -out my_crl.pem
542
+
543
+3. Copy my_crl.pem to your Kamailio config. dir
544
+
545
+4. Set up Kamailio to use the CRL:
546
+                modparam("tls", "crl", "path/my_crl.pem")
547
+
548
+9. HSM Howto
549
+
550
+   This documents OpenSSL engine support for private keys in HSM.
551
+
552
+   Assumptions: an OpenSSL engine configured with private key. We still
553
+   require the certificate file and list of CA certificates per a regular
554
+   TLS configuration.
555
+
556
+Thales Luna Example
557
+--------------------
558
+
559
+...
560
+# Example for Thales Luna
561
+modparam("tls", "engine", "gem")
562
+modparam("tls", "engine_config", "/usr/local/etc/kamailio/thales.cnf")
563
+modparam("tls", "engine_algorithms", "EC")
564
+...
565
+
566
+/usr/local/etc/kamailio/thales.cnf is a OpenSSL config format file used to
567
+bootstrap the engine, e.g., pass the PIN.
568
+
569
+...
570
+# the key kamailio is mandatory
571
+kamailio = openssl_init
572
+
573
+[ openssl_init ]
574
+engines = engine_section
575
+
576
+[ engine_section ]
577
+# gem is the name of the Thales Luna OpenSSL engine
578
+gem = gem_section
579
+
580
+[ gem_section ]
581
+# from Thales documentation
582
+dynamic_path = /usr/lib64/engines-1.1/gem.so
583
+ENGINE_INIT = 0:20:21:password=1234-ABCD-5678-EFGH
584
+...
585
+
586
+
587
+Thales nShield Connect
588
+----------------------
589
+
590
+Place holder
591
+
592
+10. Parameters
593
+
594
+   10.1. tls_method (string)
595
+   10.2. certificate (string)
596
+   10.3. private_key (string)
597
+   10.4. ca_list (string)
598
+   10.5. ca_path (str)
599
+   10.6. crl (string)
600
+   10.7. verify_certificate (boolean)
601
+   10.8. verify_depth (integer)
602
+   10.9. require_certificate (boolean)
603
+   10.10. cipher_list (string)
604
+   10.11. server_name (string)
605
+   10.12. connection_timeout (int)
606
+   10.13. tls_disable_compression (boolean)
607
+   10.14. ssl_release_buffers (integer)
608
+   10.15. ssl_freelist_max_len (integer)
609
+   10.16. ssl_max_send_fragment (integer)
610
+   10.17. ssl_read_ahead (boolean)
611
+   10.18. send_close_notify (boolean)
612
+   10.19. con_ct_wq_max (integer)
613
+   10.20. ct_wq_max (integer)
614
+   10.21. ct_wq_blk_size (integer)
615
+   10.22. tls_log (int)
616
+   10.23. tls_debug (int)
617
+   10.24. low_mem_threshold1 (integer)
618
+   10.25. low_mem_threshold2 (integer)
619
+   10.26. tls_force_run (boolean)
620
+   10.27. session_cache (boolean)
621
+   10.28. session_id (str)
622
+   10.29. renegotiation (boolean)
623
+   10.30. config (string)
624
+   10.31. xavp_cfg (string)
625
+   10.32. event_callback (str)
626
+   10.33. rand_engine (str)
627
+   10.34. engine (string)
628
+   10.35. engine_config (string)
629
+   10.36. engine_algorithms (string)
630
+   10.37. verify_client (string)
631
+
632
+10.1. tls_method (string)
633
+
634
+   Sets the TLS protocol method. Possible values are:
635
+     * TLSv1.2+ - TLSv1.2 or newer (TLSv1.3, ...) connections are accepted
636
+       (available starting with openssl/libssl v1.1.1)
637
+     * TLSv1.2 - only TLSv1.2 connections are accepted (available starting
638
+       with openssl/libssl v1.0.1e)
639
+     * TLSv1.1+ - TLSv1.1 or newer (TLSv1.2, ...) connections are accepted
640
+       (available starting with openssl/libssl v1.0.1)
641
+     * TLSv1.1 - only TLSv1.1 connections are accepted (available starting
642
+       with openssl/libssl v1.0.1)
643
+     * TLSv1+ - TLSv1.0 or newer (TLSv1.1, TLSv1.2, ...) connections are
644
+       accepted.
645
+     * TLSv1 - only TLSv1 (TLSv1.0) connections are accepted. This is the
646
+       default value.
647
+     * SSLv3 - only SSLv3 connections are accepted. Note: you shouldn't
648
+       use SSLv3 for anything which should be secure.
649
+     * SSLv2 - only SSLv2 connections, for old clients. Note: you
650
+       shouldn't use SSLv2 for anything which should be secure. Newer
651
+       versions of OpenSSL libraries don't include support for it anymore.
652
+     * SSLv23 - any of the SSLv2, SSLv3 and TLSv1 or newer methods will be
653
+       accepted.
654
+       From the OpenSSL manual: "A TLS/SSL connection established with
655
+       these methods may understand the SSLv3, TLSv1, TLSv1.1 and TLSv1.2
656
+       protocols. If extensions are required (for example server name) a
657
+       client will send out TLSv1 client hello messages including
658
+       extensions and will indicate that it also understands TLSv1.1,
659
+       TLSv1.2 and permits a fallback to SSLv3. A server will support
660
+       SSLv3, TLSv1, TLSv1.1 and TLSv1.2 protocols. This is the best
661
+       choice when compatibility is a concern."
662
+       Note: For older OpenSSL library versions, this option allows SSLv2,
663
+       with hello messages done over SSLv2. You shouldn't use SSLv2 or
664
+       SSLv3 for anything which should be secure.
665
+
666
+   If RFC 3261 conformance is desired, at least TLSv1 must be used. For
667
+   compatibility with older clients SSLv23 is the option, but again, be
668
+   aware of security concerns, SSLv2/3 being considered very insecure by
669
+   2014. For current information about what's considered secure, please
670
+   consult, IETF BCP 195, currently RFC 7525 - "Recommendations for Secure
671
+   Use of Transport Layer Security (TLS) and Datagram Transport Layer
672
+   Security (DTLS)"
673
+
674
+   Example 1.3. Set tls_method parameter
675
+...
676
+modparam("tls", "tls_method", "TLSv1")
677
+...
678
+
679
+10.2. certificate (string)
680
+
681
+   Sets the certificate file name. The certificate file can also contain
682
+   the private key in PEM format.
683
+
684
+   If the file name starts with a '.' the path will be relative to the
685
+   working directory (at runtime). If it starts with a '/' it will be an
686
+   absolute path and if it starts with anything else the path will be
687
+   relative to the main config file directory (e.g.: for kamailio -f
688
+   /etc/kamailio/kamailio.cfg it will be relative to /etc/kamailio/).
689
+
690
+   The default value is /usr/local/etc/kamailio/cert.pem
691
+
692
+   Example 1.4. Set certificate parameter
693
+...
694
+modparam("tls", "certificate", "/usr/local/etc/kamailio/my_certificate.pem")
695
+...
696
+
697
+10.3. private_key (string)
698
+
699
+   Sets the private key file name. The private key can be in the same file
700
+   as the certificate or in a separate file, specified by this
701
+   configuration parameter.
702
+
703
+   If the file name starts with a '.' the path will be relative to the
704
+   working directory (at runtime). If it starts with a '/' it will be an
705
+   absolute path and if it starts with anything else the path will be
706
+   relative to the main config file directory (e.g.: for kamailio -f
707
+   /etc/kamailio/kamailio.cfg it will be relative to /etc/kamailio/).
708
+
709
+   Note: the private key can be contained in the same file as the
710
+   certificate (just append it to the certificate file, e.g.: cat pkey.pem
711
+   >> cert.pem)
712
+
713
+   The default value is /usr/local/etc/kamailio/cert.pem
714
+
715
+   Example 1.5. Set private_key parameter
716
+...
717
+modparam("tls", "private_key", "/usr/local/etc/kamailio/my_pkey.pem")
718
+...
719
+
720
+10.4. ca_list (string)
721
+
722
+   Sets the CA list file name. This file contains a list of all the
723
+   trusted CAs certificates used when connecting to other SIP
724
+   implementations. If a signature in a certificate chain belongs to one
725
+   of the listed CAs, the verification of that certificate will succeed.
726
+
727
+   If the file name starts with a '.' the path will be relative to the
728
+   working directory (at runtime). If it starts with a '/' it will be an
729
+   absolute path and if it starts with anything else the path will be
730
+   relative to the main config file directory (e.g.: for kamailio -f
731
+   /etc/kamailio/kamailio.cfg it will be relative to /etc/kamailio/).
732
+
733
+   By default the CA file is not set.
734
+
735
+   An easy way to create the CA list is to append each trusted trusted CA
736
+   certificate in the PEM format to one file, e.g.:
737
+for f in trusted_cas/*.pem ; do cat "$f" >> ca_list.pem ; done
738
+
739
+   See also verify_certificate, verify_depth, require_certificate and crl.
740
+
741
+   Example 1.6. Set ca_list parameter
742
+...
743
+modparam("tls", "ca_list", "/usr/local/etc/kamailio/ca_list.pem")
744
+...
745
+
746
+10.5. ca_path (str)
747
+
748
+   Sets the path with the trusted CA files, to be given as parameter
749
+   SSL_CTX_load_verify_locations(). The certificates in ca_path are only
750
+   looked up when required, e.g. when building the certificate chain or
751
+   when actually performing the verification of a peer certificate. They
752
+   are not given to the client (not loaded to be provided to
753
+   SSL_CTX_set_client_CA_list()), only the ones in ca_list files are sent
754
+   to the client. It requires to use c_rehash to generate the hash map for
755
+   certificate search, for more see the manual of libssl for
756
+   SSL_CTX_load_verify_locations() function.
757
+
758
+   By default it is not set.
759
+
760
+   Example 1.7. Set ca_path parameter
761
+...
762
+modparam("tls", "ca_path", "/usr/local/etc/kamailio/ca")
763
+...
764
+
765
+10.6. crl (string)
766
+
767
+   Sets the certificate revocation list (CRL) file name. This file
768
+   contains a list of revoked certificates. Any attempt to verify a
769
+   revoked certificate will fail.
770
+
771
+   If not set, no CRL list will be used.
772
+
773
+   If the file name starts with a '.' the path will be relative to the
774
+   working directory (at runtime). If it starts with a '/' it will be an
775
+   absolute path and if it starts with anything else the path will be
776
+   relative to the main config file directory (e.g.: for kamailio -f
777
+   /etc/kamailio/kamailio.cfg it will be relative to /etc/kamailio/).
778
+
779
+Note
780
+
781
+   If set, require_certificate should also be set or it will not have any
782
+   effect.
783
+
784
+   By default the CRL file name is not set.
785
+
786
+   To update the CRL in a running Kamailio, make sure you configure TLS
787
+   via a separate TLS config file (the config modparam) and issue a
788
+   tls.reload RPC call, e.g.:
789
+ $ kamcmd tls.reload
790
+
791
+   A quick way to create the CRL in PEM format, using OpenSSL is:
792
+ $ openssl ca -gencrl -keyfile cacert.key -cert cacert.pem -out my_crl.pem
793
+
794
+   my_crl.pem will contain the signed list of the revoked certificates.
795
+
796
+   To revoke a TLS certificate use something like:
797
+ $ openssl ca -revoke bad_cert.pem -keyfile cacert.key -cert cacert.pem
798
+
799
+   and then refresh the crl file using the command above.
800
+
801
+   To display the CRL contents use:
802
+ $ openssl crl -in crl.pem -noout -text
803
+
804
+   See also ca_list, verify_certificate, verify_depth and
805
+   require_certificate.
806
+
807
+   Example 1.8. Set crl parameter
808
+...
809
+modparam("tls", "crl", "/usr/local/etc/kamailio/crl.pem")
810
+...
811
+
812
+10.7. verify_certificate (boolean)
813
+
814
+   If enabled it will force certificate verification when connecting to
815
+   other SIP servers.. For more information see the verify(1) OpenSSL man
816
+   page.
817
+
818
+   Note: the certificate verification will always fail if the ca_list is
819
+   empty.
820
+
821
+   See also: ca_list, require_certificate, verify_depth.
822
+
823
+   By default the certificate verification is off.
824
+
825
+   Example 1.9. Set verify_certificate parameter
826
+...
827
+modparam("tls", "verify_certificate", 1)
828
+...
829
+
830
+10.8. verify_depth (integer)
831
+
832
+   Sets how far up the certificate chain will the certificate verification
833
+   go in the search for a trusted CA.
834
+
835
+   See also: ca_list, require_certificate, verify_certificate,
836
+
837
+   The default value is 9.
838
+
839
+   Example 1.10. Set verify_depth parameter
840
+...
841
+modparam("tls", "verify_depth", 9)
842
+...
843
+
844
+10.9. require_certificate (boolean)
845
+
846
+   When enabled Kamailio will require a certificate from a client
847
+   connecting to the TLS port. If the client does not offer a certificate
848
+   and verify_certificate is on, certificate verification will fail.
849
+
850
+   The default value is off.
851
+
852
+   Example 1.11. Set require_certificate parameter
853
+...
854
+modparam("tls", "require_certificate", 1)
855
+...
856
+
857
+10.10. cipher_list (string)
858
+
859
+   Sets the list of accepted ciphers. The list consists of cipher strings
860
+   separated by colons. For more information on the cipher list format see
861
+   the cipher(1) OpenSSL man page.
862
+
863
+   The default value is not set (all the OpenSSL supported ciphers are
864
+   enabled).
865
+
866
+   Example 1.12. Set cipher_list parameter
867
+...
868
+modparam("tls", "cipher_list", "HIGH")
869
+...
870
+
871
+10.11. server_name (string)
872
+
873
+   Sets the Server Name Indication (SNI) value.
874
+
875
+   This is a TLS extension enabling one TLS server to serve multiple host
876
+   names with unique certificates.
877
+
878
+   The default value is empty (not set).
879
+
880
+   Example 1.13. Set server_name parameter
881
+...
882
+modparam("tls", "server_name", "kamailio.org")
883
+...
884
+
885
+10.12. connection_timeout (int)
886
+
887
+   Sets the amount of time after which an idle TLS connection will be
888
+   closed, if no I/O ever occurred after the initial open. If an I/O event
889
+   occurs, the timeout will be extended with tcp_connection_lifetime. The
890
+   value is expressed in seconds.
891
+
892
+   The default value is 10 min.
893
+
894
+   If the value set is -1, the connection will never be close on idle.
895
+
896
+   This setting can be changed also at runtime, via the RPC interface and
897
+   config framework. The config variable name is tls.connection_timeout.
898
+
899
+   Example 1.14. Set connection_timeout parameter
900
+...
901
+modparam("tls", "connection_timeout", 60)
902
+...
903
+
904
+   Example 1.15. Set tls.connection_timeout at runtime
905
+ $ kamcmd cfg.set_now_int tls connection_timeout 180
906
+
907
+10.13. tls_disable_compression (boolean)
908
+
909
+   If set compression over TLS will be disabled. Note that compression
910
+   uses a lot of memory (about 10x more then with the compression
911
+   disabled), so if you want to minimize memory usage is a good idea to
912
+   disable it. TLS compression also expose you for the CRIME security
913
+   vulnerability.
914
+
915
+   By default TLS compression is disabled.
916
+
917
+   Example 1.16. Set tls_disable_compression parameter
918
+...
919
+modparam("tls", "tls_disable_compression", 0) # enable
920
+...
921
+
922
+10.14. ssl_release_buffers (integer)
923
+
924
+   Release internal OpenSSL read or write buffers as soon as they are no
925
+   longer needed. Combined with ssl_freelist_max_len has the potential of
926
+   saving a lot of memory ( ~ 32k per connection in the default
927
+   configuration, or 16k + ssl_max_send_fragment). For Kamailio versions >
928
+   3.0 it makes little sense to disable it (0) since the tls module
929
+   already has its own internal buffering.
930
+
931
+   A value of -1 would not change this option from its openssl default.
932
+   Use 0 or 1 for enable/disable.
933
+
934
+   By default the value is 1 (enabled).
935
+
936
+Note
937
+
938
+   This option is supported only for OpenSSL versions >= 1.0.0. On all the
939
+   other versions attempting to change the default will trigger an error.
940
+
941
+   Example 1.17. Set ssl_release_buffers parameter
942
+modparam("tls", "ssl_release_buffers", 1)
943
+
944
+10.15. ssl_freelist_max_len (integer)
945
+
946
+   Sets the maximum number of free memory chunks, that OpenSSL will keep
947
+   per connection. Setting it to 0 would cause any unused memory chunk to
948
+   be immediately freed, reducing the memory footprint. A too large value
949
+   would result in extra memory consumption.
950
+
951
+   Should be combined with ssl_release_buffers.
952
+
953
+   A value of -1 has a special meaning: the OpenSSL default will be used
954
+   (no attempt on changing the value will be made). For OpenSSL 1.0 the
955
+   internal default is 32.
956
+
957
+   By default the value is 0 (no freelist).
958
+
959
+Note
960
+
961
+   This option is supported only for OpenSSL versions >= 1.0.0. On all the
962
+   other versions attempting to change the default will trigger an error.
963
+
964
+   Example 1.18. Set ssl_freelist_max_len parameter
965
+modparam("tls", "ssl_freelist_max_len", 0)
966
+
967
+10.16. ssl_max_send_fragment (integer)
968
+
969
+   Sets the maximum number of bytes (from the clear text) sent into one
970
+   TLS record. Valid values are between 512 and 16384. Note however that
971
+   even valid low values might not be big enough to allow a successful
972
+   handshake (try minimum 1024).
973
+
974
+   Lower values would lead to less memory usage, but values lower then the
975
+   typical Kamailio write size would incur a slight performance penalty.
976
+   Good values are bigger then the size of the biggest SIP packet one
977
+   normally expects to forward. For example in most setups 2048 would be a
978
+   good value.
979
+
980
+Note
981
+
982
+   Values on the lower side, even if valid (> 512), might not allow for a
983
+   successful initial handshake. This happens if the certificate does not
984
+   fit inside one send fragment. Values lower then 1024 should not be
985
+   used. Even with higher values, if the handshake fails, try increasing
986
+   the value.
987
+
988
+   A value of -1 has a special meaning: the OpenSSL default will be used
989
+   (no attempt on changing the value will be made).
990
+
991
+   By default the value is -1 (the OpenSSL default, which at least in
992
+   OpenSSL 1.0.0 is ~ 16k).
993
+
994
+Note
995
+
996
+   This option is supported only for OpenSSL versions >= 0.9.9. On all the
997
+   other versions attempting to change the default will trigger an error.
998
+
999
+   Example 1.19. Set ssl_max_send_fragment parameter
1000
+modparam("tls", "ssl_max_send_fragment", 4096)
1001
+
1002
+10.17. ssl_read_ahead (boolean)
1003
+
1004
+   Enables read ahead, reducing the number of internal OpenSSL BIO read()
1005
+   calls. This option has only debugging value, in normal circumstances it
1006
+   should not be changed from the default.
1007
+
1008
+   When disabled OpenSSL will make at least 2 BIO read() calls per
1009
+   received record: one to get the record header and one to get the rest
1010
+   of the record.
1011
+
1012
+   The TLS module buffers internally all read()s and defines its own fast
1013
+   BIO so enabling this option would only cause more memory consumption
1014
+   and a minor slow-down (extra memcpy).
1015
+
1016
+   A value of -1 has a special meaning: the OpenSSL default will be used
1017
+   (no attempt on changing the value will be made).
1018
+
1019
+   By default the value is 0 (disabled).
1020
+
1021
+   Example 1.20. Set ssl_read_ahead parameter
1022
+modparam("tls", "ssl_read_ahead", 1)
1023
+
1024
+10.18. send_close_notify (boolean)
1025
+
1026
+   Enables/disables sending close notify alerts prior to closing the
1027
+   corresponding TCP connection. Sending the close notify prior to TCP
1028
+   shutdown is "nicer" from a TLS point of view, but it has a measurable
1029
+   performance impact. Default: off. Can be set at runtime
1030
+   (tls.send_close_notify).
1031
+
1032
+   The default value is 0 (off).
1033
+
1034
+   It can be changed also at runtime, via the RPC interface and config
1035
+   framework. The config variable name is tls.send_close_notify.
1036
+
1037
+   Example 1.21. Set send_close_notify parameter
1038
+...
1039
+modparam("tls", "send_close_notify", 1)
1040
+...
1041
+
1042
+   Example 1.22. Set tls.send_close_notify at runtime
1043
+ $ kamcmd cfg.set_now_int tls send_close_notify 1
1044
+
1045
+10.19. con_ct_wq_max (integer)
1046
+
1047
+   Sets the maximum allowed per connection clear-text send queue size in
1048
+   bytes. This queue is used when data cannot be encrypted and sent
1049
+   immediately because of an ongoing TLS level renegotiation.
1050
+
1051
+   The default value is 65536 (64 Kb).
1052
+
1053
+   It can be changed also at runtime, via the RPC interface and config
1054
+   framework. The config variable name is tls.con_ct_wq_max.
1055
+
1056
+   Example 1.23. Set con_ct_wq_max parameter
1057
+...
1058
+modparam("tls", "con_ct_wq_max", 1048576)
1059
+...
1060
+
1061
+   Example 1.24. Set tls.con_ct_wq_max at runtime
1062
+ $ kamcmd cfg.set_now_int tls con_ct_wq_max 1048576
1063
+
1064
+10.20. ct_wq_max (integer)
1065
+
1066
+   Sets the maximum total number of bytes queued in all the clear-text
1067
+   send queues. These queues are used when data cannot be encrypted and
1068
+   sent immediately because of an ongoing TLS level renegotiation.
1069
+
1070
+   The default value is 10485760 (10 Mb).
1071
+
1072
+   It can be changed also at runtime, via the RPC interface and config
1073
+   framework. The config variable name is tls.ct_wq_max.
1074
+
1075
+   Example 1.25. Set ct_wq_max parameter
1076
+...
1077
+modparam("tls", "ct_wq_max", 4194304)
1078
+...
1079
+
1080
+   Example 1.26. Set tls.ct_wq_max at runtime
1081
+ $ kamcmd cfg.set_now_int tls ct_wq_max 4194304
1082
+
1083
+10.21. ct_wq_blk_size (integer)
1084
+
1085
+   Minimum block size for the internal clear-text send queues (debugging /
1086
+   advanced tuning). Good values are multiple of typical datagram sizes.
1087
+
1088
+   The default value is 4096.
1089
+
1090
+   It can be changed also at runtime, via the RPC interface and config
1091
+   framework. The config variable name is tls.ct_wq_blk_size.
1092
+
1093
+   Example 1.27. Set ct_wq_blk_size parameter
1094
+...
1095
+modparam("tls", "ct_wq_blk_size", 2048)
1096
+...
1097
+
1098
+   Example 1.28. Set tls.ct_wq_max at runtime
1099
+ $ kamcmd cfg.set_now_int tls ct_wq_blk_size 2048
1100
+
1101
+10.22. tls_log (int)
1102
+
1103
+   Sets the log level at which TLS related messages will be logged.
1104
+
1105
+   The default value is 3 (L_DBG).
1106
+
1107
+   It can be changed also at runtime, via the RPC interface and config
1108
+   framework. The config variable name is tls.log.
1109
+
1110
+   Example 1.29. Set tls_log parameter
1111
+...
1112
+# ignore TLS messages if Kamailio is started with debug less than 10
1113
+modparam("tls", "tls_log", 10)
1114
+...
1115
+
1116
+   Example 1.30. Set tls.log at runtime
1117
+ $ kamcmd cfg.set_now_int tls log 10
1118
+
1119
+10.23. tls_debug (int)
1120
+
1121
+   Sets the log level at which TLS debug messages will be logged. Note
1122
+   that TLS debug messages are enabled only if the TLS module is compiled
1123
+   with debugging enabled (e.g. -DTLS_WR_DEBUG, -DTLS_RD_DEBUG or
1124
+   -DTLS_BIO_DEBUG).
1125
+
1126
+   The default value is 3 (L_DBG).
1127
+
1128
+   It can be changed also at runtime, via the RPC interface and config
1129
+   framework. The config variable name is tls.debug.
1130
+
1131
+   Example 1.31. Set tls_debug parameter
1132
+...
1133
+# ignore TLS debug messages if Kamailio is started with debug less than 10
1134
+modparam("tls", "tls_debug", 10)
1135
+...
1136
+
1137
+   Example 1.32. Set tls.debug at runtime
1138
+ $ kamcmd cfg.set_now_int tls debug 10
1139
+
1140
+10.24. low_mem_threshold1 (integer)
1141
+
1142
+   Sets the minimal free memory from which attempts to open or accept new
1143
+   TLS connections will start to fail. The value is expressed in KB.
1144
+
1145
+   The default value depends on whether the OpenSSL library used handles
1146
+   low memory situations in a good way (openssl bug #1491). As of this
1147
+   writing this is not true for any OpenSSL version (including 0.9.8e).
1148
+
1149
+   If an ill-behaved OpenSSL version is detected, a very conservative
1150
+   value is chosen, which depends on the maximum possible number of
1151
+   simultaneously created TLS connections (and hence on the process
1152
+   number).
1153
+
1154
+   The following values have a special meaning:
1155
+     * -1 - use the default value
1156
+     * 0 - disable (TLS connections will not fail preemptively)
1157
+
1158
+   It can be changed also at runtime, via the RPC interface and config
1159
+   framework. The config variable name is tls.low_mem_threshold1.
1160
+
1161
+   See also tls.low_mem_threshold2.
1162
+
1163
+   Example 1.33. Set low_mem_threshold1 parameter
1164
+...
1165
+modparam("tls", "low_mem_threshold1", -1)
1166
+...
1167
+
1168
+   Example 1.34. Set tls.low_mem_threshold1 at runtime
1169
+ $ kamcmd cfg.set_now_int tls low_mem_threshold1 2048
1170
+
1171
+10.25. low_mem_threshold2 (integer)
1172
+
1173
+   Sets the minimal free memory from which TLS operations on already
1174
+   established TLS connections will start to fail preemptively. The value
1175
+   is expressed in KB.
1176
+
1177
+   The default value depends on whether the OpenSSL library used handles
1178
+   low memory situations (openssl bug #1491). As of this writing this is
1179
+   not true for any OpenSSL version (including 0.9.8e).
1180
+
1181
+   If an ill-behaved OpenSSL version is detected, a very conservative
1182
+   value is chosen, which depends on the maximum possible number of
1183
+   simultaneously created TLS connections (and hence on the process
1184
+   number).
1185
+
1186
+   The following values have a special meaning:
1187
+     * -1 - use the default value
1188
+     * 0 - disable (TLS operations will not fail preemptively)
1189
+
1190
+   It can be changed also at runtime, via the RPC interface and config
1191
+   framework. The config variable name is tls.low_mem_threshold2.
1192
+
1193
+   See also tls.low_mem_threshold1.
1194
+
1195
+   Example 1.35. Set tls.low_mem_threshold2 parameter
1196
+...
1197
+modparam("tls", "low_mem_threshold2", -1)
1198
+...
1199
+
1200
+   Example 1.36. Set tls.low_mem_threshold2 at runtime
1201
+ $ kamcmd cfg.set_now_int tls low_mem_threshold2 1024
1202
+
1203
+10.26. tls_force_run (boolean)
1204
+
1205
+   If enabled Kamailio will start even if some of the OpenSSL sanity
1206
+   checks fail (turn it on at your own risk).
1207
+
1208
+   If any of the following sanity checks fail, Kamailio will not start:
1209
+     * the version of the library the TLS module was compiled with is "too
1210
+       different" from the library used at runtime. The versions should
1211
+       have the same major, minor and fix level (e.g.: 0.9.8a and 0.9.8c
1212
+       are ok, but 0.9.8 and 0.9.9 are not)
1213
+     * the OpenSSL library used at compile time and the one used at
1214
+       runtime have different Kerberos options
1215
+
1216
+   By default tls_force_run is disabled.
1217
+
1218
+   Example 1.37. Set tls_force_run parameter
1219
+...
1220
+modparam("tls", "tls_force_run", 11)
1221
+...
1222
+
1223
+10.27. session_cache (boolean)
1224
+
1225
+   If enabled Kamailio will do caching of the TLS sessions data,
1226
+   generation a session_id and sending it back to client.
1227
+
1228
+   By default TLS session caching is disabled (0).
1229
+
1230
+   Example 1.38. Set session_cache parameter
1231
+...
1232
+modparam("tls", "session_cache", 1)
1233
+...
1234
+
1235
+10.28. session_id (str)
1236
+
1237
+   The value for session ID context, making sense when session caching is
1238
+   enabled.
1239
+
1240
+   By default TLS session_id is "kamailio-tls-5.x.y".
1241
+
1242
+   Example 1.39. Set session_id parameter
1243
+...
1244
+modparam("tls", "session_id", "my-session-id-context")
1245
+...
1246
+
1247
+10.29. renegotiation (boolean)
1248
+
1249
+   If enabled Kamailio will allow renegotiations of TLS connection
1250
+   initiated by the client. This may expose to a security risk if the
1251
+   client is not a trusted peer and keeps renegotiating, consuming CPU and
1252
+   bandwidth resources.
1253
+
1254
+   By default TLS renegotiation is disabled (0).
1255
+
1256
+   Example 1.40. Set renegotiation parameter
1257
+...
1258
+modparam("tls", "renegotiation", 1)
1259
+...
1260
+
1261
+10.30. config (string)
1262
+
1263
+   Sets the name of the TLS specific configuration file or configuration
1264
+   directory.
1265
+
1266
+   If set the TLS module will load a special configuration file or
1267
+   configuration files from configuration directory, in which different
1268
+   TLS parameters can be specified on a per role (server or client) and
1269
+   domain basis (for now only IPs). The corresponding module parameters
1270
+   will be ignored if a separate configuration file is used.
1271
+
1272
+   If the file or directory name starts with a '.' the path will be
1273
+   relative to the working directory (at runtime). If it starts with a '/'
1274
+   it will be an absolute path and if it starts with anything else the
1275
+   path will be relative to the main config file directory (e.g.: for
1276
+   kamailio -f /etc/kamailio/kamailio.cfg it will be relative to
1277
+   /etc/kamailio/).
1278
+
1279
+   By default no TLS configuration file is specified.
1280
+
1281
+   The following parameters can be set in the config file, for each
1282
+   domain:
1283
+     * tls_method - (str) - TLS methods
1284
+     * verify_certificate - (bool) - see modparam
1285
+     * require_certificate - (bool) - see modparam
1286
+     * verify_client - (str) - see modparam
1287
+     * private_key - (str) - see modparam
1288
+     * certificate - (str) - see modparam
1289
+     * verify_depth - (int) - see modparam
1290
+     * ca_list - (str) - see modparam
1291
+     * crl - (str) - see modparam
1292
+     * cipher_list - (str) - see modparam
1293
+     * server_name - (str) - SNI (server name identification)
1294
+     * server_name_mode - (int) - how to match server_name
1295
+     * server_id - (str) - server id
1296
+
1297
+   The value for server_name_mode specifies how to match the server_name
1298
+   (SNI). If set to 1, match the domain and all its subdomains. If set to
1299
+   2, match only the subdomains. If set to 0 (or anything else), match
1300
+   only the domain given in server_name.
1301
+
1302
+   The value for server_id can be any string, being used to match TLS
1303
+   client config profile, overriding the match on ip:port and server_name.
1304
+   This is the recommended way for selecting a specific TLS client config