Documentation

Documentation.Tutorials-TLS-2-2 History

Hide minor edits - Show changes to markup

May 10, 2017, at 01:03 PM by ionutionita92 -
Changed line 226 from:

Sharka is a bash script that was put online by Giovanni Maruzzelli that captures TLS traffic using tshark network analyzer. You can find the script in this tutorial or you can download it from our local sources. All you have to do is to set SERVERIP and SERVERADDRESS of the captured interface and the path of the PRIVKEY that will be used in the TLS negotiation. After this you can start the script and will be able to capture TLS packets using only the command line.

to:

Sharka is a bash script shared by Giovanni Maruzzelli that captures TLS traffic using tshark network analyzer. You can find the script in this tutorial or you can download it from our local sources. All you have to do is to set SERVERIP and SERVERADDRESS of the captured interface and the path of the PRIVKEY that will be used in the TLS negotiation. After this you can start the script and will be able to capture TLS packets using only the command line.

May 10, 2017, at 01:03 PM by ionutionita92 -
May 10, 2017, at 01:02 PM by ionutionita92 -
Changed line 226 from:

Sharka is a bash script that was put online by Giovanni Maruzzelli that captures TLS traffic using tshark network analyzer. You can find the script in this tutorial or you can download it from our local . All you have to do is to set SERVERIP and SERVERADDRESS of the captured interface and the path of the private key that will be used in the TLS negotiation. After this you can start the script and will be able to capture TLS packets using only the command line.

to:

Sharka is a bash script that was put online by Giovanni Maruzzelli that captures TLS traffic using tshark network analyzer. You can find the script in this tutorial or you can download it from our local sources. All you have to do is to set SERVERIP and SERVERADDRESS of the captured interface and the path of the PRIVKEY that will be used in the TLS negotiation. After this you can start the script and will be able to capture TLS packets using only the command line.

May 10, 2017, at 12:54 PM by ionutionita92 -
Changed lines 222-226 from:

IMPORTANT: Depending on your configuration, it might be necessary to configure both the private key of the server and the client in Wireshark!!!

to:

IMPORTANT: Depending on your configuration, it might be necessary to configure both the private key of the server and the client in Wireshark!!!

Sharka

Sharka is a bash script that was put online by Giovanni Maruzzelli that captures TLS traffic using tshark network analyzer. You can find the script in this tutorial or you can download it from our local . All you have to do is to set SERVERIP and SERVERADDRESS of the captured interface and the path of the private key that will be used in the TLS negotiation. After this you can start the script and will be able to capture TLS packets using only the command line.

November 10, 2016, at 01:14 PM by ionutionita92 -
Added lines 116-120:

Also, since version 2.2 almost all tls parameters were moved to a new module, tls_mgm, proto_tls handling only connection related jobs.

loadmodule "tls_mgm.so"

Changed lines 128-130 from:

modparam("proto_tls", "verify_cert", "0")
modparam("proto_tls", "require_cert", "0")
modparam("proto_tls", "ciphers_list", "NULL")

to:

modparam("tls_mgm", "verify_cert", "0")
modparam("tls_mgm", "require_cert", "0")
modparam("tls_mgm", "ciphers_list", "NULL")

Changed line 139 from:

modparam("proto_tls", "tls_method", "TLSv1")

to:

modparam("tls_mgm", "tls_method", "TLSv1")

Changed lines 151-154 from:
 modparam("proto_tls", "server_domain", "sv_dom=<your-ip-address>:<port>")           
 modparam("proto_tls", "certificate", "sv_dom:$CERT_DIR/rootCA/cacert.pem")           
 modparam("proto_tls", "private_key", "sv_dom:$CERT_DIR/rootCA/private/cakey.pem")    
 modparam("proto_tls", "ca_list", "sv_dom:$CERT_DIR/rootCA/cacert.pem")                
to:
 modparam("tls_mgm", "server_domain", "sv_dom=<your-ip-address>:<port>")           
 modparam("tls_mgm", "certificate", "sv_dom:$CERT_DIR/rootCA/cacert.pem")           
 modparam("tls_mgm", "private_key", "sv_dom:$CERT_DIR/rootCA/private/cakey.pem")    
 modparam("tls_mgm", "ca_list", "sv_dom:$CERT_DIR/rootCA/cacert.pem")                
Changed lines 157-161 from:
 modparam("proto_tls", "client_domain", "cl_dom=<UAS-ip-address>:<port>")            
 modparam("proto_tls", "certificate", "cl_dom:$CERT_DIR/user/user-cert.pem")          
 modparam("proto_tls", "private_key", "cl_dom:$CERT_DIR/user/user-privkey.pem")       
 modparam("proto_tls", "ca_list", "cl_dom:$CERT_DIR/user/user-calist.pem")             
to:
 modparam("tls_mgm", "client_domain", "cl_dom=<UAS-ip-address>:<port>")            
 modparam("tls_mgm", "certificate", "cl_dom:$CERT_DIR/user/user-cert.pem")          
 modparam("tls_mgm", "private_key", "cl_dom:$CERT_DIR/user/user-privkey.pem")       
 modparam("tls_mgm", "ca_list", "cl_dom:$CERT_DIR/user/user-calist.pem")             
Changed line 173 from:
 #define the listener
to:
 #define the listener(proto_tls)
Changed lines 177-178 from:
 loadmodule “proto_tls.so”
to:
 loadmodule "proto_tls.so"
 loadmodule "tls_mgm.so"
Changed lines 181-185 from:
 modparam("proto_tls", "verify_cert", "0")
 modparam("proto_tls", "require_cert", "0")
 modparam("proto_tls", "ciphers_list", "NULL")
 modparam("proto_tls", "tls_method", "TLSv1")
to:
 modparam("tls_mgm", "verify_cert", "0")
 modparam("tls_mgm", "require_cert", "0")
 modparam("tls_mgm", "ciphers_list", "NULL")
 modparam("tls_mgm", "tls_method", "TLSv1")
