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.
1.9 KiB
title, order, status
| title | order | status |
|---|---|---|
| W05. Configure TLS for wss:// Connections | 55 | draft |
Client-side TLS configuration for wss:// (WebSocket over TLS) connections uses almost the same API as SSLClient. ws::WebSocketClient handles both ws:// and wss:// through the same class, so there's no separate class to switch to the way SSLClient requires.
httplib::ws::WebSocketClient ws1("ws://localhost:8080/ws"); // plaintext
httplib::ws::WebSocketClient ws2("wss://localhost:8443/ws"); // TLS
Verifying the server certificate
Use set_ca_cert_path() to point at your own CA certificate. The signature matches SSLClient: the first argument is the CA certificate file, the second is an optional CA directory.
httplib::ws::WebSocketClient ws("wss://internal.example.com/ws");
ws.set_ca_cert_path("/etc/ssl/certs/internal-ca.pem");
if (ws.connect()) {
ws.send("hello");
}
To disable certificate verification entirely, use enable_server_certificate_verification(false). For details on that behavior, see T02. Control SSL Certificate Verification.
Presenting a client certificate (mTLS)
ws::WebSocketClient has a constructor overload that takes a PemMemory struct, letting wss:// connections present a client certificate.
httplib::ws::WebSocketClient::PemMemory pem{};
pem.cert_pem = client_cert.data();
pem.cert_pem_len = client_cert.size();
pem.key_pem = client_key.data();
pem.key_pem_len = client_key.size();
httplib::ws::WebSocketClient ws("wss://api.example.com/ws", pem);
if (ws.connect()) {
ws.send("hello");
}
Passing PemMemory to a ws:// (non-TLS) URL is silently ignored. There's no constructor that reads the cert files directly, so unlike SSLClient you always load the PEM into memory yourself before passing it in.
For the full mTLS picture, including server-side setup and use cases, see T04. Configure mTLS.