How to troubleshoot SSL connections with the openssl program

This article describes how to use the openssl program to troubleshoot SSL connections.

About OpenSSL

OpenSSL is an open-source implementation of the SSL and TLS protocols. It includes several code libraries and utility programs, one of which is the command-line openssl program.

The openssl program is a useful tool for troubleshooting secure TCP connections to a remote server. In addition to testing basic connectivity, openssl enables you to send raw protocol commands for additional testing.

Installing the openssl program

Linux and Mac OS X include the openssl program by default. On Microsoft Windows, however, you must download and install openssl. To do this, follow these steps:

1. Use your web browser to visit https://www.openssl.org/community/binaries.html.
2. Click the OpenSSL for Windows hyperlink that includes Pre-compiled Win32/64 libraries without external dependencies.
3. Download the most recent OpenSSL version for your PC architecture:
   • If you have a 32-bit computer, select a file whose name ends in win32.zip. For example, at the time this article is written, the newest version is openssl-1.0.2d-i386-win32.zip.
   • If you have a 64-bit computer, select a file whose name ends in win64.zip. For example, at the time this article is written, the newest version is openssl-1.0.2d-x64_86-win64.zip.
4. Extract the .zip file to a folder (you can use any folder, and you can name the folder anything you want).
5. After you extract the files, the folder contains the openssl.exe file and supporting files.
6. To run openssl, open a command prompt window, use the cd command to change to the folder where you extracted the files in step 5, and then type openssl.

Using the openssl program to troubleshoot

To troubleshoot a secure connection using the openssl program, you must know at least two things:

• The remote server name or IP address.
• The port number for the network application you want to test.

If you are only testing basic connectivity to a particular application, that is all you need. If you want to do more in-depth testing, however, you will need to know specific commands for the protocol you want to test (for example, IMAP or HTTP).

Establishing a connection

To open a connection to a remote server, open a terminal window on your computer, and then type the following command. Replace example.com with the domain name (or IP address) of the server, and replace port with the TCP port number of the protocol you want to test:

openssl s_client -connect example.com:port

When you try to establish a secure connection to a remote server using openssl, one of two things happens:

• The server accepts the connection. If this happens, openssl may display some text from the server, or simply await further input. You can then send raw commands appropriate for the protocol you are testing.
• The server rejects the connection. If this happens, you receive a message such as connect: Connection timed out or connect:errno=110. If you receive this message, confirm you are using the correct server and port number. If you are, then the server is not accepting secure connections on the specified port.

The following sections demonstrate how to do basic troubleshooting with some common types of secure connections.

Troubleshooting SSL certificates

You can use the openssl program to test and verify SSL certificates. For example, you can check whether a certificate is signed by a valid Certificate Authority (CA) or is self-signed. You can also examine the certificate's validity, expiration date, and much more.

To do this, type the following command. Replace example.com with your own domain name:

openssl s_client -connect example.com:443 -servername example.com -showcerts | openssl x509 -text -noout

The following sample output shows some important lines marked in bold:

$ openssl s_client -connect example.com:443 -servername example.com -showcerts | openssl x509 -text -noout
depth=1 C = BE, O = GlobalSign nv-sa, CN = AlphaSSL CA - SHA256 - G2
verify return:0
Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number:
            31:11:4a:f7:c9:0e:fa:ff:9c:de:ad:be:ef:8a:84:1d:66:53
    Signature Algorithm: sha256WithRSAEncryption
        Issuer: C=BE, O=GlobalSign nv-sa, CN=AlphaSSL CA - SHA256 - G2
        Validity
            Not Before: Jun 11 19:26:24 2015 GMT
            Not After : Jun 11 19:26:24 2016 GMT
        Subject: OU=Domain Control Validated, CN=*.example.com

[Output truncated]

In this output, you can see that the certificate is issued by a Certificate Authority (CA) and uses a SHA-256 fingerprint. Additionally, the certificate expires on June 11, 2016.

verify error:num=18:self signed certificate
verify return:1

Troubleshooting HTTP connections

Web server testing is a very common troubleshooting scenario. With openssl, you can open a secure connection to a remote server on port 443, and then send raw HTTP commands. For example, the following text shows an exchange between an openssl client and a remote web server. Text in red represents commands typed by the user:

