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.2 KiB
title, order, status
| title | order | status |
|---|---|---|
| W05. Configure TLS for wss:// Connections | 56 | 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.
WebSocketClient also has set_server_certificate_verifier() and set_session_verifier() for custom checks, plus the proxy setters (set_proxy(), set_proxy_basic_auth(), set_proxy_bearer_token_auth(), set_proxy_digest_auth(), set_no_proxy()). CA certificates are loaded on the first connect(), so set them before that.
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.