mirror of https://github.com/sipwise/kamailio.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
1156 lines
35 KiB
1156 lines
35 KiB
<?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 "../../../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 SSL/TLS protocol method. Possible values are:
|
|
</para>
|
|
<itemizedlist>
|
|
<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 highly 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 highly secure.
|
|
Newer versions of libssl 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 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.
|
|
</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.
|
|
</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>
|
|
<emphasis>Warning:</emphasis> try not to use certificate with keys
|
|
longer then 2048 bytes. Longer keys will severely impact performance,
|
|
in particular the TLS connection rate.
|
|
</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 >> 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", "/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. 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.: for f in
|
|
trusted_cas/*.pem ; do cat "$f" >> ca_list.pem ; done .
|
|
</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.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.
|
|
For more information see the <ulink url="http://www.openssl.org/docs/apps/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 it will require a certificate from a client. 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/apps/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 and is not working for old and obsoleted
|
|
SSL versions.
|
|
</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.send_timeout">
|
|
<title><varname>send_timeout</varname> (int)</title>
|
|
<para>
|
|
This parameter is <emphasis>obsolete</emphasis> and cannot be used
|
|
in newer TLS versions (> &kamailio; 3.0). In these versions the
|
|
send_timeout is replaced by <varname>tcp_send_timeout</varname>
|
|
(common with all the tcp connections).
|
|
</para>
|
|
</section>
|
|
|
|
<section id="tls.p.handshake_timeout">
|
|
<title><varname>handshake_timeout</varname> (int)</title>
|
|
<para>
|
|
This parameter is <emphasis>obsolete</emphasis> and cannot be used
|
|
in newer TLS versions (> &kamailio; 3.0). In these versions the
|
|
handshake_timeout is replaced by <varname>tcp_connect_timeout</varname>
|
|
(common with all the tcp connections).
|
|
</para>
|
|
</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 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.
|
|
</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 tls.connection_timeout.
|
|
</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.
|
|
</para>
|
|
<para>
|
|
By default 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 > 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 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).
|
|
</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 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.
|
|
</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/SSL 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 tls.ct_wq_max.
|
|
</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 tunning).
|
|
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 tls.ct_wq_blk_size.
|
|
</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 tls.log.
|
|
</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 tls.debug.
|
|
</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 well
|
|
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 choosed,
|
|
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 tls.low_mem_threshold1.
|
|
</para>
|
|
<para>
|
|
See also <varname>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 well 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 choosed,
|
|
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 tls.low_mem_threshold2.
|
|
</para>
|
|
<para>
|
|
See also <varname>low_mem_threshold1</varname>.
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>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>
|
|
Currently failing any of the following sanity checks will not allow Kamailio to 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 "sip-router-tls-3.1".
|
|
</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 config file is specified.
|
|
</para>
|
|
<para>
|
|
The following parameters can be set in the config file, for each
|
|
domain:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem><para>tls_method</para></listitem>
|
|
<listitem><para>verify_certificate</para></listitem>
|
|
<listitem><para>require_certificate</para></listitem>
|
|
<listitem><para>private_key</para></listitem>
|
|
<listitem><para>certificate</para></listitem>
|
|
<listitem><para>verify_depth</para></listitem>
|
|
<listitem><para>ca_list</para></listitem>
|
|
<listitem><para>crl</para></listitem>
|
|
<listitem><para>cipher_list</para></listitem>
|
|
<listitem><para>server_name</para></listitem>
|
|
<listitem><para>server_id</para></listitem>
|
|
</itemizedlist>
|
|
<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 xavp_cfg 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>
|
|
<example>
|
|
<title>Short 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 = 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
|
|
</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 tls.reload 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=>server_id) = "kamailio.org";
|
|
$du = "sip:kamailio.org:5061;transport=tls";
|
|
route(RELAY);
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
</section>
|