HeliosDB Lite v3.5.0 Release Notes

Theme: Zero-Knowledge Encryption — client-side keys, server never sees plaintext

Highlights

Most database encryption-at-rest schemes still trust the server to hold the data-encryption key. v3.5.0 adds Zero-Knowledge Encryption (ZKE) — keys are derived and held client-side, attached per-request, and zeroed from memory after use. The server can read ciphertext, validate the key hash, but never sees the plaintext key.

Three operational modes (Full, Hybrid, PerRequest) let you choose how much metadata stays visible while preserving payload secrecy.

What’s New

Client-Side Key Derivation (Argon2)

Authentication and encryption keys are derived separately on the client using Argon2id. Server stores the auth-key hash; the encryption key never touches the wire.

Embedded API change (licensed source distribution); there is no SQL, CLI or REST interface for key derivation.

Per-Request Keys

Each request carries the key in the request payload. Server uses it to decrypt for the duration of the request, then drops the reference.

Key Hash Validation (SHA-256)

The server validates the supplied key against a stored SHA-256 of the key, never the key itself. Invalid keys reject before any decryption attempt.

Nonce-Based Replay Protection

Every encrypted request carries a unique nonce. The server rejects nonces it has already seen within the replay window. Stops captured-and-replayed packets cold.

Memory Zeroization

Key buffers are scrubbed from memory after use (the zeroize crate). Embedded API change (licensed source distribution).

Three ZKE Modes

Mode	Encrypts	Use Case
Full	All data + metadata + index keys	Maximum privacy; opaque to server
Hybrid	Data only; metadata + index keys plaintext	Balance: server can plan queries, payloads stay private
PerRequest	Data only, decryption per request	Server can serve plain SQL; client opts-in for sensitive payloads

How To Enable

ZKE for PostgreSQL wire and REST clients is planned. The key derivation, encryption session, key-hash validation and nonce primitives described above are part of the embedded API (licensed source distribution); the server does not use them yet, and there is no PostgreSQL protocol extension for a ZKE handshake.

The current server accepts the ZKE settings and a per-table marker. They record the intended setting and do not yet change how rows are stored or returned:

[encryption.zke]
enabled = true
mode = "hybrid"            # "full", "hybrid" or "per_request" (default)
require_key_hash = true
replay_protection = true
nonce_window_secs = 300
max_cached_nonces = 10000

-- Mark a table (owner or superuser); DISABLE ZERO KNOWLEDGE ENCRYPTION removes the marker
ALTER TABLE docs ENABLE ZERO KNOWLEDGE ENCRYPTION;

-- Per-table status
SELECT table_name, zke_enabled FROM helios_zke_status;

For encryption at rest that applies to every client today, use TDE; see features/encryption.md.

Migration

Additive feature. Existing TDE (Transparent Data Encryption) deployments keep working unchanged; ZKE is layered on top for users who opt in.

Compatibility

Component	Version
PostgreSQL wire	14, 15, 16, 17
Argon2 (RustCrypto)	latest stable
zeroize	1.x