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.
1009 lines
35 KiB
1009 lines
35 KiB
1. TLS Module
|
|
|
|
Andrei Pelinescu-Onciul
|
|
|
|
iptelorg GmbH
|
|
|
|
Copyright © 2007 iptelorg GmbH
|
|
Revision History
|
|
Revision $Revision$ $Date$
|
|
__________________________________________________________________
|
|
|
|
1.1. Overview
|
|
1.2. Quick Start
|
|
1.3. Important Notes
|
|
1.4. Compiling the TLS Module
|
|
1.5. TLS and Low Memory
|
|
1.6. TLS Debugging
|
|
1.7. Known Limitations
|
|
1.8. Quick Certificate Howto
|
|
1.9. Parameters
|
|
|
|
1.9.1. tls_method (string)
|
|
1.9.2. certificate (string)
|
|
1.9.3. private_key (string)
|
|
1.9.4. ca_list (string)
|
|
1.9.5. crl (string)
|
|
1.9.6. verify_certificate (boolean)
|
|
1.9.7. verify_depth (integer)
|
|
1.9.8. require_certificate (boolean)
|
|
1.9.9. cipher_list (string)
|
|
1.9.10. send_timeout (int)
|
|
1.9.11. handshake_timeout (int)
|
|
1.9.12. connection_timeout (int)
|
|
1.9.13. tls_disable_compression (boolean)
|
|
1.9.14. ssl_release_buffers (integer)
|
|
1.9.15. ssl_free_list_max_len (integer)
|
|
1.9.16. ssl_max_send_fragment (integer)
|
|
1.9.17. ssl_read_ahead (boolean)
|
|
1.9.18. send_close_notify (boolean)
|
|
1.9.19. con_ct_wq_max (integer)
|
|
1.9.20. ct_wq_max (integer)
|
|
1.9.21. ct_wq_blk_size (integer)
|
|
1.9.22. tls_log (int)
|
|
1.9.23. tls_debug (int)
|
|
1.9.24. low_mem_threshold1 (integer)
|
|
1.9.25. low_mem_threshold2 (integer)
|
|
1.9.26. tls_force_run (boolean)
|
|
1.9.27. config (string)
|
|
|
|
1.10. Functions
|
|
|
|
1.10.1. is_peer_verified()
|
|
|
|
1.11. History
|
|
|
|
1.1. Overview
|
|
|
|
This module implements the TLS transport for SIP-router using the
|
|
OpenSSL library (http://www.openssl.org). To enable the TLS support
|
|
this module must be loaded and enable_tls=yes must be added to the
|
|
SIP-router config file
|
|
|
|
1.2. Quick Start
|
|
|
|
Make sure you have a proper certificate and private key and either use
|
|
the certificate and private_key module parameters, or make sure the
|
|
certificate and key are in the same PEM file, named cert.pem an placed
|
|
in [your-cfg-install-prefix]/etc/ser/. Don't forget to load the tls
|
|
module and to enable TLS (add enable_tls=yes to your config).
|
|
|
|
Example 1. quick start config
|
|
#...
|
|
loadmodule "modules/tls/tls.so"
|
|
|
|
modparam("tls", "private_key", "./andrei-test.pem")
|
|
modparam("tls", "certificate", "./andrei-test.pem")
|
|
modparam("tls", "ca_list", "./calist.pem")
|
|
|
|
enable_tls=yes
|
|
|
|
route{
|
|
# ....
|
|
}
|
|
|
|
1.3. Important Notes
|
|
|
|
The TLS module needs some special options enabled when compiling
|
|
SIP-router. These options are enabled by default, however in case
|
|
you're using a modified SIP-router version or Makefile, make sure that
|
|
you enable -DUSE_TLS and -DTLS_HOOKS (or compile with make TLS_HOOKS=1
|
|
which will take care of both options). To quickly check if your
|
|
SIP-router version was compiled with these options, run ser -V and look
|
|
for USE_TLS and TLS_HOOKS among the flags.
|
|
|
|
This module includes several workarounds for various Openssl bugs (like
|
|
compression and Kerberos using the wrong memory allocations functions,
|
|
low memory problems a.s.o). On startup it will try to enable the needed
|
|
workarounds based on the openssl library version. Each time a known
|
|
problem is detected and a workaround is enabled, a message will be
|
|
logged. In general it is recommended to compile this module on the same
|
|
machine or a similar machine to where ser will be run or to link it
|
|
statically with libssl. For example if on the compile machine openssl
|
|
does not have the kerberos support enabled, but on the target machine a
|
|
kerberos enabled openssl library is installed, ser cannot apply the
|
|
needed workarounds and will refuse to start. The same thing will happen
|
|
if the openssl versions are too different (to force ser startup anyway,
|
|
see the tls_force_run module parameter).
|
|
|
|
Try to avoid using keys larger then 1024 bytes. Large keys
|
|
significantly slow down the TLS connection handshake, thus limiting the
|
|
maximum SIP-router TLS connection rate.
|
|
|
|
Compression is fully supported if you have a new enough Openssl version
|
|
(starting with 0.9.8). Although there are some problems with zlib
|
|
compression in currently deployed Openssl versions (up to and including
|
|
0.9.8d, see openssl bug #1468), the TLS module will automatically
|
|
switch to its own fixed version. Note however that starting with sr 3.1
|
|
compression is not enabled by default, due to the huge extra memory
|
|
consumption that it causes (about 10x more memory). To enable it use
|
|
modparam("tls", "tls_disable_compression", 0) (see
|
|
tls_disable_compression).
|
|
|
|
The TLS module includes workarounds for the following known openssl
|
|
bugs: openssl #1204 (disable SS_OP_TLS_BLOCK_PADDING_BUG if compression
|
|
is enabled, for versions between 0.9.8 and 0.9.8c), openssl #1468 (fix
|
|
zlib compression memory allocation), openssl #1467 (kerberos support
|
|
will be disabled if the openssl version is less than 0.9.8e-beta1) and
|
|
openssl #1491 (stop using tls in low memory situations due to the very
|
|
high risk of openssl crashing or leaking memory). The bug reports can
|
|
be viewed at http://rt.openssl.org/.
|
|
|
|
1.4. Compiling the TLS Module
|
|
|
|
In most case compiling the TLS module is as simple as:
|
|
make -C modules/tls
|
|
|
|
or
|
|
make modules modules=modules/tls
|
|
|
|
or (compiling whole SIP-router and the tls module)
|
|
make all include_modules=tls
|
|
|
|
.
|
|
|
|
However in some cases the openssl library requires linking with other
|
|
libraries. For example compiling the openssl library with kerberos and
|
|
zlib-shared support will require linking the tls module with libkrb5
|
|
and libz. In this case just add TLS_EXTRA_LIBS="library list" to make's
|
|
command line. E.g.:
|
|
make TLS_EXTRA_LIBS="-lkrb5 -lz" all include_modules=tls
|
|
|
|
In general, if SIP-router fails to start with a symbol not found error
|
|
when trying to load the tls module (check the log), it means some
|
|
needed library was not linked and it must be added to TLS_EXTRA_LIBS
|
|
|
|
1.5. TLS and Low Memory
|
|
|
|
The openssl library doesn't handle very well low memory situations. If
|
|
memory allocations start to fail (due to memory shortage), openssl can
|
|
crash or cause memory leaks (making the memory shortage even worse). As
|
|
of this writing all openssl versions were affected (includind 0.9.8e),
|
|
see openssl bug #1491. The tls module has some workarounds for
|
|
preventing this problem (see low_mem_treshold1 and low_mem_threshold2),
|
|
however starting SIP-router with enough shared memory is higly
|
|
recommended. When this is not possible a quick way to significantly
|
|
reduce openssl memory usage it to disable compression (see
|
|
tls_disable_compression).
|
|
|
|
1.6. TLS Debugging
|
|
|
|
Debugging messages can be selectively enabled by recompiling the tls
|
|
module with a combination of the following defines:
|
|
* TLS_WR_DEBUG - debug messages for the write/send part.
|
|
* TLS_RD_DEBUG - debug messages for the read/receive part.
|
|
* TLS_BIO_DEBUG - debug messages for the custom BIO.
|
|
|
|
Example 2. Compiling TLS with Debug Messages
|
|
make -C modules/tls extra_defs="-DTLS_WR_DEBUG -DTLS_RD_DEBUG"
|
|
|
|
To change the level at which the debug messages are logged, change the
|
|
tls_debug module parameter.
|
|
|
|
1.7. Known Limitations
|
|
|
|
The private key must not encrypted (SIP-router cannot ask you for a
|
|
password on startup).
|
|
|
|
The TLS certificate verifications ignores the certificate name, subject
|
|
altname and ip extensions, it just checks if the certificate is signed
|
|
by a recognized CA. One can use the select framework to try to overcome
|
|
this limitation (check in the script for the contents of various
|
|
certificate fields), but this is not only slow, but also not exactly
|
|
standard conforming (the verification should happen during TLS
|
|
connection establishment and not after).
|
|
|
|
TLS specific config reloading is not safe, so for now better don't use
|
|
it, especially under heavy traffic.
|
|
|
|
This documentation is incomplete. The RPCs are not documented here, but
|
|
in doc/rpc_list/rpc_tls.txt or
|
|
http://sip-router.org/docbook/sip-router/branch/master/rpc_list/rpc_lis
|
|
t.html#rpc_exports.tls. The provided selects are not documented. A list
|
|
with all the ones implemented by the tls module can be seen under
|
|
doc/select_list/select_tls.txt or or
|
|
http://sip-router.org/docbook/sip-router/branch/master/select_list/sele
|
|
ct_list.html#select_list.tls.
|
|
|
|
1.8. Quick Certificate Howto
|
|
|
|
Revision History
|
|
Revision $Revision$ $Date$
|
|
|
|
There are various ways to create, sign certificates and manage small
|
|
CAs (Certificate Authorities). If you want a GUI, try tinyca
|
|
(http://tinyca.sm-zone.net/), a very nice and small CA management
|
|
application. If you are in a hurry and everything you have are the
|
|
installed openssl libraries and utilities, read on.
|
|
|
|
Assumptions: we run our own CA.
|
|
|
|
Warning: in this example no key is encrypted. The client and server
|
|
private keys must not be encrypted (ser doesn't support encrypted
|
|
keys), so make sure the corresponding files are readable only by
|
|
trusted people. You should use a password for your CA private key.
|
|
|
|
Assumptions
|
|
------------
|
|
|
|
The default openssl configuration (usually /etc/ssl/openssl.cnf)
|
|
default_ca section is the one distributed with openssl and uses the default
|
|
directories:
|
|
|
|
...
|
|
|
|
default_ca = CA_default # The default ca section
|
|
|
|
[ CA_default ]
|
|
|
|
dir = ./demoCA # Where everything is kept
|
|
certs = $dir/certs # Where the issued certs are kept
|
|
crl_dir = $dir/crl # Where the issued crl are kept
|
|
database = $dir/index.txt # database index file.
|
|
#unique_subject = no # Set to 'no' to allow creation of
|
|
# several ctificates with same subject.
|
|
new_certs_dir = $dir/newcerts # default place for new certs.
|
|
|
|
certificate = $dir/cacert.pem # The CA certificate
|
|
serial = $dir/serial # The current serial number
|
|
crlnumber = $dir/crlnumber # the current crl number
|
|
crl = $dir/crl.pem # The current CRL
|
|
private_key = $dir/private/cakey.pem# The private key
|
|
RANDFILE = $dir/private/.rand # private random number file
|
|
|
|
...
|
|
|
|
If this is not the case create a new openssl config file that uses the above
|
|
paths for the default CA and add to all the openssl commands:
|
|
-config filename. E.g.:
|
|
openssl ca -config my_openssl.cnf -in ser1_cert_req.pem -out ser1_cert.p
|
|
em
|
|
|
|
|
|
Creating CA certificate
|
|
-----------------------
|
|
1. create CA dir
|
|
mkdir ca
|
|
cd ca
|
|
|
|
2. create ca dir structure and files (see ca(1))
|
|
mkdir demoCA #default CA name, edit /etc/ss/openssl.cnf
|
|
mkdir demoCA/private
|
|
mkdir demoCA/newcerts
|
|
touch demoCA/index.txt
|
|
echo 01 >demoCA/serial
|
|
echo 01 >demoCA/crlnumber
|
|
|
|
2. create CA private key
|
|
openssl genrsa -out demoCA/private/cakey.pem 2048
|
|
chmod 600 demoCA/private/cakey.pem
|
|
|
|
3. create CA self-signed certificate
|
|
openssl req -out demoCA/cacert.pem -x509 -new -key demoCA/private/cake
|
|
y.pem
|
|
|
|
|
|
Creating a server/client certificate
|
|
------------------------------------
|
|
1. create a certificate request (and its private key in privkey.pem)
|
|
openssl req -out ser1_cert_req.pem -new -nodes
|
|
WARNING: the organization name should be the same as in the ca certifica
|
|
te.
|
|
|
|
2. sign it with the ca certificate
|
|
openssl ca -in ser1_cert_req.pem -out ser1_cert.pem
|
|
|
|
3. copy ser1_cert.pem to your ser config. dir
|
|
|
|
|
|
Setting sip-router to use the certificate
|
|
-----------------------------------------
|
|
1. create the ca list file:
|
|
for each of your ca certificates that you intend to use do:
|
|
cat cacert.pem >>calist.pem
|
|
|
|
2. copy your sip-router certificate, private key and ca list file to your
|
|
intended machine (preferably in your sip-router configuration directory,
|
|
this is the default place sip-router searches for).
|
|
|
|
3. set up sip-router.cfg to use the certificate
|
|
if your ser certificate name is different from cert.pem or it is not
|
|
placed in sip-router cfg. directory, add to your sip-router.cfg:
|
|
modparam("tls", "certificate", "/path/cert_file_name")
|
|
|
|
4. set up sip-router to use the private key
|
|
if your private key is not contained in the same file as the certificate
|
|
(or the certificate name is not the default cert.pem), add to your
|
|
sip-router.cfg:
|
|
modparam("tls", "private_key", "/path/private_key_file")
|
|
|
|
5. set up sip-router to use the ca list (optional)
|
|
add to your sip-router.cfg:
|
|
modparam("tls", "ca_list", "/path/ca_list_file")
|
|
|
|
6. set up tls authentication options:
|
|
modparam("tls", "verify_certificate", 1)
|
|
modparam("tls", "require_certificate", 1)
|
|
(for more information see the module parameters documentation)
|
|
|
|
|
|
Revoking a certificate and using a CRL
|
|
--------------------------------------
|
|
1. revoking a certificate:
|
|
openssl ca -revoke bad_cert.pem
|
|
|
|
2. generate/update the certificate revocation list:
|
|
openssl ca -gencrl -out my_crl.pem
|
|
|
|
3. copy my_crl.pem to your ser config. dir
|
|
|
|
4. set up sip-router to use the CRL:
|
|
modparam("tls", "crl", "path/my_crl.pem")
|
|
|
|
1.9. Parameters
|
|
|
|
Revision History
|
|
Revision $Revision$ $Date$
|
|
|
|
1.9.1. tls_method (string)
|
|
|
|
Sets the SSL/TLS protocol method. Possible values are:
|
|
* TLSv1 - only TLSv1 connections are accepted. This is the default
|
|
and recommended method (if you want to be rfc3261 conformant don't
|
|
change it).
|
|
* SSLv3 - only SSLv3 connections are accepted
|
|
* SSLv2 - only SSLv2 connections, for old clients. Note: you
|
|
shouldn't use SSLv2 for anything which should be highly secure.
|
|
* SSLv23 - 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.
|
|
|
|
If rfc3261 conformance is desired, TLSv1 must be used. For
|
|
compatibility with older clients SSLv23 is a good option.
|
|
|
|
Example 3. Set tls_method parameter
|
|
...
|
|
modparam("tls", "tls_method", "TLSv1")
|
|
...
|
|
|
|
1.9.2. certificate (string)
|
|
|
|
Sets the certificate file name. The certificate file can also contain
|
|
the private key in PEM format.
|
|
|
|
If the file name starts with a '.' the path will be relative to the
|
|
working directory (at runtime). If it starts with a '/' it will be an
|
|
absolute path and if it starts with anything else the path will be
|
|
relative to the main config file directory (e.g.: for ser -f
|
|
/etc/ser/ser.cfg it will be relative to /etc/ser/).
|
|
|
|
Warning: try not to use certificate with keys longer then 1024 bytes.
|
|
Longer keys will severely impact performance, in particular the TLS
|
|
connection rate.
|
|
|
|
The default value is [SER_CFG_DIR]/cert.pem.
|
|
|
|
Example 4. Set certificate parameter
|
|
...
|
|
modparam("tls", "certificate", "/usr/local/etc/ser/my_certificate.pem")
|
|
...
|
|
|
|
1.9.3. private_key (string)
|
|
|
|
Sets the private key file name.
|
|
|
|
If the file name starts with a '.' the path will be relative to the
|
|
working directory (at runtime). If it starts with a '/' it will be an
|
|
absolute path and if it starts with anything else the path will be
|
|
relative to the main config file directory (e.g.: for ser -f
|
|
/etc/ser/ser.cfg it will be relative to /etc/ser/).
|
|
|
|
Note: the private key can be contained in the same file as the
|
|
certificate (just append it to the certificate file, e.g.: cat pkey.pem
|
|
>> cert.pem)
|
|
|
|
The default value is [SER_CFG_DIR]/cert.pem.
|
|
|
|
Example 5. Set private_key parameter
|
|
...
|
|
modparam("tls", "private", "/usr/local/etc/ser/my_pkey.pem")
|
|
...
|
|
|
|
1.9.4. ca_list (string)
|
|
|
|
Sets the CA list file name. This file contains a list of all the
|
|
trusted CAs certificates. If a signature in a certificate chain belongs
|
|
to one of the listed CAs, the authentication will succeed.
|
|
|
|
If the file name starts with a '.' the path will be relative to the
|
|
working directory (at runtime). If it starts with a '/' it will be an
|
|
absolute path and if it starts with anything else the path will be
|
|
relative to the main config file directory (e.g.: for ser -f
|
|
/etc/ser/ser.cfg it will be relative to /etc/ser/).
|
|
|
|
By default the CA file is not set.
|
|
|
|
An easy way to create the CA list is to append each trusted trusted CA
|
|
certificate in the PEM format to one file, e.g.: for f in
|
|
trusted_cas/*.pem ; do cat "$f" >> ca_list.pem ; done .
|
|
|
|
See also verify_certificate, verify_depth, require_certificate and crl.
|
|
|
|
Example 6. Set ca_list parameter
|
|
...
|
|
modparam("tls", "ca_list", "/usr/local/etc/ser/ca_list.pem")
|
|
...
|
|
|
|
1.9.5. crl (string)
|
|
|
|
Sets the certificate revocation list file name. This file contains a
|
|
list of revoked certificates. Any attempt to verify a revoked
|
|
certificate will fail.
|
|
|
|
If not set, no crl list will be used.
|
|
|
|
If the file name starts with a '.' the path will be relative to the
|
|
working directory (at runtime). If it starts with a '/' it will be an
|
|
absolute path and if it starts with anything else the path will be
|
|
relative to the main config file directory (e.g.: for ser -f
|
|
/etc/ser/ser.cfg it will be relative to /etc/ser/).
|
|
|
|
Note
|
|
|
|
If set, require_certificate should also be set or it will not have any
|
|
effect.
|
|
|
|
By default the crl file is not set.
|
|
|
|
To update the crl in a running ser, make sure you configure tls via a
|
|
separate tls config file (the config modparam) and issue a tls.reload
|
|
RPC call, e.g.:
|
|
$ sercmd tls.reload
|
|
|
|
A quick way to create the CRL in PEM format, using openssl is:
|
|
$ openssl ca -gencrl -keyfile cacert.key -cert cacert.pem -out my_crl.pem
|
|
|
|
my_crl.pem will contain the signed list of the revoked certificates.
|
|
|
|
To revoke a certificate use something like:
|
|
$ openssl ca -revoke bad_cert.pem -keyfile cacert.key -cert cacert.pem
|
|
|
|
and then refresh the crl file using the command above.
|
|
|
|
To display the CRL contents use:
|
|
$ openssl crl -in crl.pem -noout -text
|
|
|
|
See also ca_list, verify_certificate, verify_depth and
|
|
require_certificate.
|
|
|
|
Example 7. Set crl parameter
|
|
...
|
|
modparam("tls", "crl", "/usr/local/etc/ser/crl.pem")
|
|
...
|
|
|
|
1.9.6. verify_certificate (boolean)
|
|
|
|
If enabled it will force certificate verification. For more information
|
|
see the verify(1) openssl man page.
|
|
|
|
Note: the certificate verification will always fail if the ca_list is
|
|
empty.
|
|
|
|
See also: ca_list, require_certificate, verify_depth.
|
|
|
|
By default the certificate verification is off.
|
|
|
|
Example 8. Set verify_certificate parameter
|
|
...
|
|
modparam("tls", "verify_certificate", 1)
|
|
...
|
|
|
|
1.9.7. verify_depth (integer)
|
|
|
|
Sets how far up the certificate chain will the certificate verification
|
|
go in the search for a trusted CA.
|
|
|
|
See also: ca_list, require_certificate, verify_certificate,
|
|
|
|
The default value is 9.
|
|
|
|
Example 9. Set verify_depth parameter
|
|
...
|
|
modparam("tls", "verify_depth", 9)
|
|
...
|
|
|
|
1.9.8. require_certificate (boolean)
|
|
|
|
When enabled it will require a certificate from a client. If the client
|
|
does not offer a certificate and verify_certificate is on, the
|
|
certificate verification will fail.
|
|
|
|
The default value is off.
|
|
|
|
Example 10. Set require_certificate parameter
|
|
...
|
|
modparam("tls", "require_certificate", 1)
|
|
...
|
|
|
|
1.9.9. cipher_list (string)
|
|
|
|
Sets the list of accepted ciphers. The list consists of cipher strings
|
|
separated by colons. For more information on the cipher list format see
|
|
the cipher(1) openssl man page.
|
|
|
|
The default value is not set (all the Openssl supported ciphers are
|
|
enabled).
|
|
|
|
Example 11. Set cipher_list parameter
|
|
...
|
|
modparam("tls", "cipher_list", "HIGH")
|
|
...
|
|
|
|
1.9.10. send_timeout (int)
|
|
|
|
This parameter is obsolete and cannot be used in newer TLS versions (>
|
|
sip-router 3.0). In these versions the send_timeout is replaced by
|
|
tcp_send_timeout (common with all the tcp connections).
|
|
|
|
1.9.11. handshake_timeout (int)
|
|
|
|
This parameter is obsolete and cannot be used in newer TLS versions (>
|
|
sip-router 3.0). In these versions the handshake_timeout is replaced by
|
|
tcp_connect_timeout (common with all the tcp connections).
|
|
|
|
1.9.12. connection_timeout (int)
|
|
|
|
Sets the amount of time after which an idle TLS connection will be
|
|
closed, if no I/O ever occured after the initial open. If an I/O event
|
|
occurs, the timeout will be extended with tcp_connection_lifetime. The
|
|
value is expressed in seconds.
|
|
|
|
The default value is 10 min.
|
|
|
|
If the value set is -1, the connection will never be close on idle.
|
|
|
|
It can be changed also at runtime, via the RPC interface and config
|
|
framework. The config variable name is tls.connection_timeout.
|
|
|
|
Example 12. Set connection_timeout parameter
|
|
...
|
|
modparam("tls", "connection_timeout", 60)
|
|
...
|
|
|
|
Example 13. Set tls.connection_timeout at runtime
|
|
$ sercmd cfg.set_now_int tls connection_timeout 180
|
|
|
|
1.9.13. tls_disable_compression (boolean)
|
|
|
|
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.
|
|
|
|
By default compression is disabled.
|
|
|
|
Example 14. Set tls_disable_compression parameter
|
|
...
|
|
modparam("tls", "tls_disable_compression", 0) # enable
|
|
...
|
|
|
|
1.9.14. ssl_release_buffers (integer)
|
|
|
|
Release internal OpenSSL read or write buffers as soon as they are no
|
|
longer needed. Combined with ssl_free_list_max_len has the potential of
|
|
saving a lot of memory ( ~ 32k per connection in the default
|
|
configuration, or 16k + ssl_max_send_fragment). For sr versions > 3.0
|
|
it makes little sense to disable it (0) since the tls module already
|
|
has its own internal buffering.
|
|
|
|
A value of -1 would not change this option from its openssl default.
|
|
Use 0 or 1 for enable/disable.
|
|
|
|
By default the value is 1 (enabled).
|
|
|
|
Note
|
|
|
|
This option is supported only for OpenSSL versions >= 1.0.0. On all the
|
|
other versions attempting to change the default will trigger an error.
|
|
|
|
Example 15. Set ssl_release_buffers parameter
|
|
modparam("tls", "ssl_release_buffers", 1)
|
|
|
|
1.9.15. ssl_free_list_max_len (integer)
|
|
|
|
Sets the maximum number of free memory chunks, that OpenSSL will keep
|
|
per connection. Setting it to 0 would cause any unused memory chunk to
|
|
be immediately freed, reducing the memory footprint. A too large value
|
|
would result in extra memory consumption.
|
|
|
|
Should be combined with ssl_release_buffers.
|
|
|
|
A value of -1 has a special meaning: the OpenSSL default will be used
|
|
(no attempt on changing the value will be made). For OpenSSL 1.0 the
|
|
internal default is 32.
|
|
|
|
By default the value is 0 (no freelist).
|
|
|
|
Note
|
|
|
|
This option is supported only for OpenSSL versions >= 1.0.0. On all the
|
|
other versions attempting to change the default will trigger an error.
|
|
|
|
Example 16. Set ssl_freelist_max_len parameter
|
|
modparam("tls", "ssl_freelist_max_len", 0)
|
|
|
|
1.9.16. ssl_max_send_fragment (integer)
|
|
|
|
Sets the maximum number of bytes (from the clear text) sent into one
|
|
TLS or SSL record. Valid values are between 512 and 16384. Note however
|
|
that even valid low values might not be big enough to allow a
|
|
succesfull handshake (try minimum 1024).
|
|
|
|
Lower values would lead to less memory usage, but values lower then the
|
|
typical 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.
|
|
|
|
Note
|
|
|
|
Values on the lower side, even if valid (> 512), might not allow for a
|
|
succesfull initial handshake. This happens if the certificate does not
|
|
fit inside one send fragment. Values lower then 1024 should not be
|
|
used. Even with higher values, if the handshake fails, try increasing
|
|
the value.
|
|
|
|
A value of -1 has a special meaning: the OpenSSL default will be used
|
|
(no attempt on changing the value will be made).
|
|
|
|
By default the value is -1 (the OpenSSL default, which at least in
|
|
OpenSSL 1.0.0 is ~ 16k).
|
|
|
|
Note
|
|
|
|
This option is supported only for OpenSSL versions >= 0.9.9. On all the
|
|
other versions attempting to change the default will trigger an error.
|
|
|
|
Example 17. Set ssl_max_send_fragment parameter
|
|
modparam("tls", "ssl_max_send_fragment", 4096)
|
|
|
|
1.9.17. ssl_read_ahead (boolean)
|
|
|
|
Enables read ahead, reducing the number of internal OpenSSL BIO read()
|
|
calls. This option has only debugging value, in normal circumstances it
|
|
should not be changed from the default.
|
|
|
|
When disabled OpenSSL will make at least 2 BIO read() calls per
|
|
received record: one to get the record header and one to get the rest
|
|
of the record.
|
|
|
|
The TLS module buffers internally all read()s and defines its own fast
|
|
BIO so enabling this option would only cause more memory consumption
|
|
and a minor slow-down (extra memcpy).
|
|
|
|
A value of -1 has a special meaning: the OpenSSL default will be used
|
|
(no attempt on changing the value will be made).
|
|
|
|
By default the value is 0 (disabled).
|
|
|
|
Example 18. Set ssl_read_ahead parameter
|
|
modparam("tls", "ssl_read_ahead", 1)
|
|
|
|
1.9.18. send_close_notify (boolean)
|
|
|
|
Enables/disables sending close notify alerts prior to closing the
|
|
corresponding TCP connection. Sending the close notify prior to tcp
|
|
shutdown is "nicer" from a TLS point of view, but it has a measurable
|
|
performance impact. Default: off. Can be set at runtime
|
|
(tls.send_close_notify).
|
|
|
|
The default value is 0 (off).
|
|
|
|
It can be changed also at runtime, via the RPC interface and config
|
|
framework. The config variable name is tls.send_close_notify.
|
|
|
|
Example 19. Set send_close_notify parameter
|
|
...
|
|
modparam("tls", "send_close_notify", 1)
|
|
...
|
|
|
|
Example 20. Set tls.send_close_notify at runtime
|
|
$ sercmd cfg.set_now_int tls send_close_notify 1
|
|
|
|
1.9.19. con_ct_wq_max (integer)
|
|
|
|
Sets the maximum allowed per connection clear-text send queue size in
|
|
bytes. This queue is used when data cannot be encrypted and sent
|
|
immediately because of an ongoing TLS/SSL level renegotiation.
|
|
|
|
The default value is 65536 (64 Kb).
|
|
|
|
It can be changed also at runtime, via the RPC interface and config
|
|
framework. The config variable name is tls.con_ct_wq_max.
|
|
|
|
Example 21. Set con_ct_wq_max parameter
|
|
...
|
|
modparam("tls", "con_ct_wq_max", 1048576)
|
|
...
|
|
|
|
Example 22. Set tls.con_ct_wq_max at runtime
|
|
$ sercmd cfg.set_now_int tls con_ct_wq_max 1048576
|
|
|
|
1.9.20. ct_wq_max (integer)
|
|
|
|
Sets the maximum total number of bytes queued in all the clear-text
|
|
send queues. These queues are used when data cannot be encrypted and
|
|
sent immediately because of an ongoing TLS/SSL level renegotiation.
|
|
|
|
The default value is 10485760 (10 Mb).
|
|
|
|
It can be changed also at runtime, via the RPC interface and config
|
|
framework. The config variable name is tls.ct_wq_max.
|
|
|
|
Example 23. Set ct_wq_max parameter
|
|
...
|
|
modparam("tls", "ct_wq_max", 4194304)
|
|
...
|
|
|
|
Example 24. Set tls.ct_wq_max at runtime
|
|
$ sercmd cfg.set_now_int tls ct_wq_max 4194304
|
|
|
|
1.9.21. ct_wq_blk_size (integer)
|
|
|
|
Minimum block size for the internal clear-text send queues (debugging /
|
|
advanced tunning). Good values are multiple of typical datagram sizes.
|
|
|
|
The default value is 4096.
|
|
|
|
It can be changed also at runtime, via the RPC interface and config
|
|
framework. The config variable name is tls.ct_wq_blk_size.
|
|
|
|
Example 25. Set ct_wq_blk_size parameter
|
|
...
|
|
modparam("tls", "ct_wq_blk_size", 2048)
|
|
...
|
|
|
|
Example 26. Set tls.ct_wq_max at runtime
|
|
$ sercmd cfg.set_now_int tls ct_wq_blk_size 2048
|
|
|
|
1.9.22. tls_log (int)
|
|
|
|
Sets the log level at which TLS related messages will be logged.
|
|
|
|
The default value is 3 (L_DBG).
|
|
|
|
It can be changed also at runtime, via the RPC interface and config
|
|
framework. The config variable name is tls.log.
|
|
|
|
Example 27. Set tls_log parameter
|
|
...
|
|
# ignore TLS messages if SIP-router is started with debug less than 10
|
|
modparam("tls", "tls_log", 10)
|
|
...
|
|
|
|
Example 28. Set tls.log at runtime
|
|
$ sercmd cfg.set_now_int tls log 10
|
|
|
|
1.9.23. tls_debug (int)
|
|
|
|
Sets the log level at which TLS debug messages will be logged. Note
|
|
that TLS debug messages are enabled only if the TLS module is compiled
|
|
with debugging enabled (e.g. -DTLS_WR_DEBUG, -DTLS_RD_DEBUG or
|
|
-DTLS_BIO_DEBUG).
|
|
|
|
The default value is 3 (L_DBG).
|
|
|
|
It can be changed also at runtime, via the RPC interface and config
|
|
framework. The config variable name is tls.debug.
|
|
|
|
Example 29. Set tls_debug parameter
|
|
...
|
|
# ignore TLS debug messages if SIP-router is started with debug less than 10
|
|
modparam("tls", "tls_debug", 10)
|
|
...
|
|
|
|
Example 30. Set tls.debug at runtime
|
|
$ sercmd cfg.set_now_int tls debug 10
|
|
|
|
1.9.24. low_mem_threshold1 (integer)
|
|
|
|
Sets the minimal free memory from which attempts to open or accept new
|
|
TLS connections will start to fail. The value is expressed in KB.
|
|
|
|
The default value depends on whether the openssl library used handles
|
|
well low memory situations (openssl bug #1491). As of this writing this
|
|
is not true for any openssl version (including 0.9.8e).
|
|
|
|
If an ill-behaved openssl version is detected, a very conservative
|
|
value is choosed, which depends on the maximum possible number of
|
|
simultaneously created TLS connections (and hence on the process
|
|
number).
|
|
|
|
The following values have a special meaning:
|
|
* -1 - use the default value
|
|
* 0 - disable (TLS connections will not fail preemptively)
|
|
|
|
It can be changed also at runtime, via the RPC interface and config
|
|
framework. The config variable name is tls.low_mem_threshold1.
|
|
|
|
See also low_mem_threshold2.
|
|
|
|
Example 31. Set low_mem_threshold1 parameter
|
|
...
|
|
modparam("tls", "low_mem_threshold1", -1)
|
|
...
|
|
|
|
Example 32. Set tls.low_mem_threshold1 at runtime
|
|
$ sercmd cfg.set_now_int tls low_mem_threshold1 2048
|
|
|
|
1.9.25. low_mem_threshold2 (integer)
|
|
|
|
Sets the minimal free memory from which TLS operations on already
|
|
established TLS connections will start to fail preemptively. The value
|
|
is expressed in KB.
|
|
|
|
The default value depends on whether the openssl library used handles
|
|
well low memory situations (openssl bug #1491). As of this writing this
|
|
is not true for any openssl version (including 0.9.8e).
|
|
|
|
If an ill-behaved openssl version is detected, a very conservative
|
|
value is choosed, which depends on the maximum possible number of
|
|
simultaneously created TLS connections (and hence on the process
|
|
number).
|
|
|
|
The following values have a special meaning:
|
|
* -1 - use the default value
|
|
* 0 - disable (TLS operations will not fail preemptively)
|
|
|
|
It can be changed also at runtime, via the RPC interface and config
|
|
framework. The config variable name is tls.low_mem_threshold2.
|
|
|
|
See also low_mem_threshold1.
|
|
|
|
Example 33. Set low_mem_threshold2 parameter
|
|
...
|
|
modparam("tls", "low_mem_threshold2", -1)
|
|
...
|
|
|
|
Example 34. Set tls.low_mem_threshold2 at runtime
|
|
$ sercmd cfg.set_now_int tls low_mem_threshold2 1024
|
|
|
|
1.9.26. tls_force_run (boolean)
|
|
|
|
If enabled SIP-router will start even if some of the openssl sanity
|
|
checks fail (turn it on at your own risk).
|
|
|
|
Currently failing any of the following sanity checks will not allow
|
|
SIP-router to start:
|
|
* the version of the library the TLS module was compiled with is "too
|
|
different" from the library used at runtime. The versions should
|
|
have the same major, minor and fix level (e.g.: 0.9.8a and 0.9.8c
|
|
are ok, but 0.9.8 and 0.9.9 are not)
|
|
* the openssl library used at compile time and the one used at
|
|
runtime have different kerberos options
|
|
|
|
By default tls_force_run is disabled.
|
|
|
|
Example 35. Set tls_force_run parameter
|
|
...
|
|
modparam("tls", "tls_force_run", 11)
|
|
...
|
|
|
|
1.9.27. config (string)
|
|
|
|
Sets the name of the TLS specific config file.
|
|
|
|
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.
|
|
|
|
If the file name starts with a '.' the path will be relative to the
|
|
working directory (at runtime). If it starts with a '/' it will be an
|
|
absolute path and if it starts with anything else the path will be
|
|
relative to the main config file directory (e.g.: for ser -f
|
|
/etc/ser/ser.cfg it will be relative to /etc/ser/).
|
|
|
|
By default no config file is specified.
|
|
|
|
The following parameters can be set in the config file, for each
|
|
domain:
|
|
* tls_method
|
|
* verify_certificate
|
|
* require_certificate
|
|
* private_key
|
|
* certificate
|
|
* verify_depth
|
|
* ca_list
|
|
* crl
|
|
* cipher_list
|
|
|
|
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.
|
|
|
|
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).
|
|
|
|
Example 36. Short config file
|
|
[server:default]
|
|
method = TLSv1
|
|
verify_certificate = yes
|
|
require_certificate = yes
|
|
private_key = default_key.pem
|
|
certificate = default_cert.pem
|
|
ca_list = default_ca.pem
|
|
crl = default_crl.pem
|
|
|
|
[client:default]
|
|
verify_certificate = yes
|
|
require_certificate = yes
|
|
|
|
#more relaxed for connection on the loopback interface
|
|
[server:127.0.0.1:5061]
|
|
method = SSLv23
|
|
verify_certificate = yes
|
|
require_certificate = no
|
|
private_key = local_key.pem
|
|
certificate = local_cert.pem
|
|
verify_depth = 3
|
|
ca_list = local_ca.pem
|
|
|
|
For a more complete example check the tls.cfg distributed with the
|
|
SIP-router source (sip_router/modules/tls/tls.cfg).
|
|
|
|
Example 37. Set config parameter
|
|
...
|
|
modparam("tls", "config", "/usr/local/etc/ser/tls.cfg")
|
|
...
|
|
|
|
It can be changed also at runtime. The new config will not be loaded
|
|
immediately, but after the first tls.reload RPC call.
|
|
|
|
Example 38. Change and reload tls config at runtime
|
|
$ sercmd cfg.set_now_string tls config "/usr/local/etc/ser/new_tls.cfg"
|
|
$ sercmd tls.reload
|
|
|
|
1.10. Functions
|
|
|
|
Revision History
|
|
Revision $Revision$ $Date$
|
|
|
|
1.10.1. is_peer_verified()
|
|
|
|
Returns true if the connection on which the message was received is TLS
|
|
, the peer presented an X509 certificate and the certificate chain
|
|
verified ok. It can be used only in a request route.
|
|
|
|
Example 39. is_peer_verified usage
|
|
if (proto==TLS && !is_peer_verified()){
|
|
sl_send_reply("400", "No certificate or verification failed");
|
|
drop;
|
|
}
|
|
|
|
1.11. History
|
|
|
|
Revision History
|
|
Revision $Revision$ $Date$
|
|
|
|
This module was put together by Jan Janak <jan@iptel.org> from code
|
|
from the experimental tls core addon
|
|
(http://cvs.berlios.de/cgi-bin/viewcvs.cgi/ser/experimental/tls/), code
|
|
originally written by Peter Griffiths and later maintained by Cesc
|
|
Santasusana and from an iptelorg tls code addon, written by Andrei
|
|
Pelinescu-Onciul <andrei@iptel.org>. Jan also added support for
|
|
multiple domains, a tls specific config, config reloading and a tls
|
|
specific select framework.
|
|
|
|
For ser/sr 3.1 most of the TLS specific code was completely re-written
|
|
to add support for asynchrounous TLS and fix several long standing
|
|
bugs.
|
|
|
|
The code is currently maintained by Andrei Pelinescu-Onciul
|
|
<andrei@iptel.org>.
|