tls - OpenGrok cross reference for /dports/net/kamailio/kamailio-5.4.5/src/modules/tls/

TLS Module

Andrei Pelinescu-Onciul

   iptelorg GmbH

Carsten Bock

   ng-voice GmbH

Olle E. Johansson

   Edvina AB

   Copyright © 2007 iptelorg GmbH

   Copyright © 2014 ng-voice GmbH
     __________________________________________________________________

   Table of Contents

   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. crl (string)
              10.6. verify_certificate (boolean)
              10.7. verify_depth (integer)
              10.8. require_certificate (boolean)
              10.9. cipher_list (string)
              10.10. server_name (string)
              10.11. send_timeout (int)
              10.12. handshake_timeout (int)
              10.13. connection_timeout (int)
              10.14. tls_disable_compression (boolean)
              10.15. ssl_release_buffers (integer)
              10.16. ssl_freelist_max_len (integer)
              10.17. ssl_max_send_fragment (integer)
              10.18. ssl_read_ahead (boolean)
              10.19. send_close_notify (boolean)
              10.20. con_ct_wq_max (integer)
              10.21. ct_wq_max (integer)
              10.22. ct_wq_blk_size (integer)
              10.23. tls_log (int)
              10.24. tls_debug (int)
              10.25. low_mem_threshold1 (integer)
              10.26. low_mem_threshold2 (integer)
              10.27. tls_force_run (boolean)
              10.28. session_cache (boolean)
              10.29. session_id (str)
              10.30. renegotiation (boolean)
              10.31. config (string)
              10.32. xavp_cfg (string)
              10.33. event_callback (str)
              10.34. rand_engine (str)
              10.35. engine (string)
              10.36. engine_config (string)
              10.37. engine_algorithms (string)
              10.38. verify_client (string)

        11. Functions

              11.1. is_peer_verified()

        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

   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 crl parameter
   1.8. Set verify_certificate parameter
   1.9. Set verify_depth parameter
   1.10. Set require_certificate parameter
   1.11. Set cipher_list parameter
   1.12. Set server_name parameter
   1.13. Set connection_timeout parameter
   1.14. Set tls.connection_timeout at runtime
   1.15. Set tls_disable_compression parameter
   1.16. Set ssl_release_buffers parameter
   1.17. Set ssl_freelist_max_len parameter
   1.18. Set ssl_max_send_fragment parameter
   1.19. Set ssl_read_ahead parameter
   1.20. Set send_close_notify parameter
   1.21. Set tls.send_close_notify at runtime
   1.22. Set con_ct_wq_max parameter
   1.23. Set tls.con_ct_wq_max at runtime
   1.24. Set ct_wq_max parameter
   1.25. Set tls.ct_wq_max at runtime
   1.26. Set ct_wq_blk_size parameter
   1.27. Set tls.ct_wq_max at runtime
   1.28. Set tls_log parameter
   1.29. Set tls.log at runtime
   1.30. Set tls_debug parameter
   1.31. Set tls.debug at runtime
   1.32. Set low_mem_threshold1 parameter
   1.33. Set tls.low_mem_threshold1 at runtime
   1.34. Set tls.low_mem_threshold2 parameter
   1.35. Set tls.low_mem_threshold2 at runtime
   1.36. Set tls_force_run parameter
   1.37. Set session_cache parameter
   1.38. Set session_id parameter
   1.39. Set renegotiation parameter
   1.40. Sample TLS Config File
   1.41. Set config parameter
   1.42. Change and reload the TLS configuration at runtime
   1.43. Set xavp_cfg parameter
   1.44. Set event_callback parameter
   1.45. Set rand_engine parameter
   1.46. Set verify_client modparam parameter
   1.47. Set verify_client tls.cfg parameter
   1.48. is_peer_verified usage
   1.49. Use of event_route[tls:connection-out]

Chapter 1. Admin Guide

   Table of Contents

   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. crl (string)
        10.6. verify_certificate (boolean)
        10.7. verify_depth (integer)
        10.8. require_certificate (boolean)
        10.9. cipher_list (string)
        10.10. server_name (string)
        10.11. send_timeout (int)
        10.12. handshake_timeout (int)
        10.13. connection_timeout (int)
        10.14. tls_disable_compression (boolean)
        10.15. ssl_release_buffers (integer)
        10.16. ssl_freelist_max_len (integer)
        10.17. ssl_max_send_fragment (integer)
        10.18. ssl_read_ahead (boolean)
        10.19. send_close_notify (boolean)
        10.20. con_ct_wq_max (integer)
        10.21. ct_wq_max (integer)
        10.22. ct_wq_blk_size (integer)
        10.23. tls_log (int)
        10.24. tls_debug (int)
        10.25. low_mem_threshold1 (integer)
        10.26. low_mem_threshold2 (integer)
        10.27. tls_force_run (boolean)
        10.28. session_cache (boolean)
        10.29. session_id (str)
        10.30. renegotiation (boolean)
        10.31. config (string)
        10.32. xavp_cfg (string)
        10.33. event_callback (str)
        10.34. rand_engine (str)
        10.35. engine (string)
        10.36. engine_config (string)
        10.37. engine_algorithms (string)
        10.38. verify_client (string)

   11. Functions

        11.1. is_peer_verified()

   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

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 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).

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;
        }
        ...
}

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 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).

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

