Troubleshooting Java SSL Connections with SSL Trace Output

How to enable Java SSL/TLS debug logs

1. JVM option (quickest) — start your Java process with:

   Code
   Copy CodeCopied
   -Djavax.net.debug=ssl,handshake,record,trustmanager 

   Common variants:

   • -Djavax.net.debug=all — everything (very verbose).
   • -Djavax.net.debug=ssl — basic SSL/TLS events.
   • -Djavax.net.debug=ssl:handshake:record — handshake plus record-level bytes.
   • Add -Djavax.net.debug=trustmanager to see certificate chain validation.

2. Programmatic enabling — set system property before any SSL classes load:

   java
   Copy CodeCopied
   System.setProperty(“javax.net.debug”, “ssl,handshake,trustmanager”);
   

   Note: must run early (static initializer or before creating SSLSocket/SSLContext).

3. Logging to a file — redirect stdout/stderr or use JVM option:

   Code
   Copy CodeCopied
   java -Djavax.net.debug=all -jar app.jar > ssl-debug.log 2>&1 

What the main log sections mean

• Handshake — shows ClientHello/ServerHello, selected protocol (e.g., TLSv1.3), and cipher suite negotiation. Useful to confirm protocol/cipher mismatch.
• Certificate messages — the server’s certificate chain, subject/issuer, and validation steps (seen with trustmanager). Use this to detect expired, untrusted, or misordered chains.
• Key exchange / Finished — key exchange details (e.g., ECDHE) and Finished messages proving successful handshake.
• Record layer — raw encrypted/decrypted record headers and lengths; helps spot unexpected close_notify or truncated records.
• Alerts — TLS alerts (e.g., handshake_failure, bad_certificate) and their origin (local/remote). Critical for diagnosing failures.
• TrustManager output — detailed verifications, reason for trust failures (path building, certificate expired, name mismatch).

Typical failure patterns and where they show up

• Unsupported protocol/cipher — Handshake shows ClientHello list; server either sends no ServerHello or an alert. Check selected protocol/cipher lines.
• Certificate path validation failure — trustmanager shows exceptions like CertPathValidatorException; look for “PKIX path building failed” or “certificate expired”.
• Hostname mismatch — certificate validated but host name check fails; look for HostnameVerifier/SSLPeerUnverifiedException entries (application-level).
• Incomplete chain (missing intermediate) — server cert chain printed but lacks issuer; trustmanager indicates unable to find valid path.
• Client auth required — server sends CertificateRequest; handshake stalls if client has no certificate.

Quick diagnostic steps when you see a failure

1. Search the log for “alert”, “Exception”, “handshakefailure”, or “CertificateException”.
2. Confirm protocol and cipher: locate ClientHello/ServerHello lines and compare supported lists.
3. Inspect certificate chain printed under Certificate messages: check validity dates, issuer, and whether intermediates are present.
4. If trust errors appear, export server certs and test with keytool:

   Code
    ffON2NH02oMAcqyoh2UU MQCbz04ET5EljRmK3YpQ CPXAhl7VTkj2dHDyAYAf” data-copycode=“true” role=“button” aria-label=“Copy Code”>Copy CodeCopied
   keytool -printcert -sslserver host:port 

5. For hostname issues, verify the certificate’s CN/SAN entries include the target host.