Changed lines 187-191 from:
 modparam("proto_tls","server_domain","sv_dom=<your-ip-address>:<port>")
 modparam("proto_tls", "certificate","sv_dom:$CERT_DIR/rootCA/cacert.pem")
 modparam("proto_tls","private_key","sv_dom:$CERT_DIR/rootCA/private/cakey.pem")
 modparam("proto_tls", "ca_list","sv_dom:$CERT_DR/rootCA/cacert.pem")
to:
 modparam("tls_mgm","server_domain","sv_dom=<your-ip-address>:<port>")
 modparam("tls_mgm", "certificate","sv_dom:$CERT_DIR/rootCA/cacert.pem")
 modparam("tls_mgm","private_key","sv_dom:$CERT_DIR/rootCA/private/cakey.pem")
 modparam("tls_mgm", "ca_list","sv_dom:$CERT_DR/rootCA/cacert.pem")
Changed lines 193-196 from:
 modparam("proto_tls", "client_domain", "cl_dom=<UAS-ip-address>:<port>")
 modparam("proto_tls", "certificate", "cl_dom:$CERT_DIR/user/user-cert.pem")
 modparam("proto_tls", "private_key","cl_dom:$CERT_DIR/user/user-privkey.pem")
 modparam("proto_tls", "ca_list","cl_dom:$CERT_DR/user/user-calist.pem")
to:
 modparam("tls_mgm", "client_domain", "cl_dom=<UAS-ip-address>:<port>")
 modparam("tls_mgm", "certificate", "cl_dom:$CERT_DIR/user/user-cert.pem")
 modparam("tls_mgm", "private_key","cl_dom:$CERT_DIR/user/user-privkey.pem")
 modparam("tls_mgm", "ca_list","cl_dom:$CERT_DR/user/user-calist.pem")
November 10, 2016, at 01:04 PM by ionutionita92 -
Changed line 113 from:

loadmodule “proto_tls.so”

to:

loadmodule "proto_tls.so"

Changed lines 123-125 from:

modparam(“proto_tls”, “verify_cert”, “0”)
modparam(“proto_tls”, “require_cert”, “0”)
modparam(“proto_tls”, “ciphers_list”, “NULL”)

to:

modparam("proto_tls", "verify_cert", "0")
modparam("proto_tls", "require_cert", "0")
modparam("proto_tls", "ciphers_list", "NULL")

Changed line 134 from:

modparam(“proto_tls”, “tls_method”, “TLSv1”)

to:

modparam("proto_tls", "tls_method", "TLSv1")

Changed lines 146-149 from:
 modparam(“proto_tls”, “server_domain”, “sv_dom=<your-ip-address>:<port>”)           
 modparam(“proto_tls”, “certificate”, “sv_dom:$CERT_DIR/rootCA/cacert.pem”)           
 modparam(“proto_tls”, “private_key”, “sv_dom:$CERT_DIR/rootCA/private/cakey.pem”)    
 modparam(“proto_tls”, “ca_list”, “sv_dom:$CERT_DIR/rootCA/cacert.pem”)                
to:
 modparam("proto_tls", "server_domain", "sv_dom=<your-ip-address>:<port>")           
 modparam("proto_tls", "certificate", "sv_dom:$CERT_DIR/rootCA/cacert.pem")           
 modparam("proto_tls", "private_key", "sv_dom:$CERT_DIR/rootCA/private/cakey.pem")    
 modparam("proto_tls", "ca_list", "sv_dom:$CERT_DIR/rootCA/cacert.pem")                
Changed lines 152-156 from:
 modparam(“proto_tls”, “client_domain”, “cl_dom=<UAS-ip-address>:<port>”)            
 modparam(“proto_tls”, “certificate”, “cl_dom:$CERT_DIR/user/user-cert.pem”)          
 modparam(“proto_tls”, “private_key”, “cl_dom:$CERT_DIR/user/user-privkey.pem”)       
 modparam(“proto_tls”, “ca_list”, “cl_dom:$CERT_DIR/user/user-calist.pem”)             
to:
 modparam("proto_tls", "client_domain", "cl_dom=<UAS-ip-address>:<port>")            
 modparam("proto_tls", "certificate", "cl_dom:$CERT_DIR/user/user-cert.pem")          
 modparam("proto_tls", "private_key", "cl_dom:$CERT_DIR/user/user-privkey.pem")       
 modparam("proto_tls", "ca_list", "cl_dom:$CERT_DIR/user/user-calist.pem")             
Changed lines 175-179 from:
 modparam(“proto_tls”, “verify_cert”, “0”)
 modparam(“proto_tls”, “require_cert”, “0”)
 modparam(“proto_tls”, “ciphers_list”, “NULL”)
 modparam(“proto_tls”, “tls_method”, “TLSv1”)
to:
 modparam("proto_tls", "verify_cert", "0")
 modparam("proto_tls", "require_cert", "0")
 modparam("proto_tls", "ciphers_list", "NULL")
 modparam("proto_tls", "tls_method", "TLSv1")
Changed lines 181-185 from:
 modparam(“proto_tls”,“server_domain”,“sv_dom=<your-ip-address>:<port>”)
 modparam(“proto_tls”, “certificate”,“sv_dom:$CERT_DIR/rootCA/cacert.pem”)
 modparam(“proto_tls”,“private_key”,“sv_dom:$CERT_DIR/rootCA/private/cakey.pem”)
 modparam(“proto_tls”, “ca_list”,“sv_dom:$CERT_DR/rootCA/cacert.pem”)
to:
 modparam("proto_tls","server_domain","sv_dom=<your-ip-address>:<port>")
 modparam("proto_tls", "certificate","sv_dom:$CERT_DIR/rootCA/cacert.pem")
 modparam("proto_tls","private_key","sv_dom:$CERT_DIR/rootCA/private/cakey.pem")
 modparam("proto_tls", "ca_list","sv_dom:$CERT_DR/rootCA/cacert.pem")
