Glossary
Envelope encryption is a two-layer approach where each secret gets its own data encryption key, and that key is wrapped by a master key stored in a key management service.
When HiClaw stores a user's API key or bot token, it generates a unique data encryption key (DEK) using AES-256-GCM with a random initialization vector. The DEK encrypts the secret, then the DEK itself is encrypted (“wrapped”) by a master key in AWS KMS.
The encrypted secret and the wrapped DEK are stored together in DynamoDB. To decrypt, HiClaw sends the wrapped DEK to KMS, gets the plaintext DEK back, and uses it to decrypt the secret. The master key never leaves KMS.
AI assistant platforms store sensitive credentials like API keys for Claude, GPT, or Gemini, plus bot tokens for Telegram and Discord. A database breach without envelope encryption would expose every user's credentials in one shot.
With envelope encryption, an attacker who gains database access only sees ciphertext. They would also need access to KMS to unwrap the data keys, which requires separate IAM permissions that are scoped to specific roles.
Encrypting every secret with a single master key means one compromise exposes everything. Envelope encryption generates a unique data key per secret, then wraps that key with the master. Rotating the master key only re-wraps data keys, not every piece of data.
AES-256-GCM for data encryption with a random initialization vector per operation. The data key itself is encrypted by AWS KMS using a customer-managed key.
All wrapped data keys become permanently undecryptable. HiClaw uses a KMS key with deletion protection and a 30-day waiting period to prevent accidental loss.
