Designing an E2E-Encrypted Terminal Chat in C++17: SRP-6a, HKDF, and a Relay-Blind Server

secret_KK — Wed, 06 May 2026 15:15:51 +0000

There is a class of security properties that most hobby chat implementations simply skip: the server should not be able to read your messages, and authentication should not require trusting the server with a password hash. cmd_chat is a deliberately minimal C++17 implementation that takes both of these seriously — using SRP-6a, HKDF-SHA256, and a Fernet-compatible AEAD scheme — without hiding the mechanics behind a TLS library.

This post is about the design decisions, the trade-offs, and the places where I deliberately kept the implementation simple in ways that a production system would not.

Design Goals and Non-Goals

Goals:

The server relays ciphertext it cannot decrypt. No key material touches the server after authentication.
Authentication is mutual and zero-knowledge. Neither side learns the other's secret; both sides prove they share it.
The crypto stack is auditable in a single afternoon. No opaque abstractions.
Cross-platform: Windows (Winsock2), Linux, macOS — same source tree, CI on all three.

Non-goals (explicitly deferred):

Perfect forward secrecy. All session confidentiality is tied to the room password. An ephemeral ECDH layer per connection would fix this; it is on the roadmap.
TLS transport. The current framing is JSON lines over raw TCP — entirely appropriate for a trusted network or a demo, not appropriate for public deployment without wrapping in TLS.
Persistent storage. The message store is in-memory. Replacing it with SQLite is a small mechanical change that would add no insight here.

System Architecture

cmd_chat_cpp/
├── CMakeLists.txt
├── client/          ← TCP connect, SRP handshake, send/recv threads, UI
├── server/          ← accept loop, per-client threads, in-memory stores, broadcast
└── common/          ← crypto.hpp, base64.hpp, json_io.hpp, uuid.hpp  (header-only)

Transport: Newline-delimited JSON (NDJSON) over raw TCP. One nlohmann::json object per line. The framing is intentionally simple — any JSON parser and nc can participate, which matters for debugging and future language interoperability.

Server threading model: One std::thread per accepted connection, detached. Shared state (MessageStore, UserSessionStore, ConnectionManager, SRPAuthManager) is guarded by per-object mutexes. This is the classic thread-per-connection model: straightforward to reason about, does not scale to thousands of concurrent clients, and is entirely appropriate for the stated scope.

Client threading model: Main thread owns stdin and the send path. A dedicated receive thread runs recv_loop() and updates the display. The two threads share no mutable state beyond the socket handle, which is safe after connection establishment.

Security Design

Client                               Server
  |                                    |
  |--- SRP step 1: username + A ------>|
  |<-- SRP step 2: salt + B -----------|
  |--- SRP step 3: client proof M ---->|
  |<-- SRP step 4: server proof H_AMK -|
  |                                    |
  |  (both sides now hold session_key) |
  |                                    |
  |  room_key = HKDF(session_key,      |
  |                  room_salt,        |
  |                  "room_key")       |
  |                                    |
  |--- Fernet(room_key, plaintext) --->|  ← server sees only opaque base64
  |<-- Fernet(room_key, plaintext) ----|

Layer 1: SRP-6a — Password-Authenticated Key Exchange

SRP is a PAKE: it gives you mutual authentication and a shared session key, and the wire messages are computationally indistinguishable from random to a passive observer who does not know the password. The server stores a verifier v = g^x mod N (where x = H(salt | password)), never the password itself.

The handshake produces session_key = H(A | B | S) independently on both sides, where S is the shared premaster secret. Neither x nor S is ever transmitted.

I used csrp with SRP_NG_2048 and SRP_SHA256. The server creates the verifier once at startup:

srp_create_salted_verification_key(
    SRP_SHA256, SRP_NG_2048, "chat",
    reinterpret_cast<const unsigned char*>(password.data()), password.size(),
    &bytes_s, &len_s, &bytes_v, &len_v, nullptr, nullptr);

One deliberate simplification: all clients authenticate as the identity "chat". The username is a display name only, not a separate credential. This means the SRP verifier is shared across all clients — the password is the room credential, not a per-user one. That is a group chat model, not a user account model.

Layer 2: HKDF-SHA256 — Room Key Derivation

After SRP, every client that authenticated with the same password holds the same session_key. HKDF turns that into a deterministic, domain-separated encryption key:

room_key = HKDF-SHA256(ikm=session_key, salt=room_salt, info="room_key", len=32)

room_salt is 16 bytes of RAND_bytes generated at server startup and transmitted during the auth handshake. The info parameter provides domain separation — if you later derive a MAC key or a different-purpose key from the same IKM, use a different info string and you get an independent key with no relation to room_key.

The implementation in common/crypto.hpp covers both the OpenSSL 3 EVP_KDF API and the legacy EVP_PKEY_derive path, since both are in active use in the wild:

std::vector<uint8_t> hkdf_sha256(
    const std::vector<uint8_t>& ikm,
    const std::vector<uint8_t>& salt,
    const std::string& info,
    size_t out_len);

Layer 3: Fernet-Compatible AEAD — Message Encryption

Each message is encrypted into a Fernet token. The layout is:

