mirror of
https://github.com/yhirose/cpp-httplib.git
synced 2026-08-25 19:37:15 +00:00
Add WebSocket TLS and timeout recipes to the Cookbook
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.
This commit is contained in:
49
docs-src/pages/en/cookbook/w05-websocket-tls.md
Normal file
49
docs-src/pages/en/cookbook/w05-websocket-tls.md
Normal file
@@ -0,0 +1,49 @@
|
||||
---
|
||||
title: "W05. Configure TLS for wss:// Connections"
|
||||
order: 55
|
||||
status: "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.
|
||||
|
||||
```cpp
|
||||
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.
|
||||
|
||||
```cpp
|
||||
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](../t02-cert-verification).
|
||||
|
||||
## Presenting a client certificate (mTLS)
|
||||
|
||||
`ws::WebSocketClient` has a constructor overload that takes a `PemMemory` struct, letting `wss://` connections present a client certificate.
|
||||
|
||||
```cpp
|
||||
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](../t04-mtls).
|
||||
Reference in New Issue
Block a user