TLS/SSL Support

(text from an email announcement by Jan)

There is a new module called TLS in the cvs repository. The module attempts to merge the TLS code from experimental cvs module (maintained by Cesc) and Andrei's implementation, to get the best of both. Furthermore the module contains some new functions for script based certificate verification.

The TLS module is much more stable than the original implementation. The original (experimental) code works only when there are no simultaneous TLS connections/attempts. The original code would either crash or block SER in seconds under heavy load so it is not really suitable for production use.

The code in TLS module is much more stable, it contains several fixes (icluding fix of openssl) and does not seem to crash even under load Unfortunately we discovered a problem during testing of TLS code which can lead to SER being blocked for the duration of tls_send_timeout interval. After that time it would recover. Andrei can probably elaborate more on this issue, but as far as I know there is no easy wayto fix it.

In conclusion the TLS code in the tls module is more stable than the original code from experimental but is not yet ready for production deployments (unless you can risk SER being blocked for some time). TLS select functions

The current HEAD SER version contains a mechanism which we internaly call the "select" framework. The select framework makes it possible to register functions from modules which can extract pieces of information from the SIP message, transports or IP datagrams. Select functions are denoted by @ character in the configuration file. The name of the select consists of tokens (optionally followed by a number in square brackes) and denoted by ., for example:

@contact[2].uri.params.transport

Would return the value of transport URI parameter from the second Contact URI in the SIP message.

TLS module makes use of this mechanism and contains several functions that can be used to retrieve TLS related information in the configuration script. Currently implemented are the following functions:

@tls.version

The version of TLS procotol being used for the actual connection

Example:

 if (@tls.version == "SSLv2") ...

@tls.desc

Same as @tls

@tls.cipher

Name of the cipher being used in the current TLS connection.

Example:

 'AES256-SHA'

@tls.cipher.bits

Number of encryption bits used by the current TLS connection.

@tls.peer

Common name of the peer certificate subject.

Example:

 if (@tls.peer == "Bob") ...

@tls.me

The local (server for inboud, client for outbound TLS connections) certificate subject Common Name

@tls.peer.subject

same as @tls.peer (just alias for completeness)

@tls.peer.issuer

The common name of peer certificate issuer.

@tls.peer.verified

True if peer provided a certificate and the certificate has been successfuly verified. False if there was no peer certificate or it has not been verified.

@tls.{peer,my}.version

Peer/local certificate version

@tls.{peer,my}.sn

Peer/local certificate serial number assigned by the certificate authority

@tls.{peer,my}.not_before

Certificate validity start

Format: 'Jun 17 15:03:20 2005 GMT'

@tls.{peer,my}.not_after

Certificate validity end (format is same as in @tls.peer.not_before)

@tls.{peer,my}.email

Email address component from the subject alternative name.

@tls.{peer,my}.host

DNS name from the certificate subject alternative name.

@tls.{peer,my}.uri

URI from certificate subject alternative name.

@tls.{peer,my}.ip

IP address from certificate subject alternative name.

@tls.{peer,my}.{subj,issuer}.locality

Certificate subject/issuer locality.

@tls.{peer,my}.{subj,issuer}.country

Certificate subject/issuer country name.

@tls.{peer,my}.{subj,issuer}.state

Certificate subject/issuer state code.

@tls.{peer,my}.{subj,issuer}.organization

Certificate subject/issuer organization name.

@tls.{peer,my}.{subj,issuer}.unit

Certificate subject/issuer organizational unit.

SSL Certificate Authentication

The functions can be used to implement SSL certificate based authentication in the configuration script:

if (proto == TLS && @tls.peer != "Bob") {
     sl_reply("403", "Forbidden");
     break;
}

This will reject any request received through TLS unless the client provides a client certificate which has subject common name set to "Bob".

Select @tls is useful for storing information about the TLS connection (the string can be stored in accounting table, for example, appended to the outgoing message as a header, and so on). Multi-domain configuration

The original (experimental) code contained the support for multi-domain configuration. This mechanism was extended a little bit in the tls module. In addition to server based TLS domains there is also preliminary support for TLS client domains. TLS client domains are used when SER attempts to connect to a remote party using TLS. This makes it possible to configure different TLS client certificates for different destinations.

In addition to that almost all TLS parameters can be now set on per-domain basis. This includes: - Certificate file - Private key file - Enable/disable certificate verification - Certificate verification depth - CA file - Request/do not request certificate from peer - Cipher list - TLS method

TLS domains are identified using IP and port, this is the destination IP and port of the TLS connections, in server TLS domains this must be one of the IP and port configured through listen directives. In TLS client domains this is the IP and port of the remote peer.

There is always one default server domain and one default client domain. These are used when no matching server/client domain can be found for IP/port pair.

TLS domains are configured through modparams, most tls modparams accept the parameter value with the following syntax: <ip>:<port>=<value.

If no IP and port has been specified then the parameters of the default domain are set:

modparam("tls", "method", "1.2.3.4:5090=SSLv23")
modparam("tls", "verify_certificate", "1")
modparam("tls", "require_certificate", "0")
modparam("tls", "private_key", "/usr/local/etc/seri/alice_prik.key")
modparam("tls", "private_key", "1.2.3.4:5090=key.pem")
modparam("tls", "ca_list", "/usr/local/etc/ser/rootca.cert.pem")
modparam("tls", "certificate", "/usr/local/etc/ser/alice_cert.crt")
modparam("tls", "handshake_timeout", 120)
modparam("tls", "send_timeout", 120)
modparam("tls", "tls_log", 2)

This configuration is somewhat suboptimal and may change yet. Currently there is no possibility to configure TLS client domains (it will be added soon). Example configuration

Here is a configuration example which demonstrates a couple of interesting things that can be done with the TLS module, XMLRPC management interface and new serctli tools. This configuration file snippet makes it possible to run serctl remotely. It uses the XMLRPC procotol which is encrypted using TLS. Futhermore TLS certificate authentication is used so only people having a correct client certificate are allowed to execute the kill command (this command will stop ser):

loadmodule "./modules/tls/tls.so"
loadmodule "./modules/sl/sl.so"
loadmodule "./modules/xmlrpc/xmlrpc.so"

listen=tls:1.2.3.4:5061

modparam("tls", "method", "SSLv23")
modparam("tls", "verify_certificate", "1")
modparam("tls", "require_certificate", "0")
modparam("tls", "private_key", "/usr/local/etc/ser/alice_prik.key")
modparam("tls", "ca_list", "/usr/local/etc/ser/rootca.cert.pem")
modparam("tls", "certificate", "/usr/local/etc/ser/alice_cert.crt")

route {
    if (proto == TLS && (method == "POST" || method == "GET")) {
        create_via(); # XMLRPC requests do not contain via, create it

        if (!@tls.peer.verified) {
            # Client did not provide certificate or it is not valid
     xmlrpc_reply("400", "Unauthorized");
     break;
        }

        if (@xmlrpc.method == "core.kill") {
             # Make sure the client has the permission to execute the command
             if (@tls.peer != "SER-Killer") {
          xmlrpc_reply("400", "Access to core.kill denied");
          break;
     }
        }

        dispatch_rpc();
        break;
    }
}