Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions .changeset/rotate-encryption-key.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
'@crypt.fyi/core': minor
'@crypt.fyi/server': minor
---

Allow rotating the server's `ENCRYPTION_KEY` without losing unexpired secrets. Data encrypted or digested at rest now records which key wrote it, and the new `ENCRYPTION_PREVIOUS_KEYS` setting keeps old keys available for reads. A new `rotate-keys` command re-encrypts existing entries with the new key and reports when the old key can be removed. Core adds `machine.createKeyring` and keyring-based encrypt, decrypt and digest functions, and `machine.isEncrypted` and `machine.isDigest` also recognise the new formats.
22 changes: 20 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -85,7 +85,25 @@
API_URL=https://{your-domain-here} ENCRYPTION_KEY=$(openssl rand -base64 32) docker compose up --build
```

`ENCRYPTION_KEY` protects verification hashes, delete tokens, IP restrictions and webhook URLs at rest in Redis. Keep it stable across restarts (e.g. in a `.env` file next to `docker-compose.yaml`); changing it makes all existing secrets unreadable until they expire.
`ENCRYPTION_KEY` protects verification hashes, delete tokens, IP restrictions and webhook URLs at rest in Redis. Keep it stable across restarts (e.g. in a `.env` file next to `docker-compose.yaml`). Replacing it outright makes all existing secrets unreadable until they expire; to change it without losing any, follow [Rotating `ENCRYPTION_KEY`](#rotating-encryption_key).

#### Rotating `ENCRYPTION_KEY`

The server holds a keyring: `ENCRYPTION_KEY` is the primary key, used for every new write, and `ENCRYPTION_PREVIOUS_KEYS` is a comma-separated list of older keys that are only used to read existing entries. Everything written at rest records which key wrote it, so the server picks the right key on each read.

1. **Generate a new key:** `openssl rand -base64 32`.
2. **Multiple server instances only: make the new key known everywhere first.** Add the new key to `ENCRYPTION_PREVIOUS_KEYS` on every instance and roll them all out. Otherwise an instance that already writes with the new key can produce entries that an instance still on the old configuration can't read. A single instance can skip this step.
3. **Promote the new key.** Set `ENCRYPTION_KEY` to the new key and move the old key to `ENCRYPTION_PREVIOUS_KEYS`, then restart every instance. The startup log line `Loaded encryption keyring` shows how many previous keys each instance loaded.
4. **Re-encrypt existing entries.** With the same environment as the server, run:

```bash
docker compose exec server node packages/server/dist/rotate-keys.js
```

(`pnpm --filter @crypt.fyi/server keys:rotate` outside Docker; add `--dry-run` to report without writing.) It re-encrypts IP restrictions, webhook URLs and delete tokens with the new key, keeping each entry's TTL and never overwriting a concurrent read or burn. It's safe to run repeatedly while the server takes traffic. Verification-hash digests can't be re-keyed, because the server never learns the hash itself, so entries created before step 3 keep needing the old key until they expire. The report's `previousKeysNeededUntil` says when that is (at most the max TTL, 7 days by default).
5. **Retire the old key.** After `previousKeysNeededUntil` has passed, run the command again. Once it reports `"safeToRemovePreviousKeys": true` (no entry or queued webhook depends on a previous key), remove the old key from `ENCRYPTION_PREVIOUS_KEYS` and restart.

If the old key leaked, you can shorten step 5, but removing it before `previousKeysNeededUntil` makes the remaining older secrets unreadable. Entries already re-encrypted in step 4 no longer expose their IP restrictions, webhook URLs or delete tokens to the old key. A non-zero `unreadable` count in the report means an entry was written with a key that is no longer configured; its secret can't be recovered unless you add that key back.

`API_URL` is read when the web container starts, so changing it only needs a restart (`docker compose up -d`), not a rebuild. It must be a plain `http(s)://host[:port][/path]` URL; the container refuses to start otherwise.

