Goal (short description)

Communication between the User Agent and the home proxy is encrypted using TLS.

Applicability

We enable end-users of domain A to communicate with their home proxy based onTLS:

User Agent A — TLS — > proxy domainA

Prerequisites

Linux machine
SER version 2.0rc or higher. Se also SER 2rc1
Server certificate and private key in PEM fomrat
CA list - list of trusted authorities in PEM format
TLS enabled client - i.e. EyeBeam or new CMC

If you use binary package, see if it supports TLS. command ser -V should show something like

ser -V
version: ser 2.0.0-rc1 (i386/linux)
flags: STATS: Off, USE_IPV6, USE_TCP, USE_TLS ......

and tls module (tls.so) has to located in module directory (depends on distribution and package i.e. /usr/local/lib/ser/modules)
Otherwise you have to recompile SER from source. Download daily snaphot from iptel.org or from CVS.
Ser 2rc daily snaphost
Ser 2.0 cvs branch

export CVSROOT=:pserver:anonymous@cvs.berlios.de:/cvsroot/ser
cvs co -r rel_2_0_0 sip_router

Ser head cvs branch

export CVSROOT=:pserver:anonymous@cvs.berlios.de:/cvsroot/ser
cvs co sip_router

Compiling of source

Make everything

make group_include="standard" include_modules="tls" all

Install it (and make before)

make group_include="standard" include_modules="tls" install

You can adjust compiled modules by group_include, include_modules and exclude_modules parameters.
Print-modules parameter show set of modules that will compiled.

make group_include="standard" include_modules="tls" print-modules

Configuration

Edit your ser.cfg

Enable TLS

Enable TLS and define the address and port where TLS will be listening

# ----------- global configuration parameters ------------------------
enable_tls=yes
listen=tls:1.2.3.4:5061

Load the module

# ------------------ module loading ----------------------------------
loadmodule "/usr/local/lib/ser/modules/tls.so"

Set the parameters

# ----------------- setting module-specific parameters ---------------
modparam("tls", "private_key", "/etc/certs/key.pem")
modparam("tls", "certificate", "/etc/certs/cert.pem")
modparam("tls", "ca_list", "/etc/certs/ca_list.pem")

modparam("tls", "require_certificate", 0)
modparam("tls", "verify_certificate", 1)

modparam("tls", "tls_method", "TLSv1")
#modparam("tls", "tls_method", "SSLv23")

modparam("tls", "tls_log", 2)
modparam("tls", "handshake_timeout", 10)
modparam("tls", "send_timeout", 10)

If tls_log is separate control for TLS logging, If it is set to lower value then debug value tls logs are printed.

Verification

modparam("tls", "require_certificate", 0)
modparam("tls", "verify_certificate", 1)

Ser acting as TLS server sends his certificate everytime.

Require=0 and Verify=0 is the weakest settings which provides just an encrypted tunnel (if cipher is not NULL)
Require=0 and Verify=1 - if TLS client provides a certificate, it is verified. This setting allows your sip client without certificate to talk to SER. SER with this setting acting as TLS client send his certificate (Mutual authentication is possible). Lots of information including verification status is written into @tls select. See iptel.org tls module page.
By mean of the @tls select you can i.e. authenticate clients with client certificate. To make in larger scale you need mapping between CN and ser UID.
@tls.peer.verified is very useful in conjuction with Require=0 and Verify=1 setting. This way you check if the client presented his certificate and it was verified.

Require=1 and Verify=1 is the strongest setting that forces to provide client certificate. If it is not presented, connection fails.

SSL vs TLS

modparam("tls", "tls_method", "TLSv1")
#modparam("tls", "tls_method", "SSLv23")

TLSv1 is RFC3261 compliant setting but SSLv23 is better for extended compatibility. If you are sure that you neighbors are set to TLSv1 use TLSv1. TLSv1 client can make connection to SSLv23 server but SSLv23 cannot talk to TLSv1 server. Dont' forget that a new TLS connecetion from opposite site can be established during the call.

Eyebeam is TLSv1 Capable but i.e. Linksys SPA 942 need SSLv23.

Sample config

Sample config without registrion authentication and with tls routing to domainB (not necessary for enabling TLS for clients)

# ----------- global configuration parameters ------------------------

debug=3         # debug level (cmd line: -dddddddddd)
#memdbg=10 # memory debug message level
#memlog=10 # memory statistics log level
log_facility=LOG_LOCAL0 # sets the facility used for logging (see syslog(3))

/* Uncomment these lines to enter debugging mode
fork=no
log_stderror=yes
*/

check_via=no    # (cmd. line: -v)
dns=no          # (cmd. line: -r)
rev_dns=no      # (cmd. line: -R)
#port=5060
children=2
#user=ser
#group=ser
#disable_core=yes #disables core dumping
#open_fd_limit=1024 # sets the open file descriptors limit
#mhomed=yes  # usefull for multihomed hosts, small performance penalty
#disable_tcp=yes
#tcp_accept_aliases=yes # accepts the tcp alias via option (see NEWS)