Changed lines 187-190 from:
 modparam(“proto_tls”, “client_domain”, “cl_dom=<UAS-ip-address>:<port>”)
 modparam(“proto_tls”, “certificate”, “cl_dom:$CERT_DIR/user/user-cert.pem”)
 modparam(“proto_tls”,“private_key”,“cl_dom:$CERT_DIR/user/user-privkey.pem”)
 modparam(“proto_tls”, “ca_list”,“cl_dom:$CERT_DR/user/user-calist.pem”)
to:
 modparam("proto_tls", "client_domain", "cl_dom=<UAS-ip-address>:<port>")
 modparam("proto_tls", "certificate", "cl_dom:$CERT_DIR/user/user-cert.pem")
 modparam("proto_tls", "private_key","cl_dom:$CERT_DIR/user/user-privkey.pem")
 modparam("proto_tls", "ca_list","cl_dom:$CERT_DR/user/user-calist.pem")
November 10, 2016, at 12:29 PM by pbaines -
Changed line 181 from:
 modparam(“proto_tls”,“server_doamain”,“sv_dom=<your-ip-address>:<port>”)
to:
 modparam(“proto_tls”,“server_domain”,“sv_dom=<your-ip-address>:<port>”)
Changed line 187 from:
 modparam(“proto_tls”, “client_doamain”, “cl_dom=<UAS-ip-address>:<port>”)
to:
 modparam(“proto_tls”, “client_domain”, “cl_dom=<UAS-ip-address>:<port>”)
March 17, 2015, at 02:46 PM by ionutionita92 -
Changed lines 142-143 from:

As specified in section 3.1 Overview, our scenario includes two TLS connections, one from the UAC to OpenSIPS and the second one from OpenSIPS to the UAS. Whereas in the first connection OpenSIPS will be the server side of the connection, in the second one it will be the client side so it is obvious that we need to define two different TLS domains.

to:

As specified in section 3.1 Overview, our scenario includes two TLS connections, one from the UAC to OpenSIPS and the second one from OpenSIPS to the UAS. Whereas in the first connection OpenSIPS will be the server side of the connection, in the second one it will be the client side so we need to define two different TLS domains.

Changed line 214 from:

Wireshark allows us to catch the TLS handshake and also to decrypt the traffic, but in order to do this we must do some configuration in Wireshark first. Go to Edit → Preferences → Protocols → SSL. Click the Edit button in RSA keys list section. Click the New button and add the ip address and port on which OpenSIPS is listening, the protocol (in our case sip) and in the Key File section search for the private key OpenSIPS uses for the connection ( for the example above $CERT_DIR/rootCA/private/cakey.pem). Save the configuration and then you can see both the TLS handshakes and the TCP messages that are being sent to and from OpenSIPS listening interface.

to:

Wireshark allows us to catch the TLS handshake and also to decrypt the traffic, but in order to do this we must configure it to know the private keys of the connection. Go to Edit → Preferences → Protocols → SSL. Click the Edit button in RSA keys list section. Click the New button and add the ip address and port on which OpenSIPS is listening, the protocol (in our case sip) and in the Key File section search for the private key OpenSIPS uses for the connection ( for the example above $CERT_DIR/rootCA/private/cakey.pem). Save the configuration and then you can see both the TLS handshakes and the TCP messages that are being sent to and from OpenSIPS listening interface.

March 17, 2015, at 02:43 PM by ionutionita92 -
Changed line 199 from:

Now that we’ve set up OpenSIPS and started it, we need to do some debugging and see if everything works fine. There will be presented two ways to debug your TLS connection. First just verifying the TLS handshake with openSSL s_client and after this a more complex type of debugging which is teaching Wireshark to decrypt messages using the private key of the connection.

to:

Now that we’ve set up OpenSIPS and started it, we need to do some debugging and see if everything works fine. There will be presented two ways to debug your TLS connection. First just verifying the TLS handshake with openSSL s_client and after this a more complex type of debugging which is teaching Wireshark to decrypt messages using the private key of the connection.

Changed lines 210-211 from:

The ip address and the port are the ones you have set earlier in the listen section of the script. If you want more advanced debugging, check the following section which tells you how to debug the tls connection using Wireshark.

to:

The ip address and the port are the ones you have set earlier in the listen section of the script. If you want more advanced debugging, check the following section which tells you how to debug the tls connection using Wireshark.

Changed line 214 from:

Wireshark allows us to catch the TLS handshake and also to decrypt the traffic, but in order to do this we must do some configuration in Wireshark first. Go to Edit → Preferences → Protocols → SSL. Click the Edit button in RSA keys list section. Click the New button and add the ip address and port on which OpenSIPS is listening, the protocol (in our case sip) and in the Key File section search for the private key OpenSIPS uses for the connection ( for the example above $CERT_DIR/rootCA/private/cakey.pem). Save the configuration and then you can see both the TLS handshakes and the TCP messages that are being sent to and from OpenSIPS listening interface.

to:

Wireshark allows us to catch the TLS handshake and also to decrypt the traffic, but in order to do this we must do some configuration in Wireshark first. Go to Edit → Preferences → Protocols → SSL. Click the Edit button in RSA keys list section. Click the New button and add the ip address and port on which OpenSIPS is listening, the protocol (in our case sip) and in the Key File section search for the private key OpenSIPS uses for the connection ( for the example above $CERT_DIR/rootCA/private/cakey.pem). Save the configuration and then you can see both the TLS handshakes and the TCP messages that are being sent to and from OpenSIPS listening interface.

March 17, 2015, at 02:42 PM by ionutionita92 -
Changed lines 15-16 from:

In this chapter we will configure a new CA and a user certificate signed by the CA. Also, you can always create your own CA or set of certificates using the scripts provided by openSSL or by other means. Since creating the certificates can take time, we will do this using OpenSIPS in only a few minutes.

to:

Before configuring OpenSIPS we need to have a CA and be able to sign certificates with this CA. In order to do this, we will configure a new CA and a user certificate signed by this CA. We will use OpenSIPS to achieve these goals, since it offers a very simple way to manage certificate related issues using opensipsctl script. Also, you can always create your own CA or set of certificates using the scripts provided by openSSL or by other means.

