Key Management

How does envelope encryption work?

Areev uses envelope encryption where each user gets a randomly-generated 256-bit Data Encryption Key (DEK) wrapped by the master key via AES-256-GCM. This context database never lets the master key encrypt AI memory data directly — it only wraps DEKs, limiting the blast radius of any single key compromise.

Each wrapped DEK occupies 60 bytes on disk: [nonce:12][ciphertext:32][tag:16]. The KeyManager records a master-rotated-at timestamp on first creation and tracks per-user DEK creation timestamps (user-dek-rotated-at:{user_id}). 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("http://localhost:4009/api/memories/default/add", json={
    "subject": "john", "relation": "likes", "object": "coffee"
})

# Provide the master key at startup
areev serve --http 0.0.0.0:4011 --master-key-env AREEV_MASTER_KEY

Which key store backends does Areev support?

Areev supports four key store backends selectable at startup via --key-backend: Local (Fjall partition, default), Vault Transit (vault feature), AWS KMS (aws-kms feature), and PKCS#11 HSM (pkcs11 feature). Each backend determines where the Customer Master Key (CMK) resides, while DEK storage always uses the local Fjall partition.

Vault supports Token, AppRole, and Kubernetes authentication with automatic background token renewal. AWS KMS uses the standard AWS credential chain with an in-memory DEK cache (default TTL: 300s). PKCS#11 wraps DEKs via HSM AES-GCM — the wrapping key never leaves the hardware. This AI agent memory architecture lets you match the key backend to your infrastructure’s security posture without changing application code.

# Use Vault Transit as the key backend
areev serve --http 0.0.0.0:4011 --key-backend vault \
  --vault-addr https://vault.internal:8200 \
  --vault-token-env VAULT_TOKEN

# Use AWS KMS
areev serve --http 0.0.0.0:4011 --key-backend aws-kms \
  --kms-key-id alias/areev-master

How does master key rotation work?

Master key rotation re-wraps all user DEKs with a new master key using a three-phase commit with rollback journal. The actual DEKs (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, the next startup calls recover_partial_rotation() which either rolls back (if journal entries exist) or forward-completes (if the journal was already cleaned up). This context database follows NIST SP 800-57 guidance, issuing a rotation warning at 80% of the default 365-day key lifetime.

# Rotate the master key
areev rotate-key --new-master-key-env AREEV_NEW_MASTER_KEY

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?

COSE Sign1 Ed25519 signing keys are managed separately via SigningKeyManager (feature: signing). Signing keys are stored under predictable prefixes in the key store, with private seeds and public verifying keys held independently. This AI memory system embeds the DID in the COSE header as the key ID, and content addressing always uses SHA-256 of the inner .mg blob, never of the COSE envelope.

Signed grains use COSE Sign1 (RFC 9052) with the EdDSA algorithm. The signing seed (32-byte Ed25519 private key material) is stored at signing-seed:{did}, the verifying key at verify-key:{did}, and the default DID at signing-did:default. A default DID can be configured for auto-signing all grains without per-request key specification.

# Signature verification is available via CLI
areev signing verify --hash hash123

# Generate a signing key for a DID
areev signing create-key --did "did:key:z6Mk..."

Related

• Encryption: AES-256-GCM encryption and blind indexes
• Crypto-Erasure: Key destruction for GDPR right to erasure
• Configuration: Setting master key and key backend