第 11 章：TLS、HTTPS 与 WSS

本章说明单向 TLS、mTLS、测试证书、客户端校验和 WSS 的配置方式。

1. 普通 TLS 与双向 TLS

模式	服务端配置	用途
普通 HTTPS/WSS	setTLS(cert, key)	客户端验证服务端；最常见的网站和 API。
可选客户端证书	五参数 setTLS + TLSClientAuthMode::Optional	有证书则校验，无证书也允许。
强制 mTLS	五参数 setTLS + TLSClientAuthMode::Required	服务端验证客户端证书。

2. HTTPS Demo

#include <sttnet.h>

#include <iostream>

int main(int argc, char **argv)
{
    using namespace stt::network;
    using stt::system::ServerSetting;

    if(argc != 3)
    {
        std::cerr << "usage: " << argv[0] << " <server.crt> <server.key>\n";
        return 1;
    }

    if(!ServerSetting::blockTerminationSignals())
        return 2;

    HttpServer server;

    // TLS 配置发生在 startListen() 之前；这里是普通单向 HTTPS：
    // 客户端验证服务端证书，服务端不要求
    // 客户端证书；需要 mTLS 时使用五参数重载。
    if(!server.setTLS(argv[1], argv[2]))
    {
        std::cerr << "failed to load certificate or private key\n";
        return 3;
    }

    server.setFunction("/secure",
        [](HttpServerFDHandler &client, HttpRequestInformation &) {
            return client.sendJson(Json::Value("TLS is active")) ? 1 : -2;
        });

    if(!server.startListen(8443))
    {
        std::cerr << "failed to listen on port 8443\n";
        return 4;
    }

    std::cout << "HTTPS demo listening on https://127.0.0.1:8443/secure\n";
    ServerSetting::waitForTerminationSignal();
    return server.close() ? 0 : 5;
}

3. 生成仅用于本地测试的证书

openssl req -x509 -newkey rsa:2048 -nodes \
  -keyout server.key -out server.crt -days 1 \
  -subj '/CN=localhost' \
  -addext 'subjectAltName=DNS:localhost,IP:127.0.0.1'

./build/examples/sttnet_tls_https server.crt server.key
curl --cacert server.crt https://localhost:8443/secure

自签名证书只适用于本地测试。生产证书覆盖实际域名，私钥采用受限权限保存；curl -k 仅用于定位测试环境问题，不属于生产配置。

4. WSS

WebSocketServer 继承相同 TLS 配置能力。在 startListen() 前调用 setTLS()，业务回调无需改变，客户端 URL 改为 wss://。

5. 客户端证书校验

server.setTLS("server.crt", "server.key", "",
              "client-ca.crt",
              TLSClientAuthMode::Required);

TLS 配置加载失败时服务不会启动。证书热重载只影响后续新连接，已有会话继续使用原上下文。