mod-tls module provides facilities to use TLS profile, allowing to secure connection avoiding sending data in plain text.
This module is included in the Turbulence official distribution. To enable it you must make it available at some of the directories that are used by Turbulence to load modules (see 4.1 Turbulence modules configuration). Under most cases this is done as follows:
>> cd /etc/turbulence/mod-enabled >> ln -s ../mod-available/mod-tls.xml
Once included the module you must restart Turbulence. Now the mod-tls is activated you must configure it. This is done by updating tls.conf file which is usually located at /etc/turbulence/tls/tls.conf. Here is an example:
<mod-tls> <!-- -*- nxml -*- --> <!-- place one certificate select for each serverName to match. Use serverName="*" to provide the same certificate for all serverNames requested. --> <certificate-select key="private.key" cert="certificate.crt" serverName="tls.example.com" /> </mod-tls>
mod-tls function is simple, you place once xml stanza (certificate-select) for each certificate you declare associated to a particular serverName.
Once a connection is received requesting that serverName, the provided certificate and key are used. You can place as many as you need certificate-select knowing that they are matched from top to bottom. If twice serverName is provided, the first found will take precedence.
You can also place a certificate-select stanza with serverName="*" which means that, if no previous stanza matches the requested serverName, then this will be used.
Here is an example to create a private key and an unsigned public certificate associated:
>> openssl genrsa 1024 > test-private.key >> openssl req -new -x509 -nodes -sha1 -days 3650 -key test-private.key > test-certificate.crt
The safest way to provide the right location to your certificates is to provide a full path. In the case full path is not provided, then turbulence will try to locate the file at known tls locations (for example /etc/turbulence/tls).
Now you got mod-tls installed and configured, you need to tell turbulence to use TLS profile. A typical escenario is to first enable TLS to protect your connection from third parties and then allow your profiles. Here is an example to be placed inside profile-path-configuration node:
<path-def path-name="Connections from localhost" src="127.*" > <if-success profile="http://iana.org/beep/TLS" > <allow profile="urn:aspl.es:beep:profiles:custom:1" /> </if-success> </path-def>
In previous example first we "require" to enable TLS to serve any profile. Only when TLS is properly enabled, the custom profile inside it is allowed.
Due the way TLS profile is designed, it is not required to place "connmarks" requiring some value stored on the connection to flag that the TLS session is really established (like it happens with SASL). Here you only place the TLS profile uri, as showed in the example, to protect profiles running inside.
Another typical escenario is to first secure the conection with TLS, then require proper SASL authentication, and the provide application profiles. This is done like follows:
<path-def path-name="(TLS+SASL)" src="127.*" server-name="tls+sasl.example.com" > <!-- first require TLS --> <if-success profile="http://iana.org/beep/TLS" > <!-- then require SASL --> <if-success connmark="sasl:is:authenticated" profile="http://iana.org/beep/SASL/.*" > <!-- then allow only profile-22:1 --> <allow profile="urn:aspl.es:beep:profiles:custom:1" /> </if-success> <!-- SASL --> </if-success> <!-- TLS --> </path-def>
Currently, mod-tls searches for tls.conf looking for it in the following other:
