---
title: "HeliosDB Lite v3.5.0 Release Notes"
---

# 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:

```toml
[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
```

```sql
-- 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](https://www.heliosdb.com/docs/lite/features/encryption/).

---

## 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 |

---

## See Also

- [Encryption tutorial](https://www.heliosdb.com/docs/lite/guides/tutorials/encryption_tutorial/) — hands-on walkthrough of encryption at rest
- [features/encryption.md](https://www.heliosdb.com/docs/lite/features/encryption/) — TDE + ZKE reference