RiddlerChat v2.2 — Technical Slick Sheet
System at a Glance
RiddlerChat v2.2 is a post-quantum, end-to-end encrypted messenger delivered as a dedicated private server per customer. Each customer gets an isolated Google Cloud Run instance plus a Linux desktop binary and an Android APK with that instance's address and access secret baked in. All encryption happens on the user's device using a hybrid ML-KEM-1024 + X25519 double ratchet; the server is a zero-knowledge relay that only ever stores and forwards ciphertext.
Status: Feature-complete for beta on Linux desktop (PyQt6) and Android (Flutter APK). The Shreddar secure-destruction module is the remaining roadmap item.
| Component | Technology | Purpose |
|---|---|---|
| Relay Server | Python 3.12, FastAPI, uvicorn | Ciphertext-only WebSocket relay, port 7576 |
| Desktop Client | PyQt6 + _pq_native C extension + liboqs 0.16.0 | Linux single-file binary (PyInstaller) |
| Android Client | Flutter/Dart + dart:ffi + cross-compiled liboqs | APK for arm64-v8a and x86_64 |
| Legacy Client | Electron 31, Web Crypto API | Classical-only dev client (not in beta) |
| Container | Docker, python:3.12-slim | One image, many customer instances |
| Cloud | GCP Cloud Run + Artifact Registry | One isolated service per customer |
Post-Quantum Native Library: Cross-Compiled liboqs
Real post-quantum cryptography runs as native code in both clients. We build liboqs 0.16.0 from source — the Open Quantum Safe project's C implementation of the NIST FIPS 203 / FIPS 204 algorithms — and bundle it into every customer build.
| Target | Shared Objects | Toolchain | Bridge to App |
|---|---|---|---|
| Linux x86-64 desktop | liboqs.so.0.16.0 + _pq_native.cpython-312-x86_64-linux-gnu.so |
Host GCC/CMake, OQS_USE_OPENSSL=ON |
CPython C extension |
| Android arm64-v8a | liboqs.so + libpq_bridge.so (AArch64 ELF) |
Android NDK cross-compile, OQS_USE_OPENSSL=OFF |
Plain-C FFI bridge → dart:ffi |
| Android x86_64 | liboqs.so + libpq_bridge.so (x86-64 ELF) |
Android NDK cross-compile (emulators, Chromebooks) | Same FFI bridge |
Exposed operations: ML-KEM-1024 keygen, encapsulate, and decapsulate; ML-DSA-87 keygen, sign, and verify.
Compliance note: liboqs implements the algorithms standardized in FIPS 203 (ML-KEM) and FIPS 204 (ML-DSA) at NIST Security Level 5. It is not a CMVP-validated FIPS 140-3 cryptographic module.
Cryptographic Protocol Stack
| Algorithm | Standard | Purpose | Security Level | Key Sizes |
|---|---|---|---|---|
| ML-KEM-1024 | FIPS 203 | Ratchet key encapsulation | Level 5 | PK: 1568 B, SK: 3168 B, CT: 1568 B |
| ML-DSA-87 | FIPS 204 | Per-message signatures | Level 5 | PK: 2592 B, SK: 4896 B, Sig: 4627 B |
| X25519 | RFC 7748 | Classical half of hybrid ratchet | ~128-bit | PK: 32 B |
| AES-256-GCM | SP 800-38D | Message encryption (header as AAD) | 256-bit | Key: 32 B, Nonce: 12 B, Tag: 16 B |
| HKDF-SHA256 / HMAC-SHA256 | RFC 5869 / 2104 | Root and chain KDFs | 256-bit | 32 B outputs |
| Schnorr ZKA + Argon2 | Schnorr 1989 / PHC 2015 | User login | DLP / memory-hard | Commitment only stored |
PQ Hybrid Double Ratchet (Implemented)
The double ratchet is shipping in both the desktop and Android clients, byte-for-byte compatible across Python and Dart.
- Session bootstrap: Each client generates ML-KEM-1024, X25519, and ML-DSA-87 identity keys on device and publishes only the public halves. The initial root key is
HKDF(X25519(id_a, id_b), info="riddlerchat-e2e-init-v2"). - Hybrid ratchet step (on every change of speaking direction): the receiver decapsulates the ML-KEM ciphertext and computes a fresh X25519 DH. Then
HKDF(pq_ss || x_ss, "riddlerchat-pq-ratchet-hybrid")feedsKDF_RK, producing a new root key and chain key. - Symmetric ratchet (every message):
mk = HMAC(ck, 0x01),ck' = HMAC(ck, 0x02). Each message key is used once and discarded. - Encryption: AES-256-GCM with the full ratchet header as associated data. The ciphertext is signed with ML-DSA-87 and verified before decryption.
- Out-of-order delivery: skipped message keys are cached, bounded by
MAX_SKIP.
Security outcome: an attacker must break both ML-KEM-1024 and X25519 to recover a ratchet secret. You get forward secrecy and post-compromise recovery.
Zero-Knowledge Relay Server
- The
Messagemodel has no plaintext field. It storesciphertext,header,signature,sender,recipient,timestamp, andcircuit_idonly. - The server never generates, receives, or holds private keys.
- Contact handshake: messages are relayed only between pairs that have completed a
contact_request→contact_accepthandshake.
Per-Customer Server Deployment
Every customer gets their own isolated stack, created with one command:
./scripts/deploy_instance.sh <customer-name> [image-tag] # e.g. ./scripts/deploy_instance.sh wayne-enterprises v2.2.0
| Phase | What Happens |
|---|---|
| 1. Image | Reuses riddlerchat-backend:<tag> from Artifact Registry, or builds and pushes it |
| 2. Secret | Generates a 256-bit deployment knock unique to this customer |
| 3. Service | gcloud run deploy (512 MiB, 1 vCPU, scale-to-zero) with instance and knock env vars |
| 4. Config | Writes instance.json into client directories |
| 5. Desktop | PyInstaller builds a single-file binary (~80 MB) with liboqs and config baked in |
| 6. Android | Flutter builds APK with baked-in server URL and knock |
Isolation: each customer has a separate Cloud Run service, URL, in-memory user database, contact graph, and message store. No state is shared between customers.
Testing
174 passed, 10 skipped in about 1 second.
| Module | Tests | Coverage |
|---|---|---|
| PQ Double Ratchet | 46 | PQ provider, hybrid ratchet, headers, E2ESession sign/verify/decrypt |
| Double Ratchet (classical) | 31 | X25519/Ed25519 ratchet, KDF chains, signatures, initial key exchange |
| Strategy Pattern | 26 | Interface compliance, auto-detection, runtime switching |
| Security & Tamper | 24 | Ciphertext/nonce/AAD/signature tampering, isolation, entropy |
| E2E Relay | 23 | No plaintext in model/threads, key publication, no server-side private keys |
| Functional Roundtrip | 17 | KEM, hybrid KEX, signing, AES-GCM |
| OQS Provider Integration | 10 | Real ML-KEM-1024 / ML-DSA-87 via OpenSSL provider |
| Python ↔ Dart Interop | 7 (+5 Dart) | HKDF, HMAC, AES-GCM, X25519 vectors match across languages |
Roadmap Status
| Item | Status |
|---|---|
| Zero-knowledge ciphertext relay | Done |
| PQ hybrid double ratchet (ML-KEM-1024 + X25519) | Done |
| ML-DSA-87 per-message signatures | Done |
| Native liboqs: desktop C extension + Android NDK cross-compile | Done |
| Linux desktop client (PyQt6, single binary) | Done (beta) |
| Android client (Flutter APK, arm64-v8a / x86_64) | Done (beta) |
| Per-customer isolated Cloud Run instances | Done |
| Per-customer client builds with baked-in server and secret | Done |
| Deployment port-knock access gate | Done |
| Contact request / accept handshake | Done |
| Instance lifecycle management | Done |
| Shreddar secure-destruction kernel object | Remaining |
| Self-service web portal and Stripe billing | Future |
Defense-in-Depth Summary
| Layer | Mechanism | Protects Against |
|---|---|---|
| Access | Per-customer 256-bit deployment knock | Strangers and scanners reaching the instance |
| Transport | TLS 1.3 (Cloud Run managed) | Network eavesdropping |
| Login | Schnorr ZKA + Argon2 | Password database theft |
| End-to-End | PQ hybrid double ratchet, on device | Server compromise, harvest-now-decrypt-later |
| Encryption | AES-256-GCM, header bound as AAD | Confidentiality and tampering |
| Authenticity | ML-DSA-87 signatures | Forgery and impersonation |
| Verification | SHA-256 key fingerprints | Man-in-the-middle key substitution |
| Isolation | One Cloud Run service per customer | Cross-tenant data exposure |
| Data Destruction | Shreddar (remaining) | Forensic recovery after teardown |