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 |
|---|---|---|
| T02. Control SSL Certificate Verification | 44 | 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().
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.
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.
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.
For details on diagnosing failures, see C18. Handle SSL errors.
For TLS configuration on a WebSocket client (
wss://), see W05. Configure TLS for wss:// Connections.