enable_tls=yes

alias=domainA

listen=tcp:1.2.3.4:5060
listen=udp:1.2.3.4:5060
listen=tls:1.2.3.4:5061

# ------------------ module loading ----------------------------------

loadmodule "/usr/local/lib/ser/modules/sl.so"
loadmodule "/usr/local/lib/ser/modules/tm.so"
loadmodule "/usr/local/lib/ser/modules/rr.so"
loadmodule "/usr/local/lib/ser/modules/textops.so"
loadmodule "/usr/local/lib/ser/modules/maxfwd.so"
loadmodule "/usr/local/lib/ser/modules/usrloc.so"
loadmodule "/usr/local/lib/ser/modules/registrar.so"
loadmodule "/usr/local/lib/ser/modules/ctl.so"
loadmodule "/usr/local/lib/ser/modules/tls.so"
loadmodule "/usr/local/lib/ser/modules/xlog.so"

# ----------------- setting module-specific parameters ---------------

# -- usrloc params --
# use memory
modparam("usrloc", "db_mode",   0)

# -- rr params --
# add value to ;lr param to make some broken UAs happy
modparam("rr", "enable_full_lr", 1)

# ctl params
# by default ctl listens on unixs:/tmp/ser_ctl if no other address is
# specified in modparams; this is also the default for sercmd
modparam("ctl", "binrpc", "unixs:/tmp/ser_ctl")
# listen on the "standard" fifo for backward compatibility
modparam("ctl", "fifo", "fifo:/tmp/ser_fifo")
# listen on tcp, localhost
#modparam("ctl", "binrpc", "tcp:localhost:2046")


modparam("tls", "private_key", "/etc/certs/key.pem")
modparam("tls", "ca_list", "/etc/certs/ca_list.pem")
modparam("tls", "certificate", "/etc/certs/cert.pem")
modparam("tls", "tls_log", 2)
modparam("tls", "handshake_timeout", 10)
modparam("tls", "send_timeout", 10)

modparam("tls", "require_certificate", 0)
modparam("tls", "verify_certificate", 1)
modparam("tls", "tls_method", "TLSv1")
#modparam("tls", "tls_method", "SSLv23")


# -------------------------  request routing logic -------------------

# main routing logic

route{

	# initial sanity checks -- messages with
	# max_forwards==0, or excessively long requests
	if (!mf_process_maxfwd_header("10")) {
		sl_reply("483","Too Many Hops");
		break;
	}
	if (msg:len >=  max_len ) {
		sl_reply("1024", "Message too big");
		break;
	}


	if (proto==TLS) {
	    xlog("L_INFO","TLS Method: %rm RURI: %ru, TLSmy : %@tls.my.subject TLSpeer : %@tls.peer.subject %@tls.peer.issuer verified: %@tls.peer.verified  \n  ");

	}

	if (!method=="REGISTER") record_route();

	# subsequent messages withing a dialog should take the
	# path determined by record-routing
	if (loose_route()) {
		# mark routing logic in request
		append_hf("P-hint: rr-enforced\r\n");
		route(FORWARD);
		break;
	}

	if (!uri==myself) {
		# mark routing logic in request
		append_hf("P-hint: outbound\r\n");

                # route domainB over TLS
		if (uri=~".*@domainB") {

			if (t_relay_to_tls("sip.domainB","5061")) {
				xlog("L_INFO","TLS DomainB Method: %rm RURI: \n  ");
			}
			else {sl_reply_error();}
    			break;
		}
		route(FORWARD);
		break;
	}

	# if the request is for other domain use UsrLoc
	# (in case, it does not work, use the following command
	# with proper names and addresses in it)
	if (uri==myself) {

		if (method=="REGISTER") {
			save_contacts("location");
			break;
		}

		# native SIP destinations are handled using our USRLOC DB
		if (!lookup_contacts("location")) {
			sl_reply("404", "Not Found");
			break;
		}
		append_hf("P-hint: usrloc applied\r\n");

	}
	route(FORWARD);
}

route[FORWARD]
{
	# send it out now; use stateful forwarding as it works reliably
	# even for UDP2TCP
	}
	if (!t_relay()) {
	    sl_reply_error();
	}
}

OS specific help

Validation, confirmation tests

Configure a UA to use TLS. Under MS Windows, good examples is Eyebeam 1.5. Make sure to choose 'TLS' as the protocol in the settings and register with the proxy. Use the diagnostic tools of the UA to see if any problems occur. Common problems are:

Invalid TLS version: though TLS 1.0 should be used according to the SIP RFC, SSL 2/3
certificate verification. CA list often doesn't include the necessary certs.
Common name of the server certificate does not match DNS name of the server

Child pages

3.5.1. TLS for SER (UA-Proxy)