yhirose
9bfd2ddf1c
Bring the READMEs and the docs pages (en and ja) in line with the current header: - Fix the client sample that does not compile, the Transfer-Encoding statement for default headers, the verifier callback comment, the thread pool spawn rule, the sanitize_filename description, and the inverted Accept-Encoding sentence. - Describe recent behaviour: TLS errors behind Read/Write failures, Host validation, Connection: close for a body without length, content_reader rules, refused CONNECT, WebSocketClient proxies, CPPHTTPLIB_INTERIM_RESPONSE_MAX_COUNT, the SSE event size limit, and the payload limit of the Stream API. - Complete the API references of WebSocket, WebSocketClient and the stream:: helpers, and the SSE reconnect rules. - Fix cookbook pages: keychain loading on every backend, received Close status, a multipart sample that trusted the client's file name, an echo sample that sent binary as text, SNI, pre-request handler scope, stop() with WebSocket handlers, and the thread pool notes. - Restore the mutex in the LLM app's Chapter 5 code.
2.6 KiB
title, order, status
| title | order | status |
|---|---|---|
| C18. Handle SSL Errors | 18 | draft |
When an HTTPS request fails, res.error() returns values like Error::SSLConnection or Error::SSLServerVerification. Sometimes that's not enough to pinpoint the cause. That's where Result::ssl_error() and Result::ssl_backend_error() help.
Get the SSL error details
httplib::Client cli("https://api.example.com");
auto res = cli.Get("/");
if (!res) {
auto err = res.error();
std::cerr << "error: " << httplib::to_string(err) << std::endl;
if (err == httplib::Error::SSLConnection ||
err == httplib::Error::SSLServerVerification ||
err == httplib::Error::Read || err == httplib::Error::Write) {
std::cerr << "ssl_error: " << res.ssl_error() << std::endl;
std::cerr << "ssl_backend_error: " << res.ssl_backend_error() << std::endl;
}
}
ssl_error() is a backend-independent TLS error category: an httplib::tls::ErrorCode cast to int. ssl_backend_error() gives you the backend's own error value. With OpenSSL that is ERR_get_error() when the handshake or a later read or write failed, and the verify result (X509_V_ERR_*) when certificate verification failed.
A request that fails after the handshake reports Error::Read or Error::Write. Even then, ssl_error() and ssl_backend_error() carry the TLS error behind it. For example, if the server requires a client certificate you didn't send, OpenSSL's error reads "tlsv13 alert certificate required". Both values are reset for each request and are 0 when no TLS error was involved.
Format OpenSSL errors as strings
When you have a value from ssl_backend_error(), pass it to the OpenSSL function that matches the kind of failure to get a readable message.
#include <openssl/err.h>
#include <openssl/x509.h>
if (res.error() == httplib::Error::SSLConnection) {
char buf[256];
ERR_error_string_n(res.ssl_backend_error(), buf, sizeof(buf));
std::cerr << "openssl: " << buf << std::endl;
} else if (res.error() == httplib::Error::SSLServerVerification ||
res.error() == httplib::Error::SSLServerHostnameVerification) {
auto code = static_cast<long>(res.ssl_backend_error());
std::cerr << "openssl: " << X509_verify_cert_error_string(code) << std::endl;
}
Common causes
| Symptom | Usual suspect |
|---|---|
SSLServerVerification |
CA certificate path isn't configured, or the cert is self-signed |
SSLServerHostnameVerification |
The cert's CN/SAN doesn't match the host |
SSLConnection |
TLS version mismatch, no shared cipher suite |
To change certificate verification settings, see T02. Control SSL certificate verification.