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.
965 lines
30 KiB
965 lines
30 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>
|
|
<revhistory>
|
|
<revision>
|
|
<revnumber>$Revision$</revnumber>
|
|
<date>$Date$</date>
|
|
</revision>
|
|
</revhistory>
|
|
</sectioninfo>
|
|
|
|
<title>Parameters</title>
|
|
|
|
<section id="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</emphasis> - only TLSv1 connections are accepted. This is the default and recommended method (if you want to be rfc3261 conformant don't change it).
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>SSLv3</emphasis> - only SSLv3 connections are accepted
|
|
</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.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>SSLv23</emphasis> - any of the above methods will be accepted, with the following limitation: the initial SSL hello message must be V2 (in the initial hello all the supported protocols are advertised enabling switching to a higher and more secure version). This means connections from SSLv3 or TLSv1 clients will not be accepted.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
If rfc3261 conformance is desired, TLSv1 must be used. For compatibility with older clients SSLv23 is a good option.
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>tls_method</varname> parameter</title>
|
|
<programlisting>
|
|
...
|
|
modparam("tls", "tls_method", "TLSv1")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="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 ser -f /etc/ser/ser.cfg it will be relative to /etc/ser/).
|
|
</para>
|
|
<para>
|
|
<emphasis>Warning:</emphasis> try not to use certificate with keys
|
|
longer then 1024 bytes. Longer keys will severely impact performance,
|
|
in particular the TLS connection rate.
|
|
</para>
|
|
<para>
|
|
The default value is [SER_CFG_DIR]/cert.pem.
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>certificate</varname> parameter</title>
|
|
<programlisting>
|
|
...
|
|
modparam("tls", "certificate", "/usr/local/etc/ser/my_certificate.pem")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="private_key">
|
|
<title><varname>private_key</varname> (string)</title>
|
|
<para>
|
|
Sets the private key file name.
|
|
</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 ser -f /etc/ser/ser.cfg it will be relative to /etc/ser/).
|
|
</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 [SER_CFG_DIR]/cert.pem.
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>private_key</varname> parameter</title>
|
|
<programlisting>
|
|
...
|
|
modparam("tls", "private", "/usr/local/etc/ser/my_pkey.pem")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="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 authentication 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 ser -f /etc/ser/ser.cfg it will be relative to /etc/ser/).
|
|
</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/ser/ca_list.pem")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="crl">
|
|
<title><varname>crl</varname> (string)</title>
|
|
<para>
|
|
Sets the certificate revocation list 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 ser -f /etc/ser/ser.cfg it will be relative to /etc/ser/).
|
|
</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 is not set.
|
|
</para>
|
|
<para>
|
|
To update the crl in a running ser, 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 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/ser/crl.pem")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="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="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="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, the 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="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="http://www.openssl.org/docs/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="send_timeout">
|
|
<title><varname>send_timeout</varname> (int)</title>
|
|
<para>
|
|
This parameter is <emphasis>obsolete</emphasis> and cannot be used
|
|
in newer TLS versions (> sip-router 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="handshake_timeout">
|
|
<title><varname>handshake_timeout</varname> (int)</title>
|
|
<para>
|
|
This parameter is <emphasis>obsolete</emphasis> and cannot be used
|
|
in newer TLS versions (> sip-router 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="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>
|
|
It 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_disable_compression">
|
|
<title><varname>tls_disable_compression</varname> (boolean)</title>
|
|
<para>
|
|
If set compression over SSL/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="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_free_list_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 sr 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="ssl_freelist_max_len">
|
|
<title><varname>ssl_free_list_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="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 ser/sip-router 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="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="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="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="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/SSL 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="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_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 SIP-router 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_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 SIP-router 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="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="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_force_run">
|
|
<title><varname>tls_force_run</varname> (boolean)</title>
|
|
<para>
|
|
If enabled SIP-router 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 SIP-router 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="config">
|
|
<title><varname>config</varname> (string)</title>
|
|
<para>
|
|
Sets the name of the TLS specific config file.
|
|
</para>
|
|
<para>
|
|
If set the TLS module will load a special config file, 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.
|
|
</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 ser -f /etc/ser/ser.cfg it will be relative to /etc/ser/).
|
|
</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>
|
|
</itemizedlist>
|
|
<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 ser main config file.
|
|
</para>
|
|
<para>
|
|
SIP-router 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
|
|
|
|
</programlisting>
|
|
</example>
|
|
<para>
|
|
For a more complete example check the <emphasis>tls.cfg</emphasis> distributed with the SIP-router source (sip_router/modules/tls/tls.cfg).
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>config</varname> parameter</title>
|
|
<programlisting>
|
|
...
|
|
modparam("tls", "config", "/usr/local/etc/ser/tls.cfg")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
<para>
|
|
It can be changed also at runtime. The new config will not be loaded
|
|
immediately, but after the first tls.reload RPC call.
|
|
<example>
|
|
<title>Change and reload tls config at runtime</title>
|
|
<programlisting>
|
|
$ &sercmd; cfg.set_now_string tls config "/usr/local/etc/ser/new_tls.cfg"
|
|
$ &sercmd; tls.reload
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
</section>
|
|
|
|
</section>
|