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
- Server certificate and private key in PEM fomrat
- CA list - list of trusted authorities in PEM format
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.
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 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)
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 weaker 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 settings allow you sip clients without certificate to talk to SER. SER with this setting acting as TLS client send his certificate (Mutual authen tication is possible). Status TLS client side verification ids written into select framwork.
SSL vs TLS
modparam("tls", "tls_method", "TLSv1") #modparam("tls", "tls_method", "SSLv23")
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
- Common name of the server certificate does not match DNS name of the server