A Developer’s Guide to openssl_client

You’ve spent several hours meticulously designing your application, ensuring that every line of code is flawless. Everything looks perfect, and you deploy it with confidence. But then things take an awkward turn. Your secure connections start to fail, leaving you scratching your head and wondering what went wrong.

SSL/TLS issues can be incredibly frustrating for DevOps teams, often leading to hours of debugging and troubleshooting. Failed handshakes, misconfigured certificates, and unexplained errors can quickly derail your progress. With 90% of applications tested showing some form of misconfiguration, understanding how to diagnose and resolve SSL/TLS issues early is critical for maintaining a secure and reliable system.

What is openssl_client?

openssl_client is a command-line utility used to test, debug, and analyze SSL/TLS connections. It helps developers gain in depth understanding into secure communication by inspecting server certificates, verifying protocol support, and troubleshooting handshake failures.

As a part of the OpenSSL toolkit, openssl_client plays a vital role in diagnosing connection issues that can arise from certificate misconfigurations, outdated protocols, or insecure cipher suites. With SSL/TLS being the foundation of secure data transmission in modern systems across APIs, web services, and cloud platforms, tools are essential for maintaining reliability and security.

Checking Your OpenSSL Version

Before using openssl_client, you need to verify that OpenSSL is installed and up to date. Outdated versions often lack support for modern protocols and can expose your system to security risks.

Run the below command to check your OpenSSL version

openssl version

Output:

If the version is outdated, update OpenSSL using your OS’s package manager:

Ubuntu/Debian:

sudo apt update && sudo apt install openssl

macOS (using Homebrew):

brew update && brew install openssl

Practical Use Cases for openssl_client

openssl_client is a multi tasking tool that helps developers and security teams diagnose and resolve SSL/TLS issues quickly. Here are common scenarios where it proves invaluable:

1. Troubleshooting SSL/TLS Misconfigurations

Failed handshakes or protocol mismatches can cause secure connections to break. Use openssl_client to test and debug these issues:

openssl s_client -connect example.com:443

What it does: Connects to the specified server and port, showing detailed information about the handshake, supported protocols, and the certificate chain.

Tip: Look for error messages like “unable to get local issuer certificate” or “handshake failure” to pinpoint the problem.

2. Verifying Certificates in Staging or Production

Ensure your server’s certificates are valid and correctly installed by displaying the certificate details:

openssl s_client -showcerts -connect example.com:443

Expected output:

CONNECTED(00000003)
Certificate chain
0 s:CN = example.com
  i:C = US, O = Let’s Encrypt, CN = R3
—–BEGIN CERTIFICATE—–
MIIFazCCBFOgAwIBAgISA+Tp…
—–END CERTIFICATE—–
1 s:C = US, O = Let’s Encrypt, CN = R3
  i:C = US, O = Internet Security Research Group, CN = ISRG Root X1
—–BEGIN CERTIFICATE—–
MIIFRzCCAy+gAwIBAgISA0…
—–END CERTIFICATE—–
—
Server certificate
subject=CN = example.com
issuer=C = US, O = Let’s Encrypt, CN = R3

What it does: Displays the server’s certificate chain, including intermediate and root certificates.

Validation: Verify expiration dates, issuer, and Subject Alternative Names (SANs).

3. Testing Protocol and Cipher Compatibility

Confirm your application supports specific SSL/TLS protocols or ciphers.

Testing a specific TLS version:

openssl s_client -connect example.com:443 -tls1_2

Expected output:

CONNECTED(00000003)
Protocol  : TLSv1.2
Cipher    : ECDHE-RSA-AES256-GCM-SHA384
…
Verify return code: 0 (ok)

Testing for ciphers:

openssl s_client -connect example.com:443 -cipher AES256-SHA

Output if incompatible:

CONNECTED(00000003)
139741457474112:error:14094410:SSL routines:ssl3_read_bytes:sslv3 alert handshake failure

What it does: Forces the connection to use a specific TLS version or cipher. If the connection fails, it indicates incompatibility or security misconfigurations.

4. Pre-deployment Security Checks

Verify your staging or pre-production environment is ready before going live:

openssl s_client -connect staging.example.com:443 -verify 5

Expected output:

CONNECTED(00000003)
depth=0 CN = staging.example.com
verify return:1
depth=1 O = Let’s Encrypt, CN = R3
verify return:1
depth=2 CN = ISRG Root X1
verify return:1
Verify return code: 0 (ok)

What it does: Checks the certificate chain up to 5 levels, ensuring there are no missing or invalid certificates.

