openssl s_client commands and examples

The s_client command from OpenSSL is a helpful test client for troubleshooting remote SSL or TLS connections. The post strives to walk you through various examples of testing SSL connections with different ciphers, TLS versions, and SSL server certificate analysis. Testing SSL configuration on servers is a critical function that should be routine in your organization or systems. This utility will help uncover errors and misconfigurations.

If you are testing the performance of your SSL connections, read our article on the openssl s_time utility.

openssl s_client examples

openssl s_client connect

openssl s_client -connect example.com:443

Use the openssl s_client -connect flag to display diagnostic information about the SSL connection to the server. The information will include the servers certificate chain, printed as subject and issuer. The end entity server certificate will be the only certificate printed in PEM format.

Details about the SSL handshake, its verification, and the TLS version and cipher will be returned. The server’s public key bit length is also returned.

Here is a screenshot of the beginning of an example output from the above command:

To specify the TLS version in the connection for testing various protocols, add the appropriate TLS/SSL flag to the command. For example, to test TLS 1.3 with openssl s_client, run the following:

openssl s_client -connect example.com:443 -tls1_3

Other supported SSL and TLS version flags include -tls1_2, tls1_1, tls1, ssl2 , and ssl3. Alternatively, to disable the use of a specific SSL/TLS protocol version, the following flags are supported: -no_ssl2, -no_ssl3, -no_tls1, -no_tls1_1, -no_tls1_2, and -no_tls1_3.

For the case of example.com, TLSv1.3 is supported. To disable TLSv1.3, use the -no_tls1_3 flag:

openssl s_client -connect example.com:443 -no_tls1_3

To verify the protocol, view the SSL-Session section of the console output.

SSL-Session:
    Protocol  : TLSv1.3
    Cipher    : ECDHE-RSA-AES128-GCM-SHA256
    Session-ID: 2BFA471935218231CFC481C6AD4E72025834B51C8791AC33AB54A4B923D04A36
    Session-ID-ctx: 
    Master-Key: 935153C4FD38007F942A4215D2763CADB16DD3103FC9B5DD625A98AE8081D6C2934B7FC860A5DC484C393

If the specified protocol is not supported on the server, you will receive an error similar to: “SSL routines:tls_construct_client_hello:no protocols available“

To debug the SSL/TLS connection with openssl s_client connect, append the -tlsextdebug flag onto your command:

openssl s_client -connect example.com:443 -tlsextdebug

Additional information is included and can be used to verify the ssl configuration of the server, but leave a comment and ask questions about anything not covered.

Regardless of what you are trying to test, the s_client is an ideal utility for testing and troubleshooting SSL configuration on your server. If you are looking for a less technical testing tool, try an application that will return the same or similar results such as SSL Labs.

openssl s_client showcerts

openssl s_client -connect example.com:443 -showcerts

The showcerts flag appended onto the openssl s_client connect command prints out and will show the entire certificate chain in PEM format, whereas leaving off showcerts only prints out and shows the end entity certificate in PEM format. Other than that one difference, the output is the same. The returned list of certificates by the server when using the showcerts flag is not a verified chain and is returned in the same order the server sent them.

While most examples you find test port 443, this will work with other ports as well. For example, testing SSL configuration on an active directory or open ldap host works the same, just specify the port, commonly 636. To show the server certificates on the AD (Active Directory) or ldap server, run the following command:

openssl s_client -connect ldap-host:636 -showcerts

After showing the certificates returned by openssl s_client connect, decode the certificates for more information about each section of the certificate with our Certificate Decoder tool.

openssl s_client -starttls

Adding the -starttls flag to your openssl s_client -connect command will send the protocol specific message for switching to SSL/TLS communication. Supported protocols include smtp, pop3, imap, ftp, xmpp, xmpp-server, irc, postgres, mysql, lmtp, nntp, sieve and active directory and ldap. For the ldap example:

openssl s_client -connect ldap-host:389 -starttls ldap

Test SIP SSL connection

The SIP protocol can also be tested with the openssl s_client tools. The SIP protocol is available over port 5061 by default, so just specify :5061 as a part of your command. Here is an example demonstrating how to test the SIP SSL connection and return the certificate chain with s_client.

openssl s_client -connect sip-host:5061 -showcerts < /dev/null

In this example, port 5061 is specified as the port for SIP, and -showcerts will show each certificate returned as part of the certificate chain. If further analysis of the certificate is needed on the server certificate, you can pipe the results into the openssl x509 command demonstrated here:

openssl s_client -connect sip-host:5061 < /dev/null | openssl x509 -noout -text

openssl s_client sni

