@@ -1,20 +1,8 @@

-TLS Module

+wolfSSL TLS Module

-Andrei Pelinescu-Onciul

+Shih-Ping Chan

-   iptelorg GmbH

-

-Carsten Bock

-

-   ng-voice GmbH

-

-Olle E. Johansson

-

-   Edvina AB

-

-   Copyright © 2007 iptelorg GmbH

-

-   Copyright © 2014 ng-voice GmbH

+   Copyright © 2022 Chan Shih-Ping

      __________________________________________________________________

    Table of Contents

@@ -24,128 +12,11 @@ Olle E. Johansson

         1. Overview

         2. Quick Start

         3. Important Notes

-        4. Compiling the TLS Module

-        5. TLS and Low Memory

-        6. TLS Debugging

-        7. Known Limitations

-        8. Quick Certificate Howto

-        9. HSM Howto

-        10. Parameters

-

-              10.1. tls_method (string)

-              10.2. certificate (string)

-              10.3. private_key (string)

-              10.4. ca_list (string)

-              10.5. ca_path (str)

-              10.6. crl (string)

-              10.7. verify_certificate (boolean)

-              10.8. verify_depth (integer)

-              10.9. require_certificate (boolean)

-              10.10. cipher_list (string)

-              10.11. server_name (string)

-              10.12. connection_timeout (int)

-              10.13. tls_disable_compression (boolean)

-              10.14. ssl_release_buffers (integer)

-              10.15. ssl_freelist_max_len (integer)

-              10.16. ssl_max_send_fragment (integer)

-              10.17. ssl_read_ahead (boolean)

-              10.18. send_close_notify (boolean)

-              10.19. con_ct_wq_max (integer)

-              10.20. ct_wq_max (integer)

-              10.21. ct_wq_blk_size (integer)

-              10.22. tls_log (int)

-              10.23. tls_debug (int)

-              10.24. low_mem_threshold1 (integer)

-              10.25. low_mem_threshold2 (integer)

-              10.26. tls_force_run (boolean)

-              10.27. session_cache (boolean)

-              10.28. session_id (str)

-              10.29. renegotiation (boolean)

-              10.30. config (string)

-              10.31. xavp_cfg (string)

-              10.32. event_callback (str)

-              10.33. rand_engine (str)

-              10.34. engine (string)

-              10.35. engine_config (string)

-              10.36. engine_algorithms (string)

-              10.37. verify_client (string)

-

-        11. Functions

-

-              11.1. is_peer_verified()

-              11.2. tls_set_connect_server_id(srvid)

-

-        12. RPC Commands

-

-              12.1. tls.info

-              12.2. tls.list

-              12.3. tls.options

-              12.4. tls.reload

-

-        13. Status

-

-              13.1. License

-              13.2. History

-

-        14. Event Routes

-

-              14.1. event_route[tls:connection-out]

-

-        15. TLS With Database Backend

+        4. Compiling the wolfSSL TLS Module

    List of Examples

    1.1. Quick Start Basic Config

-   1.2. Compiling TLS with Debug Messages

-   1.3. Set tls_method parameter

-   1.4. Set certificate parameter

-   1.5. Set private_key parameter

-   1.6. Set ca_list parameter

-   1.7. Set ca_path parameter

-   1.8. Set crl parameter

-   1.9. Set verify_certificate parameter

-   1.10. Set verify_depth parameter

-   1.11. Set require_certificate parameter

-   1.12. Set cipher_list parameter

-   1.13. Set server_name parameter

-   1.14. Set connection_timeout parameter

-   1.15. Set tls.connection_timeout at runtime

-   1.16. Set tls_disable_compression parameter

-   1.17. Set ssl_release_buffers parameter

-   1.18. Set ssl_freelist_max_len parameter

-   1.19. Set ssl_max_send_fragment parameter

-   1.20. Set ssl_read_ahead parameter

-   1.21. Set send_close_notify parameter

-   1.22. Set tls.send_close_notify at runtime

-   1.23. Set con_ct_wq_max parameter

-   1.24. Set tls.con_ct_wq_max at runtime

-   1.25. Set ct_wq_max parameter

-   1.26. Set tls.ct_wq_max at runtime

-   1.27. Set ct_wq_blk_size parameter

