Troubleshoot SSL/TLS Errors

SSL/TLS errors are classified by whether they occur during the handshake phase or after the connection is established. Handshake errors prevent the connection from being established and include certificate validation failures, protocol version mismatches, cipher suite incompatibilities, and SNI (Server Name Indication) issues. Post-handshake errors are less common and typically involve certificate revocation events or connection reset errors from TLS state corruption. Handshake failures manifest as browser security warnings, API errors with SSL exception messages, and monitoring alerts on failed health checks.

Certificate validation errors are the most common category of SSL errors. They include: expired certificates (certificate's notAfter date has passed), hostname mismatches (the certificate's Common Name or Subject Alternative Names do not match the hostname being accessed), self-signed certificates not trusted by the client's certificate store, incomplete certificate chains (intermediate certificates missing from the server's certificate bundle), and certificates signed by untrusted Certificate Authorities. Each validation error has a specific remediation—expired certificates require renewal, hostname mismatches require a new certificate or additional SAN, and incomplete chains require adding intermediate certificates to the server configuration.

Protocol version and cipher suite incompatibilities occur when the client and server cannot agree on a mutually supported protocol version and cipher combination. TLS 1.0 and 1.1 are deprecated and disabled in modern browsers and client libraries, meaning servers that only support these older protocols will fail to connect with modern clients. Cipher suites that use export-grade encryption, RC4, 3DES, or MD5 are disabled in modern clients for security reasons. Servers using only deprecated protocols or ciphers will generate SSL handshake failures with modern clients.

Mixed content warnings occur when an HTTPS page loads HTTP resources—images, scripts, stylesheets, or API calls. Browsers block active mixed content (scripts, iframes) that could be used to attack the secure context, and warn about passive mixed content (images, audio, video) that could be intercepted. Mixed content is a gradual degradation issue rather than a complete failure—the page loads but security is reduced and users see browser warnings. Use Content Security Policy's upgrade-insecure-requests directive to automatically upgrade HTTP references to HTTPS, and audit your pages for HTTP resource references.

Certificate expiration is responsible for the majority of SSL-related production outages. A certificate that expires causes every connection attempt to fail with a certificate validation error—rendering the service completely inaccessible to all users simultaneously. Certificate renewals are straightforward but easy to forget in the complexity of production operations. Monitor all certificates across all domains, subdomains, and internal services with automated expiration alerts at 30 days, 14 days, and 7 days before expiration. Configure alerts to page the on-call engineer immediately if a certificate expires rather than gradually failing to renew.

Monitor the complete certificate chain, not just the leaf certificate. A certificate chain includes the leaf certificate, one or more intermediate certificates, and the root CA certificate. If any intermediate certificate in the chain expires or is revoked, connections will fail even if the leaf certificate is valid. Certificate chain validation requires checking the validity dates and revocation status of all certificates in the chain. Automated certificate monitoring tools typically validate the complete chain and alert on any invalid certificate in the chain.

Track certificate revocation status using OCSP (Online Certificate Status Protocol) stapling to detect certificates that have been revoked before their expiration date. Revocation occurs when a private key is compromised, when an organization stops using a domain, or when a CA discovers an error in the original certificate issuance. Without OCSP monitoring, you may not discover that a certificate has been revoked until users report connection failures or until your certificate monitoring detects the revocation through API polling. OCSP stapling improves performance by including the OCSP response in the TLS handshake, but requires server-side configuration.

Certificate transparency log monitoring detects unauthorized certificates issued for your domains by compromised or malicious Certificate Authorities. Certificate Transparency (CT) logs are public, append-only logs of all certificates issued by participating CAs. Subscribe to CT log monitoring services (crt.sh, Cert Spotter) that notify you when new certificates are issued for your domains. An unexpected certificate issuance event may indicate a CA compromise, DNS hijacking, or a phishing attempt that has obtained a fraudulent certificate. Fast detection enables rapid revocation and mitigation.

