params.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
		"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
	[<!-- Include general documentation entities -->
	 <!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
	 %docentities;
	]
>

<section id="tls.parameters">
    <sectioninfo>
    </sectioninfo>

    <title>Parameters</title>

	<section id="tls.p.tls_method">
	<title><varname>tls_method</varname> (string)</title>
	<para>
		Sets the TLS protocol method. Possible values are:
	</para>
	<itemizedlist>
			<listitem>
				<para>
				<emphasis>TLSv1.3+</emphasis> - TLSv1.3 or newer (TLSv1.3, ...)
				connections are accepted (available starting with openssl/libssl v1.1.1)
				</para>
			</listitem>
			<listitem>
				<para>
				<emphasis>TLSv1.3</emphasis> - only TLSv1.3 connections are accepted
				(available starting with openssl/libssl v1.1.1)
				</para>
			</listitem>
			<listitem>
				<para>
				<emphasis>TLSv1.2+</emphasis> - TLSv1.2 or newer (TLSv1.3, ...)
				connections are accepted (available starting with openssl/libssl v1.1.1)
				</para>
			</listitem>
			<listitem>
				<para>
				<emphasis>TLSv1.2</emphasis> - only TLSv1.2 connections are accepted
				(available starting with openssl/libssl v1.0.1e)
				</para>
			</listitem>
			<listitem>
				<para>
				<emphasis>TLSv1.1+</emphasis> - TLSv1.1 or newer (TLSv1.2, ...)
				connections are accepted (available starting with openssl/libssl v1.0.1)
				</para>
			</listitem>
			<listitem>
				<para>
				<emphasis>TLSv1.1</emphasis> - only TLSv1.1 connections are accepted
				(available starting with openssl/libssl v1.0.1)
				</para>
			</listitem>
			<listitem>
				<para>
				<emphasis>TLSv1+</emphasis> - TLSv1.0 or newer (TLSv1.1, TLSv1.2, ...)
				connections are accepted.
				</para>
			</listitem>
			<listitem>
				<para>
				<emphasis>TLSv1</emphasis> - only TLSv1 (TLSv1.0) connections are
				accepted. This is the default value.
				</para>
			</listitem>
			<listitem>
				<para>
				<emphasis>SSLv3</emphasis> - only SSLv3 connections are accepted.
				Note: you shouldn't use SSLv3 for anything which should be secure.
				</para>
			</listitem>
			<listitem>
				<para>
				<emphasis>SSLv2</emphasis> - 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.
				</para>
			</listitem>
			<listitem>
				<para>
				<emphasis>SSLv23</emphasis> - any of the SSLv2, SSLv3 and TLSv1 or
				newer methods will be accepted.
				</para>
				<para>
				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."
				</para>
				<para>
				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.
				</para>
			</listitem>
	</itemizedlist>
	<para>
		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)"
	</para>
	<example>
	    <title>Set <varname>tls_method</varname> parameter</title>
	    <programlisting>
...
modparam("tls", "tls_method", "TLSv1")
...
	    </programlisting>
	</example>
	</section>

	<section id="tls.p.certificate">
	<title><varname>certificate</varname> (string)</title>
	<para>
		Sets the certificate file name. The certificate file can also contain
		the private key in PEM format.
	</para>
	<para>
		If the file name starts with a '.' the path will be relative to the
		working directory (<emphasis>at runtime</emphasis>). 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/).
	</para>
	<para>
		The default value is &kamailioconfdir;/cert.pem
	</para>
	<example>
	    <title>Set <varname>certificate</varname> parameter</title>
	    <programlisting>
...
modparam("tls", "certificate", "/usr/local/etc/kamailio/my_certificate.pem")
...
	    </programlisting>
	</example>
	</section>

	<section id="tls.p.private_key">
	<title><varname>private_key</varname> (string)</title>
	<para>
		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.
	</para>
	<para>
		If the file name starts with a '.' the path will be relative to the
		working directory (<emphasis>at runtime</emphasis>). 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/).
	</para>
	<para>
		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 &gt;&gt; cert.pem)
	</para>
	<para>
		The default value is &kamailioconfdir;/cert.pem
	</para>
	<example>
	    <title>Set <varname>private_key</varname> parameter</title>
	    <programlisting>