4. Compiling the TLS Module

   In most case compiling the TLS module is as simple as:
make -C modules/tls

   or
make modules modules=modules/tls

   or (compiling whole Kamailio and the tls module)
make all include_modules=tls

   .

   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.

AWS CloudHSM Example
--------------------

...
# Example for AWS CloudHSM (SafeNet Luna)
modparam("tls", "engine", "gem")
modparam("tls", "engine_config", "/usr/local/etc/kamailio/luna.conf")
modparam("tls", "engine_algorithms", "ALL)
...

/usr/local/etc/kamailio/luna.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 SafeNet Luna OpenSSL engine
gem = gem_section

[ gem_section ]
# from SafeNet documentation
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. crl (string)
   10.6. verify_certificate (boolean)
   10.7. verify_depth (integer)
   10.8. require_certificate (boolean)
   10.9. cipher_list (string)
   10.10. server_name (string)
   10.11. send_timeout (int)
   10.12. handshake_timeout (int)
   10.13. connection_timeout (int)
   10.14. tls_disable_compression (boolean)
   10.15. ssl_release_buffers (integer)
   10.16. ssl_freelist_max_len (integer)
   10.17. ssl_max_send_fragment (integer)
   10.18. ssl_read_ahead (boolean)
   10.19. send_close_notify (boolean)
   10.20. con_ct_wq_max (integer)
   10.21. ct_wq_max (integer)
   10.22. ct_wq_blk_size (integer)
   10.23. tls_log (int)
   10.24. tls_debug (int)
   10.25. low_mem_threshold1 (integer)
   10.26. low_mem_threshold2 (integer)
   10.27. tls_force_run (boolean)
   10.28. session_cache (boolean)
   10.29. session_id (str)
   10.30. renegotiation (boolean)
   10.31. config (string)
   10.32. xavp_cfg (string)
   10.33. event_callback (str)
   10.34. rand_engine (str)
   10.35. engine (string)
   10.36. engine_config (string)
   10.37. engine_algorithms (string)
   10.38. 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. 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.7. Set crl parameter
...
modparam("tls", "crl", "/usr/local/etc/kamailio/crl.pem")
...

10.6. 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.8. Set verify_certificate parameter
...
modparam("tls", "verify_certificate", 1)
...

10.7. 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.9. Set verify_depth parameter
...
modparam("tls", "verify_depth", 9)
...

10.8. 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.10. Set require_certificate parameter
...
modparam("tls", "require_certificate", 1)
...

10.9. 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.

   The default value is not set (all the OpenSSL supported ciphers are
   enabled).

   Example 1.11. Set cipher_list parameter
...
modparam("tls", "cipher_list", "HIGH")
...

10.10. server_name (string)

   Sets the Server Name Indication (SNI) value.

   This is a TLS extension enabling one TLS server to serve multiple host
   names with unique certificates.

   The default value is empty (not set).

   Example 1.12. Set server_name parameter
...
modparam("tls", "server_name", "kamailio.org")
...

10.11. send_timeout (int)

   This parameter is obsolete and cannot be used in newer TLS versions (>
   Kamailio 3.0). In these versions the send_timeout is replaced by
   tcp_send_timeout (common with all the tcp connections).

10.12. handshake_timeout (int)

   This parameter is obsolete and cannot be used in newer TLS versions (>
   Kamailio 3.0). In these versions the handshake_timeout is replaced by
   tcp_connect_timeout (common with all the tcp connections).

10.13. connection_timeout (int)

   Sets the amount of time after which an idle TLS connection will be
   closed, if no I/O ever occurred after the initial open. If an I/O event
   occurs, the timeout will be extended with tcp_connection_lifetime. The
   value is expressed in seconds.

   The default value is 10 min.

   If the value set is -1, the connection will never be close on idle.

   This setting can be changed also at runtime, via the RPC interface and
   config framework. The config variable name is tls.connection_timeout.

   Example 1.13. Set connection_timeout parameter
...
modparam("tls", "connection_timeout", 60)
...

   Example 1.14. Set tls.connection_timeout at runtime
 $ kamcmd cfg.set_now_int tls connection_timeout 180

10.14. tls_disable_compression (boolean)

   If set compression over TLS will be disabled. Note that compression
   uses a lot of memory (about 10x more then with the compression
   disabled), so if you want to minimize memory usage is a good idea to
   disable it. TLS compression also expose you for the CRIME security
   vulnerability.

   By default TLS compression is disabled.

   Example 1.15. Set tls_disable_compression parameter
...
modparam("tls", "tls_disable_compression", 0) # enable
...

10.15. ssl_release_buffers (integer)

   Release internal OpenSSL read or write buffers as soon as they are no
   longer needed. Combined with ssl_freelist_max_len has the potential of
   saving a lot of memory ( ~ 32k per connection in the default
   configuration, or 16k + ssl_max_send_fragment). For Kamailio versions >
   3.0 it makes little sense to disable it (0) since the tls module
   already has its own internal buffering.

   A value of -1 would not change this option from its openssl default.
   Use 0 or 1 for enable/disable.

   By default the value is 1 (enabled).

Note

   This option is supported only for OpenSSL versions >= 1.0.0. On all the
   other versions attempting to change the default will trigger an error.

   Example 1.16. Set ssl_release_buffers parameter
modparam("tls", "ssl_release_buffers", 1)

10.16. ssl_freelist_max_len (integer)

   Sets the maximum number of free memory chunks, that OpenSSL will keep
   per connection. Setting it to 0 would cause any unused memory chunk to
   be immediately freed, reducing the memory footprint. A too large value
   would result in extra memory consumption.

   Should be combined with ssl_release_buffers.

   A value of -1 has a special meaning: the OpenSSL default will be used
   (no attempt on changing the value will be made). For OpenSSL 1.0 the
   internal default is 32.

   By default the value is 0 (no freelist).

Note

   This option is supported only for OpenSSL versions >= 1.0.0. On all the
   other versions attempting to change the default will trigger an error.

   Example 1.17. Set ssl_freelist_max_len parameter
modparam("tls", "ssl_freelist_max_len", 0)

10.17. ssl_max_send_fragment (integer)

   Sets the maximum number of bytes (from the clear text) sent into one
   TLS record. Valid values are between 512 and 16384. Note however that
   even valid low values might not be big enough to allow a successful
   handshake (try minimum 1024).

   Lower values would lead to less memory usage, but values lower then the
   typical Kamailio write size would incur a slight performance penalty.
   Good values are bigger then the size of the biggest SIP packet one
   normally expects to forward. For example in most setups 2048 would be a
   good value.

Note

   Values on the lower side, even if valid (> 512), might not allow for a
   successful initial handshake. This happens if the certificate does not
   fit inside one send fragment. Values lower then 1024 should not be
   used. Even with higher values, if the handshake fails, try increasing
   the value.

   A value of -1 has a special meaning: the OpenSSL default will be used
   (no attempt on changing the value will be made).

   By default the value is -1 (the OpenSSL default, which at least in
   OpenSSL 1.0.0 is ~ 16k).

Note

   This option is supported only for OpenSSL versions >= 0.9.9. On all the
   other versions attempting to change the default will trigger an error.

   Example 1.18. Set ssl_max_send_fragment parameter
modparam("tls", "ssl_max_send_fragment", 4096)

10.18. ssl_read_ahead (boolean)

   Enables read ahead, reducing the number of internal OpenSSL BIO read()
   calls. This option has only debugging value, in normal circumstances it
   should not be changed from the default.

   When disabled OpenSSL will make at least 2 BIO read() calls per
   received record: one to get the record header and one to get the rest
   of the record.

   The TLS module buffers internally all read()s and defines its own fast
   BIO so enabling this option would only cause more memory consumption
   and a minor slow-down (extra memcpy).

   A value of -1 has a special meaning: the OpenSSL default will be used
   (no attempt on changing the value will be made).

   By default the value is 0 (disabled).

   Example 1.19. Set ssl_read_ahead parameter
modparam("tls", "ssl_read_ahead", 1)

10.19. send_close_notify (boolean)

   Enables/disables sending close notify alerts prior to closing the
   corresponding TCP connection. Sending the close notify prior to TCP
   shutdown is "nicer" from a TLS point of view, but it has a measurable
   performance impact. Default: off. Can be set at runtime
   (tls.send_close_notify).

   The default value is 0 (off).

   It can be changed also at runtime, via the RPC interface and config
   framework. The config variable name is tls.send_close_notify.

   Example 1.20. Set send_close_notify parameter
...
modparam("tls", "send_close_notify", 1)
...

   Example 1.21. Set tls.send_close_notify at runtime
 $ kamcmd cfg.set_now_int tls send_close_notify 1

10.20. con_ct_wq_max (integer)

   Sets the maximum allowed per connection clear-text send queue size in
   bytes. This queue is used when data cannot be encrypted and sent
   immediately because of an ongoing TLS level renegotiation.

   The default value is 65536 (64 Kb).

   It can be changed also at runtime, via the RPC interface and config
   framework. The config variable name is tls.con_ct_wq_max.

   Example 1.22. Set con_ct_wq_max parameter
...
modparam("tls", "con_ct_wq_max", 1048576)
...

   Example 1.23. Set tls.con_ct_wq_max at runtime
 $ kamcmd cfg.set_now_int tls con_ct_wq_max 1048576

10.21. ct_wq_max (integer)

   Sets the maximum total number of bytes queued in all the clear-text
   send queues. These queues are used when data cannot be encrypted and
   sent immediately because of an ongoing TLS level renegotiation.

   The default value is 10485760 (10 Mb).

   It can be changed also at runtime, via the RPC interface and config
   framework. The config variable name is tls.ct_wq_max.

   Example 1.24. Set ct_wq_max parameter
...
modparam("tls", "ct_wq_max", 4194304)
...

   Example 1.25. Set tls.ct_wq_max at runtime
 $ kamcmd cfg.set_now_int tls ct_wq_max 4194304

10.22. ct_wq_blk_size (integer)

   Minimum block size for the internal clear-text send queues (debugging /
   advanced tuning). Good values are multiple of typical datagram sizes.

   The default value is 4096.

   It can be changed also at runtime, via the RPC interface and config
   framework. The config variable name is tls.ct_wq_blk_size.

   Example 1.26. Set ct_wq_blk_size parameter
...
modparam("tls", "ct_wq_blk_size", 2048)
...

   Example 1.27. Set tls.ct_wq_max at runtime
 $ kamcmd cfg.set_now_int tls ct_wq_blk_size 2048

10.23. tls_log (int)

   Sets the log level at which TLS related messages will be logged.

   The default value is 3 (L_DBG).

   It can be changed also at runtime, via the RPC interface and config
   framework. The config variable name is tls.log.

   Example 1.28. Set tls_log parameter
...
# ignore TLS messages if Kamailio is started with debug less than 10
modparam("tls", "tls_log", 10)
...

   Example 1.29. Set tls.log at runtime
 $ kamcmd cfg.set_now_int tls log 10

10.24. tls_debug (int)

   Sets the log level at which TLS debug messages will be logged. Note
   that TLS debug messages are enabled only if the TLS module is compiled
   with debugging enabled (e.g. -DTLS_WR_DEBUG, -DTLS_RD_DEBUG or
   -DTLS_BIO_DEBUG).

   The default value is 3 (L_DBG).

   It can be changed also at runtime, via the RPC interface and config
   framework. The config variable name is tls.debug.

   Example 1.30. Set tls_debug parameter
...
# ignore TLS debug messages if Kamailio is started with debug less than 10
modparam("tls", "tls_debug", 10)
...

   Example 1.31. Set tls.debug at runtime
 $ kamcmd cfg.set_now_int tls debug 10

10.25. low_mem_threshold1 (integer)

   Sets the minimal free memory from which attempts to open or accept new
   TLS connections will start to fail. The value is expressed in KB.

   The default value depends on whether the OpenSSL library used handles
   low memory situations in a good way (openssl bug #1491). As of this
   writing this is not true for any OpenSSL version (including 0.9.8e).

   If an ill-behaved OpenSSL version is detected, a very conservative
   value is chosen, which depends on the maximum possible number of
   simultaneously created TLS connections (and hence on the process
   number).

   The following values have a special meaning:
     * -1 - use the default value
     * 0 - disable (TLS connections will not fail preemptively)

   It can be changed also at runtime, via the RPC interface and config
   framework. The config variable name is tls.low_mem_threshold1.

   See also tls.low_mem_threshold2.

   Example 1.32. Set low_mem_threshold1 parameter
...
modparam("tls", "low_mem_threshold1", -1)
...

   Example 1.33. Set tls.low_mem_threshold1 at runtime
 $ kamcmd cfg.set_now_int tls low_mem_threshold1 2048

10.26. low_mem_threshold2 (integer)

   Sets the minimal free memory from which TLS operations on already
   established TLS connections will start to fail preemptively. The value
   is expressed in KB.

   The default value depends on whether the OpenSSL library used handles
   low memory situations (openssl bug #1491). As of this writing this is
   not true for any OpenSSL version (including 0.9.8e).

   If an ill-behaved OpenSSL version is detected, a very conservative
   value is chosen, which depends on the maximum possible number of
   simultaneously created TLS connections (and hence on the process
   number).

   The following values have a special meaning:
     * -1 - use the default value
     * 0 - disable (TLS operations will not fail preemptively)

   It can be changed also at runtime, via the RPC interface and config
   framework. The config variable name is tls.low_mem_threshold2.

   See also tls.low_mem_threshold1.

   Example 1.34. Set tls.low_mem_threshold2 parameter
...
modparam("tls", "low_mem_threshold2", -1)
...

   Example 1.35. Set tls.low_mem_threshold2 at runtime
 $ kamcmd cfg.set_now_int tls low_mem_threshold2 1024

10.27. tls_force_run (boolean)

   If enabled Kamailio will start even if some of the OpenSSL sanity
   checks fail (turn it on at your own risk).

   If any of the following sanity checks fail, Kamailio will not start:
     * the version of the library the TLS module was compiled with is "too
       different" from the library used at runtime. The versions should
       have the same major, minor and fix level (e.g.: 0.9.8a and 0.9.8c
       are ok, but 0.9.8 and 0.9.9 are not)
     * the OpenSSL library used at compile time and the one used at
       runtime have different Kerberos options

   By default tls_force_run is disabled.

   Example 1.36. Set tls_force_run parameter
...
modparam("tls", "tls_force_run", 11)
...

10.28. session_cache (boolean)

   If enabled Kamailio will do caching of the TLS sessions data,
   generation a session_id and sending it back to client.

   By default TLS session caching is disabled (0).

   Example 1.37. Set session_cache parameter
...
modparam("tls", "session_cache", 1)
...

10.29. session_id (str)

   The value for session ID context, making sense when session caching is
   enabled.

   By default TLS session_id is "kamailio-tls-5.x.y".

   Example 1.38. Set session_id parameter
...
modparam("tls", "session_id", "my-session-id-context")
...

10.30. renegotiation (boolean)

   If enabled Kamailio will allow renegotiations of TLS connection
   initiated by the client. This may expose to a security risk if the
   client is not a trusted peer and keeps renegotiating, consuming CPU and
   bandwidth resources.

   By default TLS renegotiation is disabled (0).

   Example 1.39. Set renegotiation parameter
...
modparam("tls", "renegotiation", 1)
...

10.31. config (string)

   Sets the name of the TLS specific configuration file or configuration
   directory.

   If set the TLS module will load a special configuration file or
   configuration files from configuration directory, in which different
   TLS parameters can be specified on a per role (server or client) and
   domain basis (for now only IPs). The corresponding module parameters
   will be ignored if a separate configuration file is used.

   If the file or directory 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 no TLS configuration file is specified.

   The following parameters can be set in the config file, for each
   domain:
     * tls_method - (str) - TLS methods
     * verify_certificate - (bool) - see modparam
     * require_certificate - (bool) - see modparam
     * verify_client - (str) - see modparam
     * private_key - (str) - see modparam
     * certificate - (str) - see modparam
     * verify_depth - (int) - see modparam
     * ca_list - (str) - see modparam
     * crl - (str) - see modparam
     * cipher_list - (str) - see modparam
     * server_name - (str) - SNI (server name identification)
     * server_name_mode - (int) - how to match server_name
     * server_id - (str) - server id

   The value for server_name_mode specifies how to match the server_name
   (SNI). If set to 1, match the domain and all its subdomains. If set to
   2, match only the subdomains. If set to 0 (or anything else), match
   only the domain given in server_name.

   The value for server_id can be any string, being used to match TLS
   client config profile, overriding the match on ip:port and server_name.
   This is the recommended way for selecting a specific TLS client config
   profile, because the local or remote port is hard to predict for a
   stream connection - see parameter xavp_cfg to learn how to enable it.

   All the parameters that take filenames as values will be resolved using
   the same rules as for the tls config filename itself: starting with a
   '.' means relative to the working directory, a '/' means an absolute
   path and anything else a path relative to the directory of the current
   Kamailio main config file.

   Kamailio acts as a server when it accepts a connection and as a client
   when it initiates a new connection by itself (it connects to
   something).

   The tls.cfg consists on a set of server and client TLS domain profiles.
   A server TLS domain profile starts with [server:domain]. A client TLS
   domain profile starts with [client:domain]. The tokens 'server' and
   'client' are static values. The 'domain' part can be: 'ip:port' - the
   IP address and port to match with the TLS connection; 'default' -
   (static string) for client and server profiles to be used when no other
   profile is matched; 'any' - (static string) for client and server
   profiles to be matched based on 'server_name', no matter of IP and port
   of the TLS connection.

   There can be only one of each [server:default] and [client:default]
   profile definitions. Other profiles can be defined many times with the
   same domain ('ip:port' or 'any'), but in that case they must have
   'server_name' set for matching SNI.

   It is highly recommended to have [server:default] and [client:default]
   profile definitions. They are needed when SNI is not yet available. If
   SNI is provided, then the profile definition is searched again to match
   on 'server_name'.

   Example 1.40. Sample TLS Config File
...
[server:default]
method = TLSv1
verify_certificate = yes
require_certificate = yes
private_key = default_key.pem
certificate = default_cert.pem
ca_list = default_ca.pem
crl = default_crl.pem

[client:default]
verify_certificate = yes
require_certificate = yes

# more relaxed for connection on the loopback interface
[server:127.0.0.1:5061]
method = TLSv1
verify_certificate = yes
require_certificate = no
private_key = local_kamailio_org_key.pem
certificate = local_kamailio_org_cert.pem
verify_depth = 3
ca_list = local_ca.pem
server_name = kamailio.org

[client:127.0.0.1:5061]
method = TLSv1
verify_certificate = yes
require_certificate = yes
private_key = default_key.pem
certificate = default_cert.pem
ca_list = default_ca.pem
crl = default_crl.pem
server_name = kamailio.org
server_id = kamailio.org

# server profile on any address
[server:any]
method = TLSv1
verify_certificate = yes
require_certificate = no
private_key = kamailio_net_key.pem
certificate = kamailio_net_cert.pem
verify_depth = 3
ca_list = local_ca.pem
server_name = kamailio.net
server_name_mode = 1
...

   For a more complete example check the tls.cfg distributed with the
   Kamailio source (kamailio/modules/tls/tls.cfg).

   Example 1.41. Set config parameter
...
modparam("tls", "config", "/usr/local/etc/kamailio/tls.cfg")
...

   The file can be changed at runtime. The new config will not be loaded
   immediately, but after the first tls.reload RPC call.

   Example 1.42. Change and reload the TLS configuration at runtime
 $ kamcmd cfg.set_now_string tls config "/usr/local/etc/kamailio/new_tls.cfg"
 $ kamcmd tls.reload

10.32. xavp_cfg (string)

   Sets the name of XAVP that stores attributes for TLS connections.

   The following (inner) attributes can be set:
     * server_name - SNI to be used for outbound connections
     * server_id - string value to be used to match TLS config profile for
       client (outbound) connections. If it is set, matching the TLS
       config profile is done first on server_id and then on ip:port and
       server_name. This is the recommended way for selecting a specific
       TLS client config profile as the local or remote port is hard to
       predict for a stream connection.

   The default value is empty (not set).

   Example 1.43. Set xavp_cfg parameter
...
  modparam("tls", "xavp_cfg", "tls")
 ...
  $xavp(tls=>server_name) = "kamailio.org";
  $xavp(tls[0]=>server_id) = "kamailio.org";
  $du = "sip:kamailio.org:5061;transport=tls";
  route(RELAY);
...

10.33. event_callback (str)

   The name of the function in the kemi configuration file (embedded
   scripting language such as Lua, Python, ...) to be executed instead of
   event_route[...] blocks specific for tls module.

   The function has one string parameter, the value is the name of the
   event_route block, respectively "tls:connection-out".

   Default value is 'empty' (no function is executed for events).

   Example 1.44. Set event_callback parameter
...
modparam("tls", "event_callback", "ksr_tls_event")
...
-- event callback function implemented in Lua
function ksr_tls_event(evname)
        KSR.info("===== tls module triggered event: " .. evname .. "\n");
        return 1;
end
...

10.34. rand_engine (str)

   Set the random number generator engine for libssl.

   Note: the default random number generator (PRNG) engine of libssl
   v1.1.x is not designed for multi-process applications and can result in
   a crash. Therefore set the PRNG engine to one of the options listed in
   this section. If libssl 1.1.x (or newer) is detected at compile time,
   then the PRNG engine is set to "cryptorand".

   The following options are avaialble:
     * krand - use internal kam_rand() function
     * fastrand - use internal fastrand (ISAAC) function
     * cryptorand - use internal cryptorand (Fortuna) function
     * kxlibssl - default libssl rand engine wrapped by a Kamailio mutex

   Note: the krand and fastrand engines are not recommended for use on
   systems requiring strong security, as they may not generate numbers
   with enough randomness and are not cryptographically secure.

   The default value is empty (not set) for libssl v1.0.x or older, and
   "cryptorand" for libssl v1.1.x or newer.

   Example 1.45. Set rand_engine parameter
...
modparam("tls", "rand_engine", "fastrand")
...

10.35. engine (string)

   If OpenSSL is compiled with engine support this will allow algorithms
   to be offloaded and private keys from HSM to be used. Currently only a
   single global engine is supported. However, private keys can be
   specified per_domain.

   To use private keys from the HSM, the name is the HSM key label
   prefixed by /engine:.
...
## example for the Gem engine
modparam("tls", "engine", "gem")
# can also be set per-domain in tls.cfg
modparam("tls", "private_key", "/engine:my_HSM_key_label")

## example for engine_pkcs11
modparam("tls", "engine", "pkcs11")
modparam("tls", "private_key", "/engine:pkcs11:token=MYTOKEN;object=MYKEYLABEL")

modparam("tls", "engine_config", "/usr/local/etc/kamailio/openssl.cnf")
modparam("tls", "engine_algorithms", "ALL")
...

   By default OpenSSL engine support is disabled (NONE). This global param
   is not supported in the tls config file.

10.36. engine_config (string)

   A OpenSSL configuration file to initialize the engine. Typically used
   to send PIN to HSMs to unlock private keys. See the HSM howto for an
   example. This global param is not supported in the tls config file.

10.37. engine_algorithms (string)

   A list of cryptographic methods to be set as default in the engine.
   This is a comma-separated list of values from ALL RSA DSA DH EC RAND
   CIPHERS DIGESTS PKEY PKEY_CRYPTO PKEY_ASN1. Not all methods are
   supported by every engine.

   The default is not to set any methods as default. This global param is
   not supported in the tls config file.

10.38. verify_client (string)

   Provides an alternative to verify_certificate and require_certificate
   modparam and tls.cfg parameters, and creates an additional
   opportunistic connection establishment option for connections with with
   unverifiable certificates (optional_no_ca).

   This is useful for allowing connections from SIP phones with
   self-signed certificates, signed by unrecognized root CAs, expired
   certificates, etc.

   The following values have respective behaviors:
     * off - no client certificate request performed.
     * on - require a verified certificate from the client.
     * optional - ask client for certificate. If one is provided, it must
       be verified. Allowing missing certificate.
     * optional_no_ca - ask client for certificate. Opportunistically try
       to verify certificate. Allow connection regardless of whether there
       is no certificate or whether certificate is present (verified or
       not). Note that verification status can be retrieved via
       $tls_peer_verified.

   Default value is 'off' (no client certificate request performed).

   Recommendation: when using this parameter, do not use
   verify_certificate or require_certificate parameters. Conversion table
   is as follows:
     * verify_certificate=0, require_certificate=0 => verify_client="off"
     * verify_certificate=1, require_certificate=0 =>
       verify_client="optional"
     * verify_certificate=1, require_certificate=1 => verify_client="on"

   Example 1.46. Set verify_client modparam parameter
...
modparam("tls", "verify_client", "on")
...

   Example 1.47. Set verify_client tls.cfg parameter
...
[server:1.2.3.4:5061]
method = TLSv1
verify_client = on
...

[server:5.6.7.8:5061]
method = TLSv1.2
verify_client = optional_no_ca
...

11. Functions

   11.1. is_peer_verified()

11.1. is_peer_verified()

   Returns true if the connection on which the message was received is
   TLS, the peer presented an X509 certificate and the certificate chain
   verified ok.

   It can be used only in a request route.

   Example 1.48. is_peer_verified usage
        if (proto==TLS && !is_peer_verified()) {
                sl_send_reply("400", "No certificate or verification failed");
                exit;
        }

12. RPC Commands

   12.1. tls.info
   12.2. tls.list
   12.3. tls.options
   12.4. tls.reload

12.1. tls.info

   List internal information related to the TLS module in a short list -
   max connections, open connections and the write queue size.

   Parameters:
     * None.

12.2. tls.list

   List details about all active TLS connections.

   Parameters:
     * None.

12.3. tls.options

   List the current TLS configuration.

   Parameters:
     * None.

12.4. tls.reload

   Reload the external TLS configuration file (aka tls.cfg). It does not
   reload modparam() parameters. Note that existing active TLS connections
   are not terminated and they continue to use the old certificates. The
   new configuration will be used for new connections.

   Parameters:
     * None.

13. Status

   13.1. License
   13.2. History

13.1. License

   Most of the code for this module has been released under BSD by
   iptelorg. The GPL parts are released with an exception to link with
   OpenSSL toolkit software components.

13.2. History

   For version 3.1 most of the TLS specific code was completely re-written
   to add support for asynchronous TLS and fix several long standing bugs.

   The code is currently maintained by Andrei Pelinescu-Onciul
   <andrei@iptel.org>.

   Install does not generate self-signed certificates by default anymore.
   In order to generate them now you should do "make install-tls-cert"

14. Event Routes

   14.1. event_route[tls:connection-out]

14.1. event_route[tls:connection-out]

   Event route to be executed when a TLS connection is opened by Kamailio.
   If drop() is executed in the event route, then the data is no longer
   sent over the connection.

   Example 1.49. Use of event_route[tls:connection-out]
...
event_route[tls:connection-out] {
  if($sndto(ip)=="1.2.3.4") {
    drop;
  }
}
...

15. TLS With Database Backend

   The module does not connect to database to fetch the values for the TLS
   profile attributes. However the 'kamcli' tool can generate the tls.cfg
   from a database table. Once generated, the 'tls.cfg' can be reloaded
   with an RPC command.

   The kamcli tool can be found at https://github.com/kamailio/kamcli.

   The schema to create the database table can be seen with the command:
   "kamcli tls sqlprint". The default name for database table is 'tlscfg'.

   The most of the column names matches the corresponding attribute names
   from a TLS profile.

   The profile id in 'tls.cfg' is generated from
   '[profile_type:profile_name]'. The 'profile_type' has to be 'server' or
   'client'. The 'profile_name' can be 'default', 'any' or the pair of IP
   address and port like 'ipaddr:port'.

   The 'file_type' is specifying if the values for 'certificate',
   'private_key', 'ca_list' and 'crl' are path to files on disc (when is
   set to 0) or the content of the files (when set to 1). If 'file_type'
   is 1, then 'kamcli' will create new files on disc and store the values
   from the database in them. The target folder for 'tls.cfg' and the
   certificates related files can be set via command options for 'kamcli
   tls', for more details see the output of 'kamcli tls --help' and
   'kamcli tls cfgprint --help'.
Name		Date	Size	#Lines	LOC
..		15-Apr-2021	-
doc/	H	15-Apr-2021	-	2,135	1,984
utils/openssl_mutex_shared/	H	15-Apr-2021	-	138	102
Makefile	H A D	15-Apr-2021	2.4 KiB	78	51
README	H A D	15-Apr-2021	57.1 KiB	1,678	1,273
README.TLS	H A D	15-Apr-2021	18.7 KiB	415	386
fixed_c_zlib.h	H A D	15-Apr-2021	6.6 KiB	259	187
sbufq.h	H A D	15-Apr-2021	7.5 KiB	284	171
tls.cfg	H A D	15-Apr-2021	3.5 KiB	107	100
tls_bio.c	H A D	03-May-2022	9.6 KiB	375	264
tls_bio.h	H A D	15-Apr-2021	1.9 KiB	68	24
tls_cert.sh	H A D	15-Apr-2021	5.3 KiB	202	155
tls_cfg.c	H A D	15-Apr-2021	11.1 KiB	293	215
tls_cfg.h	H A D	15-Apr-2021	3.7 KiB	111	43
tls_config.c	H A D	15-Apr-2021	14 KiB	550	442
tls_config.h	H A D	15-Apr-2021	1.4 KiB	53	14
tls_ct_q.h	H A D	15-Apr-2021	4.1 KiB	134	43
tls_ct_wrq.c	H A D	15-Apr-2021	5.2 KiB	206	92
tls_ct_wrq.h	H A D	15-Apr-2021	3 KiB	99	15
tls_domain.c	H A D	15-Apr-2021	45.5 KiB	1,694	1,176
tls_domain.h	H A D	15-Apr-2021	6.1 KiB	237	98
tls_dump_vf.c	H A D	15-Apr-2021	5.4 KiB	150	108
tls_dump_vf.h	H A D	15-Apr-2021	1.3 KiB	42	4
tls_init.c	H A D	15-Apr-2021	25.9 KiB	873	643
tls_init.h	H A D	15-Apr-2021	2.3 KiB	93	29
tls_locking.c	H A D	15-Apr-2021	4.7 KiB	195	126
tls_locking.h	H A D	15-Apr-2021	1 KiB	35	5
tls_map.c	H A D	15-Apr-2021	4.2 KiB	196	152
tls_map.h	H A D	15-Apr-2021	1.5 KiB	78	44
tls_mod.c	H A D	03-May-2022	18.8 KiB	644	469
tls_mod.h	H A D	15-Apr-2021	1.3 KiB	46	12
tls_rand.c	H A D	03-May-2022	8.5 KiB	375	287
tls_rand.h	H A D	03-May-2022	1.2 KiB	35	11
tls_rpc.c	H A D	15-Apr-2021	7.3 KiB	264	200
tls_rpc.h	H A D	15-Apr-2021	1 KiB	34	5
tls_select.c	H A D	15-Apr-2021	43.8 KiB	1,551	1,239
tls_select.h	H A D	15-Apr-2021	1.5 KiB	50	9
tls_server.c	H A D	15-Apr-2021	48 KiB	1,513	1,044
tls_server.h	H A D	15-Apr-2021	2.9 KiB	99	42
tls_util.c	H A D	15-Apr-2021	2.3 KiB	100	44
tls_util.h	H A D	15-Apr-2021	1.8 KiB	74	30
tls_verify.c	H A D	15-Apr-2021	4 KiB	136	87
tls_verify.h	H A D	15-Apr-2021	1.5 KiB	42	6