OpenSSL command-line tools provide detailed diagnostic output for TLS connections. The command openssl s_client -connect domain.com:443 -servername domain.com initiates a TLS connection and displays the complete certificate chain, protocol version negotiated, cipher suite selected, and any verification errors. The output includes the certificate's validity dates, the complete chain of trust from leaf to root, and the verification result (OK or specific failure reason). This tool is essential for diagnosing certificate chain issues, hostname mismatch errors, and protocol/cipher incompatibilities that are difficult to diagnose from browser error messages alone.

SNI (Server Name Indication) failures cause issues when a server hosts multiple HTTPS sites on the same IP address. Without SNI, the server cannot know which certificate to present until the TLS handshake completes—a circular dependency. SNI solves this by having the client include the hostname in the TLS ClientHello message before the certificate is sent. If a server does not support SNI or a client does not send SNI (very old clients), the server presents a default certificate that may not match the requested hostname. Verify SNI is enabled on your web server and that clients include the SNI extension in their TLS handshake.

Certificate chain ordering errors cause subtle handshake failures in some client implementations. The certificate bundle presented by the server should be ordered from leaf certificate (site certificate) to intermediate certificates, with the root CA either included or omitted. Reversed chain ordering, missing intermediates, or duplicate certificate entries in the bundle cause handshake failures in strict client implementations. Validate certificate chain ordering using ssl-checker.online, the openssl verify command, or Qualys SSL Labs, which provides a detailed certificate chain analysis and flags ordering issues.

TLS 1.3 compatibility issues may arise with specific clients or intermediate network devices that do not fully support the protocol. Some enterprise network inspection devices (SSL inspection proxies, next-generation firewalls) intercept and re-encrypt TLS connections and may not support TLS 1.3. Configure servers to support both TLS 1.2 and TLS 1.3 during the transition period, removing TLS 1.0 and 1.1 but maintaining 1.2 compatibility. Monitor for handshake failure rate increases after enabling TLS 1.3 to detect compatibility issues with specific client populations.

Configure your TLS protocol versions to support TLS 1.2 and TLS 1.3 only, removing support for deprecated TLS 1.0 and TLS 1.1. Browsers deprecated TLS 1.0 and 1.1 in 2020, and enabling only modern protocol versions eliminates an entire class of vulnerabilities (BEAST, POODLE, and related protocol downgrade attacks). In nginx, set ssl_protocols TLSv1.2 TLSv1.3. In Apache, set SSLProtocol all -SSLv3 -TLSv1 -TLSv1.1. Test your configuration with a small percentage of traffic before full deployment and monitor for handshake failure rate increases that might indicate unsupported client populations.