Changed line 199 from:

Now that we’ve set up OpenSIPS and started it, we need to start the debugging and see if everything works fine. There will be presented two ways by debugging your TLS connection. First just verifying the TLS handshake with openSSL s_client and after a more complex type of debugging which is teaching Wireshark to decrypt messages using the private key of the connection.

to:

Now that we’ve set up OpenSIPS and started it, we need to do some debugging and see if everything works fine. There will be presented two ways to debug your TLS connection. First just verifying the TLS handshake with openSSL s_client and after this a more complex type of debugging which is teaching Wireshark to decrypt messages using the private key of the connection.

Changed lines 214-216 from:

Wireshark allows us to catch the TLS handshake and also to decrypt the traffic, but in order to do this we must do some configuration in Wireshark first. Go to Edit → Preferences → Protocols → SSL. Click the Edit button in RSA keys list section. Click the New button and add the ip address and port on which OpenSIPS is listening, the protocol (in our case sip) and in the Key File section search for the private key OpenSIPS uses for the connection ( for the example above $CERT_DIR/rootCA/private/cakey.pem). Save the configuration and then you can see both the TLS handshakes and the TCP messages that are being sent to and from OpenSIPS listening interface.

to:

Wireshark allows us to catch the TLS handshake and also to decrypt the traffic, but in order to do this we must do some configuration in Wireshark first. Go to Edit → Preferences → Protocols → SSL. Click the Edit button in RSA keys list section. Click the New button and add the ip address and port on which OpenSIPS is listening, the protocol (in our case sip) and in the Key File section search for the private key OpenSIPS uses for the connection ( for the example above $CERT_DIR/rootCA/private/cakey.pem). Save the configuration and then you can see both the TLS handshakes and the TCP messages that are being sent to and from OpenSIPS listening interface.
IMPORTANT: Depending on your configuration, it might be necessary to configure both the private key of the server and the client in Wireshark!!!

March 17, 2015, at 02:24 PM by ionutionita92 -
Changed line 162 from:

IMPORTANT: The ip address and port from the server domain must be the ones you set in the “listen” script line for OpenSIPS to match that domain. When OpenSIPS acts as client, the ip address and port must be the ones of the server (remote peer), with which initiates the TLS handshake.

to:

IMPORTANT: The ip address and port from the server domain must be the ones you set in the “listen” script line for OpenSIPS to match that domain. When OpenSIPS acts as client, the ip address and port must be the ones of the server (remote peer) with whom initiates the TLS handshake.

March 17, 2015, at 02:23 PM by ionutionita92 -
Changed line 87 from:

As you probably discovered, in OpenSIPS 2.2 the tls became a module, so now, every parameter we want to pass to TLS will be a modparam parameter. The scenario is very simple, UAC is trying to send an invite to an UAS by using OpenSIPS as a proxy, and both connections UAC<->OpenSIPS and OpenSIPS<->UAS are using encrypted data transfer, using TLS. So we will try to provide a basic TLS script configuration which tries to use basically all the configurable parameters of the TLS module, from which you can start building your own.

to:

As you probably discovered, in OpenSIPS 2.2 the tls became a module, so now, every parameter we want to pass to TLS will be a modparam parameter. The scenario is very simple, UAC is trying to send an invite to an UAS by using OpenSIPS as a proxy, and both connections UAC<->OpenSIPS and OpenSIPS<->UAS are using encrypted data transfer, using TLS. So we will try to provide a basic TLS script configuration which tries to use basically all the configurable parameters of the TLS module, from which you can start building your own.

March 17, 2015, at 02:22 PM by ionutionita92 -
Changed line 81 from:

is 'opensips'.

to:

is opensips.

March 17, 2015, at 02:22 PM by ionutionita92 -
Changed lines 10-12 from:

Configuring TLS can sometimes be time consuming, most times because of badly generated or used certificates. What this tutorial is trying to do is providing a basic TLS configuration for OpenSIPS which we know for sure that will work and be the entry point for future, more complicated, TLS setups. At first we will be trying to do the most important thing of all: generating some certificates which we can use to later configure OpenSIPS. . If all you want to do is testing the TLS, you can always skip to section 2.4 Using OpenSIPS built-in certificates. The next step will be writing a script for OpenSIPS which will use TLS. After starting OpenSIPS, what we must do is testing that OpenSIPS works fine listening for TLS connections from UACs and creating new connections with UACs and debugging the handshake.

to:

Configuring TLS can sometimes be time consuming, most times because of badly generated or used certificates. What this tutorial is trying to do is providing a basic TLS configuration for OpenSIPS which we know for sure that will work and be the entry point for future, more complicated, TLS setups. At first we will be trying to do the most important thing of all: generating some certificates which we can use to later configure OpenSIPS. If all you want to do is testing the TLS, you can always skip to section 2.4 Using OpenSIPS built-in certificates. The next step will be writing a script for OpenSIPS which will use TLS. After starting OpenSIPS, what we must do is testing that OpenSIPS works fine listening for TLS connections from UACs and creating new connections with UACs and debugging the handshake.

Changed lines 80-81 from:

If all you want to do is testing, you can always use the certificates located in $OPENSIPS_HOME/etc/tls, but we strongly recommend to you not to use this certificates in real case scenarios, because, as you can imagine, everyone has access to them.

to:

If all you want to do is testing, you can always use the certificates located in $OPENSIPS_HOME/etc/tls, but we strongly recommend to you not to use this certificates in real case scenarios, because, as you can imagine, everyone has access to them. Also notice that the passphrase with which the CA is configured is 'opensips'.

March 17, 2015, at 02:19 PM by ionutionita92 -
Changed line 203 from:

> openssl s_client -showcerts -debug -connect <your-ip-address>:<port> -no_ssl2 -bugs

to:
 openssl s_client -showcerts -debug -connect <your-ip-address>:<port> -no_ssl2 -bugs
March 16, 2015, at 08:36 PM by ionutionita92 -
Changed lines 10-12 from:

Configuring TLS can sometimes be time consuming, most times because of badly generated or used certificates. What this tutorial is trying to do is providing a basic TLS configuration for openSips which we know for sure that will work and be the entry point for future, more complicated, TLS setups. At first we will be trying to do the most important thing of all: generating some certificates which we can use to later configure openSips. The next step will be writing a script for openSips which will use TLS. After starting openSips, what we must do is testing that openSips works fine listening for TLS connections from UACs and creating new connections with UACs and debugging the handshake.

to:

Configuring TLS can sometimes be time consuming, most times because of badly generated or used certificates. What this tutorial is trying to do is providing a basic TLS configuration for OpenSIPS which we know for sure that will work and be the entry point for future, more complicated, TLS setups. At first we will be trying to do the most important thing of all: generating some certificates which we can use to later configure OpenSIPS. . If all you want to do is testing the TLS, you can always skip to section 2.4 Using OpenSIPS built-in certificates. The next step will be writing a script for OpenSIPS which will use TLS. After starting OpenSIPS, what we must do is testing that OpenSIPS works fine listening for TLS connections from UACs and creating new connections with UACs and debugging the handshake.

Changed lines 15-16 from:

During this chapter we will try to configure a new CA and a user certificate signed by the CA. If all you want to do is testing the TLS, you can always skip to section 2.4 Using openSips built-in certificates. Also, you can always create your own CA or set of certificates using the scripts provided by openSSL or by other means.

to:

In this chapter we will configure a new CA and a user certificate signed by the CA. Also, you can always create your own CA or set of certificates using the scripts provided by openSSL or by other means. Since creating the certificates can take time, we will do this using OpenSIPS in only a few minutes.

Changed line 19 from:

First thing we need to do is setup the context for our certificates to be created. Let’s say that you want to use $OPENSIPS_HOME/tls_cnf ($OPENSIPS_HOME represents the path to your openSips install).

to:

First thing we need to do is setup the context for our certificates to be created. Let’s say that you want to use $OPENSIPS_HOME/tls_cnf ($OPENSIPS_HOME represents the path to your OpenSIPS install).

Changed lines 22-23 from:

> cd $OPENSIPS_HOME
> mkdir tls_cnf; cd tls_cnf; mkdir tls

to:

cd $OPENSIPS_HOME
mkdir tls_cnf; cd tls_cnf; mkdir tls

Changed line 30 from:

Next we need to generate our certificating authority, but first we need a configuration file for this, because based on this configuration file, openSips will know the details of your request. In this configuration file you can set the paths where the CA will be generated, validity, DN etc. For users who did this before, it looks similar to “openssl.cnf” file. You can find an example in $OPENSIPS_HOME/etc/tls/ca.conf. In this tutorial we only want to make it work, so we will use that file by copying it to our tls_cnf/tls folder.

to:

Next we need to generate our certificating authority, but first we need a configuration file for this, because based on this configuration file, OpenSIPS will know the details of your request. In this configuration file you can set the paths where the CA will be generated, validity, DN etc. For users who did this before, it looks similar to “openssl.cnf” file. You can find an example in $OPENSIPS_HOME/etc/tls/ca.conf. In this tutorial we only want to make it work, so we will use that file by copying it to our tls_cnf/tls folder.

Changed line 32 from:

> cp $OPENSIPS_HOME/etc/tls/ca.conf $OPENSIPS_HOME/tls_cnf/tls/

to:

cp $OPENSIPS_HOME/etc/tls/ca.conf $OPENSIPS_HOME/tls_cnf/tls/

Changed line 39 from:

Now that we set up the context, we can create the CA. Go to your $OPENSIPS_HOME/scripts folder.

to:

Now that we set up the context, we can create the CA. Go to your $OPENSIPS_HOME/scripts folder.

Changed line 41 from:

> cd $OPENSIPS_HOME/scripts

to:

cd $OPENSIPS_HOME/scripts

Changed line 46 from:

Here you should be able to find the “opensipsctl” script. Use the following command:

to:

Here you should be able to find the opensipsctl script. Use the following command:

Changed line 48 from:

> ./opensipsctl tls rootCA $OPENSIPS_HOME/tls_cnf/tls

to:

./opensipsctl tls rootCA $OPENSIPS_HOME/tls_cnf/tls

Changed lines 57-58 from:

To create a user certificate you will need to create request.conf and <user_name>.conf file in order to use opensipsctl. In this tutorial we will simply use the files provided by opensips in $OPENSIPS_HOME/etc/tls called request.conf and user.conf.

to:

To create a user certificate you will need to create request.conf and <user_name>.conf file in order to use opensipsctl. In this tutorial we will simply use the files provided by OpenSIPS in $OPENSIPS_HOME/etc/tls called request.conf and user.conf.

Changed lines 60-61 from:

> cp $OPENSIPS_HOME/etc/tls/request.conf $OPENSIPS_HOME/tls_cnf/tls/
> cp $OPENSIPS_HOME/etc/tls/user.conf $OPENSIPS_HOME/tls_cnf/tls/

to:

cp $OPENSIPS_HOME/etc/tls/request.conf $OPENSIPS_HOME/tls_cnf/tls/
cp $OPENSIPS_HOME/etc/tls/user.conf $OPENSIPS_HOME/tls_cnf/tls/

Changed line 70 from:

> cd $OPENSIPS_HOME/scripts

to:

cd $OPENSIPS_HOME/scripts

Changed lines 77-79 from:

The third parameter’s meaning is the name of the user which must be the same as the <user_name>.conf file. So, for example, if we wanted the user alice, the file must have had the name alice.conf . The fourth parameter represents the path where you have the configuration files. Now, that we have created the certificates we can move to the following section, a script example to use TLS with openSips.

Using openSips built-in certificates

to:

The third parameter’s meaning is the name of the user which must be the same as the <user_name>.conf file. So, for example, if we wanted the user alice, the file must have had the name alice.conf . The fourth parameter represents the path where you have the configuration files. Now, that we have created the certificates we can move to the following section, a script example to use TLS with OpenSIPS.