-   1.28. Set tls.ct_wq_max at runtime

-   1.29. Set tls_log parameter

-   1.30. Set tls.log at runtime

-   1.31. Set tls_debug parameter

-   1.32. Set tls.debug at runtime

-   1.33. Set low_mem_threshold1 parameter

-   1.34. Set tls.low_mem_threshold1 at runtime

-   1.35. Set tls.low_mem_threshold2 parameter

-   1.36. Set tls.low_mem_threshold2 at runtime

-   1.37. Set tls_force_run parameter

-   1.38. Set session_cache parameter

-   1.39. Set session_id parameter

-   1.40. Set renegotiation parameter

-   1.41. Sample TLS Config File

-   1.42. Set config parameter

-   1.43. Change and reload the TLS configuration at runtime

-   1.44. Set xavp_cfg parameter

-   1.45. Set event_callback parameter

-   1.46. Set rand_engine parameter

-   1.47. Set verify_client modparam parameter

-   1.48. Set verify_client tls.cfg parameter

-   1.49. is_peer_verified usage

-   1.50. tls_set_connect_server_id usage

-   1.51. Use of event_route[tls:connection-out]

 Chapter 1. Admin Guide

@@ -154,1560 +25,57 @@ Chapter 1. Admin Guide

    1. Overview

    2. Quick Start

    3. Important Notes

-   4. Compiling the TLS Module

-   5. TLS and Low Memory

-   6. TLS Debugging

-   7. Known Limitations

-   8. Quick Certificate Howto

-   9. HSM Howto

-   10. Parameters

-

-        10.1. tls_method (string)

-        10.2. certificate (string)

-        10.3. private_key (string)

-        10.4. ca_list (string)

-        10.5. ca_path (str)

-        10.6. crl (string)

-        10.7. verify_certificate (boolean)

-        10.8. verify_depth (integer)

-        10.9. require_certificate (boolean)

-        10.10. cipher_list (string)

-        10.11. server_name (string)

-        10.12. connection_timeout (int)

-        10.13. tls_disable_compression (boolean)

-        10.14. ssl_release_buffers (integer)

-        10.15. ssl_freelist_max_len (integer)

-        10.16. ssl_max_send_fragment (integer)

-        10.17. ssl_read_ahead (boolean)

-        10.18. send_close_notify (boolean)

-        10.19. con_ct_wq_max (integer)

-        10.20. ct_wq_max (integer)

-        10.21. ct_wq_blk_size (integer)

-        10.22. tls_log (int)

-        10.23. tls_debug (int)

-        10.24. low_mem_threshold1 (integer)

-        10.25. low_mem_threshold2 (integer)

-        10.26. tls_force_run (boolean)

-        10.27. session_cache (boolean)

-        10.28. session_id (str)

-        10.29. renegotiation (boolean)

-        10.30. config (string)

-        10.31. xavp_cfg (string)

-        10.32. event_callback (str)

-        10.33. rand_engine (str)

-        10.34. engine (string)

-        10.35. engine_config (string)

-        10.36. engine_algorithms (string)

-        10.37. verify_client (string)

-

-   11. Functions

-

-        11.1. is_peer_verified()

-        11.2. tls_set_connect_server_id(srvid)

-

-   12. RPC Commands

-

-        12.1. tls.info

-        12.2. tls.list

-        12.3. tls.options

-        12.4. tls.reload

-

-   13. Status

-

-        13.1. License

-        13.2. History

-

-   14. Event Routes

-

-        14.1. event_route[tls:connection-out]

-

-   15. TLS With Database Backend

+   4. Compiling the wolfSSL TLS Module

 1. Overview

-   This module implements the TLS transport for Kamailio using the OpenSSL

