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