8f0ff32056
T04 (mTLS) had grown a "WebSocketClient" subsection describing wss:// client certificates, and c12/t02 were getting similar WebSocketClient asides for timeouts and CA paths. The Cookbook's own index already separates WebSocket into its own category (W01-W04) from TLS/Security (T01-T05) and Client (C01-C19), so burying WebSocketClient specifics inside those pages fought the site's structure. Move that content into two new recipes under the WebSocket category instead: - W05: wss:// TLS setup (set_ca_cert_path CA directory parity, PemMemory client certificate) - W06: WebSocketClient's three timeouts, including the recently added chrono overloads T04, T02, C12, and W01 now carry a single reference link to the new pages instead of duplicated explanations, matching the site's existing cross-link convention. While rewriting T04's client-side section, noticed it documented SSLClient's file-path constructor but not its PemMemory one, even though the server-side section covered both forms for SSLServer. Added the missing PemMemory example so both sides are symmetric.
2.3 KiB
title, order, status
| title | order | status |
|---|---|---|
| T02. Control SSL Certificate Verification | 43 | 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().
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 reads the OS default store at startup, 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.