-   library (http://www.openssl.org). To enable the Kamailio TLS support

+   This module implements the TLS transport for Kamailio using the wolfSSL

+   library (https://www.wolfssl.com). To enable the Kamailio TLS support

    this module must be loaded and enable_tls=yes core setting must be

    added to the Kamailio config file.

-   IMPORTANT: the tls module must be loaded before any other Kamailio

-   module that uses libssl (OpenSSL library). A safe option is to have the

-   tls module loaded first (be in the first "loadmodule" in Kamailio.cfg).

+   This module is derived from the tls module and adapted to wolfSSL using

+   the OpenSSL-compatibility layer. Credit goes to the authors of the tls

+   module.

+

+   This module is based on wolfSSL 5.2.0 and 5.3.0 and is not fully

+   compatible with the tls module (protocol versions < 1.1 not supported

+   it the Debian package for example.

-   IMPORTANT: using this module compiled with newer versions of libssl

-   (e.g., v1.1+) may require Kamailio to be started with --atexit=no

-   command line parameters to avoid calling C atexit callbacks inside the

-   process ending during daemonize procedure as well as during shut down,

-   which can lead to crashes because it destroys and then accesses shared

-   memory. For example, such case has been reported for Ubuntu 20.04 or

-   RedHat 8.

+   This user is referred to the documentation of the tls module for

+   configuration and other information. Not all configuration keys are

+   implemented (e.g., protocol versions — defaults to 1.2+ and cipher

+   suites).

 2. Quick Start

    The default kamailio.cfg file has basic tls support included, it has to

    be enabled with "#!define WITH_TLS" directive.

-   The most important parameters to set the path to the public certificate

-   and private key files. You can either have them in different file or in

-   the same file in PEM format. The parameters for them are certificate

-   and private_key. They can be given as modparam or or provided in the

-   profiles of tls.cfg file.

-

-   When installing tls module of kamailio, a sample 'tls.cfg' file is

-   deployed in the same folder with 'kamailio.cfg', along with freshly

-   generated self signed certificates.

-

-   HINT: be sure you have enable_tls=yes to your kamailio.cfg.

-

    Example 1.1. Quick Start Basic Config

 #...

 loadmodule "sl.so"

-loadmodule "tls.so"

-

-modparam("tls", "private_key", "./server-test.pem")

-modparam("tls", "certificate", "./server-test.pem")

-modparam("tls", "ca_list", "./calist.pem")

-

-enable_tls=yes

-

-request_route {

-        if(proto != TLS) {

-                sl_send_reply("403", "Accepting TLS Only");

-                exit;

-        }

-        ...

-}

+loadmodule "tls_wolfssl.so"

+#... refer to Quick Start oftls module

+#... for further configuration

 3. Important Notes

-   The TLS module needs some special options enabled when compiling

-   Kamailio. These options are enabled by default, however in case you're

-   using a modified Kamailio version or Makefile, make sure that you

-   enable -DUSE_TLS and -DTLS_HOOKS (or compile with make TLS_HOOKS=1

-   which will take care of both options).

-

-   To quickly check if your Kamailio version was compiled with these

-   options, run kamailio -V and look for USE_TLS and TLS_HOOKS among the

-   flags.

-

-   For OpenSSL (libssl) v1.1.x, it is required to preload

-   'openssl_mutex_shared' library shipped by Kamailio. For more details

-   see 'src/modules/tls/openssl_mutex_shared/README.md'.

-

-   This module includes several workarounds for various Openssl bugs (like

-   compression and Kerberos using the wrong memory allocations functions,

-   low memory problems a.s.o). On startup it will try to enable the needed

-   workarounds based on the OpenSSL library version. Each time a known

-   problem is detected and a workaround is enabled, a message will be

-   logged. In general it is recommended to compile this module on the same

-   machine or a similar machine to where kamailio will be run or to link

-   it statically with libssl. For example if on the compile machine

-   OpenSSL does not have the Kerberos support enabled, but on the target

-   machine a Kerberos enabled OpenSSL library is installed, Kamailio

-   cannot apply the needed workarounds and will refuse to start. The same

-   thing will happen if the OpenSSL versions are too different (to force

-   Kamailio startup anyway, see the tls_force_run module parameter).

-

-   Compression is fully supported if you have a new enough OpenSSL version

-   (starting with 0.9.8). Although there are some problems with zlib

-   compression in currently deployed OpenSSL versions (up to and including

-   0.9.8d, see openssl bug #1468), the TLS module will automatically

-   switch to its own fixed version. Note however that starting with

-   Kamailio 3.1 compression is not enabled by default, due to the huge

-   extra memory consumption that it causes (about 10x more memory). To

-   enable it use modparam("tls", "tls_disable_compression", 0) (see

-   tls_disable_compression).

+   The wolfSSL TLS module is intended to be compiled with a recent version

+   of wolfSSL (5.2.0+).

-   The TLS module includes workarounds for the following known openssl

-   bugs:

-     * openssl #1204 (disable SS_OP_TLS_BLOCK_PADDING_BUG if compression

-       is enabled, for versions between 0.9.8 and 0.9.8c),

-     * openssl #1468 (fix zlib compression memory allocation),

-     * openssl #1467 (kerberos support will be disabled if the openssl

-       version is less than 0.9.8e-beta1)

-     * openssl #1491 (stop using tls in low memory situations due to the

-       very high risk of openssl crashing or leaking memory).

+4. Compiling the wolfSSL TLS Module

-   The bug reports can be viewed at http://rt.openssl.org/.

+   The development package for wolfSSL is required (libwolfssl-dev or

+   equivalent).

-4. Compiling the TLS Module

-

-   In most case compiling the TLS module is as simple as:

-make -C modules/tls

+   In most case compiling the wolfSSL TLS module is as simple as:

+make -C modules/tls_wolfssl

    or

-make modules modules=modules/tls

+make modules modules=modules/tls_wolfssl

    or (compiling whole Kamailio and the tls module)

-make all include_modules=tls

+make all include_modules=tls_wolfssl

    .

-

-   However in some cases the OpenSSL library requires linking with other

-   libraries. For example compiling the OpenSSL library with Kerberos and

-   zlib-shared support will require linking the TLS module with libkrb5

-   and libz. In this case just add TLS_EXTRA_LIBS="library list" to make's

-   command line. E.g.:

-make TLS_EXTRA_LIBS="-lkrb5 -lz" all include_modules=tls

-

-   In general, if Kamailio fails to start with a symbol not found error

-   when trying to load the TLS module (check the log), it means some

-   needed library was not linked and it must be added to TLS_EXTRA_LIBS

-

-   Elliptic Curve Diffie-Hellman (EDCH)-Ciphers are only supported in

-   OpenSSL 1.0.0e and later.

-

-5. TLS and Low Memory

-

-   The Openssl library doesn't handle low memory situations very well. If

-   memory allocations start to fail (due to memory shortage), Openssl can

-   crash or cause memory leaks (making the memory shortage even worse). As

-   of this writing all Openssl versions were affected (including 0.9.8e),

-   see Openssl bug #1491. The TLS module has some workarounds for

-   preventing this problem (see low_mem_treshold1 and low_mem_threshold2),

-   however starting Kamailio with enough shared memory is higly

-   recommended. When this is not possible a quick way to significantly

-   reduce Openssl memory usage it to disable compression (see

-   tls_disable_compression).

-

-6. TLS Debugging

-

-   Debugging messages can be selectively enabled by recompiling the TLS

-   module with a combination of the following defines:

-     * TLS_WR_DEBUG - debug messages for the write/send part.

-     * TLS_RD_DEBUG - debug messages for the read/receive part.

-     * TLS_BIO_DEBUG - debug messages for the custom BIO.

-

-   Example 1.2. Compiling TLS with Debug Messages

-make -C modules/tls extra_defs="-DTLS_WR_DEBUG -DTLS_RD_DEBUG"

-

-   To change the level at which the debug messages are logged, change the

-   tls_debug module parameter.

-

-7. Known Limitations

-

-   The private key must not be encrypted (Kamailio cannot ask you for a

-   password on startup).

-

-   The TLS certificate verifications ignores the certificate name, Subject

-   Altname and IP extensions, it just checks if the certificate is signed

-   by a recognized CA. One can use the select framework to try to overcome

-   this limitation (check in the script for the contents of various

-   certificate fields), but this is not only slow, but also not exactly

-   standard conforming (the verification should happen during TLS

-   connection establishment and not after).

-

-   TLS specific config reloading is not safe, so for now better don't use

-   it, especially under heavy traffic.

-

-   This documentation is incomplete. The provided selects are not

-   documented in this file. A list with all the ones implemented by the

-   TLS module can be found in the Cookbook https://www.kamailio.org/wiki/

-   in the section Selects for the respective version of Kamailio.

-

-8. Quick Certificate Howto

-

-   There are various ways to create, sign certificates and manage small

-   CAs (Certificate Authorities). If you are in a hurry and everything you

-   have are the installed OpenSSL libraries and utilities, read on.

-

-   Assumptions: we run our own CA.

-

-   Warning: in this example no key is encrypted. The client and server

-   private keys must not be encrypted (Kamailio doesn't support encrypted

-   keys), so make sure the corresponding files are readable only by

-   trusted people. You should use a password to protect your CA private

-   key.

-

-Assumptions

-

-The default openssl configuration (usually /etc/ssl/openssl.cnf)

-default_ca section is the one distributed with openssl and uses the default

-directories:

-

-...

-

-default_ca      = CA_default            # The default ca section

-

-[ CA_default ]

-

-dir             = ./demoCA              # Where everything is kept

-certs           = $dir/certs            # Where the issued certs are kept

-crl_dir         = $dir/crl              # Where the issued crl are kept

-database        = $dir/index.txt        # database index file.

-#unique_subject = no                    # Set to 'no' to allow creation of

-                                        # several certificates with same subject

-.

-new_certs_dir   = $dir/newcerts         # default place for new certs.

-

-certificate     = $dir/cacert.pem       # The CA certificate

-serial          = $dir/serial           # The current serial number

-crlnumber       = $dir/crlnumber        # the current CRL number

-crl             = $dir/crl.pem          # The current CRL

-private_key     = $dir/private/cakey.pem# The private key

-RANDFILE        = $dir/private/.rand    # private random number file

-

-...

-

-If this is not the case create a new OpenSSL config file that uses the above

-paths for the default CA and add to all the openssl commands:

- -config filename. E.g.:

-        openssl ca -config my_openssl.cnf -in kamailio1_cert_req.pem -out kamail

-io1_cert.pem

-

-

-Creating the CA certificate

-1. Create the CA directory

-        mkdir ca

-        cd ca

-

-2. Create the CA directory structure and files  (see ca(1))

-        mkdir demoCA            #default CA name, edit /etc/ssl/openssl.cnf

-        mkdir  demoCA/private

-        mkdir demoCA/newcerts

-        touch demoCA/index.txt

-        echo 01 >demoCA/serial

-        echo 01 >demoCA/crlnumber

-

-2. Create CA private key

-        openssl genrsa -out demoCA/private/cakey.pem 2048

-        chmod 600 demoCA/private/cakey.pem

-

-3. Create CA self-signed certificate

-        openssl req -out demoCA/cacert.pem   -x509 -new -key demoCA/private/cake

-y.pem

-

-

-Creating a server/client TLS certificate

-1. Create a certificate request (and its private key in privkey.pem)

-

-        openssl req -out kamailio1_cert_req.pem -new -nodes

-

-        WARNING: the organization name should be the same as in the CA certifica

-te.

-

-2. Sign it with the CA certificate

-        openssl ca -in kamailio1_cert_req.pem -out kamailio1_cert.pem

-

-3. Copy kamailio1_cert.pem to your Kamailio configuration dir

-

-

-Setting Kamailio to use the TLS certificate

-1. Create the CA list file:

-        for each of your CA certificates that you intend to use do:

-                cat cacert.pem >>calist.pem

-

-2. Copy your Kamailio certificate, private key and ca list file to your

-        intended machine (preferably in your Kamailio configuration directory,

-         this is the default place Kamailio searches for).

-

-3. Set up Kamailio.cfg to use the certificate

-        if your Kamailio certificate name is different from cert.pem or it is no

-t

-        placed in Kamailio cfg. directory, add to your kamailio.cfg:

-                modparam("tls", "certificate", "/path/cert_file_name")

-

-4. Set up Kamailio to use the private key

-        if your private key is not contained in the same file as the certificate

-        (or the certificate name is not the default cert.pem), add to your

-         Kamailio.cfg:

-                modparam("tls", "private_key", "/path/private_key_file")

-

-5. Set up Kamailio to use the CA list (optional)

-   The CA list is not used for your server certificate - it's used to approve ot

-her servers

-   and clients connecting to your server with a client certificate or for approv

-ing

-   a certificate used by a server your server connects to.

-        add to your Kamailio.cfg:

-                modparam("tls", "ca_list", "/path/ca_list_file")

-

-6. Set up TLS authentication options:

-                modparam("tls", "verify_certificate", 1)

-                modparam("tls", "require_certificate", 1)

-        (for more information see the module parameters documentation)

-

-

-Revoking a certificate and using a CRL

-1. Revoking a certificate:

-        openssl ca -revoke bad_cert.pem

-

-2. Generate/update the certificate revocation list:

-        openssl ca -gencrl -out my_crl.pem

-

-3. Copy my_crl.pem to your Kamailio config. dir

-

-4. Set up Kamailio to use the CRL:

-                modparam("tls", "crl", "path/my_crl.pem")

-

-9. HSM Howto

-

-   This documents OpenSSL engine support for private keys in HSM.

-

-   Assumptions: an OpenSSL engine configured with private key. We still

-   require the certificate file and list of CA certificates per a regular

-   TLS configuration.

-

-Thales Luna Example

-

-...

-# Example for Thales Luna

-modparam("tls", "engine", "gem")

-modparam("tls", "engine_config", "/usr/local/etc/kamailio/thales.cnf")

-modparam("tls", "engine_algorithms", "EC")

-...

-

-/usr/local/etc/kamailio/thales.cnf is a OpenSSL config format file used to

-bootstrap the engine, e.g., pass the PIN.

-

-...

-# the key kamailio is mandatory

-kamailio = openssl_init

-

-[ openssl_init ]

-engines = engine_section

-

-[ engine_section ]

-# gem is the name of the Thales Luna OpenSSL engine

-gem = gem_section

-

-[ gem_section ]

-# from Thales documentation

-dynamic_path = /usr/lib64/engines-1.1/gem.so

-ENGINE_INIT = 0:20:21:password=1234-ABCD-5678-EFGH

-...

-

-

-Thales nShield Connect

-

-Place holder

-

-10. Parameters

-

-   10.1. tls_method (string)

-   10.2. certificate (string)

-   10.3. private_key (string)

-   10.4. ca_list (string)

-   10.5. ca_path (str)

-   10.6. crl (string)

-   10.7. verify_certificate (boolean)

-   10.8. verify_depth (integer)

-   10.9. require_certificate (boolean)

-   10.10. cipher_list (string)

-   10.11. server_name (string)

-   10.12. connection_timeout (int)

-   10.13. tls_disable_compression (boolean)

-   10.14. ssl_release_buffers (integer)

-   10.15. ssl_freelist_max_len (integer)

-   10.16. ssl_max_send_fragment (integer)

-   10.17. ssl_read_ahead (boolean)

-   10.18. send_close_notify (boolean)

-   10.19. con_ct_wq_max (integer)

-   10.20. ct_wq_max (integer)

-   10.21. ct_wq_blk_size (integer)

-   10.22. tls_log (int)

-   10.23. tls_debug (int)

-   10.24. low_mem_threshold1 (integer)

-   10.25. low_mem_threshold2 (integer)

-   10.26. tls_force_run (boolean)

-   10.27. session_cache (boolean)

-   10.28. session_id (str)

-   10.29. renegotiation (boolean)

-   10.30. config (string)

-   10.31. xavp_cfg (string)

-   10.32. event_callback (str)

-   10.33. rand_engine (str)

-   10.34. engine (string)

-   10.35. engine_config (string)

-   10.36. engine_algorithms (string)

-   10.37. verify_client (string)

-

-10.1. tls_method (string)

-

-   Sets the TLS protocol method. Possible values are:

-     * TLSv1.2+ - TLSv1.2 or newer (TLSv1.3, ...) connections are accepted

-       (available starting with openssl/libssl v1.1.1)

-     * TLSv1.2 - only TLSv1.2 connections are accepted (available starting

-       with openssl/libssl v1.0.1e)

-     * TLSv1.1+ - TLSv1.1 or newer (TLSv1.2, ...) connections are accepted

-       (available starting with openssl/libssl v1.0.1)

-     * TLSv1.1 - only TLSv1.1 connections are accepted (available starting

-       with openssl/libssl v1.0.1)

-     * TLSv1+ - TLSv1.0 or newer (TLSv1.1, TLSv1.2, ...) connections are

-       accepted.

-     * TLSv1 - only TLSv1 (TLSv1.0) connections are accepted. This is the

-       default value.

-     * SSLv3 - only SSLv3 connections are accepted. Note: you shouldn't

-       use SSLv3 for anything which should be secure.

-     * SSLv2 - only SSLv2 connections, for old clients. Note: you

-       shouldn't use SSLv2 for anything which should be secure. Newer

-       versions of OpenSSL libraries don't include support for it anymore.

-     * SSLv23 - any of the SSLv2, SSLv3 and TLSv1 or newer methods will be

-       accepted.

-       From the OpenSSL manual: "A TLS/SSL connection established with

-       these methods may understand the SSLv3, TLSv1, TLSv1.1 and TLSv1.2

-       protocols. If extensions are required (for example server name) a

-       client will send out TLSv1 client hello messages including

-       extensions and will indicate that it also understands TLSv1.1,

-       TLSv1.2 and permits a fallback to SSLv3. A server will support

-       SSLv3, TLSv1, TLSv1.1 and TLSv1.2 protocols. This is the best

-       choice when compatibility is a concern."

-       Note: For older OpenSSL library versions, this option allows SSLv2,

-       with hello messages done over SSLv2. You shouldn't use SSLv2 or

-       SSLv3 for anything which should be secure.

-

-   If RFC 3261 conformance is desired, at least TLSv1 must be used. For

-   compatibility with older clients SSLv23 is the option, but again, be

-   aware of security concerns, SSLv2/3 being considered very insecure by

-   2014. For current information about what's considered secure, please

-   consult, IETF BCP 195, currently RFC 7525 - "Recommendations for Secure

-   Use of Transport Layer Security (TLS) and Datagram Transport Layer

-   Security (DTLS)"

-

-   Example 1.3. Set tls_method parameter

-...

-modparam("tls", "tls_method", "TLSv1")

-...

-

-10.2. certificate (string)

-

-   Sets the certificate file name. The certificate file can also contain

-   the private key in PEM format.

-

-   If the file name starts with a '.' the path will be relative to the

-   working directory (at runtime). If it starts with a '/' it will be an

-   absolute path and if it starts with anything else the path will be

-   relative to the main config file directory (e.g.: for kamailio -f

-   /etc/kamailio/kamailio.cfg it will be relative to /etc/kamailio/).

-

-   The default value is /usr/local/etc/kamailio/cert.pem

-

-   Example 1.4. Set certificate parameter

-...

-modparam("tls", "certificate", "/usr/local/etc/kamailio/my_certificate.pem")

-...

-

-10.3. private_key (string)

-

-   Sets the private key file name. The private key can be in the same file

-   as the certificate or in a separate file, specified by this

-   configuration parameter.

-

-   If the file name starts with a '.' the path will be relative to the

-   working directory (at runtime). If it starts with a '/' it will be an

-   absolute path and if it starts with anything else the path will be

-   relative to the main config file directory (e.g.: for kamailio -f

-   /etc/kamailio/kamailio.cfg it will be relative to /etc/kamailio/).

-

-   Note: the private key can be contained in the same file as the

-   certificate (just append it to the certificate file, e.g.: cat pkey.pem

-   >> cert.pem)

-

-   The default value is /usr/local/etc/kamailio/cert.pem

-

-   Example 1.5. Set private_key parameter

-...

-modparam("tls", "private_key", "/usr/local/etc/kamailio/my_pkey.pem")

-...

-

-10.4. ca_list (string)

-

-   Sets the CA list file name. This file contains a list of all the

-   trusted CAs certificates used when connecting to other SIP

-   implementations. If a signature in a certificate chain belongs to one

-   of the listed CAs, the verification of that certificate will succeed.

-

-   If the file name starts with a '.' the path will be relative to the

-   working directory (at runtime). If it starts with a '/' it will be an

-   absolute path and if it starts with anything else the path will be

-   relative to the main config file directory (e.g.: for kamailio -f

-   /etc/kamailio/kamailio.cfg it will be relative to /etc/kamailio/).

-

-   By default the CA file is not set.

-

-   An easy way to create the CA list is to append each trusted trusted CA

-   certificate in the PEM format to one file, e.g.:

-for f in trusted_cas/*.pem ; do cat "$f" >> ca_list.pem ; done

-

-   See also verify_certificate, verify_depth, require_certificate and crl.

-

-   Example 1.6. Set ca_list parameter

-...

-modparam("tls", "ca_list", "/usr/local/etc/kamailio/ca_list.pem")

-...

-

-10.5. ca_path (str)

-

-   Sets the path with the trusted CA files, to be given as parameter

-   SSL_CTX_load_verify_locations(). The certificates in ca_path are only

-   looked up when required, e.g. when building the certificate chain or

-   when actually performing the verification of a peer certificate. They

-   are not given to the client (not loaded to be provided to

-   SSL_CTX_set_client_CA_list()), only the ones in ca_list files are sent

-   to the client. It requires to use c_rehash to generate the hash map for

-   certificate search, for more see the manual of libssl for

-   SSL_CTX_load_verify_locations() function.

-

-   By default it is not set.

-

-   Example 1.7. Set ca_path parameter

-...

-modparam("tls", "ca_path", "/usr/local/etc/kamailio/ca")

-...

-

-10.6. crl (string)

-

-   Sets the certificate revocation list (CRL) file name. This file

-   contains a list of revoked certificates. Any attempt to verify a

-   revoked certificate will fail.

-

-   If not set, no CRL list will be used.

-

-   If the file name starts with a '.' the path will be relative to the

-   working directory (at runtime). If it starts with a '/' it will be an

-   absolute path and if it starts with anything else the path will be

-   relative to the main config file directory (e.g.: for kamailio -f

-   /etc/kamailio/kamailio.cfg it will be relative to /etc/kamailio/).

-

-Note

-

-   If set, require_certificate should also be set or it will not have any

-   effect.

-

-   By default the CRL file name is not set.

-

-   To update the CRL in a running Kamailio, make sure you configure TLS

-   via a separate TLS config file (the config modparam) and issue a

-   tls.reload RPC call, e.g.:

- $ kamcmd tls.reload

-

-   A quick way to create the CRL in PEM format, using OpenSSL is:

- $ openssl ca -gencrl -keyfile cacert.key -cert cacert.pem -out my_crl.pem

-

-   my_crl.pem will contain the signed list of the revoked certificates.

-

-   To revoke a TLS certificate use something like:

- $ openssl ca -revoke bad_cert.pem -keyfile cacert.key -cert cacert.pem

-

-   and then refresh the crl file using the command above.

-

-   To display the CRL contents use:

- $ openssl crl -in crl.pem -noout -text

-

-   See also ca_list, verify_certificate, verify_depth and

-   require_certificate.

-

-   Example 1.8. Set crl parameter

-...

-modparam("tls", "crl", "/usr/local/etc/kamailio/crl.pem")

-...

-

-10.7. verify_certificate (boolean)

-

-   If enabled it will force certificate verification when connecting to

-   other SIP servers.. For more information see the verify(1) OpenSSL man

-   page.

-

-   Note: the certificate verification will always fail if the ca_list is

-   empty.

-

-   See also: ca_list, require_certificate, verify_depth.

-

-   By default the certificate verification is off.

-

-   Example 1.9. Set verify_certificate parameter

-...

-modparam("tls", "verify_certificate", 1)

-...

-

-10.8. verify_depth (integer)

-

-   Sets how far up the certificate chain will the certificate verification

-   go in the search for a trusted CA.

-

-   See also: ca_list, require_certificate, verify_certificate,

-

-   The default value is 9.

-

-   Example 1.10. Set verify_depth parameter

-...

-modparam("tls", "verify_depth", 9)

-...

-

-10.9. require_certificate (boolean)

-

-   When enabled Kamailio will require a certificate from a client

-   connecting to the TLS port. If the client does not offer a certificate

-   and verify_certificate is on, certificate verification will fail.

-

-   The default value is off.

-

-   Example 1.11. Set require_certificate parameter

-...

-modparam("tls", "require_certificate", 1)

-...

-

-10.10. cipher_list (string)

-

-   Sets the list of accepted ciphers. The list consists of cipher strings

-   separated by colons. For more information on the cipher list format see

-   the cipher(1) OpenSSL man page.