What is ColorNet SSL Poke Plus Utility?
SSL Poke Plus is a utility to test SSL connections and view SSL certificates. It was inspired by the somewhat ubiquitious SSL Poke Java program circulating around the Internet, which is used to quickly and easily determine whether the Java Runtime Environment (JRE) on a particular computer can connect to a particular server with SSL. The Plus used here comes from adding a number of enhancements -- viewing and interpreting X509 certificates, forcing connections, downloading pages, etc. -- that go beyond just determining if a conneciton can be made.
What can ColorNet SSL Poke Plus Do?
o Test establishing an SSL connection to one or more SSL servers
o View the full contents of each certificate provided by an SSL server
o View a summary of each certificate provided by an SSL server (easy reading)
o Retrieve a page from an SSL server
o Force a connection for viewing certificate(s) when the certificate(s) are not valid
o Output in text, XML or JSON (for automating within an application)
What are the Requirements?
The ColorNet SSL Poke Plus utility requires Java 8+.
What About Self-Signed Certificates?
Java uses its own certificate database for verification (usually $JAVA_HOME/lib/security/cacerts), which is different than the certificates used by a traditional web browser or operating system. For users and developers of Java applications, this can mean different results between accessibility from a brower and a Java application on the same computer.
In particular, an organization will sometimes use self-signed certificates for internal systems. In these cases, if a Java application requires SSL access to such an internal system, it can be accomodated by adding the self-signed certificate to the Java certificate database (cacerts). SSL Poke Plus can help verify this configuration.
Nonetheless, SSL Poke Plus offers additional features for verifying and viewing certificates that make it useful outside of specifically verifying Java SSL connecivity.
How Do I Run ColorNet SSL Poke Plus?
- Download the SSL Poke Plus utility (either tar or zip)
- Unpack the Archive:
$ tar xvf SSL-1.1.0.tar
or
$ unzip SSL-1.1.0.zip
- Run the SSL Poke Plus utility:
$ cd SSL-1.1.0
$ java -jar SSL-1.1.0-EXE.jar <host[:<port>]> {options}
{options} include:
-connect Attempt to connect to SSL host (default)
-timeout {seconds} Number of seconds to wait for a connection (default 15)
-get Attempt to get a web page after connecting (default '/')
-hosts {file} File containing a list of hosts (as {host}:{port}) to verify
-page Page to get after connecting (overrides '/')
-version Print version number and exit (any other options ignored)
To view X509 certificates:
-info Display X509 certificate information (default full)
-summary Display only certificate summary (name/date/issuer/validity)
-format {type} Certificate summary format (text (default), xml, or json)
-force Force connection to read certificate(s) (even if invalid)
How Can I Use a Hosts File for Automated SSL Checks?
Using the -hosts {file} option permits checking multiple SSL hosts in one request, each host listed on a separate line within the specified {file}. Append a colon (':') and port number to the host name if the SSL port is not the default (443).
SSL Poke Plus will return a non-zero exit code only if SSL failed connecting to one or more of the hosts contained in the file. It is therefore possible to take action only if one or more of the hosts failed, and do nothing if all were successful. For example, using the bash shell:
$ java -jar SSL-1.1.0-EXE.jar -hosts sslhosts.txt > /tmp/sslhosts.log || \
cat /tmp/sslhosts.log | mailx -s "SSL Failures" user@domain.com
or a scheduler (e.g., cron), an e-mail can be sent with a list of which hosts were successful at establishing an SSL connection, and which failed, only if one or more hosts contained in the file have failed.
I Am Using SSL Poke Plus in a Script / What Are the Exit Codes?
Exit codes without a hosts file:
0 - Success
1 - Bad parameter or incompatible parameters specified
2 - Socket Connection Timeout
3 - SSL Handshake Failed
4 - Unexpected Exception (including DNS errors)
5 - Formatting Exception (XML or JSON)
Exit codes with hosts file:
| 0 |
All hosts contained in the hosts file passed SSL verification |
| 1 - 255 |
Specifies the number of hosts that failed SSL verification |
| 256 |
Internal error |
What Is a Certificate Summary?
Because the full output of an X509 certificate can easily contain anywhere from 50 plus to more than a hundered lines of text, as a convenience the SSL Poke Plus utility provides a -info -summary option that only includes: subject, start date, end date, validity flag, and issuer of each X509 certificate.
For example, in text (default) format:
$ java -jar SSL-1.1.0-EXE.jar wsurls.com -info -summary
Subject: CN=wsurls.com
Start Date: Sun Apr 30 15:40:57 EDT 2023
End Date: Sat Jul 29 15:40:56 EDT 2023
Valid: true
Alternative Name: wsurls.com
Issuer: CN=R3, O=Let's Encrypt, C=US
Subject: CN=R3, O=Let's Encrypt, C=US
Start Date: Thu Sep 03 20:00:00 EDT 2020
End Date: Mon Sep 15 12:00:00 EDT 2025
Valid: true
Issuer: CN=ISRG Root X1, O=Internet Security Research Group, C=US
Subject: CN=ISRG Root X1, O=Internet Security Research Group, C=US
Start Date: Wed Jan 20 14:14:03 EST 2021
End Date: Mon Sep 30 14:14:03 EDT 2024
Valid: true
Issuer: CN=DST Root CA X3, O=Digital Signature Trust Co.
For example, in XML (-format xml) format:
$ java -jar SSL-1.1.0-EXE.jar wsurls.com -info -summary -format xml
<X509Certificates>
<X509Certificate>
<Subject>CN=wsurls.com</Subject>
<StartDate>Sun Apr 30 15:40:57 EDT 2023</StartDate>
<EndDate>Sat Jul 29 15:40:56 EDT 2023</EndDate>
<Valid>true</Valid>
<AlternativeNames>
<AlternativeName>wsurls.com</AlternativeName>
</AlternativeNames>
<Issuer>CN=R3, O=Let's Encrypt, C=US</Issuer>
</X509Certificate>
<X509Certificate>
<Subject>CN=R3, O=Let's Encrypt, C=US</Subject>
<StartDate>Thu Sep 03 20:00:00 EDT 2020</StartDate>
<EndDate>Mon Sep 15 12:00:00 EDT 2025</EndDate>
<Valid>true</Valid>
<Issuer>CN=ISRG Root X1, O=Internet Security Research Group, C=US</Issuer>
</X509Certificate>
<X509Certificate>
<Subject>CN=ISRG Root X1, O=Internet Security Research Group, C=US</Subject>
<StartDate>Wed Jan 20 14:14:03 EST 2021</StartDate>
<EndDate>Mon Sep 30 14:14:03 EDT 2024</EndDate>
<Valid>true</Valid>
<Issuer>CN=DST Root CA X3, O=Digital Signature Trust Co.</Issuer>
</X509Certificate>
</X509Certificates>
For example, in JSON (-format json) format:
$ java -jar SSL-1.1.0-EXE.jar wsurls.com -info -summary -format json
{
"X509Certificates": {
"X509Certificate": [
{
"StartDate": "Sun Apr 30 15:40:57 EDT 2023",
"Valid": true,
"AlternativeNames": {
"AlternativeName": "wsurls.com"
},
"Issuer": "CN=R3, O=Let\u0027s Encrypt, C=US",
"EndDate": "Sat Jul 29 15:40:56 EDT 2023",
"Subject": "CN=wsurls.com"
},
{
"StartDate": "Thu Sep 03 20:00:00 EDT 2020",
"Valid": true,
"Issuer": "CN=ISRG Root X1, O=Internet Security Research Group, C=US",
"EndDate": "Mon Sep 15 12:00:00 EDT 2025",
"Subject": "CN=R3, O=Let\u0027s Encrypt, C=US"
},
{
"StartDate": "Wed Jan 20 14:14:03 EST 2021",
"Valid": true,
"Issuer": "CN=DST Root CA X3, O=Digital Signature Trust Co.",
"EndDate": "Mon Sep 30 14:14:03 EDT 2024",
"Subject": "CN=ISRG Root X1, O=Internet Security Research Group, C=US"
}
]
}
}
Still To Do
Nothing currently planned.