Using OpenSIPS built-in certificates

Changed lines 86-87 from:

As you probably discovered, in openSips 2.2 the tls became a module, so now, every parameter we want to pass to TLS will be a ‘modparam’ parameter. The scenario is very simple, sipp UAC is trying to send an invite to an UAS by using openSips as a proxy, and both connections UAC<->openSips and openSips<->UAS are using encrypted data transfer, using TLS.

to:

As you probably discovered, in OpenSIPS 2.2 the tls became a module, so now, every parameter we want to pass to TLS will be a modparam parameter. The scenario is very simple, UAC is trying to send an invite to an UAS by using OpenSIPS as a proxy, and both connections UAC<->OpenSIPS and OpenSIPS<->UAS are using encrypted data transfer, using TLS. So we will try to provide a basic TLS script configuration which tries to use basically all the configurable parameters of the TLS module, from which you can start building your own.

Changed line 89 from:

In order to accept TLS connections, openSips must have a TLS listener. In order to do this we have to include the following line in our script:

to:

In order to accept TLS connections, OpenSIPS must have a TLS listener. In order to do this we have to include the following line in our script:

Changed line 97 from:

When openSips will start, you should be able to see the listener by entering the following command in your command line

to:

When OpenSIPS will start, you should be able to see the listener by entering the following command in your command line

Changed line 99 from:
 # netstat -tlp | grep <port>
to:

netstat -tlp | grep <port>

Changed lines 119-120 from:

set parameters to enable certificate checking or ciphers. As openSips enables these checkings by default because a real TLS configuration must check the certificates, we will need to disable them.

to:

set parameters to enable certificate checking or ciphers. As OpenSIPS enables these checkings by default because a real TLS configuration must check the certificates, we will need to disable them.

Changed lines 141-142 from:

As specified in section 3.1 Overview, our scenario includes two TLS connections, one from the UAC to openSips and the second one from openSips to the UAS. Whereas in the first connection openSips will be the server side of the connection, in the second one it will be the client side so it is obvious that we need to define two different TLS domains.

to:

As specified in section 3.1 Overview, our scenario includes two TLS connections, one from the UAC to OpenSIPS and the second one from OpenSIPS to the UAS. Whereas in the first connection OpenSIPS will be the server side of the connection, in the second one it will be the client side so it is obvious that we need to define two different TLS domains.

Changed lines 161-162 from:

IMPORTANT: The ip address and port from the server domain must be the ones you set in the “listen” script line for openSips to match that domain. When openSips acts as client, the ip address and port must be the ones of the server with which initiates the TLS handshake.

to:

IMPORTANT: The ip address and port from the server domain must be the ones you set in the “listen” script line for OpenSIPS to match that domain. When OpenSIPS acts as client, the ip address and port must be the ones of the server (remote peer), with which initiates the TLS handshake.

Changed lines 196-198 from:

S_client simple testing

Now that we’ve set up openSips and started it, we need to start the debugging and see if everything works fine. A very simple and fast method to see that the handshake works fine is the s_client tool that openSSL provides. The command for the script in the previous chapter looks like this

to:

Troubleshooting

Overview

Now that we’ve set up OpenSIPS and started it, we need to start the debugging and see if everything works fine. There will be presented two ways by debugging your TLS connection. First just verifying the TLS handshake with openSSL s_client and after a more complex type of debugging which is teaching Wireshark to decrypt messages using the private key of the connection.

S_client simple testing

A very simple and fast method to see that the handshake works fine is the s_client tool that openSSL provides. The command for the script in the previous chapter looks like this

Changed lines 211-214 from:

Wireshark tracing

Wireshark allows us to catch the TLS handshake and also to decrypt the traffic, but in order to do this we must do some configuration in Wireshark first. Go to Edit → Preferences → Protocols → SSL. Click the Edit button in RSA keys list section. Click the New button and add the ip address and port on which openSips is listening, the protocol (in our case sip) and in the Key File section search for the private key openSips uses for the connection ( for the example above $CERT_DIR/rootCA/private/cakey.pem). Save the configuration and then you can see both the TLS handshakes and the TCP messages that are being sent to and from openSips listening interface.

to:

Wireshark tracing

Wireshark allows us to catch the TLS handshake and also to decrypt the traffic, but in order to do this we must do some configuration in Wireshark first. Go to Edit → Preferences → Protocols → SSL. Click the Edit button in RSA keys list section. Click the New button and add the ip address and port on which OpenSIPS is listening, the protocol (in our case sip) and in the Key File section search for the private key OpenSIPS uses for the connection ( for the example above $CERT_DIR/rootCA/private/cakey.pem). Save the configuration and then you can see both the TLS handshakes and the TCP messages that are being sent to and from OpenSIPS listening interface.

March 16, 2015, at 07:26 PM by ionutionita92 -
Changed line 86 from:

s you probably discovered, in openSips 2.2 the tls became a module, so now, every parameter we want to pass to TLS will be a ‘modparam’ parameter. The scenario is very simple, sipp UAC is trying to send an invite to an UAS by using openSips as a proxy, and both connections UAC<->openSips and openSips<->UAS are using encrypted data transfer, using TLS.

to:

As you probably discovered, in openSips 2.2 the tls became a module, so now, every parameter we want to pass to TLS will be a ‘modparam’ parameter. The scenario is very simple, sipp UAC is trying to send an invite to an UAS by using openSips as a proxy, and both connections UAC<->openSips and openSips<->UAS are using encrypted data transfer, using TLS.

March 16, 2015, at 07:25 PM by ionutionita92 -
Changed line 161 from:

IMPORTANT: The ip address and port from the server domain must be the ones you set in the “listen” script line for openSips to match that domain. When openSips acts as client, the ip address and port must be the ones of the server with which it initiates the TLS handshake.

to:

