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:
yhirose
2026-08-07 17:17:07 -04:00
parent 2dd44d0f52
commit 8f0ff32056
14 changed files with 224 additions and 20 deletions

View File

@@ -0,0 +1,49 @@
---
title: "W05. wss接続でTLSを設定する"
order: 55
status: "draft"
---
`wss://`WebSocket over TLS接続のクライアント側TLS設定は、`SSLClient`とほぼ同じAPIです。`ws::WebSocketClient``ws://``wss://`を同じクラスで扱うので、`SSLClient`のような別クラスへの切り替えは不要です。
```cpp
httplib::ws::WebSocketClient ws1("ws://localhost:8080/ws"); // 平文
httplib::ws::WebSocketClient ws2("wss://localhost:8443/ws"); // TLS
```
## サーバー証明書の検証
`set_ca_cert_path()`で独自のCA証明書を指定できます。シグネチャは`SSLClient`と同じで、第1引数がCA証明書ファイル、第2引数がCA証明書ディレクトリ省略可です。
```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");
}
```
証明書検証そのものを無効にしたい場合は`enable_server_certificate_verification(false)`が使えます。挙動の詳細は[T02. SSL証明書の検証を制御する](../t02-cert-verification)を参照してください。
## クライアント証明書を使うmTLS
`ws::WebSocketClient`には`PemMemory`構造体を受け取るコンストラクタがあり、`wss://`接続でクライアント証明書を提示できます。
```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");
}
```
`ws://`非TLSのURLに`PemMemory`を渡した場合は黙って無視されます。`SSLClient`と違い、ファイルパスから直接読み込むコンストラクタは用意されていないので、PEMをメモリ上に読み込んでから渡す必要があります。
mTLSの全体像サーバー側の設定や用途の解説を含むは[T04. mTLSを設定する](../t04-mtls)を参照してください。