SSL Handshake Debugger

Usage

$ ssl-handshake-debugger -h
Usage: ssl-handshake-debugger [-ahv] [-c=<ciphers>] [-f=<fileName>] [-ks=<keystore>] [-ksp=<keystorePassword>] [--openAIApiKey=<openAIApiKey>] [-p=<port>] [-pr=<protocols>] [-s=<server>] [-ts=<truststore>] [-tsp=<truststorePassword>]
                              [-u=<url>] <mode>

Description:

Command line application that tests SSL/TLS handshake as client or server and prints the javax.net.debug output.
*     <mode>                mode to run, client or server

Parameters:
  -s, -server=<server>                            ip or host to bind or call
  -u, -url=<url>                                  url to be called
  -p, --port=<port>                               port to listen or be hit, default value is 443
  -c, --ciphers=<ciphers>                         enabled cipher suites(e.g TLS_DHE_RSA_WITH_AES_256_GCM_SHA384, TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384)
  -f, --file=<fileName>                           filename to write the handshake output
  -pr, --protocols=<protocols>                    jvm ssl/tls enabled protocols list(e.g. TLSv1.2, TLSv1.3)
  -ts, --truststore=<truststore>                  truststore path
  -tsp, --truststorePassword=<truststorePassword> truststore password
  -ks, --keystore=<keystore>                      keystore path
  -ksp, --keystorePassword=<keystorePassword>     keystorePassword
  --openAIApiKey=<openAIApiKey>                   OpenAI API Key (ChatGPT)
  -a, --all                                       use javax.net.debug=all instead of javax.net.debug=ssl:handshake:verbose
  -v, --version                                   display version info
  -h, --help                                      display this help message

Installation

Use the following command to get the ssl-handshake-debugger installed on your machine:

sh <(curl -s https://raw.githubusercontent.com/gabrielpadilh4/ssl-handshake-debugger/main/install.sh)

It will download and extract the binaries of ssl-handshake-debugger command on $HOME/ssl-handshake-debugger and add it to the $PATH variable by changing the .bashrc file.

Usage Examples

These examples showcase various scenarios for using the SSL handshake debugger CLI, it demonstrates how to set server or client modes, define server details, enable debugging, specify protocols, cipher suites, keystore, and truststore paths, and direct output to a file. Adjust these commands according to your specific needs and configurations.

Running as Server

ssl-handshake-debugger -s localhost -p 443 -pr TLSv1.2 -c TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 server

-s localhost: Specifies the server as 'localhost'.

-p 443: Sets the port to '443'.

-pr TLSv1.2: Defines the enabled SSL/TLS protocols to 'TLSv1.2'.

-c TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384: Specifies the enabled cipher suite

Running as Client

Calling a server and port:

ssl-handshake-debugger -s example.com -p 443 client

-s localhost: Specifies the server as 'localhost'.

-p 443: Sets the port to '443'.

Calling an URL:

ssl-handshake-debugger -u https://example.com

-u https://example.com: Specifies the url to be called.

Enabling Debugging for All SSL Operations

ssl-handshake-debugger -s example.com -p 443 -a client

-a: Sets the debugging mode to 'all' for all SSL operations.

Specifying Keystore and Truststore

ssl-handshake-debugger -s example.com -p 443 -ks /path/to/keystore -ksp password -ts /path/to/truststore -tsp password client

-ks /path/to/keystore: Sets the path to the keystore.

-ksp password: Specifies the keystore password.

-ts /path/to/truststore: Sets the path to the truststore.

-tsp password: Specifies the truststore password.

Writing Output to a File

ssl-handshake-debugger -s example.com -p 443 -f output.txt client

-f output.txt: Writes the handshake output to a file named 'output.txt'.

Using ChatGPT OpenAPI

First you need to create an API Key on OpenAPI, save it and run the following command:

ssl-handshake-debugger client -s self-signed.badssl.com -p 443 --openAIApiKey=YOUR_API_KEY

The result should be:

The error message "PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target" typically occurs when the Java application is unable to establish a secure connection with a remote server due to an invalid or missing SSL certificate.

To fix this issue, you can follow these steps:

1. Identify the certificate authority (CA) that issued the SSL certificate for the remote server.
2. Obtain the root and intermediate certificates from the CA.
3. Import the root and intermediate certificates into the Java keystore.

Here is a step-by-step guide:

1. Identify the certificate authority (CA):

   • Check the SSL certificate details in your web browser when accessing the remote server. Look for the "Issued by" or "Certificate Authority" information.
   • Contact the server administrator or the CA to obtain the necessary certificates.

2. Obtain the root and intermediate certificates:

   • Visit the CA's website and search for their root and intermediate certificates.
   • Download the certificates in PEM or DER format.

3. Import the root and intermediate certificates into the Java keystore:

   • Open a command prompt or terminal.
   • Locate the Java installation directory and navigate to the "bin" folder.
   • Run the following command to import the root certificate:

     keytool -import -alias root -keystore <path_to_java_home>/jre/lib/security/cacerts -file <path_to_root_certificate>
     

     Replace <path_to_java_home> with the actual path to your Java installation directory, and <path_to_root_certificate> with the path to the downloaded root certificate file.
   • When prompted for the keystore password, enter the default password: "changeit".
   • Confirm the import by typing "yes" when prompted.
   • Repeat the above steps for each intermediate certificate, using a unique alias for each.

4. Restart your Java application and try connecting to the remote server again. The error should no longer occur.

Note: It's important to ensure that the root and intermediate certificates are obtained from a trusted source and are not tampered with.

About

Command line application built in Java that tests SSL/TLS handshake as client or server and prints the javax.net.debug output.

Output as client:

See here

Output as server:

See here

Building from Source

To build from source, refer to the building and working with the code base guide.

Contributing

Before contributing to ssl-handshake-debugger, please read our contributing guidelines.

License

• Apache License, Version 2.0