Chapter 11: TLS, HTTPS, WSS

This chapter describes one-way TLS, mutual TLS, test certificates, client validation, and WSS configuration.

1. One-way TLS and mutual TLS

Mode	Configuration	Use
Ordinary HTTPS/WSS	setTLS(cert, key)	Clients verify the server; the server does not require client certificates.
Optional client certificate	five-argument setTLS + Optional	Validate a certificate when supplied but allow clients without one.
Required mTLS	five-argument setTLS + Required	Every client presents a trusted certificate.

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;

    // Configure TLS before startListen(). This is ordinary one-way HTTPS:
    // clients verify the server certificate; the server does not require a
    // client certificate. Use the five-argument overload for explicit 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. Local-only test certificate

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

Self-signed certificates are limited to local testing. Production certificates cover the actual hostname, private keys use restricted permissions, and curl -k is not part of the production configuration.

4. WSS and mTLS

Call setTLS() on WebSocketServer before listening; application callbacks stay unchanged. For required client certificates:

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