Debian Codegraph @

src/modules/tls/README

raw
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. private_key_password (string)
39 10.5. key_password_mode (int)
40 10.6. ca_list (string)
41 10.7. ca_path (str)
42 10.8. crl (string)
43 10.9. verify_certificate (boolean)
44 10.10. verify_depth (integer)
45 10.11. require_certificate (boolean)
46 10.12. cipher_list (string)
47 10.13. server_name (string)
48 10.14. connection_timeout (int)
49 10.15. tls_disable_compression (boolean)
50 10.16. ssl_release_buffers (integer)
51 10.17. ssl_freelist_max_len (integer)
52 10.18. ssl_max_send_fragment (integer)
53 10.19. ssl_read_ahead (boolean)
54 10.20. send_close_notify (boolean)
55 10.21. con_ct_wq_max (integer)
56 10.22. ct_wq_max (integer)
57 10.23. ct_wq_blk_size (integer)
58 10.24. tls_log (int)
59 10.25. tls_debug (int)
60 10.26. low_mem_threshold1 (integer)
61 10.27. low_mem_threshold2 (integer)
62 10.28. tls_force_run (boolean)
63 10.29. session_cache (boolean)
64 10.30. session_id (str)
65 10.31. renegotiation (boolean)
66 10.32. init_mode (int)
67 10.33. config (string)
68 10.34. xavp_cfg (string)
69 10.35. event_callback (str)
70 10.36. rand_engine (str)
71 10.37. engine (string)
72 10.38. engine_config (string)
73 10.39. engine_algorithms (string)
74 10.40. verify_client (string)
75 10.41. provider_quirks (integer)
76 10.42. provider_quirks_config (string)
77 10.43. keylog_mode (int)
78 10.44. keylog_file (str)
79 10.45. keylog_peer (str)
80
81 11. Functions
82
83 11.1. is_peer_verified()
84 11.2. tls_set_connect_server_id(srvid)
85
86 12. RPC Commands
87
88 12.1. tls.info
89 12.2. tls.list
90 12.3. tls.options
91 12.4. tls.kill
92 12.5. tls.reload
93
94 13. Status
95
96 13.1. License
97 13.2. History
98
99 14. Event Routes
100
101 14.1. event_route[tls:connection-out]
102
103 15. TLS With Database Backend
104
105 List of Examples
106
107 1.1. Quick Start Basic Config
108 1.2. Compiling TLS with Debug Messages
109 1.3. Set tls_method parameter
110 1.4. Set certificate parameter
111 1.5. Set private_key parameter
112 1.6. Set private_key_password parameter
113 1.7. Set key_password_mode parameter
114 1.8. Set ca_list parameter
115 1.9. Set ca_path parameter
116 1.10. Set crl parameter
117 1.11. Set verify_certificate parameter
118 1.12. Set verify_depth parameter
119 1.13. Set require_certificate parameter
120 1.14. Set cipher_list parameter
121 1.15. Set server_name parameter
122 1.16. Set connection_timeout parameter
123 1.17. Set tls.connection_timeout at runtime
124 1.18. Set tls_disable_compression parameter
125 1.19. Set ssl_release_buffers parameter
126 1.20. Set ssl_freelist_max_len parameter
127 1.21. Set ssl_max_send_fragment parameter
128 1.22. Set ssl_read_ahead parameter
129 1.23. Set send_close_notify parameter
130 1.24. Set tls.send_close_notify at runtime
131 1.25. Set con_ct_wq_max parameter
132 1.26. Set tls.con_ct_wq_max at runtime
133 1.27. Set ct_wq_max parameter
134 1.28. Set tls.ct_wq_max at runtime
135 1.29. Set ct_wq_blk_size parameter
136 1.30. Set tls.ct_wq_max at runtime
137 1.31. Set tls_log parameter
138 1.32. Set tls.log at runtime
139 1.33. Set tls_debug parameter
140 1.34. Set tls.debug at runtime
141 1.35. Set low_mem_threshold1 parameter
142 1.36. Set tls.low_mem_threshold1 at runtime
143 1.37. Set tls.low_mem_threshold2 parameter
144 1.38. Set tls.low_mem_threshold2 at runtime
145 1.39. Set tls_force_run parameter
146 1.40. Set session_cache parameter
147 1.41. Set session_id parameter
148 1.42. Set renegotiation parameter
149 1.43. Set init_mode parameter
150 1.44. Sample TLS Config File
151 1.45. Set config parameter
152 1.46. Change and reload the TLS configuration at runtime
153 1.47. Set xavp_cfg parameter
154 1.48. Set event_callback parameter
155 1.49. Set rand_engine parameter
156 1.50. Set verify_client modparam parameter
157 1.51. Set verify_client tls.cfg parameter
158 1.52. Set provider_quirks modparam parameter
159 1.53. Set provider_quirks_config modparam parameter
160 1.54. Set keylog_mode parameter
161 1.55. Set keylog_file parameter
162 1.56. Set keylog_peer parameter
163 1.57. is_peer_verified usage
164 1.58. tls_set_connect_server_id usage
165 1.59. Use of event_route[tls:connection-out]
166
167 Chapter 1. Admin Guide
168
169 Table of Contents
170
171 1. Overview
172 2. Quick Start
173 3. Important Notes
174 4. Compiling the TLS Module
175 5. TLS and Low Memory
176 6. TLS Debugging
177 7. Known Limitations
178 8. Quick Certificate Howto
179 9. HSM Howto
180 10. Parameters
181
182 10.1. tls_method (string)
183 10.2. certificate (string)
184 10.3. private_key (string)
185 10.4. private_key_password (string)
186 10.5. key_password_mode (int)
187 10.6. ca_list (string)
188 10.7. ca_path (str)
189 10.8. crl (string)
190 10.9. verify_certificate (boolean)
191 10.10. verify_depth (integer)
192 10.11. require_certificate (boolean)
193 10.12. cipher_list (string)
194 10.13. server_name (string)
195 10.14. connection_timeout (int)
196 10.15. tls_disable_compression (boolean)
197 10.16. ssl_release_buffers (integer)
198 10.17. ssl_freelist_max_len (integer)
199 10.18. ssl_max_send_fragment (integer)
200 10.19. ssl_read_ahead (boolean)
201 10.20. send_close_notify (boolean)
202 10.21. con_ct_wq_max (integer)
203 10.22. ct_wq_max (integer)
204 10.23. ct_wq_blk_size (integer)
205 10.24. tls_log (int)
206 10.25. tls_debug (int)
207 10.26. low_mem_threshold1 (integer)
208 10.27. low_mem_threshold2 (integer)
209 10.28. tls_force_run (boolean)
210 10.29. session_cache (boolean)
211 10.30. session_id (str)
212 10.31. renegotiation (boolean)
213 10.32. init_mode (int)
214 10.33. config (string)
215 10.34. xavp_cfg (string)
216 10.35. event_callback (str)
217 10.36. rand_engine (str)
218 10.37. engine (string)
219 10.38. engine_config (string)
220 10.39. engine_algorithms (string)
221 10.40. verify_client (string)
222 10.41. provider_quirks (integer)
223 10.42. provider_quirks_config (string)
224 10.43. keylog_mode (int)
225 10.44. keylog_file (str)
226 10.45. keylog_peer (str)
227
228 11. Functions
229
230 11.1. is_peer_verified()
231 11.2. tls_set_connect_server_id(srvid)
232
233 12. RPC Commands
234
235 12.1. tls.info
236 12.2. tls.list
237 12.3. tls.options
238 12.4. tls.kill
239 12.5. tls.reload
240
241 13. Status
242
243 13.1. License
244 13.2. History
245
246 14. Event Routes
247
248 14.1. event_route[tls:connection-out]
249
250 15. TLS With Database Backend
251
252 1. Overview
253
254 This module implements the TLS transport for Kamailio using the OpenSSL
255 library. To enable the Kamailio TLS support this module must be loaded
256 and enable_tls=yes core setting must be added to the Kamailio config
257 file.
258
259 Read the "Important Notes" section because it has relevant information
260 about configuring properly the module for various libssl versions,
261 components and operating systems.
262
263 2. Quick Start
264
265 The default kamailio.cfg file has basic tls support included, it has to
266 be enabled with "#!define WITH_TLS" directive.
267
268 The most important parameters to set the path to the public certificate
269 and private key files. You can either have them in different file or in
270 the same file in PEM format. The parameters for them are certificate
271 and private_key. They can be given as modparam or provided in the
272 profiles of tls.cfg file.
273
274 When installing tls module of kamailio, a sample 'tls.cfg' file is
275 deployed in the same folder with 'kamailio.cfg'. For freshly generated
276 self signed certificates make must be called from tls folder
277 make install-tls-cert
278
279 HINT: be sure you have enable_tls=yes to your kamailio.cfg.
280
281 Example 1.1. Quick Start Basic Config
282 #...
283 loadmodule "sl.so"
284 loadmodule "tls.so"
285
286 modparam("tls", "private_key", "./server-test.pem")
287 modparam("tls", "certificate", "./server-test.pem")
288 modparam("tls", "ca_list", "./calist.pem")
289
290 enable_tls=yes
291
292 request_route {
293 if(proto != TLS) {
294 sl_send_reply("403", "Accepting TLS Only");
295 exit;
296 }
297 ...
298 }
299
300 3. Important Notes
301
302 The TLS module needs some special options enabled when compiling
303 Kamailio. These options are enabled by default, however in case you are
304 using a modified Kamailio version or Makefile, make sure that you
305 enable -DUSE_TLS and -DTLS_HOOKS (or compile with make TLS_HOOKS=1
306 which will take care of both options).
307
308 To quickly check if your Kamailio version was compiled with these
309 options, run kamailio -V and look for USE_TLS and TLS_HOOKS among the
310 flags.
311
312 This module includes several workarounds for various Openssl bugs (like
313 compression and Kerberos using the wrong memory allocations functions,
314 low memory problems a.s.o). On startup it will try to enable the needed
315 workarounds based on the OpenSSL library version. Each time a known
316 problem is detected and a workaround is enabled, a message will be
317 logged. In general it is recommended to compile this module on the same
318 machine or a similar machine to where kamailio will be run or to link
319 it statically with libssl. For example if on the compile machine
320 OpenSSL does not have the Kerberos support enabled, but on the target
321 machine a Kerberos enabled OpenSSL library is installed, Kamailio
322 cannot apply the needed workarounds and will refuse to start. The same
323 thing will happen if the OpenSSL versions are too different (to force
324 Kamailio startup anyway, see the tls_force_run module parameter).
325
326 Compression is fully supported if you have a new enough OpenSSL version
327 (starting with 0.9.8). Although there are some problems with zlib
328 compression in currently deployed OpenSSL versions (up to and including
329 0.9.8d, see openssl bug #1468), the TLS module will automatically
330 switch to its own fixed version. Note however that starting with
331 Kamailio 3.1 compression is not enabled by default, due to the huge
332 extra memory consumption that it causes (about 10x more memory). To
333 enable it use modparam("tls", "tls_disable_compression", 0) (see
334 tls_disable_compression).
335
336 The TLS module includes workarounds for the following known openssl
337 bugs:
338 * openssl #1204 (disable SS_OP_TLS_BLOCK_PADDING_BUG if compression
339 is enabled, for versions between 0.9.8 and 0.9.8c),
340 * openssl #1468 (fix zlib compression memory allocation),
341 * openssl #1467 (kerberos support will be disabled if the openssl
342 version is less than 0.9.8e-beta1)
343 * openssl #1491 (stop using tls in low memory situations due to the
344 very high risk of openssl crashing or leaking memory).
345
346 The bug reports can be viewed at http://rt.openssl.org/.
347
348 Note 1: the tls module must be loaded before any other Kamailio module
349 that uses libssl (OpenSSL library). A safe option is to have the tls
350 module loaded first (be in the first "loadmodule" in kamailio.cfg).
351
352 Note 2: for libssl v3.x, the core parameter "tls_threads_mode" has to
353 be set, see the Core Cookbook for possible values.
354
355 Note 3: using this module compiled with newer versions of libssl (e.g.,
356 v1.1+) may require Kamailio to be started with --atexit=no command line
357 parameters to avoid calling C atexit callbacks inside the process
358 ending during daemonize procedure as well as during shut down, which
359 can lead to crashes because it destroys and then accesses shared
360 memory. For example, such case has been reported for Ubuntu 20.04 or
361 RedHat 8.
362
363 Note 4: with some particular combination of OS, openssl and
364 mysql-client libraries, there were reports of random crashes, in such
365 case try to set the db_mysql module parameter opt_ssl_mode to 1.
366
367 4. Compiling the TLS Module
368
369 In most case compiling the TLS module is as simple as:
370 make -C modules/tls
371
372 or
373 make modules modules=modules/tls
374
375 or (compiling whole Kamailio and the tls module)
376 make all include_modules=tls
377
378 .
379
380 However in some cases the OpenSSL library requires linking with other
381 libraries. For example compiling the OpenSSL library with Kerberos and
382 zlib-shared support will require linking the TLS module with libkrb5
383 and libz. In this case just add TLS_EXTRA_LIBS="library list" to make's
384 command line. E.g.:
385 make TLS_EXTRA_LIBS="-lkrb5 -lz" all include_modules=tls
386
387 In general, if Kamailio fails to start with a symbol not found error
388 when trying to load the TLS module (check the log), it means some
389 needed library was not linked and it must be added to TLS_EXTRA_LIBS
390
391 Elliptic Curve Diffie-Hellman (EDCH)-Ciphers are only supported in
392 OpenSSL 1.0.0e and later.
393
394 5. TLS and Low Memory
395
396 The Openssl library doesn't handle low memory situations very well. If
397 memory allocations start to fail (due to memory shortage), Openssl can
398 crash or cause memory leaks (making the memory shortage even worse). As
399 of this writing all Openssl versions were affected (including 0.9.8e),
400 see Openssl bug #1491. The TLS module has some workarounds for
401 preventing this problem (see low_mem_threshold1 and
402 low_mem_threshold2), however starting Kamailio with enough shared
403 memory is higly recommended. When this is not possible a quick way to
404 significantly reduce Openssl memory usage it to disable compression
405 (see tls_disable_compression).
406
407 6. TLS Debugging
408
409 Debugging messages can be selectively enabled by recompiling the TLS
410 module with a combination of the following defines:
411 * TLS_WR_DEBUG - debug messages for the write/send part.
412 * TLS_RD_DEBUG - debug messages for the read/receive part.
413 * TLS_BIO_DEBUG - debug messages for the custom BIO.
414
415 Example 1.2. Compiling TLS with Debug Messages
416 make -C modules/tls extra_defs="-DTLS_WR_DEBUG -DTLS_RD_DEBUG"
417
418 To change the level at which the debug messages are logged, change the
419 tls_debug module parameter.
420
421 7. Known Limitations
422
423 The private key must not be encrypted (Kamailio cannot ask you for a
424 password on startup).
425
426 The TLS certificate verifications ignores the certificate name, Subject
427 Altname and IP extensions, it just checks if the certificate is signed
428 by a recognized CA. One can use the select framework to try to overcome
429 this limitation (check in the script for the contents of various
430 certificate fields), but this is not only slow, but also not exactly
431 standard conforming (the verification should happen during TLS
432 connection establishment and not after).
433
434 This documentation is incomplete. The provided selects are not
435 documented in this file. A list with all the ones implemented by the
436 TLS module can be found in the Cookbook
437 https://www.kamailio.org/wikidocs/ in the section Selects for the
438 respective version of Kamailio.
439
440 8. Quick Certificate Howto
441
442 There are various ways to create, sign certificates and manage small
443 CAs (Certificate Authorities). If you are in a hurry and everything you
444 have are the installed OpenSSL libraries and utilities, read on.
445
446 Assumptions: we run our own CA.
447
448 Warning: in this example no key is encrypted. The client and server
449 private keys must not be encrypted (Kamailio doesn't support encrypted
450 keys), so make sure the corresponding files are readable only by
451 trusted people. You should use a password to protect your CA private
452 key.
453
454 Assumptions
455 ------------
456
457 The default openssl configuration (usually /etc/ssl/openssl.cnf)
458 default_ca section is the one distributed with openssl and uses the default
459 directories:
460
461 ...
462
463 default_ca = CA_default # The default ca section
464
465 [ CA_default ]
466
467 dir = ./demoCA # Where everything is kept
468 certs = $dir/certs # Where the issued certs are kept
469 crl_dir = $dir/crl # Where the issued crl are kept
470 database = $dir/index.txt # database index file.
471 #unique_subject = no # Set to 'no' to allow creation of
472 # several certificates with same subject
473 .
474 new_certs_dir = $dir/newcerts # default place for new certs.
475
476 certificate = $dir/cacert.pem # The CA certificate
477 serial = $dir/serial # The current serial number
478 crlnumber = $dir/crlnumber # the current CRL number
479 crl = $dir/crl.pem # The current CRL
480 private_key = $dir/private/cakey.pem# The private key
481 RANDFILE = $dir/private/.rand # private random number file
482
483 ...
484
485 If this is not the case create a new OpenSSL config file that uses the above
486 paths for the default CA and add to all the openssl commands:
487 -config filename. E.g.:
488 openssl ca -config my_openssl.cnf -in kamailio1_cert_req.pem -out kamail
489 io1_cert.pem
490
491
492 Creating the CA certificate
493 ---------------------------
494 1. Create the CA directory
495 mkdir ca
496 cd ca
497
498 2. Create the CA directory structure and files (see ca(1))
499 mkdir demoCA #default CA name, edit /etc/ssl/openssl.cnf
500 mkdir demoCA/private
501 mkdir demoCA/newcerts
502 touch demoCA/index.txt
503 echo 01 >demoCA/serial
504 echo 01 >demoCA/crlnumber
505
506 2. Create CA private key
507 openssl genrsa -out demoCA/private/cakey.pem 2048
508 chmod 600 demoCA/private/cakey.pem
509
510 3. Create CA self-signed certificate
511 openssl req -out demoCA/cacert.pem -x509 -new -key demoCA/private/cake
512 y.pem
513
514
515 Creating a server/client TLS certificate
516 ----------------------------------------
517 1. Create a certificate request (and its private key in privkey.pem)
518
519 openssl req -out kamailio1_cert_req.pem -new -nodes
520
521 WARNING: the organization name should be the same as in the CA certifica
522 te.
523
524 2. Sign it with the CA certificate
525 openssl ca -in kamailio1_cert_req.pem -out kamailio1_cert.pem
526
527 3. Copy kamailio1_cert.pem to your Kamailio configuration dir
528
529
530 Setting Kamailio to use the TLS certificate
531 ---------------------------------------------
532 1. Create the CA list file:
533 for each of your CA certificates that you intend to use do:
534 cat cacert.pem >>calist.pem
535
536 2. Copy your Kamailio certificate, private key and ca list file to your
537 intended machine (preferably in your Kamailio configuration directory,
538 this is the default place Kamailio searches for).
539
540 3. Set up kamailio.cfg to use the certificate
541 if your Kamailio certificate name is different from cert.pem or it is no
542 t
543 placed in Kamailio config directory, add to your kamailio.cfg:
544 modparam("tls", "certificate", "/path/cert_file_name")
545
546 4. Set up Kamailio to use the private key
547 if your private key is not contained in the same file as the certificate
548 (or the certificate name is not the default cert.pem), add to your
549 kamailio.cfg:
550 modparam("tls", "private_key", "/path/private_key_file")
551
552 5. Set up Kamailio to use the CA list (optional)
553 The CA list is not used for your server certificate - it's used to approve ot
554 her servers
555 and clients connecting to your server with a client certificate or for approv
556 ing
557 a certificate used by a server your server connects to.
558 add to your Kamailio.cfg:
559 modparam("tls", "ca_list", "/path/ca_list_file")
560
561 6. Set up TLS authentication options:
562 modparam("tls", "verify_certificate", 1)
563 modparam("tls", "require_certificate", 1)
564 (for more information see the module parameters documentation)
565
566
567 Revoking a certificate and using a CRL
568 --------------------------------------
569 1. Revoking a certificate:
570 openssl ca -revoke bad_cert.pem
571
572 2. Generate/update the certificate revocation list:
573 openssl ca -gencrl -out my_crl.pem
574
575 3. Copy my_crl.pem to your Kamailio config directory.
576
577 4. Set up kamailio.cfg to use the CRL:
578 modparam("tls", "crl", "path/my_crl.pem")
579
580 9. HSM Howto
581
582 This documents OpenSSL engine support for private keys in HSM.
583
584 Assumptions: an OpenSSL engine configured with private key. We still
585 require the certificate file and list of CA certificates per a regular
586 TLS configuration.
587
588 Thales Luna Example
589 --------------------
590
591 ...
592 # Example for Thales Luna
593 modparam("tls", "engine", "gem")
594 modparam("tls", "engine_config", "/usr/local/etc/kamailio/thales.cnf")
595 modparam("tls", "engine_algorithms", "EC")
596 ...
597
598 /usr/local/etc/kamailio/thales.cnf is an OpenSSL config format file used to
599 bootstrap the engine, e.g., pass the PIN.
600
601 ...
602 # the key kamailio is mandatory
603 kamailio = openssl_init
604
605 [ openssl_init ]
606 engines = engine_section
607
608 [ engine_section ]
609 # gem is the name of the Thales Luna OpenSSL engine
610 gem = gem_section
611
612 [ gem_section ]
613 # from Thales documentation
614 dynamic_path = /usr/lib64/engines-1.1/gem.so
615 ENGINE_INIT = 0:20:21:password=1234-ABCD-5678-EFGH
616 ...
617
618
619 Thales nShield Connect
620 ----------------------
621
622 Place holder
623
624 10. Parameters
625
626 10.1. tls_method (string)
627 10.2. certificate (string)
628 10.3. private_key (string)
629 10.4. private_key_password (string)
630 10.5. key_password_mode (int)
631 10.6. ca_list (string)
632 10.7. ca_path (str)
633 10.8. crl (string)
634 10.9. verify_certificate (boolean)
635 10.10. verify_depth (integer)
636 10.11. require_certificate (boolean)
637 10.12. cipher_list (string)
638 10.13. server_name (string)
639 10.14. connection_timeout (int)
640 10.15. tls_disable_compression (boolean)
641 10.16. ssl_release_buffers (integer)
642 10.17. ssl_freelist_max_len (integer)
643 10.18. ssl_max_send_fragment (integer)
644 10.19. ssl_read_ahead (boolean)
645 10.20. send_close_notify (boolean)
646 10.21. con_ct_wq_max (integer)
647 10.22. ct_wq_max (integer)
648 10.23. ct_wq_blk_size (integer)
649 10.24. tls_log (int)
650 10.25. tls_debug (int)
651 10.26. low_mem_threshold1 (integer)
652 10.27. low_mem_threshold2 (integer)
653 10.28. tls_force_run (boolean)
654 10.29. session_cache (boolean)
655 10.30. session_id (str)
656 10.31. renegotiation (boolean)
657 10.32. init_mode (int)
658 10.33. config (string)
659 10.34. xavp_cfg (string)
660 10.35. event_callback (str)
661 10.36. rand_engine (str)
662 10.37. engine (string)
663 10.38. engine_config (string)
664 10.39. engine_algorithms (string)
665 10.40. verify_client (string)
666 10.41. provider_quirks (integer)
667 10.42. provider_quirks_config (string)
668 10.43. keylog_mode (int)
669 10.44. keylog_file (str)
670 10.45. keylog_peer (str)
671
672 10.1. tls_method (string)
673
674 Sets the TLS protocol method. Possible values are:
675 * TLSv1.3+ - TLSv1.3 or newer (TLSv1.3, ...) connections are accepted
676 (available starting with openssl/libssl v1.1.1)
677 * TLSv1.3 - only TLSv1.3 connections are accepted (available starting
678 with openssl/libssl v1.1.1)
679 * TLSv1.2+ - TLSv1.2 or newer (TLSv1.3, ...) connections are accepted
680 (available starting with openssl/libssl v1.1.1)
681 * TLSv1.2 - only TLSv1.2 connections are accepted (available starting
682 with openssl/libssl v1.0.1e)
683 * TLSv1.1+ - TLSv1.1 or newer (TLSv1.2, ...) connections are accepted
684 (available starting with openssl/libssl v1.0.1)
685 * TLSv1.1 - only TLSv1.1 connections are accepted (available starting
686 with openssl/libssl v1.0.1)
687 * TLSv1+ - TLSv1.0 or newer (TLSv1.1, TLSv1.2, ...) connections are
688 accepted.
689 * TLSv1 - only TLSv1 (TLSv1.0) connections are accepted. This is the
690 default value.
691 * SSLv3 - only SSLv3 connections are accepted. Note: you shouldn't
692 use SSLv3 for anything which should be secure.
693 * SSLv2 - only SSLv2 connections, for old clients. Note: you
694 shouldn't use SSLv2 for anything which should be secure. Newer
695 versions of OpenSSL libraries don't include support for it anymore.
696 * SSLv23 - any of the SSLv2, SSLv3 and TLSv1 or newer methods will be
697 accepted.
698 From the OpenSSL manual: "A TLS/SSL connection established with
699 these methods may understand the SSLv3, TLSv1, TLSv1.1 and TLSv1.2
700 protocols. If extensions are required (for example server name) a
701 client will send out TLSv1 client hello messages including
702 extensions and will indicate that it also understands TLSv1.1,
703 TLSv1.2 and permits a fallback to SSLv3. A server will support
704 SSLv3, TLSv1, TLSv1.1 and TLSv1.2 protocols. This is the best
705 choice when compatibility is a concern."
706 Note: For older OpenSSL library versions, this option allows SSLv2,
707 with hello messages done over SSLv2. You shouldn't use SSLv2 or
708 SSLv3 for anything which should be secure.
709
710 If RFC 3261 conformance is desired, at least TLSv1 must be used. For
711 compatibility with older clients SSLv23 is the option, but again, be
712 aware of security concerns, SSLv2/3 as well as TLS v1.0 and v1.1 are
713 being considered very insecure and are therefore deprecated since March
714 2021 (RFC 8996). For current information about what's considered
715 secure, please consult, IETF BCP 195, currently RFC 9325 -
716 "Recommendations for Secure Use of Transport Layer Security (TLS) and
717 Datagram Transport Layer Security (DTLS)"
718
719 Example 1.3. Set tls_method parameter
720 ...
721 modparam("tls", "tls_method", "TLSv1")
722 ...
723
724 10.2. certificate (string)
725
726 Sets the certificate file name. The certificate file can also contain
727 the private key in PEM format.
728
729 If the file name starts with a '.' the path will be relative to the
730 working directory (at runtime). If it starts with a '/' it will be an
731 absolute path and if it starts with anything else the path will be
732 relative to the main config file directory (e.g.: for kamailio -f
733 /etc/kamailio/kamailio.cfg it will be relative to /etc/kamailio/).
734
735 The default value is /usr/local/etc/kamailio/cert.pem
736
737 Example 1.4. Set certificate parameter
738 ...
739 modparam("tls", "certificate", "/usr/local/etc/kamailio/my_certificate.pem")
740 ...
741
742 10.3. private_key (string)
743
744 Sets the private key file name. The private key can be in the same file
745 as the certificate or in a separate file, specified by this
746 configuration parameter.
747
748 If the file name starts with a '.' the path will be relative to the
749 working directory (at runtime). If it starts with a '/' it will be an
750 absolute path and if it starts with anything else the path will be
751 relative to the main config file directory (e.g.: for kamailio -f
752 /etc/kamailio/kamailio.cfg it will be relative to /etc/kamailio/).
753
754 Note: the private key can be contained in the same file as the
755 certificate (just append it to the certificate file, e.g.: cat pkey.pem
756 >> cert.pem)
757
758 The default value is /usr/local/etc/kamailio/cert.pem
759
760 Example 1.5. Set private_key parameter
761 ...
762 modparam("tls", "private_key", "/usr/local/etc/kamailio/my_pkey.pem")
763 ...
764
765 10.4. private_key_password (string)
766
767 The password for the private key.
768
769 The default value is empty.
770
771 Example 1.6. Set private_key_password parameter
772 ...
773 modparam("tls", "private_key_password", "secret")
774 ...
775
776 10.5. key_password_mode (int)
777
778 The mode to get the password for the private key. If 0, take it from
779 the config "private_key_password". If 1, promt for it at start up.
780
781 The default value is 0.
782
783 Example 1.7. Set key_password_mode parameter
784 ...
785 modparam("tls", "key_password_mode", 0)
786 ...
787
788 10.6. ca_list (string)
789
790 Sets the CA list file name. This file contains a list of all the
791 trusted CAs certificates used when connecting to other SIP
792 implementations. If a signature in a certificate chain belongs to one
793 of the listed CAs, the verification of that certificate will succeed.
794
795 If the file name starts with a '.' the path will be relative to the
796 working directory (at runtime). If it starts with a '/' it will be an
797 absolute path and if it starts with anything else the path will be
798 relative to the main config file directory (e.g.: for kamailio -f
799 /etc/kamailio/kamailio.cfg it will be relative to /etc/kamailio/).
800
801 By default the CA file is not set.
802
803 An easy way to create the CA list is to append each trusted trusted CA
804 certificate in the PEM format to one file, e.g.:
805 for f in trusted_cas/*.pem ; do cat "$f" >> ca_list.pem ; done
806
807 See also verify_certificate, verify_depth, require_certificate and crl.
808
809 Example 1.8. Set ca_list parameter
810 ...
811 modparam("tls", "ca_list", "/usr/local/etc/kamailio/ca_list.pem")
812 ...
813
814 10.7. ca_path (str)
815
816 Sets the path with the trusted CA files, to be given as parameter
817 SSL_CTX_load_verify_locations(). The certificates in ca_path are only
818 looked up when required, e.g. when building the certificate chain or
819 when actually performing the verification of a peer certificate. They
820 are not given to the client (not loaded to be provided to
821 SSL_CTX_set_client_CA_list()), only the ones in ca_list files are sent
822 to the client. It requires to use c_rehash to generate the hash map for
823 certificate search, for more see the manual of libssl for
824 SSL_CTX_load_verify_locations() function.
825
826 By default it is not set.
827
828 Example 1.9. Set ca_path parameter
829 ...
830 modparam("tls", "ca_path", "/usr/local/etc/kamailio/ca")
831 ...
832
833 10.8. crl (string)
834
835 Sets the certificate revocation list (CRL) file name. This file
836 contains a list of revoked certificates. Any attempt to verify a
837 revoked certificate will fail.
838
839 If not set, no CRL list will be used.
840
841 If the file name starts with a '.' the path will be relative to the
842 working directory (at runtime). If it starts with a '/' it will be an
843 absolute path and if it starts with anything else the path will be
844 relative to the main config file directory (e.g.: for kamailio -f
845 /etc/kamailio/kamailio.cfg it will be relative to /etc/kamailio/).
846
847 Note
848
849 If set, require_certificate should also be set or it will not have any
850 effect.
851
852 By default the CRL file name is not set.
853
854 To update the CRL in a running Kamailio, make sure you configure TLS
855 via a separate TLS config file (the config modparam) and issue a
856 tls.reload RPC call, e.g.:
857 $ kamcmd tls.reload
858
859 A quick way to create the CRL in PEM format, using OpenSSL is:
860 $ openssl ca -gencrl -keyfile cacert.key -cert cacert.pem -out my_crl.pem
861
862 my_crl.pem will contain the signed list of the revoked certificates.
863
864 To revoke a TLS certificate use something like:
865 $ openssl ca -revoke bad_cert.pem -keyfile cacert.key -cert cacert.pem
866
867 and then refresh the crl file using the command above.
868
869 To display the CRL contents use:
870 $ openssl crl -in crl.pem -noout -text
871
872 See also ca_list, verify_certificate, verify_depth and
873 require_certificate.
874
875 Example 1.10. Set crl parameter
876 ...
877 modparam("tls", "crl", "/usr/local/etc/kamailio/crl.pem")
878 ...
879
880 10.9. verify_certificate (boolean)
881
882 If enabled it will force certificate verification when connecting to
883 other SIP servers.. For more information see the verify(1) OpenSSL man
884 page.
885
886 Note: the certificate verification will always fail if the ca_list is
887 empty.
888
889 See also: ca_list, require_certificate, verify_depth.
890
891 By default the certificate verification is off.
892
893 Example 1.11. Set verify_certificate parameter
894 ...
895 modparam("tls", "verify_certificate", 1)
896 ...
897
898 10.10. verify_depth (integer)
899
900 Sets how far up the certificate chain will the certificate verification
901 go in the search for a trusted CA.
902
903 See also: ca_list, require_certificate, verify_certificate,
904
905 The default value is 9.
906
907 Example 1.12. Set verify_depth parameter
908 ...
909 modparam("tls", "verify_depth", 9)
910 ...
911
912 10.11. require_certificate (boolean)
913
914 When enabled Kamailio will require a certificate from a client
915 connecting to the TLS port. If the client does not offer a certificate
916 and verify_certificate is on, certificate verification will fail.
917
918 The default value is off.
919
920 Example 1.13. Set require_certificate parameter
921 ...
922 modparam("tls", "require_certificate", 1)
923 ...
924
925 10.12. cipher_list (string)
926
927 Sets the list of accepted ciphers. The list consists of cipher strings
928 separated by colons. For more information on the cipher list format see
929 the cipher(1) OpenSSL man page.
930
931 The default value is not set (all the OpenSSL supported ciphers are
932 enabled).
933
934 Example 1.14. Set cipher_list parameter
935 ...
936 modparam("tls", "cipher_list", "HIGH")
937 ...
938
939 10.13. server_name (string)
940
941 Sets the Server Name Indication (SNI) value.
942
943 This is a TLS extension enabling one TLS server to serve multiple host
944 names with unique certificates.
945
946 The default value is empty (not set).
947
948 Example 1.15. Set server_name parameter
949 ...
950 modparam("tls", "server_name", "kamailio.org")
951 ...
952
953 10.14. connection_timeout (int)
954
955 Sets the amount of time after which an idle TLS connection will be
956 closed, if no I/O ever occurred after the initial open. If an I/O event
957 occurs, the timeout will be extended with tcp_connection_lifetime. The
958 value is expressed in seconds.
959
960 The default value is 10 min.
961
962 If the value set is -1, the connection will never be close on idle.
963
964 This setting can be changed also at runtime, via the RPC interface and
965 config framework. The config variable name is tls.connection_timeout.
966
967 Example 1.16. Set connection_timeout parameter
968 ...
969 modparam("tls", "connection_timeout", 60)
970 ...
971
972 Example 1.17. Set tls.connection_timeout at runtime
973 $ kamcmd cfg.set_now_int tls connection_timeout 180
974
975 10.15. tls_disable_compression (boolean)
976
977 If set compression over TLS will be disabled. Note that compression
978 uses a lot of memory (about 10x more than with the compression
979 disabled), so if you want to minimize memory usage is a good idea to
980 disable it. TLS compression also expose you for the CRIME security
981 vulnerability.
982
983 By default TLS compression is disabled.
984
985 Example 1.18. Set tls_disable_compression parameter
986 ...
987 modparam("tls", "tls_disable_compression", 0) # enable
988 ...
989
990 10.16. ssl_release_buffers (integer)
991
992 Release internal OpenSSL read or write buffers as soon as they are no
993 longer needed. Combined with ssl_freelist_max_len has the potential of
994 saving a lot of memory ( ~ 32k per connection in the default
995 configuration, or 16k + ssl_max_send_fragment). For Kamailio versions >
996 3.0 it makes little sense to disable it (0) since the tls module
997 already has its own internal buffering.
998
999 A value of -1 would not change this option from its openssl default.
1000 Use 0 or 1 for enable/disable.
1001
1002 By default the value is 1 (enabled).
1003
1004 Note
1005
1006 This option is supported only for OpenSSL versions >= 1.0.0. On all the
1007 other versions attempting to change the default will trigger an error.
1008
1009 Example 1.19. Set ssl_release_buffers parameter
1010 modparam("tls", "ssl_release_buffers", 1)
1011
1012 10.17. ssl_freelist_max_len (integer)
1013
1014 Sets the maximum number of free memory chunks, that OpenSSL will keep
1015 per connection. Setting it to 0 would cause any unused memory chunk to
1016 be immediately freed, reducing the memory footprint. A too large value
1017 would result in extra memory consumption.
1018
1019 Should be combined with ssl_release_buffers.
1020
1021 A value of -1 has a special meaning: the OpenSSL default will be used
1022 (no attempt on changing the value will be made). For OpenSSL 1.0 the
1023 internal default is 32.
1024
1025 By default the value is 0 (no freelist).
1026
1027 Note
1028
1029 This option is supported only for OpenSSL versions >= 1.0.0. On all the
1030 other versions attempting to change the default will trigger an error.
1031
1032 Example 1.20. Set ssl_freelist_max_len parameter
1033 modparam("tls", "ssl_freelist_max_len", 0)
1034
1035 10.18. ssl_max_send_fragment (integer)
1036
1037 Sets the maximum number of bytes (from the clear text) sent into one
1038 TLS record. Valid values are between 512 and 16384. Note however that
1039 even valid low values might not be big enough to allow a successful
1040 handshake (try minimum 1024).
1041
1042 Lower values would lead to less memory usage, but values lower than the
1043 typical Kamailio write size would incur a slight performance penalty.
1044 Good values are bigger than the size of the biggest SIP packet one
1045 normally expects to forward. For example in most setups 2048 would be a
1046 good value.
1047
1048 Note
1049
1050 Values on the lower side, even if valid (> 512), might not allow for a
1051 successful initial handshake. This happens if the certificate does not
1052 fit inside one send fragment. Values lower than 1024 should not be
1053 used. Even with higher values, if the handshake fails, try increasing
1054 the value.
1055
1056 A value of -1 has a special meaning: the OpenSSL default will be used
1057 (no attempt on changing the value will be made).
1058
1059 By default the value is -1 (the OpenSSL default, which at least in
1060 OpenSSL 1.0.0 is ~ 16k).
1061
1062 Note
1063
1064 This option is supported only for OpenSSL versions >= 0.9.9. On all the
1065 other versions attempting to change the default will trigger an error.
1066
1067 Example 1.21. Set ssl_max_send_fragment parameter
1068 modparam("tls", "ssl_max_send_fragment", 4096)
1069
1070 10.19. ssl_read_ahead (boolean)
1071
1072 Enables read ahead, reducing the number of internal OpenSSL BIO read()
1073 calls. This option has only debugging value, in normal circumstances it
1074 should not be changed from the default.
1075
1076 When disabled OpenSSL will make at least 2 BIO read() calls per
1077 received record: one to get the record header and one to get the rest
1078 of the record.
1079
1080 The TLS module buffers internally all read()s and defines its own fast
1081 BIO so enabling this option would only cause more memory consumption
1082 and a minor slow-down (extra memcpy).
1083
1084 A value of -1 has a special meaning: the OpenSSL default will be used
1085 (no attempt on changing the value will be made).
1086
1087 By default the value is 0 (disabled).
1088
1089 Example 1.22. Set ssl_read_ahead parameter
1090 modparam("tls", "ssl_read_ahead", 1)
1091
1092 10.20. send_close_notify (boolean)
1093
1094 Enables/disables sending close notify alerts prior to closing the
1095 corresponding TCP connection. Sending the close notify prior to TCP
1096 shutdown is "nicer" from a TLS point of view, but it has a measurable
1097 performance impact. Default: off. Can be set at runtime
1098 (tls.send_close_notify).
1099
1100 The default value is 0 (off).
1101
1102 It can be changed also at runtime, via the RPC interface and config
1103 framework. The config variable name is tls.send_close_notify.
1104
1105 Example 1.23. Set send_close_notify parameter
1106 ...
1107 modparam("tls", "send_close_notify", 1)
1108 ...
1109
1110 Example 1.24. Set tls.send_close_notify at runtime
1111 $ kamcmd cfg.set_now_int tls send_close_notify 1
1112
1113 10.21. con_ct_wq_max (integer)
1114
1115 Sets the maximum allowed per connection clear-text send queue size in
1116 bytes. This queue is used when data cannot be encrypted and sent
1117 immediately because of an ongoing TLS level renegotiation.
1118
1119 The default value is 65536 (64 Kb).
1120
1121 It can be changed also at runtime, via the RPC interface and config
1122 framework. The config variable name is tls.con_ct_wq_max.
1123
1124 Example 1.25. Set con_ct_wq_max parameter
1125 ...
1126 modparam("tls", "con_ct_wq_max", 1048576)
1127 ...
1128
1129 Example 1.26. Set tls.con_ct_wq_max at runtime
1130 $ kamcmd cfg.set_now_int tls con_ct_wq_max 1048576
1131
1132 10.22. ct_wq_max (integer)
1133
1134 Sets the maximum total number of bytes queued in all the clear-text
1135 send queues. These queues are used when data cannot be encrypted and
1136 sent immediately because of an ongoing TLS level renegotiation.
1137
1138 The default value is 10485760 (10 Mb).
1139
1140 It can be changed also at runtime, via the RPC interface and config
1141 framework. The config variable name is tls.ct_wq_max.
1142
1143 Example 1.27. Set ct_wq_max parameter
1144 ...
1145 modparam("tls", "ct_wq_max", 4194304)
1146 ...
1147
1148 Example 1.28. Set tls.ct_wq_max at runtime
1149 $ kamcmd cfg.set_now_int tls ct_wq_max 4194304
1150
1151 10.23. ct_wq_blk_size (integer)
1152
1153 Minimum block size for the internal clear-text send queues (debugging /
1154 advanced tuning). Good values are multiple of typical datagram sizes.
1155
1156 The default value is 4096.
1157
1158 It can be changed also at runtime, via the RPC interface and config
1159 framework. The config variable name is tls.ct_wq_blk_size.
1160
1161 Example 1.29. Set ct_wq_blk_size parameter
1162 ...
1163 modparam("tls", "ct_wq_blk_size", 2048)
1164 ...
1165
1166 Example 1.30. Set tls.ct_wq_max at runtime
1167 $ kamcmd cfg.set_now_int tls ct_wq_blk_size 2048
1168
1169 10.24. tls_log (int)
1170
1171 Sets the log level at which TLS related messages will be logged.
1172
1173 The default value is 3 (L_DBG).
1174
1175 It can be changed also at runtime, via the RPC interface and config
1176 framework. The config variable name is tls.log.
1177
1178 Example 1.31. Set tls_log parameter
1179 ...
1180 # ignore TLS messages if Kamailio is started with debug less than 10
1181 modparam("tls", "tls_log", 10)
1182 ...
1183
1184 Example 1.32. Set tls.log at runtime
1185 $ kamcmd cfg.set_now_int tls log 10
1186
1187 10.25. tls_debug (int)
1188
1189 Sets the log level at which TLS debug messages will be logged. Note
1190 that TLS debug messages are enabled only if the TLS module is compiled
1191 with debugging enabled (e.g. -DTLS_WR_DEBUG, -DTLS_RD_DEBUG or
1192 -DTLS_BIO_DEBUG).
1193
1194 The default value is 3 (L_DBG).
1195
1196 It can be changed also at runtime, via the RPC interface and config
1197 framework. The config variable name is tls.debug.
1198
1199 Example 1.33. Set tls_debug parameter
1200 ...
1201 # ignore TLS debug messages if Kamailio is started with debug less than 10
1202 modparam("tls", "tls_debug", 10)
1203 ...
1204
1205 Example 1.34. Set tls.debug at runtime
1206 $ kamcmd cfg.set_now_int tls debug 10
1207
1208 10.26. low_mem_threshold1 (integer)
1209
1210 Sets the minimal free memory from which attempts to open or accept new
1211 TLS connections will start to fail. The value is expressed in KB.
1212
1213 The default value depends on whether the OpenSSL library used handles
1214 low memory situations in a good way (openssl bug #1491). As of this
1215 writing this is not true for any OpenSSL version (including 0.9.8e).
1216
1217 If an ill-behaved OpenSSL version is detected, a very conservative
1218 value is chosen, which depends on the maximum possible number of
1219 simultaneously created TLS connections (and hence on the process
1220 number).
1221
1222 The following values have a special meaning:
1223 * -1 - use the default value
1224 * 0 - disable (TLS connections will not fail preemptively)
1225
1226 It can be changed also at runtime, via the RPC interface and config
1227 framework. The config variable name is tls.low_mem_threshold1.
1228
1229 See also tls.low_mem_threshold2.
1230
1231 Example 1.35. Set low_mem_threshold1 parameter
1232 ...
1233 modparam("tls", "low_mem_threshold1", -1)
1234 ...
1235
1236 Example 1.36. Set tls.low_mem_threshold1 at runtime
1237 $ kamcmd cfg.set_now_int tls low_mem_threshold1 2048
1238
1239 10.27. low_mem_threshold2 (integer)
1240
1241 Sets the minimal free memory from which TLS operations on already
1242 established TLS connections will start to fail preemptively. The value
1243 is expressed in KB.
1244
1245 The default value depends on whether the OpenSSL library used handles
1246 low memory situations (openssl bug #1491). As of this writing this is
1247 not true for any OpenSSL version (including 0.9.8e).
1248
1249 If an ill-behaved OpenSSL version is detected, a very conservative
1250 value is chosen, which depends on the maximum possible number of
1251 simultaneously created TLS connections (and hence on the process
1252 number).
1253
1254 The following values have a special meaning:
1255 * -1 - use the default value
1256 * 0 - disable (TLS operations will not fail preemptively)
1257
1258 It can be changed also at runtime, via the RPC interface and config
1259 framework. The config variable name is tls.low_mem_threshold2.
1260
1261 See also tls.low_mem_threshold1.
1262
1263 Example 1.37. Set tls.low_mem_threshold2 parameter
1264 ...
1265 modparam("tls", "low_mem_threshold2", -1)
1266 ...
1267
1268 Example 1.38. Set tls.low_mem_threshold2 at runtime
1269 $ kamcmd cfg.set_now_int tls low_mem_threshold2 1024
1270
1271 10.28. tls_force_run (boolean)
1272
1273 If enabled Kamailio will start even if some of the OpenSSL sanity
1274 checks fail (turn it on at your own risk).
1275
1276 If any of the following sanity checks fail, Kamailio will not start:
1277 * the version of the library the TLS module was compiled with is "too
1278 different" from the library used at runtime. The versions should
1279 have the same major, minor and fix level (e.g.: 0.9.8a and 0.9.8c
1280 are ok, but 0.9.8 and 0.9.9 are not)
1281 * the OpenSSL library used at compile time and the one used at
1282 runtime have different Kerberos options
1283
1284 By default tls_force_run is disabled.
1285
1286 Example 1.39. Set tls_force_run parameter
1287 ...
1288 modparam("tls", "tls_force_run", 11)
1289 ...
1290
1291 10.29. session_cache (boolean)
1292
1293 If enabled Kamailio will do caching of the TLS sessions data,
1294 generation a session_id and sending it back to client.
1295
1296 By default TLS session caching is disabled (0).
1297
1298 Example 1.40. Set session_cache parameter
1299 ...
1300 modparam("tls", "session_cache", 1)
1301 ...
1302
1303 10.30. session_id (str)
1304
1305 The value for session ID context, making sense when session caching is
1306 enabled.
1307
1308 By default TLS session_id is "kamailio-tls-5.x.y".
1309
1310 Example 1.41. Set session_id parameter
1311 ...
1312 modparam("tls", "session_id", "my-session-id-context")
1313 ...
1314
1315 10.31. renegotiation (boolean)
1316
1317 If enabled Kamailio will allow renegotiations of TLS connection
1318 initiated by the client. This may expose to a security risk if the
1319 client is not a trusted peer and keeps renegotiating, consuming CPU and
1320 bandwidth resources.
1321
1322 By default TLS renegotiation is disabled (0).
1323
1324 Example 1.42. Set renegotiation parameter
1325 ...
1326 modparam("tls", "renegotiation", 1)
1327 ...
1328
1329 10.32. init_mode (int)
1330
1331 Allow setting flags that control how the module is initialized and
1332 works at runtime. Many flags (bits) can be set at the same time (set
1333 the parameter to the sum of corresponding values). The flags are
1334 refered with 0-indexing.
1335
1336 If flag (bit) at index 0 is set (value 1), the memory management
1337 operations registered for TLS are wrapped within a pthread mutex lock.
1338 It can be useful with newer versions of libssl and libcrypto, which
1339 have a more pthread multi-threading oriented design.
1340
1341 If flag (bit) at index 1 is set (value 2), the module executes openssl
1342 fork prepare API functions (see
1343 https://www.openssl.org/docs/man1.1.1/man3/OPENSSL_fork_prepare.html).
1344 It is done only for openssl version greater or equal with 1.1.1.
1345
1346 Default value is 0.
1347
1348 Example 1.43. Set init_mode parameter
1349 ...
1350 modparam("tls", "init_mode", 1)
1351 ...
1352
1353 10.33. config (string)
1354
1355 Sets the name of the TLS specific configuration file or configuration
1356 directory.
1357
1358 If set the TLS module will load a special configuration file or
1359 configuration files from configuration directory, in which different
1360 TLS parameters can be specified on a per role (server or client) and
1361 domain basis (for now only IPs). The corresponding module parameters
1362 will be ignored if a separate configuration file is used.
1363
1364 If the file or directory name starts with a '.' the path will be
1365 relative to the working directory (at runtime). If it starts with a '/'
1366 it will be an absolute path and if it starts with anything else the
1367 path will be relative to the main config file directory (e.g.: for
1368 kamailio -f /etc/kamailio/kamailio.cfg it will be relative to
1369 /etc/kamailio/).
1370
1371 By default no TLS configuration file is specified.
1372
1373 The following parameters can be set in the config file, for each
1374 domain:
1375 * tls_method - (str) - TLS methods
1376 * verify_certificate - (bool) - see modparam
1377 * require_certificate - (bool) - see modparam
1378 * verify_client - (str) - see modparam
1379 * private_key - (str) - see modparam
1380 * certificate - (str) - see modparam
1381 * verify_depth - (int) - see modparam
1382 * ca_list - (str) - see modparam
1383 * crl - (str) - see modparam
1384 * cipher_list - (str) - see modparam
1385 * server_name - (str) - SNI (server name identification)
1386 * server_name_mode - (int) - how to match server_name
1387 * server_id - (str) - server id
1388
1389 The value for server_name_mode specifies how to match the server_name
1390 (SNI). If set to 1, match the domain and all its subdomains. If set to
1391 2, match only the subdomains. If set to 0 (or anything else), match
1392 only the domain given in server_name.
1393
1394 The value for server_id can be any string, being used to match TLS
1395 client config profile, overriding the match on ip:port and server_name.
1396 This is the recommended way for selecting a specific TLS client config
1397 profile, because the local or remote port is hard to predict for a
1398 stream connection - see parameter xavp_cfg to learn how to enable it.
1399
1400 All the parameters that take filenames as values will be resolved using
1401 the same rules as for the tls config filename itself: starting with a
1402 '.' means relative to the working directory, a '/' means an absolute
1403 path and anything else a path relative to the directory of the current
1404 Kamailio main config file.
1405
1406 Kamailio acts as a server when it accepts a connection and as a client
1407 when it initiates a new connection by itself (it connects to
1408 something).
1409
1410 The tls.cfg consists on a set of server and client TLS domain profiles.
1411 A server TLS domain profile starts with [server:domain]. A client TLS
1412 domain profile starts with [client:domain]. The tokens 'server' and
1413 'client' are static values. The 'domain' part can be: 'ip:port' - the
1414 IP address and port to match with the TLS connection; 'default' -
1415 (static string) for client and server profiles to be used when no other
1416 profile is matched; 'any' - (static string) for client and server
1417 profiles to be matched based on 'server_name', no matter of IP and port
1418 of the TLS connection.
1419
1420 There can be only one of each [server:default] and [client:default]
1421 profile definitions. Other profiles can be defined many times with the
1422 same domain ('ip:port' or 'any'), but in that case they must have
1423 'server_name' set for matching SNI.
1424
1425 It is highly recommended to have [server:default] and [client:default]
1426 profile definitions. They are needed when SNI is not yet available. If
1427 SNI is provided, then the profile definition is searched again to match
1428 on 'server_name'.
1429
1430 Example 1.44. Sample TLS Config File
1431 ...
1432 [server:default]
1433 method = TLSv1
1434 verify_certificate = yes
1435 require_certificate = yes
1436 private_key = default_key.pem
1437 certificate = default_cert.pem
1438 ca_list = default_ca.pem
1439 crl = default_crl.pem
1440
1441 [client:default]
1442 verify_certificate = yes
1443 require_certificate = yes
1444
1445 # more relaxed for connection on the loopback interface
1446 [server:127.0.0.1:5061]
1447 method = TLSv1
1448 verify_certificate = yes
1449 require_certificate = no
1450 private_key = local_kamailio_org_key.pem
1451 certificate = local_kamailio_org_cert.pem
1452 verify_depth = 3
1453 ca_list = local_ca.pem
1454 server_name = kamailio.org
1455
1456 [client:127.0.0.1:5061]
1457 method = TLSv1
1458 verify_certificate = yes
1459 require_certificate = yes
1460 private_key = default_key.pem
1461 certificate = default_cert.pem
1462 ca_list = default_ca.pem
1463 crl = default_crl.pem
1464 server_name = kamailio.org
1465 server_id = kamailio.org
1466
1467 # server profile on any address
1468 [server:any]
1469 method = TLSv1
1470 verify_certificate = yes
1471 require_certificate = no
1472 private_key = kamailio_net_key.pem
1473 certificate = kamailio_net_cert.pem
1474 verify_depth = 3
1475 ca_list = local_ca.pem
1476 server_name = kamailio.net
1477 server_name_mode = 1
1478 ...
1479
1480 For a more complete example check the tls.cfg distributed with the
1481 Kamailio source (kamailio/modules/tls/tls.cfg).
1482
1483 Example 1.45. Set config parameter
1484 ...
1485 modparam("tls", "config", "/usr/local/etc/kamailio/tls.cfg")
1486 ...
1487
1488 The file can be changed at runtime. The new config will not be loaded
1489 immediately, but after the first tls.reload RPC call.
1490
1491 Example 1.46. Change and reload the TLS configuration at runtime
1492 $ kamcmd cfg.set_now_string tls config "/usr/local/etc/kamailio/new_tls.cfg"
1493 $ kamcmd tls.reload
1494
1495 10.34. xavp_cfg (string)
1496
1497 Sets the name of XAVP that stores attributes for TLS connections.
1498
1499 The following (inner) attributes can be set:
1500 * server_name - SNI to be used for outbound connections
1501 * server_id - string value to be used to match TLS config profile for
1502 client (outbound) connections. If it is set, matching the TLS
1503 config profile is done first on server_id and then on ip:port and
1504 server_name. This is the recommended way for selecting a specific
1505 TLS client config profile as the local or remote port is hard to
1506 predict for a stream connection.
1507
1508 The default value is empty (not set).
1509
1510 Example 1.47. Set xavp_cfg parameter
1511 ...
1512 modparam("tls", "xavp_cfg", "tls")
1513 ...
1514 $xavp(tls=>server_name) = "kamailio.org";
1515 $xavp(tls[0]=>server_id) = "kamailio.org";
1516 $du = "sip:kamailio.org:5061;transport=tls";
1517 route(RELAY);
1518 ...
1519
1520 10.35. event_callback (str)
1521
1522 The name of the function in the kemi configuration file (embedded
1523 scripting language such as Lua, Python, ...) to be executed instead of
1524 event_route[...] blocks specific for tls module.
1525
1526 The function has one string parameter, the value is the name of the
1527 event_route block, respectively "tls:connection-out".
1528
1529 Default value is 'empty' (no function is executed for events).
1530
1531 Example 1.48. Set event_callback parameter
1532 ...
1533 modparam("tls", "event_callback", "ksr_tls_event")
1534 ...
1535 -- event callback function implemented in Lua
1536 function ksr_tls_event(evname)
1537 KSR.info("===== tls module triggered event: " .. evname .. "\n");
1538 return 1;
1539 end
1540 ...
1541
1542 10.36. rand_engine (str)
1543
1544 Set the random number generator engine for libssl.
1545
1546 Note: the default random number generator (PRNG) engine of libssl
1547 v1.1.x is not designed for multi-process applications and can result in
1548 a crash. Therefore set the PRNG engine to one of the options listed in
1549 this section. If libssl 1.1.x (or newer) is detected at compile time,
1550 then the PRNG engine is set to "cryptorand".
1551
1552 The following options are available:
1553 * krand - use internal kam_rand() function
1554 * fastrand - use internal fastrand (ISAAC) function
1555 * cryptorand - use internal cryptorand (Fortuna) function
1556 * kxlibssl - default libssl rand engine wrapped by a Kamailio mutex
1557
1558 Note: the krand and fastrand engines are not recommended for use on
1559 systems requiring strong security, as they may not generate numbers
1560 with enough randomness and are not cryptographically secure.
1561
1562 The default value is empty (not set) for libssl v1.0.x or older, and
1563 "cryptorand" for libssl v1.1.x or newer.
1564
1565 Example 1.49. Set rand_engine parameter
1566 ...
1567 modparam("tls", "rand_engine", "fastrand")
1568 ...
1569
1570 10.37. engine (string)
1571
1572 If OpenSSL is compiled with engine support this will allow algorithms
1573 to be offloaded and private keys from HSM to be used. Currently only a
1574 single global engine is supported. However, private keys can be
1575 specified per_domain.
1576
1577 To use private keys from the HSM, the name is the HSM key label
1578 prefixed by /engine:.
1579 ...
1580 ## example for the Gem engine
1581 modparam("tls", "engine", "gem")
1582 # can also be set per-domain in tls.cfg
1583 modparam("tls", "private_key", "/engine:my_HSM_key_label")
1584
1585 ## example for engine_pkcs11
1586 modparam("tls", "engine", "pkcs11")
1587 modparam("tls", "private_key", "/engine:pkcs11:token=MYTOKEN;object=MYKEYLABEL")
1588
1589 modparam("tls", "engine_config", "/usr/local/etc/kamailio/openssl.cnf")
1590 modparam("tls", "engine_algorithms", "ALL")
1591 ...
1592
1593 By default OpenSSL engine support is disabled (NONE). This global param
1594 is not supported in the tls config file.
1595
1596 10.38. engine_config (string)
1597
1598 An OpenSSL configuration file to initialize the engine. Typically used
1599 to send PIN to HSMs to unlock private keys. See the HSM howto for an
1600 example. This global param is not supported in the tls config file.
1601
1602 10.39. engine_algorithms (string)
1603
1604 A list of cryptographic methods to be set as default in the engine.
1605 This is a comma-separated list of values from ALL RSA DSA DH EC RAND
1606 CIPHERS DIGESTS PKEY PKEY_CRYPTO PKEY_ASN1. Not all methods are
1607 supported by every engine.
1608
1609 The default is not to set any methods as default. This global param is
1610 not supported in the tls config file.
1611
1612 10.40. verify_client (string)
1613
1614 Provides an alternative to verify_certificate and require_certificate
1615 modparam and tls.cfg parameters, and creates an additional
1616 opportunistic connection establishment option for connections with with
1617 unverifiable certificates (optional_no_ca).
1618
1619 This is useful for allowing connections from SIP phones with
1620 self-signed certificates, signed by unrecognized root CAs, expired
1621 certificates, etc.
1622
1623 The following values have respective behaviors:
1624 * off - no client certificate request performed.
1625 * on - require a verified certificate from the client.
1626 * optional - ask client for certificate. If one is provided, it must
1627 be verified. Allowing missing certificate.
1628 * optional_no_ca - ask client for certificate. Opportunistically try
1629 to verify certificate. Allow connection regardless of whether there
1630 is no certificate or whether certificate is present (verified or
1631 not). Note that verification status can be retrieved via
1632 $tls_peer_verified.
1633
1634 Default value is 'off' (no client certificate request performed).
1635
1636 Recommendation: when using this parameter, do not use
1637 verify_certificate or require_certificate parameters. Conversion table
1638 is as follows:
1639 * verify_certificate=0, require_certificate=0 => verify_client="off"
1640 * verify_certificate=1, require_certificate=0 =>
1641 verify_client="optional"
1642 * verify_certificate=1, require_certificate=1 => verify_client="on"
1643
1644 Example 1.50. Set verify_client modparam parameter
1645 ...
1646 modparam("tls", "verify_client", "on")
1647 ...
1648
1649 Example 1.51. Set verify_client tls.cfg parameter
1650 ...
1651 [server:1.2.3.4:5061]
1652 method = TLSv1
1653 verify_client = on
1654 ...
1655
1656 [server:5.6.7.8:5061]
1657 method = TLSv1.2
1658 verify_client = optional_no_ca
1659 ...
1660
1661 10.41. provider_quirks (integer)
1662
1663 Reload a provider in the child - needed in MP-mode only
1664 (tcp_main_threads = 0) for some providers. The configuration file for
1665 the provider is provided in the provider_quirks_config parameter.
1666 Should be 0 in MT-mode.
1667 * 0 - no reload (default)
1668 * 1 - reloads a provider in a new library context in the child.
1669 pkcs11-provider is known to require this.
1670
1671 Example 1.52. Set provider_quirks modparam parameter
1672 ...
1673 modparam("tls", "provider_quirks", 1)
1674 # 1: provider_quirks_config parameter must be set
1675 ...
1676
1677 10.42. provider_quirks_config (string)
1678
1679 A file name of a OpenSSL configuration snippet that contains the
1680 provider configuration. The file must contain two mandatory keys:
1681 quirks_sect - section to load, quirks_provider - the provider to load.
1682
1683 Example 1.53. Set provider_quirks_config modparam parameter
1684 ...
1685 modparam("tls", "provider_quirks_config", "/etc/kamailio/tls/pkcs11-provider.cnf
1686 ")
1687 ...
1688
1689 A provider example:
1690 # /etc/kamailio/tls/pkcs11-provider.cnf
1691 quirks_sect = pkcs11_sect
1692 quirks_provider = pkcs11
1693
1694 [pkcs11_sect]
1695 module = pkcs11.so
1696 pkcs11-module-path = /usr/lib64/libsoftokn3.so
1697 pkcs11-module-init-args = configDir=/etc/kamailio/certs/tokens
1698 pkcs11-module-token-pin = file:/etc/kamailio/certs/pinfile-softoken.txt
1699 pkcs11-module-quirks = no-deinit no-operation-state
1700 activate = 1
1701
1702 10.43. keylog_mode (int)
1703
1704 Control the TLS key logging functionality, available for libssl version
1705 greater than 1.1.0. Its value is composed from bitwise values (can be
1706 made as sum of them):
1707 * 0 - keys logging not enabled
1708 * 1 (bit 1) - initialise keys logging
1709 * 2 (bit 2) - keys logging active
1710 * 4 (bit 3) - write keys to NOTICE log
1711 * 8 (bit 4) - write keys to file
1712 * 16 (bit 5) - send keys to udp peer
1713 * 1024 (bit 11) - enable filtering of keys logging. When set,
1714 filtering is done on: "CLIENT_RANDOM",
1715 "CLIENT_HANDSHAKE_TRAFFIC_SECRET",
1716 "SERVER_HANDSHAKE_TRAFFIC_SECRET", "EXPORTER_SECRET",
1717 "CLIENT_TRAFFIC_SECRET_0", "SERVER_TRAFFIC_SECRET_0"
1718
1719 Bit position is the index starting from 1 (practically a non-zero value
1720 is (2 power (bitpos - 1)) ).
1721
1722 The default value: 0.
1723
1724 Example 1.54. Set keylog_mode parameter
1725 ...
1726 modparam("tls", "keylog_mode", 15)
1727 ...
1728
1729 10.44. keylog_file (str)
1730
1731 Path to the file where to write the TLS keys. The values are appended
1732 to the content of the file. The value 8 (bit 4) has to be set to
1733 keylog_mode parameter.
1734
1735 The default value: NULL.
1736
1737 Example 1.55. Set keylog_file parameter
1738 ...
1739 modparam("tls", "keylog_file", "/tmp/kamailio-tls-keylog.txt")
1740 ...
1741
1742 10.45. keylog_peer (str)
1743
1744 Address of the peer where to send the keys log. It has to be in the
1745 format "proto:ip:port". Only "udp" protocol (proto) is supported. The
1746 value 16 (bit 5) has to be set to keylog_mode parameter.
1747
1748 The default value: NULL.
1749
1750 Example 1.56. Set keylog_peer parameter
1751 ...
1752 modparam("tls", "keylog_peer", "udp:127.0.0.1:8020")
1753 ...
1754
1755 11. Functions
1756
1757 11.1. is_peer_verified()
1758 11.2. tls_set_connect_server_id(srvid)
1759
1760 11.1. is_peer_verified()
1761
1762 Returns true if the connection on which the message was received is
1763 TLS, the peer presented an X509 certificate and the certificate chain
1764 verified ok.
1765
1766 It can be used only in a request route.
1767
1768 Example 1.57. is_peer_verified usage
1769 ...
1770 if (proto==TLS && !is_peer_verified()) {
1771 sl_send_reply("400", "No certificate or verification failed");
1772 exit;
1773 }
1774 ...
1775
1776 11.2. tls_set_connect_server_id(srvid)
1777
1778 Set the server id of the tls profile to be used by next client connect,
1779 being reset after use. It is an alternative to the use of xavp to
1780 specify server id of a client profile for the cases when xavps are no
1781 longer available (e.g., after event_route[tm:local-request]).
1782
1783 If the parameter is an empty string, then the value is reset.
1784
1785 It can be used only in ANY_ROUTE.
1786
1787 Example 1.58. tls_set_connect_server_id usage
1788 ...
1789 tls_set_connect_server_id("clientone");
1790 ...
1791
1792 12. RPC Commands
1793
1794 12.1. tls.info
1795 12.2. tls.list
1796 12.3. tls.options
1797 12.4. tls.kill
1798 12.5. tls.reload
1799
1800 12.1. tls.info
1801
1802 List internal information related to the TLS module in a short list -
1803 max connections, open connections and the write queue size.
1804
1805 Parameters:
1806 * None.
1807
1808 12.2. tls.list
1809
1810 List details about all active TLS connections.
1811
1812 Parameters:
1813 * None.
1814
1815 12.3. tls.options
1816
1817 List the current TLS configuration.
1818
1819 Parameters:
1820 * None.
1821
1822 12.4. tls.kill
1823
1824 Kill a TLS session by id.
1825
1826 Parameters:
1827 * None.
1828
1829 12.5. tls.reload
1830
1831 Reload the external TLS configuration file (aka tls.cfg). It does not
1832 reload modparam() parameters. Note that existing active TLS connections
1833 are not terminated and they continue to use the old certificates. The
1834 new configuration will be used for new connections.
1835
1836 Reload is generally safe and usable in production environments. If
1837 possible should be done in a time where the service has lower
1838 usage/connections.
1839
1840 This RPC command is exported with "RPC_EXEC_DELTA" flag, therefore its
1841 execution rate can be restricted to specific time intervals by setting
1842 the "rpc_exec_delta" core parameter.
1843
1844 Parameters:
1845 * None.
1846
1847 13. Status
1848
1849 13.1. License
1850 13.2. History
1851
1852 13.1. License
1853
1854 Most of the code for this module has been released under BSD by
1855 iptelorg. The GPL parts are released with an exception to link with
1856 OpenSSL toolkit software components.
1857
1858 13.2. History
1859
1860 For version 3.1 most of the TLS specific code was completely re-written
1861 to add support for asynchronous TLS and fix several long standing bugs.
1862
1863 The code is currently maintained by Andrei Pelinescu-Onciul
1864 <[email protected]>.
1865
1866 Install does not generate self-signed certificates by default anymore.
1867 In order to generate them now you should do "make install-tls-cert"
1868
1869 14. Event Routes
1870
1871 14.1. event_route[tls:connection-out]
1872
1873 14.1. event_route[tls:connection-out]
1874
1875 Event route to be executed when a TLS connection is opened by Kamailio.
1876 If drop() is executed in the event route, then the data is no longer
1877 sent over the connection.
1878
1879 Example 1.59. Use of event_route[tls:connection-out]
1880 ...
1881 event_route[tls:connection-out] {
1882 if($sndto(ip)=="1.2.3.4") {
1883 drop;
1884 }
1885 }
1886 ...
1887
1888 15. TLS With Database Backend
1889
1890 The module does not connect to database to fetch the values for the TLS
1891 profile attributes. However the 'kamcli' tool can generate the tls.cfg
1892 from a database table. Once generated, the 'tls.cfg' can be reloaded
1893 with an RPC command.
1894
1895 The kamcli tool can be found at https://github.com/kamailio/kamcli.
1896
1897 The schema to create the database table can be seen with the command:
1898 "kamcli tls sqlprint". The default name for database table is 'tlscfg'.
1899
1900 The most of the column names matches the corresponding attribute names
1901 from a TLS profile.
1902
1903 The profile id in 'tls.cfg' is generated from
1904 '[profile_type:profile_name]'. The 'profile_type' has to be 'server' or
1905 'client'. The 'profile_name' can be 'default', 'any' or the pair of IP
1906 address and port like 'ipaddr:port'.
1907
1908 The 'file_type' is specifying if the values for 'certificate',
1909 'private_key', 'ca_list' and 'crl' are path to files on disc (when is
1910 set to 0) or the content of the files (when set to 1). If 'file_type'
1911 is 1, then 'kamcli' will create new files on disc and store the values
1912 from the database in them. The target folder for 'tls.cfg' and the
1913 certificates related files can be set via command options for 'kamcli
1914 tls', for more details see the output of 'kamcli tls --help' and
1915 'kamcli tls cfgprint --help'.