How to debug TLS handshake with cURL

The TLS handshake establishes secure communication by exchanging certificates, negotiating ciphers, and confirming trust. Failures often arise from misconfigurations, outdated protocols, or incompatible cipher suites.

cURL provides verbose and trace options to reveal handshake details, pinpointing exactly where the secure connection fails. Examining these diagnostics accelerates troubleshooting and clarifies configuration issues.

By analyzing TLS debug output, administrators can rectify problems, ensure proper encryption, and maintain stable, secure connections that uphold modern security standards.

1. Open a terminal.
2. Use --verbose for initial TLS negotiation details.

   $ curl "https://www.example.com" --verbose

   Check lines indicating SSL/TLS protocol versions and cipher suites.

3. Enable more detailed tracing with --trace-time and --trace-ascii.

   $ curl "https://www.example.com" --trace-time --trace-ascii debug.txt

   Review debug.txt for a step-by-step handshake trace.

4. Combine with --insecure if inspecting self-signed or expired certificates.

   $ curl --insecure --verbose "https://www.example.com"

   Observe handshake behavior even with invalid certificates.

5. Adjust cipher or protocol settings and repeat tests to isolate the issue.

   Modifying parameters helps pinpoint the root cause of handshake failures.