Using TLS with OpenSIPS: Why do we need it and how is it configured? While support for TLS existed in version 1, the configuration changed significantly in version 2. This article briefly covers the new v2 setup.
The role of TLS in VoIP calls
Today, it is common practice to use encrypted communication over the Internet whenever possible. The most familiar example is https which provides secure, encrypted web browser sessions for things like online banking and e-shopping. The underlying mechanism for this is TLS (Transport Layer Security). The same mechanism is also available for SIP thereby allowing VoIP calls to be set up over a secure communication channel. Remember that TLS only provides protection from packet-sniffing interception by a malicious third party. Generally, it does not make your IP phone system any less vulnerable to toll fraud, password guessing and unauthorised use so don’t be lulled into a false sense of security.
There are obvious commercial reasons for an ITSP to be able to offer this as a premium service or just as an inducement for customers to choose them rather than a rival who cannot offer it. In addition, TLS is likely to work better for mobile SIP clients because it is based on TCP rather than UDP so it is useful to have it as an option to allow support of the widest possible range of User Agent devices. Furthermore, it may be obligatory to use TLS for some applications such as where credit card numbers are being entered over the phone. TLS is also obligatory for some 3rd party interconnections such as the Direct Routing feature in Microsoft Teams (which also requires SRTP media encryption).
It is important to appreciate that SIP over TLS only provides encryption of the call’s setup messages and does not provide encryption of the media streams. If you require the media to be encrypted, then it is necessary to use SRTP rather than RTP. Usually, where media encryption is required, it is also necessary to use TLS for the SIP messages to ensure that important meta-data cannot be intercepted during call setup. Configuration for SRTP is likely to be required on the end-points (FreeSwitch, Asterisk, etc) behind your OpenSIPS proxy, but their configuration is not discussed here. If one of your end points doesn’t support SRTP, it is possible to use a combination of OpenSIPS and RTPEngine to transcode between SRTP and RTP. The scripting for a transcoding OpenSIPS+RTPEngine solution would be very similar to the WebRTC solution described in the Smartvox article here. If you are planning to use RTPEngine for this type of transcoding, please be aware that the arguments to be passed to RTPEngine would change slightly between WebRTC and SRTP as follows: WebRTC arguments “ICE=force RTP/SAVPF” should change to “RTP/SAVP” for SRTP.
ZRTP is another option that may be used for media encryption as long as both end-points support it. Again, it is not discussed in this article.
Configuring OpenSIPS v2.2.x to support TLS communication
If you installed OpenSIPS using a source tarball, it is possible some of the required modules will not have been built. This is because they are treated as “not required” by default. You can check if they are present by looking in the <lib>/opensips/modules directory and looking for files proto_tls.so and tls_mgm.so, where <lib> is likely to be one of /lib or /lib64 or /usr/lib or /usr/lib64. If those files are not present alongside all the other “.so” files, then it will be necessary to rebuild from source, but first go into the make menuconfig forms and select ‘Configure Compile Options’ then ‘Configure Excluded Modules’ then select the two previously excluded modules; save; rebuild.
Looking at the opensips.cfg file, using version 2.2.3, you will need to include a listen statement a bit like this (tip: if using v3.x, replace the word “listen” with “socket”):
listen=tls:10.34.56.78:5061
OpenSIPS can listen on multiple ports and multiple interfaces using various protocols. So it is perfectly acceptable to have more than one listen statement and to have, for example, port 5060 listening for UDP connections alongside port 5061 listening for TLS.
Load the following modules, in addition to the usual ones:
loadmodule "tls_mgm.so" loadmodule "proto_tls.so"
…and configure various parameters in the tls_mgm module using modparam statements, including:
modparam("tls_mgm", "tls_method", "SSLv23") # This option seems to work nicely in most cases
modparam("tls_mgm", "certificate", "/etc/opensips/tls/mycerts/mycertfile.pem") # Path to your server certificate file
modparam("tls_mgm", "private_key", "/etc/opensips/tls/mycerts/mykeyfile.pem") # The path to your key certificate file
modparam("tls_mgm", "ca_list", "/etc/opensips/tls/mycerts/ca-chain.pem") # Path to your certificate authority chain
I was using self-signed certificates (.pem files), having previously set up my own Certificate Authority. If you are trying something similar, make sure you are using SHA256 certificate encryption. Do not use SHA-1 because it is no longer considered secure. The risk here is that you may have created the config file (typically called openssl.cnf) for an older version of openssl, then not updated the cnf file as time moved on. If so, you could be setting the default certificate encryption to SHA-1. I had this problem for a while, but fixed it by editing my openssl.cnf file and changing the following line:
default_md = sha256 (previously it said default_md=md5)
You can, I believe, also set the desired encryption as a command line argument when you run openssl from the command line.
For my test rig, I added a modparam statement to define the “ca_list” parameter. This defines the path to a file containing the CA’s certificate or a certificate chain – again this was a .pem file. You may need this for some commercially issued certs too.
My settings for certificate verification requirements were very easy-going, as follows:
modparam("tls_mgm", "verify_cert", "0") # "1" is more secure and usually works okay
modparam("tls_mgm", "require_cert", "0")
…and because I was using self-signed certificates it was also necessary to disable the stricter certificate checks on the client device too. See later section in this article for details.
There is nothing special you do in the route blocks, but if you are setting up OpenSIPS as a Registrar server, a useful tip is to set the global parameter “tcp_connection_lifetime” to a value that is just larger than the maximum registration expire time you expect to see. Without this, the TLS connection established during registration is likely to be dropped before the next re-register happens. That, in turn, is likely to cause problems with requests sent to a UA behind NAT or behind a firewall (most are) meaning that the UA can make calls but cannot always receive them. There are other issues with the connection lifetime which are discussed in more detail below.
Here’s another small detail to watch out for, especially during testing: When a device has registered via TCP or TLS, the established network-level connection needs to remain active. However, every time you re-start the OpenSIPS service on your server it will break the network connection. This doesn’t happen with UDP. You should therefore try to avoid re-starting the service too many times when testing because it could send you up a blind alley regarding potential bugs and problems that would simply not happen if the service was left running uninterrupted. You will almost certainly need to re-register your UA devices after each re-start of the OpenSIPS service.
Persistence of TCP connections
As mentioned above, a registering device will establish a TCP connection between itself and your server. This is true for TLS too since it is just an encrypted connection over TCP. These connections use up finite server resources, particularly file handles, which means you don’t want stale connections to be left open too long. On the other hand, you do want the active and viable connections to remain open because this allows the server to communicate with the user’s device through their firewall and also because there is a cost (in terms of elapsed time and other server resources such as CPU) every time a new connection has to be made. Selecting the correct value to use for “tcp_connection_lifetime” could potentially leave you wondering how best to balance these two opposing demands.
For registering devices, it makes sense to use a connection lifetime that is just a bit longer than the re-register time. Since you do have quite a lot of control over maximum expire times for registrations this can be used as the basis for a sensible strategy. However, calls from a carrier or any peer server that is authorised purely on the basis of its IP address, might use TCP or TLS without there being any registrations. In this case, it is possible for a call to be initiated with an INVITE request which creates a new TCP connection only for that connection to be dropped when the tcp_connection_lifetime is reached. This is unlikely to break the call immediately, but it can mess up the call tear down transactions – the BYE request. One solution that could be used here is to enable re-INVITEs at intervals less than the tcp_connection_lifetime. The re-INVITE’s could be achieved by enabling SIP Session Timers or, if using OpenSIPS, they can be internally generated by the Dialog module. To do the latter, you must add option “R” or “r” (or both) to the argument passed to the function create_dialog().
A bit about certificates
To enable TLS, you must have a valid server certificate and a private key installed on (or accessible from) your OpenSIPS server. Certificates can be purchased from the likes of Comodo, Digicert, Geotrust, etc. If you are using a rented virtual private server, many of the hosting service providers can supply certificates as an add-on feature. For in-house development and testing, it is possible to generate your own “self-signed” certificates using openssl – a quick Google search will find instructions for doing this. However, in the open source community it is probably fair to say that the most popular solution is LetsEncrypt. Again, you can find details pretty easily just by searching on the web.
[Update: In OpenSIPS v3, the new Command Line Interface includes a TLS module which can be used to create your own Certificate Authority and then generate certificates.]A bit about using LetsEncrypt certificates
One drawback of LetsEncrypt is that the certificates need to be renewed quite often; a task that only makes sense if it is totally automated. Certbot or scripts such as acme.sh can be used to help with issuing, deploying and the all-important renewing of your LetsEncrypt certificates, making the whole process fairly painless provided you are prepared to invest a few hours reading the instructions and wikis, finding out how these things all hang together. Here is a snippet showing the modparam statements I used for one of my test servers using LetsEncrypt certificates managed by certbot:
modparam("tls_mgm", "certificate", "/etc/letsencrypt/live/<domain>/cert.pem")
modparam("tls_mgm", "private_key", "/etc/letsencrypt/live/<domain>/privkey.pem")
modparam("tls_mgm", "ca_list", "/etc/letsencrypt/live/<domain>/fullchain.pem")
The OpenSIPS TLS_MGM module can be configured directly from the modparam statements in the modules section of the script (as shown above) or from entries in a database table. If you configured tls_mgm only using modparam statements, then it is necessary (at least in version 2.x.x of OpenSIPS) to restart the opensips service before any change to the parameters or certificates is seen. This means that, when using LetsEncrypt, you must restart the opensips service after each certificate renewal. Consequently, there is a strong incentive to put the certificate, private key and ca-chain information into the relevant database table rather than using modparam to point to your certificate files, when using LetsEncrypt. The advantage of database-based certificates in v2.x.x is that you can use the tls_reload MI command to instruct OpenSIPS to reload the certificate without any interruption to your service. That said, you will then have the new problem of needing to automatically copy the renewed certificate text into the relevant blob fields in the tls_mgm table and issuing the reload instruction. Furthermore, it is possible that version 3.x.x of OpenSIPS has better solutions for reloading the certificates on a production server – I haven’t investigated that.
Matching the certificate and the server
The certificate you use for TLS is matched to the host server through the ‘subject CN’ value. For this, you can use the IP address of the server or, more usually, its hostname (a fully qualified domain name). When you use the hostname, it is important that OpenSIPS is fully aware of its own hostname, either through the use of the auto_alias option or by explicitly defining that hostname as an alias, including the tls protocol and the port (usually 5061). For example:
alias=tls:mysipserver.mydomain.com:5061
Fine tuning the protocol
Two of the parameters available in the modparam section of the TLS_MGM module can be used to adjust the balance between security and device compatibility.
The first is tls_method. For maximum security on your connections I would set this to “TLSv1_2” because that forces the connection protocol to use the more secure TLS v1.2 protocol. However, for the greatest compatibility range I would set it to “SSLv23”.
The other parameter, not mentioned above, is ciphers_list. This parameter is used to define a list of ciphers in preferred order of use. The list is comma separated. The openssl package comes with a large number of ciphers which can be listed from the Linux command line using the following command:
openssl ciphers 'ALL:eNULL:!LOW:!EXPORT' | sed 's/:/\n/g'
The above command lists all the supported ciphers, one per line. You can pipe the list directly into grep to filter it down to a smaller subset or search for a specific cipher if you know the name.
Here are my suggestions for two different cipher lists. The first uses modern secure ciphers and the second also includes several older, less secure ciphers. Only use one or the other. The advantage of including older ciphers is that some old VoIP phones and devices need them:
# A short list of the better ciphers that we would only expect to be supported on new IP phones
modparam("tls_mgm", "ciphers_list", "AES256-GCM-SHA384,AES256-SHA256,AES256-SHA,CAMELLIA256-SHA")
# A longer list including more of the old and vulnerable ciphers - more compatibility, less security
modparam("tls_mgm", "ciphers_list", "AES256-GCM-SHA384,AES256-SHA256,AES256-SHA,CAMELLIA256-SHA,AES128-SHA,SEED-SHA,CAMELLIA128-SHA,RC4-SHA,DES-CBC3-SHA")
Configuring the client device
There are too many client devices available for it to be possible to describe how they are all configured. However, I can offer some guidance based on a few specific examples and it will almost certainly be applicable to many others. My testing was done using self-signed certificates for the OpenSIPS server. This has the advantage of avoiding fees, but the disadvantage that your client devices will have very little trust for the server certificate. Sometimes, in this situation, you can disable server cert verification on the client app or you can install your own CA certificate on the client either as a generic device default or as an explicit file used by the VoIP app.
Using a Bria softphone, set up the account as usual and then select “Account Advanced” (under the heading Account Extras). Scroll down to the section entitled “Transport and Security” and tap on the SIP Transport setting which opens a set of radio buttons offering UDP, TCP, TLS and Auto. Select TLS. If you are using self-signed rather than commercial certificates on the server, you will almost certainly need to un-tick the option “Verify TLS Cert” which is in the TLS Cert Management section.
I found it more difficult setting up a Zoiper softphone, although the situation was confused because there was a curious lack of persistence on the ‘Disable certificate verification’ option. I recommend that you completely exit the Zoiper app then re-launch it after setting up an account because some settings may change through a restart.
Most of the relevant settings for the Zoiper softphone are found under the Accounts tab on the main “Preferences” form; select the account – or create a new one – and insert the usual settings for Domain, Username and Password on the ‘General’ tab. On the ‘Advanced’ tab of the user account, select “Use TLS transport” from the relevant drop-down and select the “Don’t use” option in the section called “TLS client certificate”.
You’re not done yet. Now click on the cog symbol at the top of the preferences form to get to the global ‘Advanced’ settings and in that select the “Security” tab. I found it necessary to copy the CA certificate (or certificate chain) to my device and then insert the path to this file in the box labelled “Extra CA Certificates (PEM)”. I also set Protocol suite to TLS v1 rather than SSL v2/3 and ticked the box ‘Use only strong ciphers’.
Testing it on an old Snom 360 phone with v7 firmware, the simplest way to make it use TLS was by adding the transport parameter to the end of the registrar address (or you can use the Outbound Proxy box too). I was testing on a LAN and set the Outbound Proxy as follows:
192.168.0.111;transport=tls
Please note that newer Snom phones may have stricter rules for TLS connections and verification of certificates etc.
On the Yealink T21P phone, there is a drop-down selector for “Transport” on the main account form. Set this to TLS. On the same form, set the Server Host port to 5061 or whatever port number you set on the server.
Next, go to the Security tab and select “Trusted Certificates” from the navigation panel on the left. When using self-signed certificates, I always set this as follows:
If you are using commercial server certificates, it should be possible to enable the option to only accept trusted certificates.
On my T21P E2 model, it was also necessary to change a setting under the Security tab in the section “Server Certificates”. Based on the description given on the Yealink data entry form, it doesn’t make a lot of sense. However, purely from trial-and-error I found it necessary to change the drop-down box labelled “Device Certificates” to Custom Certificates as shown below. This was not necessary on an older T26 handset running older firmware.
Very good and useful article.