Key Management

How does envelope encryption work?

Areev uses envelope encryption: each user gets a randomly-generated 256-bit Data Encryption Key (DEK), wrapped by the master key via AES-256-GCM. Master keys never encrypt grain data directly — they only wrap DEKs, limiting the blast radius of any single key compromise.

Each wrapped DEK occupies 60 bytes on disk: [nonce:12][ciphertext:32][tag:16]. Areev records a master-rotated-at timestamp on first creation and tracks per-user DEK creation timestamps. Key canaries — encrypted known plaintext — verify that DEKs can still decrypt correctly, catching corruption before it causes data loss.

The autonomous memory engine creates or retrieves a user’s wrapped DEK on first access. The DEK is unwrapped in memory for the duration of the operation and zeroized on drop, ensuring key material does not persist in process memory after use.

import requests

# Key management is transparent — store a grain and the DEK is created automatically
resp = requests.post("https://acme.areev.ai/api/memories/default/add", json={
    "subject": "john", "relation": "likes", "object": "coffee"
})

Where do master keys live?

Areev cloud holds master keys in a managed HSM. The master key is never extractable, never written to disk in clear, and is wrapped with a region-specific KEK that rotates on a separate schedule. Wrapped DEKs are stored alongside the rest of your data in your cell’s encrypted Fjall partition.

You do not configure key material as a cloud customer — Areev provisions, rotates, and audits the master key on your behalf. The control plane records every key-handling event in the hash-chained audit trail, so you can verify rotation history and DEK lifecycle from the Console under Settings → Security → Key history.

LayerWhere it livesRotation
Region KEKHSM (cloud-managed)Quarterly
Master keyHSM, wrapped by region KEKAnnual (or on-demand)
Per-user DEKFjall partition, wrapped by master keyOn master rotation, or on user request
Per-scope DEKFjall partition, wrapped by master keyOn master rotation, or on scope erasure

How does master key rotation work?

Master key rotation re-wraps all DEKs with a new master key using a three-phase commit with rollback journal. The DEKs themselves (and therefore grain data) do not change — only the wrapping changes, making rotation an O(users) operation rather than O(grains).

Phase 1 saves a rollback journal with old wrapped DEKs. Phase 2 writes a rotation marker and the re-wrapped DEKs. Phase 3 swaps the master key and removes the marker and journal. If the process crashes mid-rotation, recovery either rolls back (if journal entries exist) or forward-completes (if the journal was already cleaned up). Areev follows NIST SP 800-57 guidance and rotates the master key annually by default.

Phase 1: Save rollback journal (old wrapped DEKs)
Phase 2: Write rotation marker, then re-wrapped DEKs
Phase 3: Swap master key, remove marker and journal

On failure: Rollback from journal, remove marker
On startup: recover_partial_rotation() detects and fixes partial rotations

How are signing keys managed?

Areev signs grains with COSE Sign1 (RFC 9052) using EdDSA over Ed25519. Signing keys are managed separately from encryption keys, with private seeds and public verifying keys stored independently. The DID is embedded in the COSE header as the key ID; content addressing always uses SHA-256 of the inner .mg blob, never of the COSE envelope.

You can register a signing DID for your organization through the Console under Settings → Security → Signing, or programmatically via POST /api/security/signing/keys. Once registered, Areev can auto-sign all grains in a memory without per-request key specification.