$ openssl s_client -connect example.com:443
CONNECTED(00000003)
depth=1 C = BE, O = GlobalSign nv-sa, CN = AlphaSSL CA - SHA256 - G2
verify return:0
---
Certificate chain
 0 s:/OU=Domain Control Validated/CN=*.example.com
   i:/C=BE/O=GlobalSign nv-sa/CN=AlphaSSL CA - SHA256 - G2
 1 s:/C=BE/O=GlobalSign nv-sa/CN=AlphaSSL CA - SHA256 - G2
   i:/C=BE/O=GlobalSign nv-sa/OU=Root CA/CN=GlobalSign Root CA
---
Server certificate
-----BEGIN CERTIFICATE-----

[Output truncated]

-----END CERTIFICATE-----
subject=/OU=Domain Control Validated/CN=*.example.com
issuer=/C=BE/O=GlobalSign nv-sa/CN=AlphaSSL CA - SHA256 - G2
---
No client certificate CA names sent
---
SSL handshake has read 3042 bytes and written 424 bytes
---
New, TLSv1/SSLv3, Cipher is ECDHE-RSA-AES256-GCM-SHA384
Server public key is 2048 bit
Secure Renegotiation IS supported
Compression: NONE
Expansion: NONE
SSL-Session:
    Protocol  : TLSv1.2
    Cipher    : ECDHE-RSA-AES256-GCM-SHA384

[Output truncated]

Escape character is '^]'.

HEAD / HTTP/1.1
Host: example.com

HTTP/1.1 200 OK
Date: Tue, 18 Aug 2015 16:07:15 GMT
Server: Apache
X-Powered-By: PHP/5.3.27
Content-Type: text/html

In this exchange, openssl opens a connection to example.com on port 443 (HTTP secure port). The user receives information about the SSL certificate, as well as the ciphers that are in use. The user then sends a raw HTTP command (HEAD). The HTTP response confirms that the web server is accepting connections and responding to requests on port 443.

Troubleshooting IMAP and POP connections

Similar to the procedure for web server troubleshooting, you can test secure POP (port 995) and IMAP (port 993) connectivity.

The following text shows a sample exchange between an openssl client and a remote IMAP server. Text in red represents commands typed by the user:

$ openssl s_client -connect example.com:993
CONNECTED(00000003)
depth=1 C = US, O = DigiCert Inc, OU = www.digicert.com, CN = DigiCert SHA2 High Assurance Server CA
verify return:0
---
Certificate chain
 0 s:/C=US/ST=Washington/L=Bellingham/O=Example.com, Inc./CN=*.example.com
   i:/C=US/O=DigiCert Inc/OU=www.digicert.com/CN=DigiCert SHA2 High Assurance Server CA
 1 s:/C=US/O=DigiCert Inc/OU=www.digicert.com/CN=DigiCert SHA2 High Assurance Server CA
   i:/C=US/O=DigiCert Inc/OU=www.digicert.com/CN=DigiCert High Assurance EV Root CA
---
Server certificate
-----BEGIN CERTIFICATE-----

[Output truncated]

-----END CERTIFICATE-----
subject=/C=US/ST=Washington/L=Bellingham/O=Example.com, Inc./CN=*.example.com
issuer=/C=US/O=DigiCert Inc/OU=www.digicert.com/CN=DigiCert SHA2 High Assurance Server CA
---
No client certificate CA names sent
---
SSL handshake has read 3419 bytes and written 488 bytes
---
New, TLSv1/SSLv3, Cipher is DHE-RSA-AES256-GCM-SHA384
Server public key is 2048 bit

[Output truncated]

---
* OK [CAPABILITY IMAP4rev1 LITERAL+ SASL-IR LOGIN-REFERRALS ID ENABLE IDLE NAMESPACE AUTH=PLAIN AUTH=LOGIN] Dovecot ready.
QUIT

The responses show that the server is accepting connections and responding to requests on port 993. Additionally, the line that starts with * OK shows that IMAP is running and ready for requests.

More Information

For more information about OpenSSL, please visit https://www.openssl.org.