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.
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 ldap host works the same, just specify the port, commonly 636. To show the server certificates on the 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 ldap. For the ldap example:
openssl s_client -connect ldap-host:389 -starttls ldap
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 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.
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.
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:
|openssl s_client option||Option Description|
|-cert||The certificate to be used for TLS client authentication.|
|-certform||The format of the certificate. PEM is the default, but DER may be specified.|
|-key||The private key matching the provided certificate.|
|-keyform||The format of the private key. PEM is the default, but DER may be specified.|
|-cert_chain||The complete trust chain.|
|-pass||The password source of the private key, if encrypted with a password.|
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.
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.