Troubleshooting TLS/SSL

Note:
This documentation has moved to a new home! Please update your bookmarks to the new URL for the up-to-date version of this page.

Debugging TLS/SSL connections and protocols can be daunting due to their complexity. Here are some troubleshooting tips.

Separate the client and server

Whenever testing TLS/SSL connections over the network, it’s best to really separate the client and the server. Remember that the crypto library configuration file is read by the library, not just by a server or a client. It’s read by both. Therefore having separate systems acting as clients and servers, with their own configuration files, makes things simpler to analyse.

Tools

Here are some tools to help troubleshooting a TLS/SSL configuration.

OpenSSL server and client apps

The OpenSSL server and client tools are very handy to quickly bring up a server with a selection of ciphers and protocols and test it with a client. Being part of OpenSSL, these tools will also initialise the library defaults directly from the OpenSSL config file, so they are very useful to test your configuration changes.

To bring up an OpenSSL server, a certificate with a private key is needed. There are many ways to generate a pair, and here is a quick one:

$ openssl req -new -x509 -nodes -days 30 -out myserver.pem -keyout myserver.key

Answer the questions as you prefer, but the one that needs special attention is the commonName (CN) one, which should match the hostname of this server. Then bring up the OpenSSL server with this command:

$ openssl s_server -cert myserver.pem -key myserver.key

That will bring up a TLS/SSL server on port 4433. Extra options that can be useful:

  • -port N: Set a port number. Remember that ports below 1024 require root privileges, so use sudo if that’s the case.
  • -www: Will send back a summary of the connection information, like ciphers used, protocols, etc.
  • -tls1_2, -tls1_3, -no_tls1_3, -no_tls1_2: Enable only the mentioned protocol version, or, with the no_ prefix variant, disable it.
  • -cipher <string>: Use the specified cipher string for TLS1.2 and lower.
  • -ciphersuite <string>: Use the specified string for TLS1.3 ciphers.

The client connection tool can be used like this when connecting to server:

$ echo | openssl s_client -connect server:port 2>&1 | grep ^New

That will generally show the TLS version used, and the selected cipher:

$ echo | openssl s_client -connect j-server.lxd:443 2>&1  | grep ^New
New, TLSv1.3, Cipher is TLS_AES_256_GCM_SHA384

The ciphers and protocols can also be selected with the same command line options as the server:

$ echo | openssl s_client -connect j-server.lxd:443 -no_tls1_3 2>&1  | grep ^New
New, TLSv1.2, Cipher is ECDHE-RSA-AES256-GCM-SHA384

$ echo | openssl s_client -connect j-server.lxd:443 -no_tls1_3 2>&1 -cipher DEFAULT:-AES256 | grep ^New
New, TLSv1.2, Cipher is ECDHE-RSA-CHACHA20-POLY1305

The sslscan tool

The sslscan tool comes from a package with the same name, and it will scan a server and list the supported algorithms and protocols. It’s super useful for determining if your configuration has really disabled or enabled a particular cipher or TLS version.

To use the tool, point it at the server you want to scan:

$ sslscan j-server.lxd

And you will get a report of the ciphers and algorithms supported by that server. Consult its manpage for more details.

References

This page was last modified 3 months ago. Help improve this document in the forum.