mirror of
https://github.com/yhirose/cpp-httplib.git
synced 2026-10-20 11:29:38 +00:00
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.
52 lines
2.2 KiB
Markdown
52 lines
2.2 KiB
Markdown
---
|
|
title: "W05. Configure TLS for wss:// Connections"
|
|
order: 56
|
|
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).
|
|
|
|
`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.
|
|
|
|
```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).
|