All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
mod-tls: TLS support for Turbulence

Index

Introduction

mod-tls module provides facilities to use TLS profile, allowing to secure connection avoiding sending data in plain text.

Base configuration

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. 

       The close-on-failure="yes" attribute allows to control if the
       module should close the connection after a TLS handshake
       failure or leave the connection as is. Leave this setting as is
       to have a recommended secure configuration.
   -->
   <certificate-select close-on-failure="yes" 
                       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

How paths are handled to find certificates and private keys provided

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

How to configure profile path to enable 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.

SECURITY CLARIFICATION: 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. This is because the module installs an internal alias value to check the TLS profile successful activation and that value is only available when the connection is completed. Moreover, mod-tls closes the connection if a failure is found to avoid any confusion or implementation failure that may let the channel open (the TLS one) causing the profile path to accept the inner profiles (which could be a problem). That's why it is recommended the close-on-failure="yes" declaration (or not place any declaration about this which in turn will cause the same effect).

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>

Configuring mod-tls search path

Currently, mod-tls searches for tls.conf looking for it in the following other: