Testing and Debugging TLS Connections (2024)

Test TLS Connections with a Web Browser

Testing TLS connections is sometimes a bit tricky. You have to find aSIP client which supports TLS, and then if there are problems, you oftendo not know if the problem is caused by the SIP client or the SIPserver.

When using Kamailio as SIP proxy it is very easy to test TLS connectionsby using a web browser and configure Kamailio to accept HTTP(S)connections too. Just add the following config snippets to kamailio.cfgand restart Kamailio:

# to allow HTTP requeststcp_accept_no_cl=yes...# load web server moduleloadmodule "xhttp.so"...# xhttp event routeevent_route[xhttp:request] { xhttp_reply("200", "OK", "text/html","<html><body>Received HTTP request to $hu from [$si:$sp] with protocol $proto</body></html>");}

Then point your browser to Kamailio and check if the configurationworks:

Try plain TCP (HTTP) connections: http://ip.address.ofyour.sipproxy:5060/
If TCP works, try TLS (HTTPS) connections: https://ip.address.ofyour.sipproxy:5061/

If the browser complains about invalid certificates, but after acceptingthe invalid certificate you receive the response from Kamailio, then TLSworks technically, but you have problems with the certificate validation(e.g. Kamailio's certificate was not signed by a well known CA and youhave to import the CA into the browser's certificate store).

Test TLS Connections with OpenSSL

This command is useful to connect to the TLS server without anycertificate validation.

Debugging TLS Connections

On the server side you can use the "ssldump" utility to see the TLShandshake, e.g. "ssldump port 5061". This will show you which partycloses the TLS connection (e.g. sends "Alert" message) and maybe alsothe cause (e.g. "unknown CA"). Note: ssldump is quite old and sometimesfails to decode some TLS protocol elements.

For example this is the ssldump trace from a failing handshake betweenKamailio 3.3 and Eyebeam 1.5:

New TCP connection #1: pc177.example.com(51642) <-> sip.example.com(5061)1 1 0.0009 (0.0009) C>S Handshake ClientHello Version 3.1 cipher suites TLS_DHE_RSA_WITH_AES_256_CBC_SHA TLS_RSA_WITH_AES_256_CBC_SHA TLS_DHE_DSS_WITH_AES_256_CBC_SHA compression methods NULL1 2 0.0022 (0.0012) S>C Handshake ServerHello Version 3.1 session_id[0]= cipherSuite TLS_RSA_WITH_AES_256_CBC_SHA compressionMethod NULL1 3 0.0022 (0.0000) S>C Handshake Certificate1 4 0.0022 (0.0000) S>C Handshake ServerHelloDone1 5 0.0038 (0.0016) C>S Alert level fatal value unknown_ca1 0.0044 (0.0005) C>S TCP RST

Above trace clearly shows that the client closes the TLS/TCP connectiondue to "unknown_ca". This usually means that the client is configured toperform certificate validation but the validation failed. Either thesigning CA is unknown to the client, or the intermediate certificatesare missing. After adding the intermediate certificates to Kamailio'sTLS configuration ("ca_list" parameter) Eyebeam accepted the certificateand the correct trace is:

New TCP connection #1: pc177.example.com(51733) <-> sip.example.com(5061)1 1 0.0009 (0.0009) C>S Handshake ClientHello Version 3.1 cipher suites TLS_DHE_RSA_WITH_AES_256_CBC_SHA TLS_RSA_WITH_AES_256_CBC_SHA TLS_DHE_DSS_WITH_AES_256_CBC_SHA compression methods NULL1 2 0.0024 (0.0015) S>C Handshake ServerHello Version 3.1 session_id[0]= cipherSuite TLS_RSA_WITH_AES_256_CBC_SHA compressionMethod NULL1 3 0.0024 (0.0000) S>C Handshake Certificate1 4 0.0024 (0.0000) S>C Handshake ServerHelloDone1 5 0.0118 (0.0093) C>S Handshake ClientKeyExchange1 6 0.0118 (0.0000) C>S ChangeCipherSpec1 7 0.0118 (0.0000) C>S Handshake1 8 0.0311 (0.0193) S>C ChangeCipherSpec1 9 0.0311 (0.0000) S>C Handshake1 10 0.0433 (0.0121) C>S application_data1 11 0.0433 (0.0000) C>S application_data1 12 0.1175 (0.0741) S>C application_data1 13 0.1185 (0.0010) S>C application_data

On the client side it is handy to use Wireshark to capture the SIPStraffic via connections attempts. Then verify the handshake to find outwhich party closes the connection. Wireshark is also handy to inspectthe certificates exchanged in the TLS handshake, e.g. if the server alsoprovided the proper server certificate and intermediate certificates.

Decoding of TLS Connections with Wireshark

Wireshark can be used to decode SSL/TLS sessions. To decode SSL/TLSconnections, the following requirements must be fulfilled:

The private key of the TLS server is known (maybe both keys are needed if mutual TLS (=client certificate) is used?)
The TLS connections does not use a Diffie-Hellman cipher
Wireshark captures the TLS session from the beginning (including the TLS handshake)

To decode TLS connections configure Wireshark and Kamailio:

Copy the server's private key to the PC running Wireshark. Then configure Wireshark to use this key:
Edit → Preferences → Protocols → SSL → RSA Keys List: e.g.: ip.address.of.server,5061,sip,c:\key.pem
If the server uses Diffie-Hellman (DH) Ciphers (depends on default compile time settings of libssl) you have to configure Kamailio to use other ciphers. See:
http://kamailio.org/docs/modules/3.3.x/modules/tls.html#cipher_list and
http://www.openssl.org/docs/apps/ciphers.html
To make sure you capture the TLS handshake
Close the SIP client
Start Wireshark and start capturing
Start the SIP client.

If you have problems decoding the TLS session you should enabledebugging in Wireshark: Edit -> Preferences -> Protocols -> SSL -> SSLDebug File

Unencrypted TLS (NULL cipher)

TLS allows unencrypted usage when using the NULL cipher. This is veryuseful for debugging TLS connection, as you immediately see the SIPtraffic.

The NULL cipher is usually disabled, thus it must be explicitly enabled.In Kamailio this can be done by configuring the TLS module:

modparam("tls", "cipher_list", "NULL")

Of course also the SIP client must be configured to use the NULL cipher.Unfortunately this is hardly supported by SIP clients.

TLS Clients

Following a list of TLS clients and the certificate store they use(please extend):

Eyebeam Windows: Windows certificate store
QjSimple: select CA file in configuration dialog
Internet Explorer: Windows certificate store
Chrome: Windows certificate store
Firefox: Dedicated Firefox certificate store
Asterisk: Configured in sip.conf

SIP Clients with TLS Client Certificate Support

Following a list of SIP clients that support TLS user certificates(needed for incoming TLS connections, of if the TLS server requiresmutual TLS (MTLS))

QjSimple: select private key and certificate file in configuration dialog
Jitis: Settings -> Advanced -> TLS

Trunking with Microsoft Lync

For Microsoft Lync it is very important that the CN in the Kamailioserver (and client) certificate use the name configured in the Topologyas the PSTN trunk. Other names may be in the SubjectAltName fields. Lyncby default asks for a TLS client certificate when connecting to it usingTLS. MS calls this MTLS - Mutual TLS.

Microsoft: TLS and MTLS in Lync http://technet.microsoft.com/en-us/library/gg195752(v=ocs.14).aspx