Expand All @@ -95,7 +113,7 @@ A prebuilt API server image (`linux/amd64`, `linux/arm64`) is published to GHCR
docker pull ghcr.io/osbytes/crypt.fyi-server:latest
```

It runs with `NODE_ENV=production` and requires `REDIS_URL` and `ENCRYPTION_KEY`.
It runs with `NODE_ENV=production` and requires `REDIS_URL` and `ENCRYPTION_KEY` (plus `ENCRYPTION_PREVIOUS_KEYS` while [rotating it](#rotating-encryption_key)).

The web client image is not published to GHCR yet; build it with `docker compose` as above.

Expand Down
18 changes: 17 additions & 1 deletion SPECIFICATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -302,6 +302,20 @@ Abstract
alone cannot be replayed to read or burn an entry
- Delete tokens MUST NOT be stored in plaintext; servers MUST store them
encrypted so they can be returned in webhook payloads
- The server-side key that protects these values MUST be rotatable without
making unexpired entries unreadable. Servers SHOULD hold a keyring of one
primary key, used for all new writes, and previous keys used only for
reads, and SHOULD tag each stored ciphertext and digest with the id of
the key that produced it. The reference implementation uses
`m2:<kid>:` ciphertexts (AES-256-GCM with an HKDF-derived key, the header
bound as associated data) and `hm2:<kid>:` HMAC-SHA-256 digests, where
`kid` is derived from the key itself. Encrypted values SHOULD be
re-encrypted with the primary key after a rotation. Digests cannot be
re-keyed without the original hash, so a previous key MUST stay loaded
until every entry digested with it has expired, which the maximum TTL
bounds
- A read MUST fail without consuming a failed attempt when the entry's key
is not loaded, so a misconfigured keyring cannot burn entries

### 6.3. Access Control

Expand Down Expand Up @@ -378,7 +392,9 @@ Abstract

Key configuration parameters:
- `REDIS_URL`: Redis connection string
- `ENCRYPTION_KEY`: Server-side encryption key for metadata
- `ENCRYPTION_KEY`: Server-side encryption key for metadata (primary key)
- `ENCRYPTION_PREVIOUS_KEYS`: Comma-separated previous keys, accepted for
reads only while rotating `ENCRYPTION_KEY`
- `RATE_LIMIT_MAX`: Maximum requests per time window
- `BODY_LIMIT_BYTES`: Maximum request body size
- `CORS_ORIGIN`: Allowed CORS origins
Expand Down
2 changes: 2 additions & 0 deletions docker-compose.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,8 @@ services:
- PORT=${SERVER_PORT:-4321}
# Protects verification hashes, delete tokens, IP restrictions and webhook URLs at rest in Redis.
- ENCRYPTION_KEY=${ENCRYPTION_KEY:?ENCRYPTION_KEY is required (e.g. openssl rand -base64 32)}
# Comma-separated keys kept for reading existing entries while rotating ENCRYPTION_KEY (see README).
- ENCRYPTION_PREVIOUS_KEYS=${ENCRYPTION_PREVIOUS_KEYS:-}
ports:
- '${SERVER_PORT:-4321}:${SERVER_PORT:-4321}'
depends_on:
Expand Down
120 changes: 119 additions & 1 deletion packages/core/src/encryption/machine.test.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,20 @@
import { encrypt, decrypt, digest, isDigest, isEncrypted } from './machine';
import {
encrypt,
decrypt,
digest,
isDigest,
isEncrypted,
keyId,
keyIdOf,
createKeyring,
encryptWithKeyring,
decryptWithKeyring,
digestWithKeyring,
digestCandidates,
hasPreviousKeys,
isOnPrimaryKey,
} from './machine';
import { DecryptError } from './encryption';
import { encrypt as gcmEncrypt } from './gcm';

describe('machine digest', () => {
Expand Down Expand Up @@ -57,3 +73,105 @@ describe('machine cipher', () => {
expect(await decrypt(legacy, key)).toBe(plaintext);
});
});

describe('machine keyring', () => {
const oldKey = 'old-high-entropy-machine-key-0123456789';
const newKey = 'new-high-entropy-machine-key-9876543210';
const before = createKeyring(oldKey);
const rotating = createKeyring(newKey, [oldKey]);
const after = createKeyring(newKey);

it('derives a stable, url-safe id that does not contain the key', () => {
expect(keyId(oldKey)).toBe(keyId(oldKey));
expect(keyId(oldKey)).not.toBe(keyId(newKey));
expect(keyId(oldKey)).toMatch(/^[A-Za-z0-9_-]{8}$/);
expect(oldKey).not.toContain(keyId(oldKey));
});

it('uses the first key as primary and ignores duplicates and blanks', () => {
const keyring = createKeyring(newKey, [oldKey, newKey, '']);
expect(keyring.primaryId).toBe(keyId(newKey));
expect([...keyring.keys.keys()]).toEqual([keyId(newKey), keyId(oldKey)]);
expect(() => createKeyring('')).toThrow();
});

it('tags ciphertext with the primary key id', async () => {
const enc = await encryptWithKeyring('secret', rotating);
expect(enc.startsWith(`m2:${keyId(newKey)}:`)).toBe(true);
expect(isEncrypted(enc)).toBe(true);
expect(keyIdOf(enc)).toBe(keyId(newKey));
expect(enc).not.toContain('secret');
});

it('reads values written before a rotation while writing with the new key', async () => {
const written = await encryptWithKeyring('secret', before);
expect(await decryptWithKeyring(written, rotating)).toBe('secret');
expect(keyIdOf(await encryptWithKeyring('secret', rotating))).toBe(keyId(newKey));
});

it('fails once the key a value was written with is removed', async () => {
const written = await encryptWithKeyring('secret', before);
await expect(decryptWithKeyring(written, after)).rejects.toThrow();
});

it('rejects a ciphertext relabelled with another key id', async () => {
const written = await encryptWithKeyring('secret', before);
const relabelled = written.replace(keyId(oldKey), keyId(newKey));
await expect(decryptWithKeyring(relabelled, rotating)).rejects.toThrow();
});

it('reads m1 and legacy PBKDF2 values under any key in the ring', async () => {
const m1 = await encrypt('m1 value', oldKey);
const legacy = await gcmEncrypt('legacy value', oldKey);
expect(await decryptWithKeyring(m1, rotating)).toBe('m1 value');
expect(await decryptWithKeyring(legacy, rotating)).toBe('legacy value');
await expect(decryptWithKeyring(m1, after)).rejects.toThrow();
});

it('digests with the primary key and tags the digest', () => {
const d = digestWithKeyring('value', rotating, 'ctx');
expect(d.startsWith(`hm2:${keyId(newKey)}:`)).toBe(true);
expect(isDigest(d)).toBe(true);
expect(d).toBe(digestWithKeyring('value', after, 'ctx'));
expect(d).not.toBe(digestWithKeyring('value', before, 'ctx'));
});

it('matches stored digests by the key they name', () => {
const stored = digestWithKeyring('value', before, 'ctx');
expect(digestCandidates(stored, 'value', rotating, 'ctx')).toEqual([stored]);
expect(digestCandidates(stored, 'other', rotating, 'ctx')).not.toContain(stored);
expect(digestCandidates(stored, 'value', after, 'ctx')).toEqual([]);
});

it('matches hm1 digests under any key and passes pre-digest values through', () => {
const hm1 = digest('value', oldKey, 'ctx');
expect(digestCandidates(hm1, 'value', rotating, 'ctx')).toContain(hm1);
expect(digestCandidates(hm1, 'value', after, 'ctx')).not.toContain(hm1);
expect(digestCandidates('abc123', 'abc123', rotating, 'ctx')).toEqual(['abc123']);
});

it('rejects values that cannot be ciphertext without trying each key', async () => {
await expect(decryptWithKeyring('192.168.1.1,10.0.0.0/24', rotating)).rejects.toThrow(
DecryptError,
);
await expect(decryptWithKeyring('::1', rotating)).rejects.toThrow(DecryptError);
});

it('tells whether a value was written with the primary key', async () => {
expect(await isOnPrimaryKey(await encryptWithKeyring('x', rotating), rotating)).toBe(true);
expect(await isOnPrimaryKey(await encryptWithKeyring('x', before), rotating)).toBe(false);
expect(await isOnPrimaryKey(await encrypt('x', newKey), rotating)).toBe(true);
expect(await isOnPrimaryKey(await encrypt('x', oldKey), rotating)).toBe(false);
});

it('reports whether a keyring holds previous keys', () => {
expect(hasPreviousKeys(rotating)).toBe(true);
expect(hasPreviousKeys(after)).toBe(false);
expect(hasPreviousKeys(createKeyring(newKey, [newKey]))).toBe(false);
});

it('never accepts the stored digest itself as the value', () => {
const stored = digestWithKeyring('value', rotating, 'ctx');
expect(digestCandidates(stored, stored, rotating, 'ctx')).not.toContain(stored);
});
});
Loading
Loading