IMPORTANT: The ip address and port from the server domain must be the ones you set in the “listen” script line for openSips to match that domain. When openSips acts as client, the ip address and port must be the ones of the server with which initiates the TLS handshake.

March 16, 2015, at 07:24 PM by ionutionita92 -
Changed line 145 from:
 modparam(“proto_tls”, “server_doamain”, “sv_dom=<your-ip-address>:<port>”)           
to:
 modparam(“proto_tls”, “server_domain”, “sv_dom=<your-ip-address>:<port>”)           
Changed line 151 from:
 modparam(“proto_tls”, “client_doamain”, “cl_dom=<UAS-ip-address>:<port>”)            
to:
 modparam(“proto_tls”, “client_domain”, “cl_dom=<UAS-ip-address>:<port>”)            
March 16, 2015, at 07:14 PM by ionutionita92 -
Changed lines 15-16 from:

During this chapter we will try to configure a new CA and a user certificate signed by the CA. If all you want to do is testing the TLS, you can always skip to section 2.4 Using openSips built-in certificates. Also, you can always create your own CA or set of certificates using the scripts provided by openSSL or by other means.

to:

During this chapter we will try to configure a new CA and a user certificate signed by the CA. If all you want to do is testing the TLS, you can always skip to section 2.4 Using openSips built-in certificates. Also, you can always create your own CA or set of certificates using the scripts provided by openSSL or by other means.

Changed line 99 from:
  1. netstat -tlp | grep <port>
to:
 # netstat -tlp | grep <port>
Changed lines 141-211 from:

As specified in section 3.1 Overview, our scenario includes two TLS connections, one from the UAC to openSips and the second one from openSips to the UAS. Whereas in the first connection openSips will be the server side of the connection, in the second one it will be the client side so it is obvious that we need to define two different TLS domains.

to:

As specified in section 3.1 Overview, our scenario includes two TLS connections, one from the UAC to openSips and the second one from openSips to the UAS. Whereas in the first connection openSips will be the server side of the connection, in the second one it will be the client side so it is obvious that we need to define two different TLS domains.

 #first the  server domain
 modparam(“proto_tls”, “server_doamain”, “sv_dom=<your-ip-address>:<port>”)           
 modparam(“proto_tls”, “certificate”, “sv_dom:$CERT_DIR/rootCA/cacert.pem”)           
 modparam(“proto_tls”, “private_key”, “sv_dom:$CERT_DIR/rootCA/private/cakey.pem”)    
 modparam(“proto_tls”, “ca_list”, “sv_dom:$CERT_DIR/rootCA/cacert.pem”)                

 #and the client domain                                                               
 modparam(“proto_tls”, “client_doamain”, “cl_dom=<UAS-ip-address>:<port>”)            
 modparam(“proto_tls”, “certificate”, “cl_dom:$CERT_DIR/user/user-cert.pem”)          
 modparam(“proto_tls”, “private_key”, “cl_dom:$CERT_DIR/user/user-privkey.pem”)       
 modparam(“proto_tls”, “ca_list”, “cl_dom:$CERT_DIR/user/user-calist.pem”)             



IMPORTANT: The ip address and port from the server domain must be the ones you set in the “listen” script line for openSips to match that domain. When openSips acts as client, the ip address and port must be the ones of the server with which it initiates the TLS handshake.

Full script example

Now that we specified all we need to set in order to be able to use TLS both as a server and as a client we will specify here a full script (only the TLS part) in order to make things more clear. Basically it is all we explained in the previous sections of this chapter put together.

 #define the listener
 listen = tls:<your-ip-address>:<port>

 #set module path
 loadmodule “proto_tls.so”

 #set global tls parameters
 modparam(“proto_tls”, “verify_cert”, “0”)
 modparam(“proto_tls”, “require_cert”, “0”)
 modparam(“proto_tls”, “ciphers_list”, “NULL”)
 modparam(“proto_tls”, “tls_method”, “TLSv1”)

 #server domain
 modparam(“proto_tls”,“server_doamain”,“sv_dom=<your-ip-address>:<port>”)
 modparam(“proto_tls”, “certificate”,“sv_dom:$CERT_DIR/rootCA/cacert.pem”)
 modparam(“proto_tls”,“private_key”,“sv_dom:$CERT_DIR/rootCA/private/cakey.pem”)
 modparam(“proto_tls”, “ca_list”,“sv_dom:$CERT_DR/rootCA/cacert.pem”)

 #client domain
 modparam(“proto_tls”, “client_doamain”, “cl_dom=<UAS-ip-address>:<port>”)
 modparam(“proto_tls”, “certificate”, “cl_dom:$CERT_DIR/user/user-cert.pem”)
 modparam(“proto_tls”,“private_key”,“cl_dom:$CERT_DIR/user/user-privkey.pem”)
 modparam(“proto_tls”, “ca_list”,“cl_dom:$CERT_DR/user/user-calist.pem”)



S_client simple testing

Now that we’ve set up openSips and started it, we need to start the debugging and see if everything works fine. A very simple and fast method to see that the handshake works fine is the s_client tool that openSSL provides. The command for the script in the previous chapter looks like this

> openssl s_client -showcerts -debug -connect <your-ip-address>:<port> -no_ssl2 -bugs



The ip address and the port are the ones you have set earlier in the listen section of the script. If you want more advanced debugging, check the following section which tells you how to debug the tls connection using Wireshark.

Wireshark tracing

Wireshark allows us to catch the TLS handshake and also to decrypt the traffic, but in order to do this we must do some configuration in Wireshark first. Go to Edit → Preferences → Protocols → SSL. Click the Edit button in RSA keys list section. Click the New button and add the ip address and port on which openSips is listening, the protocol (in our case sip) and in the Key File section search for the private key openSips uses for the connection ( for the example above $CERT_DIR/rootCA/private/cakey.pem). Save the configuration and then you can see both the TLS handshakes and the TCP messages that are being sent to and from openSips listening interface.

March 16, 2015, at 07:01 PM by ionutionita92 -
Added lines 1-141:
Documentation -> Tutorials -> TLS

