mirror of
https://github.com/yhirose/cpp-httplib.git
synced 2026-10-19 11:19:36 +00:00
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.
60 lines
2.6 KiB
Markdown
60 lines
2.6 KiB
Markdown
---
|
|
title: "C18. Handle SSL Errors"
|
|
order: 18
|
|
status: "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
|
|
|
|
```cpp
|
|
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.
|
|
|
|
```cpp
|
|
#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](../t02-cert-verification).
|