...
modparam("tls", "private_key", "/usr/local/etc/kamailio/my_pkey.pem")
...
	    </programlisting>
	</example>
	</section>

	<section id="tls.p.ca_list">
	<title><varname>ca_list</varname> (string)</title>
	<para>
		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.
	</para>
	<para>
		If the file name starts with a '.' the path will be relative to the
		working directory (<emphasis>at runtime</emphasis>). 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/).
	</para>
	<para>
		By default the CA file is not set.
	</para>
	<para>
		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.:
	    <programlisting>
for f in trusted_cas/*.pem ; do cat "$f" &gt;&gt; ca_list.pem ; done 
	    </programlisting>
	</para>
	<para>
		See also
		<emphasis>verify_certificate</emphasis>,
		<emphasis>verify_depth</emphasis>,
		<emphasis>require_certificate</emphasis> and
		<emphasis>crl</emphasis>.
	</para>
	<example>
	    <title>Set <varname>ca_list</varname> parameter</title>
	    <programlisting>
...
modparam("tls", "ca_list", "/usr/local/etc/kamailio/ca_list.pem")
...
	    </programlisting>
	</example>
	</section>

	<section id="tls.p.ca_path">
	<title><varname>ca_path</varname> (str)</title>
	<para>
		Sets the path with the trusted CA files, to be given as parameter
		SSL_CTX_load_verify_locations(). The certificates in ca_path are only
		looked up when required, e.g. when building the certificate chain
		or when actually performing the verification of a peer certificate. They
		are not given to the client (not loaded to be provided to
		SSL_CTX_set_client_CA_list()), only the ones in ca_list files are sent
		to the client. It requires to use c_rehash to generate the hash map
		for certificate search, for more see the manual of libssl for
		SSL_CTX_load_verify_locations() function.
	</para>
	<para>
		By default it is not set.
	</para>
	<example>
	    <title>Set <varname>ca_path</varname> parameter</title>
	    <programlisting>
...
modparam("tls", "ca_path", "/usr/local/etc/kamailio/ca")
...
	    </programlisting>
	</example>
	</section>

	<section id="tls.p.crl">
	<title><varname>crl</varname> (string)</title>
	<para>
		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.
	</para>
	<para>
		If not set, no CRL list will be used.
	</para>
	<para>
		If the file name starts with a '.' the path will be relative to the
		working directory (<emphasis>at runtime</emphasis>). 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/).
	</para>
	<note><para>
		If set, <varname>require_certificate</varname> should also be set
		or it will not have any effect.
	</para></note>
	<para>
		By default the CRL file name is not set.
	</para>
	<para>
		To update the CRL in a running &kamailio;, make sure you configure TLS
		via a separate TLS config file
		(the <varname>config</varname> modparam) and issue a tls.reload
		RPC call, e.g.:
		<programlisting>
 $ &sercmd; tls.reload
		</programlisting>
	</para>
	<para>
		A quick way to create the CRL in PEM format, using OpenSSL is:
		<programlisting>
 $ openssl ca -gencrl -keyfile cacert.key -cert cacert.pem -out my_crl.pem
		</programlisting>
		 my_crl.pem will contain the signed list of the revoked certificates.
	</para>
	<para>
		To revoke a TLS certificate use something like:
		<programlisting>
 $ openssl ca -revoke bad_cert.pem -keyfile cacert.key -cert cacert.pem
		</programlisting>
		and then refresh the crl file using the command above.
	</para>
	<para>
		To display the CRL contents use:
		<programlisting>
 $ openssl crl -in crl.pem -noout -text
		</programlisting>
	</para>
	<para>
		See also
		<emphasis>ca_list</emphasis>,
		<emphasis>verify_certificate</emphasis>,
		<emphasis>verify_depth</emphasis> and
		<emphasis>require_certificate</emphasis>.
	</para>
	<example>
	    <title>Set <varname>crl</varname> parameter</title>
	    <programlisting>
...
modparam("tls", "crl", "/usr/local/etc/kamailio/crl.pem")
...
	    </programlisting>
	</example>
	</section>

<section id="tls.p.verify_certificate">
	<title><varname>verify_certificate</varname> (boolean)</title>
	<para>
		If enabled it will force certificate verification when connecting to 
		other SIP servers..
		For more information see the
		<ulink url="https://www.openssl.org/docs/manmaster/man1/verify.html">verify(1)</ulink>
		OpenSSL man page.
	</para>
	<para>
		Note: the certificate verification will always fail if the ca_list is empty.
	</para>
	<para>
		See also: <varname>ca_list</varname>, <varname>require_certificate</varname>, <varname>verify_depth</varname>.
	</para>
	<para>
		By default the certificate verification is off.
	</para>
	<example>
	    <title>Set <varname>verify_certificate</varname> parameter</title>
	    <programlisting>
...
modparam("tls", "verify_certificate", 1)
...
	    </programlisting>
	</example>
	</section>

<section id="tls.p.verify_depth">
	<title><varname>verify_depth</varname> (integer)</title>
	<para>
		Sets how far up the certificate chain will the certificate verification go in the search for a trusted CA.
	</para>
	<para>
		See also: <varname>ca_list</varname>, <varname>require_certificate</varname>, <varname>verify_certificate</varname>,
	</para>
	<para>
		The default value is 9.
	</para>
	<example>
	    <title>Set <varname>verify_depth</varname> parameter</title>
	    <programlisting>
...
modparam("tls", "verify_depth", 9)
...
	    </programlisting>
	</example>
	</section>

<section id="tls.p.require_certificate">
	<title><varname>require_certificate</varname> (boolean)</title>
	<para>
		When enabled &kamailio; will require a certificate from a client
		connecting to the TLS port. If the client does not offer a certificate
		and <varname>verify_certificate</varname> is on, certificate verification will fail.
	</para>
	<para>
		The default value is off.
	</para>
	<example>
	    <title>Set <varname>require_certificate</varname> parameter</title>
	    <programlisting>
...
modparam("tls", "require_certificate", 1)
...
	    </programlisting>
	</example>
	</section>

<section id="tls.p.cipher_list">
	<title><varname>cipher_list</varname> (string)</title>
	<para>
		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
		<ulink url="https://www.openssl.org/docs/manmaster/man1/ciphers.html">
		cipher(1)</ulink> OpenSSL man page.
	</para>
	<para>
		The default value is not set (all the OpenSSL supported ciphers are enabled).
	</para>
	<example>
	    <title>Set <varname>cipher_list</varname> parameter</title>
	    <programlisting>
...
modparam("tls", "cipher_list", "HIGH")
...
	    </programlisting>
	</example>
	</section>

	<section id="tls.p.server_name">
	<title><varname>server_name</varname> (string)</title>
	<para>
		Sets the Server Name Indication (SNI) value.
	</para>
	<para>
		This is a TLS extension enabling one TLS server to serve multiple host
		names with unique certificates.
	</para>
	<para>
		The default value is empty (not set).
	</para>
	<example>
	    <title>Set <varname>server_name</varname> parameter</title>
	    <programlisting>
...
modparam("tls", "server_name", "kamailio.org")
...
	    </programlisting>
	</example>
	</section>

	<section id="tls.p.connection_timeout">
	<title><varname>connection_timeout</varname> (int)</title>
	<para>
		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.
	</para>
	<para>
		The default value is 10 min.
	</para>
	<para>
		If the value set is -1, the connection will never be close on idle.
	</para>
	<para>
		This setting can be changed also at runtime, via the RPC interface and config
		framework. The config variable name is
		<emphasis>tls.connection_timeout</emphasis>.
	</para>
	<example>
	    <title>Set <varname>connection_timeout</varname> parameter</title>
	    <programlisting>
...
modparam("tls", "connection_timeout", 60)
...
	    </programlisting>
	</example>
	<example>
		<title>Set <varname>tls.connection_timeout</varname> at runtime</title>
		<programlisting>
 $ &sercmd; cfg.set_now_int tls connection_timeout 180
		</programlisting>
	</example>
	</section>

	<section id="tls.p.tls_disable_compression">
	<title><varname>tls_disable_compression</varname> (boolean)</title>
	<para>
		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 
 		<ulink url="https://en.wikipedia.org/wiki/CRIME_(security_exploit)">
		CRIME</ulink> security vulnerability.
	</para>
	<para>
		By default TLS compression is disabled.
	</para>
	<example>
	    <title>Set <varname>tls_disable_compression</varname> parameter</title>
	    <programlisting>
...
modparam("tls", "tls_disable_compression", 0) # enable
...
	    </programlisting>
	</example>
	</section>


<section id="tls.p.ssl_release_buffers">
	<title><varname>ssl_release_buffers</varname> (integer)</title>
	<para>
		Release internal OpenSSL read or write buffers as soon as they are
		no longer needed. Combined with
		<varname>ssl_freelist_max_len</varname> has the potential of saving
		a lot of memory ( ~ 32k per connection in the default configuration,
		or 16k + <varname>ssl_max_send_fragment</varname>).
		For &kamailio; versions &gt; 3.0 it makes little sense to disable it (0)
		since the tls module already has its own internal buffering.
	</para>
	<para>
		A value of -1 would not change this option from its openssl default.
		Use 0 or 1 for enable/disable.
	</para>
	<para>
		By default the value is 1 (enabled).
	</para>
	<note>
		<para>
			This option is supported only for
			OpenSSL versions >= <emphasis>1.0.0</emphasis>.
			On all the other versions attempting
			to change the default will trigger an error.
		</para>
	</note>
	<example>
	    <title>Set <varname>ssl_release_buffers</varname> parameter</title>
	    <programlisting>
modparam("tls", "ssl_release_buffers", 1)
	    </programlisting>
	</example>
	</section>


<section id="tls.p.ssl_freelist_max_len">
	<title><varname>ssl_freelist_max_len</varname> (integer)</title>
	<para>
		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.
	</para>
	<para>
		Should be combined with <varname>ssl_release_buffers</varname>.
	</para>
	<para>
		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.
	</para>
	<para>
		By default the value is 0 (no freelist).
	</para>
	<note>
		<para>
			This option is supported only for
			OpenSSL versions >= <emphasis>1.0.0</emphasis>.
			On all the other versions attempting
			to change the default will trigger an error.
		</para>
	</note>
	<example>
		<title>Set <varname>ssl_freelist_max_len</varname> parameter</title>
		<programlisting>
modparam("tls", "ssl_freelist_max_len", 0)
		</programlisting>
	</example>
	</section>


<section id="tls.p.ssl_max_send_fragment">
	<title><varname>ssl_max_send_fragment</varname> (integer)</title>
	<para>
		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).
	</para>
	<para>
		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.
	</para>
	<note>
		<para>
			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.
		</para>
	</note>
	<para>
		A value of -1 has a special meaning: the OpenSSL default will be used
		(no attempt on changing the value will be made).
	</para>
	<para>
		By default the value is -1 (the OpenSSL default, which at least in
		OpenSSL 1.0.0 is ~ 16k).
	</para>
	<note>
		<para>
			This option is supported only for
			OpenSSL versions >= <emphasis>0.9.9</emphasis>.
			On all the other versions attempting
			to change the default will trigger an error.
		</para>
	</note>
	<example>
		<title>Set <varname>ssl_max_send_fragment</varname> parameter</title>
		<programlisting>
modparam("tls", "ssl_max_send_fragment", 4096)
		</programlisting>
	</example>
	</section>


<section id="tls.p.ssl_read_ahead">
	<title><varname>ssl_read_ahead</varname> (boolean)</title>
	<para>
		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.
	</para>
	<para>
		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.
	</para>
	<para>
		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).
	</para>
	<para>
		A value of -1 has a special meaning: the OpenSSL default will be used
		(no attempt on changing the value will be made).
	</para>
	<para>
		By default the value is 0 (disabled).
	</para>
	<example>
		<title>Set <varname>ssl_read_ahead</varname> parameter</title>
		<programlisting>
modparam("tls", "ssl_read_ahead", 1)
		</programlisting>
	</example>
	</section>


	<section id="tls.p.send_close_notify">
	<title><varname>send_close_notify</varname> (boolean)</title>
	<para>
		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).
	</para>
	<para>
		The default value is 0 (off).
	</para>
	<para>
		It can be changed also at runtime, via the RPC interface and config
		framework. The config variable name is tls.send_close_notify.
	</para>
	<example>
	    <title>Set <varname>send_close_notify</varname> parameter</title>
	    <programlisting>
...
modparam("tls", "send_close_notify", 1)
...
	    </programlisting>
	</example>
	<example>
		<title>Set <varname>tls.send_close_notify</varname> at runtime</title>
		<programlisting>
 $ &sercmd; cfg.set_now_int tls send_close_notify 1
		</programlisting>
	</example>
	</section>


	<section id="tls.p.con_ct_wq_max">
	<title><varname>con_ct_wq_max</varname> (integer)</title>
	<para>
		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.
	</para>
	<para>
		The default value is 65536 (64 Kb).
	</para>
	<para>
		It can be changed also at runtime, via the RPC interface and config
		framework. The config variable name is tls.con_ct_wq_max.
	</para>
	<example>
	    <title>Set <varname>con_ct_wq_max</varname> parameter</title>
	    <programlisting>
...
modparam("tls", "con_ct_wq_max", 1048576)
...
	    </programlisting>
	</example>
	<example>
		<title>Set <varname>tls.con_ct_wq_max</varname> at runtime</title>
		<programlisting>
 $ &sercmd; cfg.set_now_int tls con_ct_wq_max 1048576
		</programlisting>
	</example>
	</section>


	<section id="tls.p.ct_wq_max">
	<title><varname>ct_wq_max</varname> (integer)</title>
	<para>
		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.
	</para>
	<para>
		The default value is 10485760 (10 Mb).
	</para>
	<para>
		It can be changed also at runtime, via the RPC interface and config
		framework. The config variable name is <varname>tls.ct_wq_max</varname>.
	</para>
	<example>
	    <title>Set <varname>ct_wq_max</varname> parameter</title>
	    <programlisting>
...
modparam("tls", "ct_wq_max", 4194304)
...
	    </programlisting>
	</example>
	<example>
		<title>Set <varname>tls.ct_wq_max</varname> at runtime</title>
		<programlisting>
 $ &sercmd; cfg.set_now_int tls ct_wq_max 4194304
		</programlisting>
	</example>
	</section>


	<section id="tls.p.ct_wq_blk_size">
	<title><varname>ct_wq_blk_size</varname> (integer)</title>
	<para>
		Minimum block size for the internal clear-text send queues
		(debugging / advanced tuning).
		Good values are multiple of typical datagram sizes.
	</para>
	<para>
		The default value is 4096.
	</para>
	<para>
		It can be changed also at runtime, via the RPC interface and config
		framework. The config variable name is <varname>tls.ct_wq_blk_size</varname>.
	</para>
	<example>
	    <title>Set <varname>ct_wq_blk_size</varname> parameter</title>
	    <programlisting>
...
modparam("tls", "ct_wq_blk_size", 2048)
...
	    </programlisting>
	</example>
	<example>
		<title>Set <varname>tls.ct_wq_max</varname> at runtime</title>
		<programlisting>
 $ &sercmd; cfg.set_now_int tls ct_wq_blk_size 2048
		</programlisting>
	</example>
	</section>


	<section id="tls.p.tls_log">
	<title><varname>tls_log</varname> (int)</title>
	<para>
		Sets the log level at which TLS related messages will be logged.
	</para>
	<para>
		The default value is 3 (L_DBG).
	</para>
	<para>
		It can be changed also at runtime, via the RPC interface and config
		framework. The config variable name is <varname>tls.log</varname>.
	</para>
	<example>
		<title>Set <varname>tls_log</varname> parameter</title>
		<programlisting>
...
# ignore TLS messages if Kamailio is started with debug less than 10
modparam("tls", "tls_log", 10)
...
		</programlisting>
	</example>
	<example>
		<title>Set <varname>tls.log</varname> at runtime</title>
		<programlisting>
 $ &sercmd; cfg.set_now_int tls log 10
		</programlisting>
	</example>
	</section>


	<section id="tls.p.tls_debug">
	<title><varname>tls_debug</varname> (int)</title>
	<para>
		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).
	</para>
	<para>
		The default value is 3 (L_DBG).
	</para>
	<para>
		It can be changed also at runtime, via the RPC interface and config
		framework. The config variable name is <varname>tls.debug</varname>.
	</para>
	<example>
		<title>Set <varname>tls_debug</varname> parameter</title>
		<programlisting>
...
# ignore TLS debug messages if Kamailio is started with debug less than 10
modparam("tls", "tls_debug", 10)
...
		</programlisting>
	</example>
	<example>
		<title>Set <varname>tls.debug</varname> at runtime</title>
		<programlisting>
 $ &sercmd; cfg.set_now_int tls debug 10
		</programlisting>
	</example>
	</section>


<section id="tls.p.low_mem_threshold1">
	<title><varname>low_mem_threshold1</varname> (integer)</title>
	<para>
		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.
	</para>
	<para>
		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).
	</para>
	<para>
		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).
	</para>
	<para>
		The following values have a special meaning:
	</para>
	<itemizedlist>
			<listitem>
				<para>
					-1 - use the default value
				</para>
			</listitem>
			<listitem>
				<para>
					0 - disable (TLS connections will not fail preemptively)
				</para>
			</listitem>
	</itemizedlist>
	<para>
		It can be changed also at runtime, via the RPC interface and config
		framework. The config variable name is <varname>tls.low_mem_threshold1</varname>.
	</para>
	<para>
		See also <varname>tls.low_mem_threshold2</varname>.
	</para>
	<example>
		<title>Set <varname>low_mem_threshold1</varname> parameter</title>
		<programlisting>
...
modparam("tls", "low_mem_threshold1", -1)
...
	</programlisting>
	</example>
	<example>
		<title>Set <varname>tls.low_mem_threshold1</varname> at runtime</title>
		<programlisting>
 $ &sercmd; cfg.set_now_int tls low_mem_threshold1 2048
		</programlisting>
	</example>
	</section>

<section id="tls.p.low_mem_threshold2">
	<title><varname>low_mem_threshold2</varname> (integer)</title>
	<para>
		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.
	</para>
	<para>
		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).
	</para>
	<para>
		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).
	</para>
	<para>
		The following values have a special meaning:
	</para>
	<itemizedlist>
			<listitem>
				<para>
					-1 - use the default value
				</para>
			</listitem>
			<listitem>
				<para>
					0 - disable (TLS operations will not fail preemptively)
				</para>
			</listitem>
	</itemizedlist>
	<para>
		It can be changed also at runtime, via the RPC interface and config
		framework. The config variable name is <varname>tls.low_mem_threshold2</varname>.
	</para>
	<para>
		See also <varname>tls.low_mem_threshold1</varname>.
	</para>
	<example>
		<title>Set <varname>tls.low_mem_threshold2</varname> parameter</title>
		<programlisting>
...
modparam("tls", "low_mem_threshold2", -1)
...
	</programlisting>
	</example>
	<example>
		<title>Set <varname>tls.low_mem_threshold2</varname> at runtime</title>
		<programlisting>
 $ &sercmd; cfg.set_now_int tls low_mem_threshold2 1024
		</programlisting>
	</example>
	</section>

	<section id="tls.p.tls_force_run">
	<title><varname>tls_force_run</varname> (boolean)</title>
	<para>
		If enabled &kamailio; will start even if some of the OpenSSL sanity checks fail (turn it on at your own risk).
	</para>
	<para>
		If any of the following sanity checks fail, Kamailio will not start:
	</para>
	<itemizedlist>
		<listitem>
			<para>
				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)
			</para>
		</listitem>
		<listitem>
			<para>
				the OpenSSL library used at compile time and the one used at
				runtime have different Kerberos options 
			</para>
		</listitem>
	</itemizedlist>
	<para>
		By default tls_force_run is disabled.
	</para>
	<example>
		<title>Set <varname>tls_force_run</varname> parameter</title>
		<programlisting>
...
modparam("tls", "tls_force_run", 11)
...
	</programlisting>
	</example>
	</section>

	<section id="tls.p.session_cache">
	<title><varname>session_cache</varname> (boolean)</title>
	<para>
		If enabled &kamailio; will do caching of the TLS sessions data,
		generation a session_id and sending it back to client.
	</para>
	<para>
		By default TLS session caching is disabled (0).
	</para>
	<example>
		<title>Set <varname>session_cache</varname> parameter</title>
		<programlisting>
...
modparam("tls", "session_cache", 1)
...
	</programlisting>
	</example>
	</section>

	<section id="tls.p.session_id">
	<title><varname>session_id</varname> (str)</title>
	<para>
		The value for session ID context, making sense when session caching is enabled.
	</para>
	<para>
		By default TLS session_id is "kamailio-tls-5.x.y".
	</para>
	<example>
		<title>Set <varname>session_id</varname> parameter</title>
		<programlisting>
...
modparam("tls", "session_id", "my-session-id-context")
...
	</programlisting>
	</example>
	</section>

	<section id="tls.p.renegotiation">
	<title><varname>renegotiation</varname> (boolean)</title>
	<para>
		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.
	</para>
	<para>
		By default TLS renegotiation is disabled (0).
	</para>
	<example>
		<title>Set <varname>renegotiation</varname> parameter</title>
		<programlisting>
...
modparam("tls", "renegotiation", 1)
...
	</programlisting>
	</example>
	</section>

	<section id="tls.p.config">
	<title><varname>config</varname> (string)</title>
	<para>
		Sets the name of the TLS specific configuration file or configuration directory.
	</para>
	<para>
		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.
	</para>
	<para>
		If the file or directory name starts with a '.' the path will be relative to the
		working directory (<emphasis>at runtime</emphasis>). 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/).
	</para>
	<para>
		By default no TLS configuration file is specified.
	</para>
	<para>
		The following parameters can be set in the config file, for each
		domain:
	</para>
	<itemizedlist>
			<listitem><para>tls_method - (str) - TLS methods</para></listitem>
			<listitem><para>verify_certificate - (bool) - see modparam</para></listitem>
			<listitem><para>require_certificate - (bool) - see modparam</para></listitem>
			<listitem><para>verify_client - (str) - see modparam</para></listitem>
			<listitem><para>private_key - (str) - see modparam</para></listitem>
			<listitem><para>certificate - (str) - see modparam</para></listitem>
			<listitem><para>verify_depth - (int) - see modparam</para></listitem>
			<listitem><para>ca_list - (str) - see modparam</para></listitem>
			<listitem><para>crl - (str) - see modparam</para></listitem>
			<listitem><para>cipher_list - (str) - see modparam</para></listitem>
			<listitem><para>server_name - (str) - SNI (server name identification)</para></listitem>
			<listitem><para>server_name_mode - (int) - how to match server_name</para></listitem>
			<listitem><para>server_id - (str) - server id</para></listitem>
	</itemizedlist>
	<para>
		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.
	</para>
	<para>
		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
		<varname>xavp_cfg</varname> to learn how to enable it.
	</para>
	<para>
		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.
	</para>
	<para>
		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).
	</para>
	<para>
		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.
	</para>
	<para>
		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.
	</para>
	<para>
		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'.
	</para>

	<example>
		<title>Sample TLS Config File</title>
	<programlisting>
...
[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
...
	</programlisting>
	</example>
	<para>
		For a more complete example check the <emphasis>tls.cfg</emphasis> distributed 
		with the &kamailio; source (kamailio/modules/tls/tls.cfg).
	</para>
	<example>
		<title>Set <varname>config</varname> parameter</title>
		<programlisting>
...
modparam("tls", "config", "/usr/local/etc/kamailio/tls.cfg")
...
	</programlisting>
	</example>
	<para>
		The file can be changed at runtime. The new config will not be loaded
		immediately, but after the first <varname>tls.reload</varname> RPC call.
		<example>
			<title>Change and reload the TLS configuration at runtime</title>
			<programlisting>
 $ &sercmd; cfg.set_now_string tls config "/usr/local/etc/kamailio/new_tls.cfg"
 $ &sercmd; tls.reload
			</programlisting>
		</example>
	</para>
	</section>

	<section id="tls.p.xavp_cfg">
	<title><varname>xavp_cfg</varname> (string)</title>
	<para>
		Sets the name of XAVP that stores attributes for TLS connections.
	</para>
	<para>
		The following (inner) attributes can be set:
	</para>
	<itemizedlist>
		<listitem><para>server_name - SNI to be used for outbound connections</para></listitem>
		<listitem><para>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.</para></listitem>
	</itemizedlist>
	<para>
		The default value is empty (not set).
	</para>
	<example>
	    <title>Set <varname>xavp_cfg</varname> parameter</title>
	    <programlisting>
...
  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);
...
	    </programlisting>
	</example>
	</section>
	<section id="tls.p.event_callback">
		<title><varname>event_callback</varname> (str)</title>
		<para>
			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.
		</para>
		<para>
			The function has one string parameter, the value is the name of
			the event_route block, respectively "tls:connection-out".
		</para>
		<para>
		<emphasis>
			Default value is 'empty' (no function is executed for events).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>event_callback</varname> parameter</title>
		<programlisting format="linespecific">
...
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
...
</programlisting>
	    </example>
	</section>

	<section id="tls.p.rand_engine">
	<title><varname>rand_engine</varname> (str)</title>
	<para>
		Set the random number generator engine for libssl.
	</para>
	<para>
		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".
	</para>
	<para>
		The following options are avaialble:
	</para>
	<itemizedlist>
		<listitem><para>krand - use internal kam_rand() function</para></listitem>
		<listitem><para>fastrand - use internal fastrand (ISAAC) function</para></listitem>
		<listitem><para>cryptorand - use internal cryptorand (Fortuna) function</para></listitem>
		<listitem><para>kxlibssl - default libssl rand engine wrapped by a &kamailio; mutex</para></listitem>
	</itemizedlist>
	<para>
		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.
	</para>
	<para>
		The default value is empty (not set) for libssl v1.0.x or older, and
		"cryptorand" for libssl v1.1.x or newer.
	</para>
	<example>
	    <title>Set <varname>rand_engine</varname> parameter</title>
	    <programlisting>
...
modparam("tls", "rand_engine", "fastrand")
...
	    </programlisting>
	</example>
	</section>

	<section id="tls.p.engine">
	<title><varname>engine</varname> (string)</title>
	<para>
	        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.
	</para>

	<para>
	        To use private keys from the HSM, the name is the HSM key label prefixed by <varname>/engine:</varname>.
	</para>
		<programlisting format="linespecific">
...
## 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")
...
                </programlisting>
	<para>
		By default OpenSSL engine support  is disabled (NONE). This global param is not supported in the tls config file.
	</para>
        </section>

	<section id="tls.p.engine_config">
	<title><varname>engine_config</varname> (string)</title>
	<para>
	        An 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.
	</para>
        </section>


	<section id="tls.p.engine_algorithms">
	<title><varname>engine_algorithms</varname> (string)</title>
	<para>
	        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.
	</para>
	<para>
	        The default is not to set any methods as default. This global param is not supported in the tls config file.
	</para>
        </section>

	<section id="tls.p.verify_client">
	<title><varname>verify_client</varname> (string)</title>
	<para>
		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).
	</para>
	<para>
		This is useful for allowing connections from SIP phones with self-signed
		certificates, signed by unrecognized root CAs, expired certificates, etc.
	</para>
	<para>
		The following values have respective behaviors:
	</para>
	<itemizedlist>
		<listitem><para>off - no client certificate request performed.</para></listitem>
		<listitem><para>on - require a verified certificate from the client.</para></listitem>
		<listitem><para>optional - ask client for certificate. If one is provided, it must
				be verified. Allowing missing certificate.</para></listitem>
		<listitem><para>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.</para></listitem>
	</itemizedlist>
	<para>
		Default value is 'off' (no client certificate request performed).
	</para>
	<para>
		Recommendation: when using this parameter, do not use verify_certificate or
		require_certificate parameters. Conversion table is as follows:
	</para>
	<itemizedlist>
		<listitem><para>verify_certificate=0, require_certificate=0 => verify_client="off"</para></listitem>
		<listitem><para>verify_certificate=1, require_certificate=0 => verify_client="optional"</para></listitem>
		<listitem><para>verify_certificate=1, require_certificate=1 => verify_client="on"</para></listitem>
	</itemizedlist>
	<example>
		<title>Set <varname>verify_client</varname> modparam parameter</title>
		<programlisting>
...
modparam("tls", "verify_client", "on")
...
		</programlisting>
	</example>
	<example>
		<title>Set <varname>verify_client</varname> tls.cfg parameter</title>
		<programlisting>
...
[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
...
		</programlisting>
	</example>
	</section>
 </section>