Please note that republishing this article in full or in part is only allowed under the conditions described here.

SSL/TLS - Typical problems and how to debug them

This guide tries to help with debugging of SSL/TLS problems and shows the most common problems in interaction between client and server. It is not intended to help with writing applications and thus does not care about specific API's etc. But it should help with problems outside of a specific API, like different or broken SSL stacks or misconfigurations.

The guide is based on the knowledge gained as the maintainer of the IO::Socket::SSL Perl module or by debugging SSL problems at work or for fun.

Unfortunatly SSL/TLS is a hard to debug protocol because:


Basic information

Useful/required knowledge

While SSL/TLS is a complex protocol there a some basics one should understand in order to debug and fix most problems:

Common misunderstandings about SSL/TLS

Security relevant errors which don't cause obvious problems

These kind of problems are not obvious, because everything seems to work fine. But they open ways for attacks and thus need to be fixed. Unfortunatly, often these kind of problems are caused by an attempt to fix another problem and by not understanding the security implications of the applied workaround.

Start with debugging

Useful tools for debugging

Often an error message alone is not sufficient to solve the problem. In this case the following tools can be of help:

The usual steps in debugging

The steps shown here are useful to solve the problem. Even if one can not solve the problem by oneself by using these steps it is recommended to do as much of them as possible and provide the collected information to anybody willing to help. Chances are much higher that they will then look into the problem.

If still not resolved: provide anybody willing to help with the collected information and also with debug information and a packet capture in a form usable by wireshark. Also provide information about the used SSL stacks (i.e. browser or application version, programming language version, OS version).

WARNING: while you might disable verification or downgrade ciphers or protocol to insecure versions to track down the problem do not simply leave it this way once you've "fixed" the problem this way. Instead track down the cause of the problem and fix it, especially:

How to check for common problems

Commonly seen and more unusual problems

Common problems caused by SSL stacks at server, client or middlebox

Common problems caused by misconfiguration

Problems due to bad certificates

Bad certificates are a very common error. The most common problems are:

In these cases either the certificate need to be fixed or the application must import the certificate as trusted or use certificate/public key pinning.

Less common errors are:

Problems caused by inconsistent handling of root certificates

Each SSL stack has its own way to handle the trust anchors (the root certificates). Even different applications using the same stack often do not share the same root certificates:

More unusal but existing problems

Finding and fixing the problem

Problem solving by error message or symptom

When it worked before, works with other applications, servers ...

It still does not work