This module implements the TLS transport for ser 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 ser config file

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

#...
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{
	# ....
}

The tls module needs some special options enabled when compiling ser. These options are enabled by default, however in case you're using a modified ser 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 ser 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 ser TLS connection rate.

Compression is fully supported and used by default, 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. There's no need to force-disable the 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/.

In most case compiling the TLS module is as simple as:

make modules modules=modules/tls

or

cd modules/tls
make

or (compiling whole ser 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 ser 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

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

The private key must not encrypted (ser cannot ask you for a password on startup).

The tls certificate verifications ignores the certificate name, 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 select framework and rpc sections are completely missing.

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.

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
	
2. create CA private key
	openssl genrsa -out demoCA/private/cakey.pem 2048
	chmod 600 demoCA/private/cakey.pem
	
3. create CA self-signed certificate
	openssl req -out demoCA/cacert.pem   -x509 -new -key demoCA/private/cakey.pem


Creating a server/client 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 certificate.
	
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 ser 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 ser certificate, private key and ca list file to your 
	intended machine (preferably in your ser cfg. directory, this is the 
	default place ser searches for)
	
3. set up ser.cfg to use the certificate
	if your ser certificate name is different from cert.pem or it is not
	placed in ser cfg. directory, add to your ser.cfg:
		modparam("tls", "certificate", "/path/cert_file_name")
	
4. set up ser to use the private key
	if your private key is not contained in the certificate (or the
	 certificate name is not the default cert.pem), add to your ser.cfg:
		modparam("tls", "private_key", "/path/private_key_file")
	
5. set up ser to use the ca list (optional)
	add to your ser.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)

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.

The code is currently maintained by Andrei Pelinescu-Onciul <andrei@iptel.org>.