Cipher suite configuration determines the algorithms used for key exchange, authentication, encryption, and message authentication in TLS connections. Modern cipher suite recommendations prioritize forward secrecy (ephemeral key exchange that prevents retroactive decryption if the server's private key is later compromised), AES-GCM or ChaCha20 encryption, and SHA-256 or SHA-384 message authentication. The Mozilla SSL Configuration Generator provides current, maintained cipher suite recommendations for nginx, Apache, HAProxy, and other servers, and is updated when new vulnerabilities are discovered or cipher suites deprecated.

HSTS (HTTP Strict Transport Security) enforces HTTPS-only access by instructing browsers to never make HTTP connections to your domain. Set the Strict-Transport-Security header with a max-age of at least 1 year (31536000 seconds) on all HTTPS responses. Add the includeSubDomains directive only after verifying that all subdomains support HTTPS. Add the preload directive and submit to the HSTS preload list to prevent even the first HTTP connection attempt from users who have never visited your site. HSTS provides strong protection against SSL stripping attacks that downgrade HTTPS to HTTP.

TLS session resumption improves performance for returning connections by reusing previously negotiated cryptographic parameters without a full handshake. TLS 1.2 supports session IDs and session tickets; TLS 1.3 supports session tickets and 0-RTT resumption. Session tickets encrypt session state using a server-held key and store it at the client, allowing resumption without server-side storage. Configure session ticket key rotation (daily is standard) to limit the exposure window if ticket keys are compromised, and monitor session resumption rates to validate that the performance optimization is working.

Let's Encrypt with certbot or similar ACME-protocol clients provides free automated certificate issuance and renewal for publicly accessible domains. Certbot with the --deploy-hook option executes a script after successful renewal to reload your web server, ensuring the new certificate takes effect immediately. Certificate renewal is attempted every 60 days by default; certificates expire after 90 days, providing a 30-day renewal window. Verify that certbot's cron job or systemd timer is functioning by checking renewal logs at least weekly. Configure certbot to send email alerts on renewal failures so that manual intervention happens before expiration.

Cloud provider certificate management (AWS Certificate Manager, Google-managed SSL certificates, Azure Key Vault certificates) provides automatic renewal with integration into cloud load balancers and CDN services. ACM certificates for resources in AWS renew automatically at no cost and never require manual renewal action. The main risk with cloud-managed certificates is that automatic renewal requires maintaining domain validation records (DNS records or HTTP validation files)—if these validation mechanisms break (DNS records are deleted, server returns 404 for HTTP challenge), automatic renewal fails and the certificate expires. Monitor renewal status through cloud provider APIs.

Certificate pinning for mobile applications and specific high-security endpoints adds a layer of protection against fraudulent certificates but requires careful management to avoid locking out users when certificates rotate. Certificate pinning stores the expected certificate or public key hash in the application and rejects connections presenting different certificates. When a pinned certificate is renewed (even with the same key), applications that pin to the certificate's full content will reject the new certificate. Pin to the public key hash (SPKI pinning) rather than the full certificate to allow certificate renewal without application updates, and always pin to at least 2 backup keys to allow key rotation.

Multi-domain certificate management with Subject Alternative Names (SANs) simplifies certificate deployment for organizations with many subdomains. A wildcard certificate (*.example.com) covers all first-level subdomains but not nested subdomains (api.v2.example.com) or the bare domain (example.com). A SAN certificate explicitly lists all domains it covers and can include disparate domains. Manage SAN certificates carefully when adding or removing domains—adding a new subdomain requires reissuing the entire certificate, and missed subdomains result in hostname mismatch errors. Automate SAN certificate management with ACME clients that support multi-domain certificates.

Qualys SSL Labs provides the most comprehensive external certificate and configuration audit tool. The SSL Labs test scans your server from multiple locations, validates the certificate chain, tests all supported protocol versions and cipher suites, checks HSTS and OCSP stapling configuration, and assigns an overall grade from A+ to F with specific recommendations for each finding. Run SSL Labs tests after any certificate or configuration change, and schedule monthly audits to detect configuration drift or newly discovered vulnerabilities. Target an A rating (A+ with HSTS preloading) as the acceptable minimum for production services.

Internal certificate monitoring for non-public services (internal APIs, databases, service mesh mTLS) requires additional tooling beyond external monitoring services that only scan publicly accessible hosts. Implement a certificate inventory and monitoring system that periodically checks certificate validity for all internal endpoints by establishing test TLS connections and inspecting the returned certificates. Tools like x509lint, certigo, and custom scripts using OpenSSL can validate internal certificates that external scanners cannot reach.

Security vulnerability monitoring for TLS libraries (OpenSSL, LibreSSL, BoringSSL) and web servers is necessary to detect when your configuration requires updating due to newly discovered vulnerabilities. Subscribe to security advisories for your TLS library and web server, and plan prompt patching for critical TLS vulnerabilities. Historical vulnerabilities like Heartbleed, BEAST, POODLE, and CRIME required rapid response across the industry. Maintaining current versions of TLS libraries and applying security patches within 48 hours for critical vulnerabilities minimizes exposure windows.

Certificate health in production monitoring dashboards alongside other operational metrics ensures certificate status is visible to on-call engineers during incident response. Include certificate expiration dates (time remaining until expiration for each monitored domain), OCSP status, and most recent SSL Labs grade in operational dashboards. During an incident where SSL errors are reported, having certificate health visible on the same dashboard as service health metrics eliminates one category of investigation steps and allows rapid assessment of whether a certificate issue is contributing to the incident.