openssl s_client -connect example.com:443 -servername example.com

SNI is a TLS extension that supports one host or IP address to serve multiple hostnames so that host and IP no longer have to be one to one. Use the -servername switch to enable SNI in s_client. If the certificates are not the same when using the -servername flag vs without it, you will know that SNI is required.

Appending the noservername flag onto the openssl s_client command will not send the SNI (Server Name Indication). Note that this cannot be used in the same command with the servername flag. For example:

openssl s_client -connect example.com:443 -noservername

openssl s_client get certificate

To get a certificate in a file from a server with openssl s_client, run the following command:

echo | openssl s_client -connect example.com:443 2>&1 | sed --quiet '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > example.com.pem

To print or show the entire certificate chain to a file, remember to use the -showcerts option.

openssl s_client verify

To verify the SSL connection to the server, run the following command:

openssl s_client -verify_return_error -connect example.com:443

If the server returns any errors then the SSL Handshake will fail and the connection will be aborted.

openssl s_client verify hostname

To verify that the certificate installed on a remote server covers the hostname, run the following command:

openssl s_client -verify_hostname www.example.com -connect example.com:443

It is useful to verify the hostname with the CN or SANs on the installed certificate with openssl s_client if and when there are multiple hosts protected and identified by the same certificate.

If the hostname does not match, you will receive the following error:

verify error:num=62:Hostname mismatch

In addition, you will see another verification error:

Verification error: Hostname mismatch

If the host is protected by a wildcard certificate, make sure that the wildcard covers the subdomain of the host. For example, a certificate with CN=*.example.com will cover www.example.com but not test.www.example.com. Again, the wildcard must be present on the subdomain part needing covered. So for test.www.example.com, you would need a certificate with a CN or SAN equal to *.www.example.com

openssl s_client ciphers

You can pass a cipher to the openssl s_client command with the -ciphersuites flag. This flag is useful for the TLSv1.3 cipher list to be modified by the client. While the server ultimately determines which cipher is used in the SSL connection, generally speaking it should take the first supported cipher in the list sent by the client. If you have a preferred cipher or list of ciphers, it can be sent along with this flag. Read our post on the openssl ciphers command to learn how to display a list ciphers for a given SSL or TLS protocol version.

For example:

echo | openssl s_client -connect www.example.com:443 -tls1_3 -ciphersuites TLS_AES_128_GCM_SHA256 2>/dev/null | grep New

Will output the following:

New, TLSv1.3, Cipher is TLS_AES_128_GCM_SHA256

The server should accept and use the provided cipher in the connection. If you want to provide a list of ciphers, they can be delimitered with a colon (:).

If modifying or specifying the cipher list for a TLSv1.2 connection, the -cipher flag is used instead of the -ciphersuites flag.

For example:

echo | openssl s_client -connect www.example.com:443 -tls1_2 -cipher AES128-GCM-SHA256 2>/dev/null | grep New

Will output the following:

New, TLSv1.2, Cipher is AES128-GCM-SHA256

A helpful resource for determining the strength of each cipher suite is at https://ciphersuite.info/cs/.

TLS Client Auth with openssl s_client

openssl s_client also provides the capability to test TLS client auth. There are a couple of ways to do this by using both the -cert and -key options. This example makes use of only the -cert option, by combining both the certificate and private key used for authentication in the same file.

openssl s_client \
  -connect example.com:443 \
  -cert <cert_and_key.pem>

To elaborate further on the alternate options for connecting with TLS client auth:

Override openssl configuration file

When using the openssl s_client utility to test a server’s SSL or TLS configuration, sometimes it is useful to override the default openssl configuration. For example, you may want to lower the security level of the openssl version you are running.

To lower the security level of your openssl configuration, perform the following steps: (has only been tested on Ubuntu)

• Make a copy of your openssl configuration file.
• Add the following to the beginning of your configuration file.

openssl_conf = default_conf

• Add the following to the end of your configuration file, making sure to set the security level to the level you wish to test.

[ default_conf ]
ssl_conf = ssl_sect
[ssl_sect]
system_default = system_default_sect
[system_default_sect]
MinProtocol = TLSv1.2
CipherString = DEFAULT:@SECLEVEL=1

• Override the system configuration file by exporting the OPENSSL_CONF environment variable. This will allow you to test a different configuration without affecting your system wide configuration.

export OPENSSL_CONF=mycopy-openssl.cnf

Conclusion

We hope this information has been valuable and don’t forget to ask questions in the comments section. If you would like to see more examples of how to use openssl s client let us know! Until then, visit out OpenSSL page to view more examples of openssl commands.

Read more of our content.