HTTP::Server returns generic OpenSSL error when presented with an expired client certificate

Question

When an HTTP::Server is configured with a TLS context that enables peer verification and requires a client certificate, presenting an expired client certificate causes the TLS handshake to abort. The server raises an OpenSSL::SSL::Error, but the exception does not expose a distinct reason code or message that clearly indicates certificate expiry versus other verification failures (e.g., unknown CA, hostname mismatch). Developers need a reliable way to detect this specific condition to enforce least‑privilege handling of credentials without parsing error strings.
Assuming Crystal 1.12+ linked against OpenSSL 1.1.1 or later, and using the default VERIFY_PEER | VERIFY_FAIL_IF_NO_PEER_CERT mode, what information is available in the rescued OpenSSL::SSL::Error to differentiate an expired certificate?

Which OpenSSL verify result codes map to expiry and are they surfaced through the Crystal binding?
Can the error message be inspected safely for expiry indicators without relying on brittle string matching?
Is there a configuration option or callback that would allow the server to raise a custom exception type for expired client certificates?

Tasadduq Burney · Answer

Short answer
The rescued OpenSSL::SSL::Error does not reliably expose the OpenSSL verify result code, so an expired client certificate cannot be distinguished from an unknown CA or other verification failure using the exception alone. Treat the handshake failure as a generic client-certificate rejection unless binding-level callback support is confirmed.
OpenSSL verify result codes
X509_V_ERR_CERT_HAS_EXPIRED is verify result 10 and applies to the certificate itself. X509_V_ERR_CRL_HAS_EXPIRED (13) refers to CRL expiry, not the certificate. Whether result 10 is surfaced by the Crystal OpenSSL binding or HTTP::Server is unconfirmed.
Error message inspection
Do not parse OpenSSL::SSL::Error#message for expiry indicators. OpenSSL error text varies by version and build, making string matching brittle and unsafe for security decisions.
Custom exception or callback
No standard Crystal option is confirmed to raise a custom exception type specifically for expired client certificates. A verify callback could inspect X509_STORE_CTX_get_error and return 0 or 1 to fail or continue selectively, but that requires SSL_CTX_set_verify or equivalent binding exposure, which has not been confirmed for Crystal 1.12+.
Verification steps

Run a minimal HTTP::Server with TLS and verify_mode set to VERIFY_PEER | VERIFY_FAIL_IF_NO_PEER_CERT.
Connect with an expired client certificate and rescue OpenSSL::SSL::Error.
Print the exception class, #message, and exposed methods.
Inspect the Crystal OpenSSL binding source for verify-callback exposure and for SSL_get_verify_result or X509_STORE_CTX_get_error usage.

Assumptions and uncertainty
This answer assumes Crystal 1.12+ linked against OpenSSL 1.1.1 or later. OpenSSL 3.x provider behavior or other binding versions may differ. The handshake aborts before the HTTP handler runs, so expiry-specific handling cannot occur in the request handler.
Missing diagnostic detail that changes the recommendation: does your installed Crystal OpenSSL binding expose a verify callback or the numeric verify result on the SSL context? If yes, register a callback that checks for result 10 and maps it to a custom exception. If no, handle all peer-verification failures uniformly at the TLS layer.

HTTP::Server returns generic OpenSSL error when presented with an expired client certificate

1 answer

Short answer

OpenSSL verify result codes

Error message inspection

Custom exception or callback

Verification steps

Assumptions and uncertainty

Your perspective belongs here.

0 question comments