token = version(1B 0x80) | timestamp(8B big-endian) | IV(16B) | ciphertext | HMAC-SHA256(32B)

The HMAC covers everything from version through the end of ciphertext. This is encrypt-then-MAC — the MAC is over the ciphertext, not the plaintext, which is what you want for a padding-oracle-resistant scheme. AES-128-CBC with a fresh RAND_bytes IV per message.

The server stores and rebroadcasts the base64-encoded token unchanged. It has no key. It cannot decrypt, forge, or modify a message without the HMAC check failing on the receiving client.

std::string fernet_encrypt(const std::vector<uint8_t>& key, const std::string& plaintext);
std::string fernet_decrypt(const std::vector<uint8_t>& key, const std::string& token);

One honest note: AES-128-CBC is not the current best practice for new designs — AES-256-GCM gives you authenticated encryption natively, without a separate HMAC, and eliminates the IV-reuse-is-catastrophic property of CBC. I used CBC + HMAC to match the Fernet specification precisely and to keep the construction transparent. For a production system, reach for GCM or ChaCha20-Poly1305.

The Wire Protocol

Authentication phase (four round trips):

{"cmd": "srp_init", "username": "alice", "A": "<base64>"}
{"user_id": "<uuid>", "B": "<base64>", "salt": "<hex>", "room_salt": "<base64>"}
{"cmd": "srp_verify", "user_id": "<uuid>", "M": "<base64>"}
{"H_AMK": "<base64>", "session_key": "<base64>"}

Chat phase:

{"type": "init",    "messages": [...], "users": ["alice", "bob"]}
{"type": "message", "text": "<fernet-token>"}
{"type": "message", "username": "alice", "text": "<fernet-token>", "timestamp": "..."}
{"type": "user_joined", "username": "bob"}
{"type": "user_left",   "username": "bob"}

The json_io.hpp helpers handle framing — send appends \n, recv reads until \n:

bool send_json(SOCKET sock, const nlohmann::json& j);
std::optional<nlohmann::json> recv_json(SOCKET sock);

std::optional on recv_json is deliberate — nullopt signals EOF or a parse error, which the caller uses to terminate the connection cleanly rather than entering an invalid state.

Known Limitations Worth Naming

No forward secrecy. If the room password is ever compromised, all past session keys (which are derived from the password via SRP) can be recomputed and all past messages can be decrypted — assuming an adversary recorded the traffic. An ephemeral ECDH exchange per connection would bound the blast radius to that session.

Replay is possible at the SRP layer. The current implementation does not validate that the SRP ephemeral values A and B are fresh across reconnections. A full implementation would include a session nonce in the proof. This is a known omission.

session_key is transmitted but not used for chat crypto. After SRP, the server sends session_key to the client for potential per-session keying. In the current implementation, encrypt_text and decrypt_text use room_key (derived from the password directly), not from session_key. This is documented as a known gap between the README security diagram and the actual implementation — aligning them is a clean next step.

Thread-per-connection does not scale. For the stated use case (small team, trusted network) this is fine. For anything beyond ~100 concurrent connections, io_uring or epoll/kqueue with an event loop would be the right move.

Build and Dependency Management

All C++ dependencies except OpenSSL are fetched at configure time via CMake FetchContent:

FetchContent_Declare(nlohmann_json
    URL https://github.com/nlohmann/json/releases/download/v3.11.3/json.tar.xz)
FetchContent_Declare(csrp
    GIT_REPOSITORY https://github.com/cocagne/csrp.git
    GIT_TAG        15d6bd7)

csrp has no CMakeLists.txt of its own, so it is built manually as a static library after FetchContent_Populate:

add_library(csrp STATIC ${csrp_SOURCE_DIR}/srp.c)
target_link_libraries(csrp PUBLIC OpenSSL::Crypto)

OpenSSL is the only system dependency. CI builds on GitHub Actions cover Windows (Chocolatey), Ubuntu (libssl-dev), and macOS (Homebrew openssl@3).

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j$(nproc)

./build/cmd_chat_server serve 0.0.0.0 9000 --password roomsecret
./build/cmd_chat_client connect 127.0.0.1 9000 alice roomsecret

What I Would Change in a Production Version

AES-256-GCM instead of AES-128-CBC + HMAC. Simpler construction, no padding oracle surface, authenticated natively by the AEAD mode.
Ephemeral ECDH per session (X25519) layered on top of SRP to achieve forward secrecy.
TLS for the transport layer. The current raw TCP is fine for a controlled environment; wrapping with OpenSSL::SSL (or just boringssl) would take the transport threat model off the table.
Per-user credentials. The current single-verifier model makes sense for a shared room but not for a multi-room or multi-tenant system.
io_uring-based event loop on Linux to replace thread-per-connection for anything that needs to scale.

Source

GitHub: double-k-3033/cmd-chat-cpp

The implementation is intentionally small — around 600 lines across all source files — so the full crypto flow is traceable from a single reading session. If you are evaluating PAKE schemes, building a custom secure channel in C++, or just want a working reference for HKDF + Fernet without an opaque wrapper library, it should be useful.

DEV Community: secret_KK