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.
58 lines
2.6 KiB
Markdown
58 lines
2.6 KiB
Markdown
---
|
|
title: "T02. Control SSL Certificate Verification"
|
|
order: 44
|
|
status: "draft"
|
|
---
|
|
|
|
By default, an HTTPS client verifies the server certificate — it uses the OS root certificate store to check the chain and the hostname. Here are the APIs for changing that behavior.
|
|
|
|
## Specify a custom CA certificate
|
|
|
|
When connecting to a server whose certificate is signed by an internal CA, use `set_ca_cert_path()`.
|
|
|
|
```cpp
|
|
httplib::Client cli("https://internal.example.com");
|
|
cli.set_ca_cert_path("/etc/ssl/certs/internal-ca.pem");
|
|
|
|
auto res = cli.Get("/");
|
|
```
|
|
|
|
The first argument is the CA certificate file; the second is an optional CA directory. With the OpenSSL backend, you can also pass an `X509_STORE*` directly via `set_ca_cert_store()`.
|
|
|
|
Once you set a custom CA, the client trusts only that CA and skips the OS store. To trust both, also call `cli.enable_system_ca(true)`. CA certificates are loaded once, on the client's first connection, so make these settings before the first request.
|
|
|
|
## Disable certificate verification (not recommended)
|
|
|
|
For development servers or self-signed certificates, you can skip verification entirely.
|
|
|
|
```cpp
|
|
httplib::Client cli("https://self-signed.example.com");
|
|
cli.enable_server_certificate_verification(false);
|
|
|
|
auto res = cli.Get("/");
|
|
```
|
|
|
|
That's all it takes to disable chain verification.
|
|
|
|
> **Warning:** Disabling certificate verification removes protection against man-in-the-middle attacks. **Never do this in production.** If you find yourself needing it outside of dev/test, pause and make sure you're not doing something wrong.
|
|
|
|
## Disable hostname verification only
|
|
|
|
There's an in-between option: verify the certificate chain, but skip the hostname check. Useful when you need to reach a server whose cert CN/SAN doesn't match the request's hostname.
|
|
|
|
```cpp
|
|
cli.enable_server_hostname_verification(false);
|
|
```
|
|
|
|
The certificate itself is still validated, so this is safer than fully disabling verification — but still not recommended in production.
|
|
|
|
## Use the OS cert store as-is
|
|
|
|
On most Linux distributions, root certificates live in a single file like `/etc/ssl/certs/ca-certificates.crt`. cpp-httplib loads the OS default store on the client's first connection, so for most servers you don't need to configure anything.
|
|
|
|
> The same APIs work on the mbedTLS and wolfSSL backends. For choosing between backends, see [T01. Choosing between OpenSSL, mbedTLS, and wolfSSL](../t01-tls-backends).
|
|
|
|
> For details on diagnosing failures, see [C18. Handle SSL errors](../c18-ssl-errors).
|
|
|
|
> For TLS configuration on a WebSocket client (`wss://`), see [W05. Configure TLS for wss:// Connections](../w05-websocket-tls).
|