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: tls module must be loaded before any other Kamailio module that uses libssl (OpenSSL library). A safe option is to have tls module loaded first (be in the first "loadmodule" inside Kamailio.cfg).

2. Quick Start

Make sure you have a proper certificate and private key and either use the certificate and private_key module parameters, or make sure the certificate and key are in the same PEM file, named cert.pem an placed in [your-cfg-install-prefix]/etc/kamailio/. Don't forget to load the tls module and to enable TLS (add enable_tls=yes to your config).

Example 1.1. Quick start config

#...
loadmodule "modules/tls/tls.so"

modparam("tls", "private_key", "./andrei-test.pem")
modparam("tls", "certificate", "./andrei-test.pem")
modparam("tls", "ca_list", "./calist.pem")

enable_tls=yes

route{
	# ....
}

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.

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

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. A list with all the ones implemented by the TLS module can be seen under doc/select_list/select_tls.txt or or http://sip-router.org/docbook/sip-router/branch/master/select_list/select_list.html#select_list.tls.

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 ctificates 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 kamailio1_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/cakey.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 certificate.
	
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 not
	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 other servers
   and clients connecting to your server with a client certificate or for approving
   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. Parameters

9.1. `tls_method` (string)

Sets the SSL/TLS protocol method. Possible values are:

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 highly secure.
SSLv2 - only SSLv2 connections, for old clients. Note: you shouldn't use SSLv2 for anything which should be highly secure. Newer versions of libssl 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 libssl version, this option allows SSLv2, with hello messages done over SSLv2. You shouldn't use SSLv2 or SSLv3 for anything which should be highly 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.

Example 1.3. Set tls_method parameter

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

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

Warning: try not to use certificate with keys longer then 2048 bytes. Longer keys will severely impact performance, in particular the TLS connection rate.

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

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

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", "/usr/local/etc/kamailio/my_pkey.pem")
...

9.4. `ca_list` (string)

Sets the CA list file name. This file contains a list of all the trusted CAs certificates. If a signature in a certificate chain belongs to one of the listed CAs, the verification of that certificate will succeed.

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

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

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

9.6. `verify_certificate` (boolean)

If enabled it will force certificate verification. 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)
...

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

9.8. `require_certificate` (boolean)

When enabled it will require a certificate from a client. 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)
...

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

9.10. `server_name` (string)

Sets the Server Name Indication (SNI) value.

This is a TLS extension and is not working for old and obsoleted SSL versions.

The default value is empty (not set).

Example 1.12. Set server_name parameter

...
modparam("tls", "server_name", "kamailio.org")
...

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

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

9.13. `connection_timeout` (int)

Sets the amount of time after which an idle TLS connection will be closed, if no I/O ever occured 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

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

By default compression is disabled.

Example 1.15. Set tls_disable_compression parameter

...
modparam("tls", "tls_disable_compression", 0) # enable
...

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

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

9.17. `ssl_max_send_fragment` (integer)

Sets the maximum number of bytes (from the clear text) sent into one TLS or SSL record. Valid values are between 512 and 16384. Note however that even valid low values might not be big enough to allow a succesfull 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 succesfull 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)

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

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

9.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/SSL 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

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

9.22. `ct_wq_blk_size` (integer)

Minimum block size for the internal clear-text send queues (debugging / advanced tunning). 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

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

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

9.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 well 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 choosed, 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.

9.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 well 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 choosed, 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.

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

Currently failing any of the following sanity checks will not allow Kamailio to 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)
...

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

9.29. `session_id` (str)

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

By default TLS session_id is "sip-router-tls-3.1".

Example 1.38. Set session_id parameter

...
modparam("tls", "session_id", "my-session-id-context")
...

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

9.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 config file is specified.

The following parameters can be set in the config file, for each domain:

tls_method
verify_certificate
require_certificate
private_key
certificate
verify_depth
ca_list
crl
cipher_list
server_name
server_id

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

Example 1.40. Short 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 = SSLv23
verify_certificate = yes
require_certificate = no
private_key = local_key.pem
certificate = local_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

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

9.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=>server_id) = "kamailio.org";
  $du = "sip:kamailio.org:5061;transport=tls";
  route(RELAY);
...

10. Functions

10.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.44. is_peer_verified usage

	if (proto==TLS && !is_peer_verified()){
		sl_send_reply("400", "No certificate or verification failed");
		drop;
	}

11. RPC Commands

11.1. `tls.info`

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

Parameters:

None.

11.2. `tls.list`

List details about all active TLS connections.

Parameters:

None.

11.3. `tls.options`

List the current TLS configuration.

Parameters:

None.

11.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. New configuration will be used for new connections.

Parameters:

None.

12. Status

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

12.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"

TLS Module

Andrei Pelinescu-Onciul

Carsten Bock

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

9.1. tls_method (string)

9.2. certificate (string)

9.3. private_key (string)

9.4. ca_list (string)

9.5. crl (string)

Note

9.6. verify_certificate (boolean)

9.7. verify_depth (integer)

9.8. require_certificate (boolean)

9.9. cipher_list (string)

9.10. server_name (string)

9.11. send_timeout (int)

9.12. handshake_timeout (int)

9.13. connection_timeout (int)

9.14. tls_disable_compression (boolean)

9.15. ssl_release_buffers (integer)

Note

9.16. ssl_freelist_max_len (integer)

Note

9.17. ssl_max_send_fragment (integer)

Note

Note

9.18. ssl_read_ahead (boolean)

9.19. send_close_notify (boolean)

9.20. con_ct_wq_max (integer)

9.21. ct_wq_max (integer)

9.22. ct_wq_blk_size (integer)

9.23. tls_log (int)

9.24. tls_debug (int)

9.25. low_mem_threshold1 (integer)

9.26. low_mem_threshold2 (integer)

9.27. tls_force_run (boolean)

9.28. session_cache (boolean)

9.29. session_id (str)

9.30. renegotiation (boolean)

9.31. config (string)

9.32. xavp_cfg (string)

10. Functions

10.1. is_peer_verified()

11. RPC Commands

11.1. tls.info

11.2. tls.list

11.3. tls.options

11.4. tls.reload

12. Status

12.1. License

12.2. History

9.1. `tls_method` (string)

9.2. `certificate` (string)

9.3. `private_key` (string)

9.4. `ca_list` (string)

9.5. `crl` (string)

9.6. `verify_certificate` (boolean)

9.7. `verify_depth` (integer)

9.8. `require_certificate` (boolean)

9.9. `cipher_list` (string)

9.10. `server_name` (string)

9.11. `send_timeout` (int)

9.12. `handshake_timeout` (int)

9.13. `connection_timeout` (int)

9.14. `tls_disable_compression` (boolean)

9.15. `ssl_release_buffers` (integer)

9.16. `ssl_freelist_max_len` (integer)

9.17. `ssl_max_send_fragment` (integer)

9.18. `ssl_read_ahead` (boolean)

9.19. `send_close_notify` (boolean)

9.20. `con_ct_wq_max` (integer)

9.21. `ct_wq_max` (integer)

9.22. `ct_wq_blk_size` (integer)

9.23. `tls_log` (int)

9.24. `tls_debug` (int)

9.25. `low_mem_threshold1` (integer)

9.26. `low_mem_threshold2` (integer)

9.27. `tls_force_run` (boolean)

9.28. `session_cache` (boolean)

9.29. `session_id` (str)

9.30. `renegotiation` (boolean)

9.31. `config` (string)

9.32. `xavp_cfg` (string)

10.1. `is_peer_verified()`

11.1. `tls.info`

11.2. `tls.list`

11.3. `tls.options`

11.4. `tls.reload`