5. Integrating into CI/CD Pipelines

Automate certificate validation and protocol testing as part of your CI/CD pipeline:

openssl s_client -quiet -connect example.com:443 </dev/null

Expected Output (silent):

If successful, no output is returned. If failed, an error like:

139741457474112:error:14094410:SSL routines:ssl3_read_bytes:sslv3 alert handshake failure:ssl/record/rec_layer_s3.c:1543:

What it does: Silently connects and exits with an error code if issues are found.

Tip: Combine this with scripting tools to fail a pipeline when misconfigurations are detected.

Step-by-Step Guide to Using openssl_client

This section provides a practical walkthrough of essential openssl_client commands to help developers quickly debug and verify secure connections.

1. Connect to a Server

Verify SSL/TLS connectivity to a server and display handshake details:

openssl s_client -connect example.com:443

• What it does: Initiates a connection to the specified server and port (e.g., port 443 for HTTPS).
• Output: Displays details of the TLS handshake, supported protocols, and certificates.
• Tip: Look for “Verify return code: 0 (ok)” to confirm a successful handshake.

2. Test Protocol Compatibility

Ensure your server supports modern and secure TLS protocols:

Force TLS 1.3:

openssl s_client -connect example.com:443 -tls1_3

Force TLS 1.2:

openssl s_client -connect example.com:443 -tls1_2

What it does: Forces openssl_client to attempt the connection with a specific protocol version.

Why it’s useful: Identifies whether legacy or unsupported protocols are causing issues.

3. View Certificate Details

Display the server’s certificate chain and key details:

openssl s_client -showcerts -connect example.com:443

What it does: Shows all certificates presented by the server, including intermediates.

How to use: Review certificate expiration, issuer, and SANs (Subject Alternative Names).

4. Debug Handshake Failures

Use verbose mode to gain deeper insight into SSL/TLS handshake problems:

openssl s_client -debug -connect example.com:443

Expected output:

SSL_connect:before SSL initialization
SSL_connect:SSLv3/TLS write client hello
SSL_connect:SSLv3/TLS read server hello
SSL_connect:TLSv1.3, Cipher is TLS_AES_256_GCM_SHA384
SSL_connect:TLSv1.3 write encrypted extensions
SSL_connect:TLSv1.3 write certificate verify
SSL_connect:TLSv1.3 write finished
SSL_connect:TLSv1.3 read server finished
—
SSL handshake has read 4343 bytes and written 383 bytes
Verify return code: 0 (ok)

What it does: Outputs detailed information about each stage of the handshake process

When to use: Ideal for diagnosing errors like handshake failures, cipher mismatches, or invalid certificates.

Tip: Pair this with -state for additional debug output:

openssl s_client -debug -state -connect example.com:443

Best Practices for Debugging with openssl_client

To get the most out of openssl_client and ensure efficient debugging, here are actionable tips:

1. Use the Latest TLS Versions and Secure Ciphers

Avoid testing outdated or insecure protocols. Always validate servers with the latest TLS versions (e.g., TLS 1.3) and strong cipher suites to ensure compatibility and security.

2. Focus on Verbose Logs for Misconfiguration Diagnosis

Combine verbose options like -debug and -state to quickly identify handshake failures, missing certificates, or protocol mismatches.

3. Automate and Validate Continuously

Integrate openssl_client tests into scripts or CI/CD pipelines to ensure SSL/TLS configurations remain secure across development stages.

4. Cross-check with Automated Security Tools

Although openssl_client provides indepth information, you can combine it with automated security tools like Spectral to get more comprehensive validation, catching edge cases and misconfigurations that may be missed manually.

Building Resilient Applications with Secure Connections

Secure connections are the conerstone of modern applications, ensuring data integrity and trust between systems. However, SSL/TLS misconfigurations can disrupt this foundation, leading to critical issues like failed handshakes or insecure protocols.

Tools like openssl_client give developers the power to validate, troubleshoot, and optimize SSL/TLS configurations with precision. With openssl_client, developers can inspect certificates, test protocol compatibility, and debug handshake failures to identify and address problems before they impact production environments.

Although openssl_client is the perfect tool for manual diagnostics, scaling secure practices across complex environments requires automation. That’s where Spectral comes in. Spectral integrates automated security checks into CI/CD pipelines, helping you detect vulnerabilities, misconfigurations, and secret leaks before they become real issues.Ready to enhance your application security? Contact Spectral today to learn how our platform can help you build more secure and resilient applications.