TLS

written by Ionut-Razvan Ionita

(:toc Table of Content:)

Introduction

Configuring TLS can sometimes be time consuming, most times because of badly generated or used certificates. What this tutorial is trying to do is providing a basic TLS configuration for openSips which we know for sure that will work and be the entry point for future, more complicated, TLS setups. At first we will be trying to do the most important thing of all: generating some certificates which we can use to later configure openSips. The next step will be writing a script for openSips which will use TLS. After starting openSips, what we must do is testing that openSips works fine listening for TLS connections from UACs and creating new connections with UACs and debugging the handshake.

Generating certificates

Overview

During this chapter we will try to configure a new CA and a user certificate signed by the CA. If all you want to do is testing the TLS, you can always skip to section 2.4 Using openSips built-in certificates. Also, you can always create your own CA or set of certificates using the scripts provided by openSSL or by other means.

Creating the CA

Creating context

First thing we need to do is setup the context for our certificates to be created. Let’s say that you want to use $OPENSIPS_HOME/tls_cnf ($OPENSIPS_HOME represents the path to your openSips install). Create this folder (if it doesn’t exist) and inside create a folder named tls. Will explain later why we needed to do this.

> cd $OPENSIPS_HOME
> mkdir tls_cnf; cd tls_cnf; mkdir tls



Setting up ca.conf file

Next we need to generate our certificating authority, but first we need a configuration file for this, because based on this configuration file, openSips will know the details of your request. In this configuration file you can set the paths where the CA will be generated, validity, DN etc. For users who did this before, it looks similar to “openssl.cnf” file. You can find an example in $OPENSIPS_HOME/etc/tls/ca.conf. In this tutorial we only want to make it work, so we will use that file by copying it to our tls_cnf/tls folder.

> cp $OPENSIPS_HOME/etc/tls/ca.conf $OPENSIPS_HOME/tls_cnf/tls/



Creating the CA

Now that we set up the context, we can create the CA. Go to your $OPENSIPS_HOME/scripts folder.

> cd $OPENSIPS_HOME/scripts



Here you should be able to find the “opensipsctl” script. Use the following command:

> ./opensipsctl tls rootCA $OPENSIPS_HOME/tls_cnf/tls



The rootCA parameter specifies to the script that you want to create a new certificating authority (the parameter cannot be changed). The last parameter specifies the folder where we want this CA to be installed, so we will chose the folder we set up earlier.

After giving the command you will be requested to introduce a passphrase. We will use this passphrase later when we will create the certificates. The server certificate will consist of the certificate found in the new rootCA folder created $OPENSIPS_HOME/tls_cnf/tls/rootCA/cacert.pem, and the private key will be in $OPENSIPS_HOME/tls_cnf/tls/rootCA/private/cakey.pem.

Creating server and client certificates

To create a user certificate you will need to create request.conf and <user_name>.conf file in order to use opensipsctl. In this tutorial we will simply use the files provided by opensips in $OPENSIPS_HOME/etc/tls called request.conf and user.conf.

> cp $OPENSIPS_HOME/etc/tls/request.conf $OPENSIPS_HOME/tls_cnf/tls/
> cp $OPENSIPS_HOME/etc/tls/user.conf $OPENSIPS_HOME/tls_cnf/tls/



Next we have to go again to $OPENSIPS_HOME/scripts and use opensipsctl.

> cd $OPENSIPS_HOME/scripts
./opensipsctl tls userCERT user $OPENSIPS_HOME/tls_cnf/tls



The third parameter’s meaning is the name of the user which must be the same as the <user_name>.conf file. So, for example, if we wanted the user alice, the file must have had the name alice.conf . The fourth parameter represents the path where you have the configuration files. Now, that we have created the certificates we can move to the following section, a script example to use TLS with openSips.

Using openSips built-in certificates

If all you want to do is testing, you can always use the certificates located in $OPENSIPS_HOME/etc/tls, but we strongly recommend to you not to use this certificates in real case scenarios, because, as you can imagine, everyone has access to them.
IMPORTANT: in the following sections we will refer to the folder where the certificates are located as $CERT_DIR, so none of the paths presented above are valid anymore, but we will keep the notations rootCA as the folder where the CA is installed and user where the user certificates are.

Script example

Overview

s you probably discovered, in openSips 2.2 the tls became a module, so now, every parameter we want to pass to TLS will be a ‘modparam’ parameter. The scenario is very simple, sipp UAC is trying to send an invite to an UAS by using openSips as a proxy, and both connections UAC<->openSips and openSips<->UAS are using encrypted data transfer, using TLS.

The listener

In order to accept TLS connections, openSips must have a TLS listener. In order to do this we have to include the following line in our script:

listen=tls:<your-ip-address>:<port>



When openSips will start, you should be able to see the listener by entering the following command in your command line

  1. netstat -tlp | grep <port>



where port is the port you gave to listen line in your script.

Including TLS module and setting the parameters

Since TLS became a module, now we need to insert the following line in the modules section

loadmodule “proto_tls.so”



Since this is a test scenario, we only want to check that the TLS handshake works fine, so we won’t set parameters to enable certificate checking or ciphers. As openSips enables these checkings by default because a real TLS configuration must check the certificates, we will need to disable them.

modparam(“proto_tls”, “verify_cert”, “0”)
modparam(“proto_tls”, “require_cert”, “0”)
modparam(“proto_tls”, “ciphers_list”, “NULL”)



We will need to specify the TLS method which will specify what type of protocol we will use. In this tutorial we will use “TLSv1”, but you can always use another one, see the full list in the module’s documentation section.

modparam(“proto_tls”, “tls_method”, “TLSv1”)



Setting up TLS domains

As specified in section 3.1 Overview, our scenario includes two TLS connections, one from the UAC to openSips and the second one from openSips to the UAS. Whereas in the first connection openSips will be the server side of the connection, in the second one it will be the client side so it is obvious that we need to define two different TLS domains.


Page last modified on May 10, 2017, at 01:03 PM