alkdev/alknet
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(architecture): add ADR-021, resolve OQ-22 — key rotation via version-indexed paths

Browse Source 
Key rotation uses version-indexed derivation paths: each key version maps
to a distinct SLIP-0010 path (m/74'/2'/0'/{version-2}'). v2 is at index 0
(PATHS::ENCRYPTION), v3 at index 1, etc.

Mechanism:
- encryption_path_for_version(version) constructs the path
- decrypt derives the key at the version-indicated path (not always
  PATHS::ENCRYPTION)
- rotate(blob, to_version) decrypts with old key, re-encrypts with new
- No new mnemonic needed — same seed, different path
- Partial rotation is safe — old keys remain derivable
- The vault does not self-rotate; the assembly layer iterates blobs

Source drift flagged:
- decrypt currently ignores key_version for path selection (always uses
  PATHS::ENCRYPTION) — must use version-indexed paths
- rotate method does not exist in source — must be added
- CURRENT_KEY_VERSION must bump from 1 to 2 (per ADR-020, reinforced here)

OQ-22 resolved. Only OQ-21 (remote vault admin, deferred) remains.
This commit is contained in:
glm-5.2
2026-06-19 10:09:20 +00:00
parent 6e9414bc81
commit dc27753680
8 changed files with 332 additions and 70 deletions
Download Patch File Download Diff File Expand all files Collapse all files

253
docs/architecture/decisions/021-key-rotation-via-version-indexed-paths.md Normal file
View File

@@ -0,0 +1,253 @@
# ADR-021: Key Rotation via Version-Indexed Derivation Paths
## Status
Accepted
## Context
ADR-020 established that the vault derives the AES-256-GCM encryption key
from the BIP39 seed via SLIP-0010 HD derivation at path `m/74'/2'/0'/0'`.
The `EncryptedData.key_version` field exists for rotation tracking, but
the current implementation always derives at the same path regardless of
version — `key_version` is metadata, not a functional selector.
OQ-22 asked: how does key rotation work? The key versioning is in place,
but the rotation mechanism — how a new key is derived, how existing data
is re-encrypted, and how the vault selects the right key for decryption —
is not specified.
### Why rotation matters
Key rotation is a fundamental security hygiene practice. The scenarios
that require it:
1. **Suspected key compromise**: the encryption key may have leaked
(memory dump, process compromise, log accident). All data encrypted
with that key must be re-encrypted with a new key.
2. **Periodic rotation**: security policy mandates key rotation every N
months. The vault must support this without re-deriving from a new
mnemonic (which would require re-deploying all nodes).
3. **Version transition**: moving from TS PBKDF2 data (v1) to vault HD
data (v2, per ADR-020) is itself a rotation. The mechanism should
generalize — it's the same operation.
### What "rotation" means concretely
Rotating from key version N to N+1:
1. Derive a new encryption key at a new derivation path
2. For each existing `EncryptedData` blob with `key_version: N`:
- Decrypt with the v-N key
- Re-encrypt the plaintext with the v-(N+1) key
- Replace the blob in storage with `key_version: N+1`
3. New encryptions use `key_version: N+1`
4. Old keys remain available for decrypting any data that hasn't been
rotated yet (partial rotation is safe)
The question is: **how is the new key derived?** The options:
- **Option A: New derivation path per version.** `m/74'/2'/0'/0'` for v2,
`m/74'/2'/0'/1'` for v3, etc. Each version gets its own HD key. No
new seed needed.
- **Option B: New mnemonic (new seed).** Generate a new mnemonic, unlock
with it, re-encrypt everything. This is heavy — it changes *all* derived
keys (identity, SSH host, etc.), not just the encryption key.
- **Option C: KDF from the existing key.** Use HKDF or PBKDF2 with the
existing derived key + the salt as input. This is the salt field's
potential use (OQ-20 mentioned this), but it adds KDF complexity and
the salt becomes load-bearing.
## Decision
### 1. Version-indexed derivation paths
Each key version maps to a unique derivation path. The last hardened index
in the encryption path is the key version:
```
v2: m/74'/2'/0'/0' ← PATHS::ENCRYPTION (current)
v3: m/74'/2'/0'/1'
v4: m/74'/2'/0'/2'
...
```
The `encryption_path_for_version(version)` function constructs the path:
```rust
pub fn encryption_path_for_version(version: u32) -> String {
// v1 is the TS PBKDF2 legacy — not an HD path. The vault starts at v2.
// v2 → m/74'/2'/0'/0', v3 → m/74'/2'/0'/1', etc.
let index = version.saturating_sub(2);
format!("m/74'/2'/0'/{}'", index)
}
```
`PATHS::ENCRYPTION` remains `m/74'/2'/0'/0'` — it's the v2 path, and v2
is the current version. When the vault is rotated to v3,
`encryption_path_for_version(3)` produces `m/74'/2'/0'/1'`.
This means:
- No new mnemonic needed — rotation uses the same seed, different path
- Each version's key is cryptographically independent (HD derivation
ensures this)
- The derivation path is self-documenting (`m/74'/2'/0'/1'` is clearly
"encryption key, version 3")
- Old keys are always derivable (the seed doesn't change), so partial
rotation is safe — the vault can decrypt any version
### 2. `encrypt_key(version)` and `decrypt_key(version)` methods
The `VaultServiceHandle` gains version-aware key derivation:
```rust
impl VaultServiceHandle {
/// Derive the encryption key for the given version. Cached.
fn derive_encryption_key_for_version(
&self,
version: u32,
) -> Result<EncryptionKey, VaultServiceError> {
let path = encryption_path_for_version(version);
// ... derive at path, cache by path ...
}
/// Encrypt with the current key version.
pub fn encrypt(&self, plaintext: &str, key_version: u32) -> Result<EncryptedData, VaultServiceError>;
/// Decrypt by deriving the key at the version indicated by the blob.
pub fn decrypt(&self, encrypted: &EncryptedData) -> Result<String, VaultServiceError> {
let key = self.derive_encryption_key_for_version(encrypted.key_version)?;
encryption::decrypt(encrypted, &key)
}
}
```
`decrypt` now derives the key at the path **indicated by
`encrypted.key_version`** — not always at `PATHS::ENCRYPTION`. This is
the fix for the W1 drift issue from the vault review: the current source
ignores `key_version` for key selection; the spec now makes it functional.
### 3. `rotate` method
```rust
impl VaultServiceHandle {
/// Re-encrypt an EncryptedData blob from one key version to another.
///
/// Decrypts with the key at the blob's current key_version,
/// re-encrypts with the key at `to_version`. Returns the new
/// EncryptedData. Does not update storage — the caller replaces the
/// blob in storage.
pub fn rotate(
&self,
encrypted: &EncryptedData,
to_version: u32,
) -> Result<EncryptedData, VaultServiceError> {
let plaintext = self.decrypt(encrypted)?;
self.encrypt(&plaintext, to_version)
}
}
```
`rotate` is a vault method, not a storage operation. It decrypts and
re-encrypts; the caller (the assembly layer or a migration tool) handles
replacing the blob in storage. This keeps the vault focused on crypto and
the storage system focused on storage.
### 4. `CURRENT_KEY_VERSION` and rotation policy
```rust
pub const CURRENT_KEY_VERSION: u32 = 2;
```
`encrypt()` stamps `CURRENT_KEY_VERSION` (or the explicitly-passed version)
onto new `EncryptedData` blobs. The assembly layer decides when to rotate:
- **Manual rotation**: an operator triggers rotation (e.g., a CLI command
`alknet vault rotate --to v3` that loads all blobs, calls `rotate` on
each, and writes them back to storage).
- **No automatic rotation**: the vault does not self-rotate. Rotation is
an operational action, not a runtime behavior. The vault provides the
mechanism; the policy is external.
### 5. Cache implications
The `KeyCache` is keyed by derivation path. Since each version has a
distinct path, the cache naturally holds multiple versions simultaneously.
This is correct — during a rotation, the vault may need to decrypt old
blobs (v2) and encrypt new blobs (v3), and both keys should be cached.
The cache's TTL and LRU eviction still apply. If the cache evicts an old
version's key during a long rotation, the next `decrypt` of an old blob
re-derives it (the seed hasn't changed). This is correct but slightly
slower — the rotation tool should be aware that cache misses on old keys
are expected.
## Consequences
**Positive:**
- Key rotation is a vault method (`rotate`), not a storage operation or a
full mnemonic change. It's cheap (HD derivation) and local.
- Partial rotation is safe. Old and new keys coexist — the vault can
decrypt any version. This means a rotation can be performed incrementally
(rotate some blobs, verify, rotate the rest).
- No new mnemonic needed. The same seed produces all version keys. A
backup node with the same mnemonic can decrypt any version.
- The derivation path is self-documenting. `m/74'/2'/0'/1'` is clearly
"encryption key version 3."
- The `salt` field remains unused — no KDF complexity. Rotation is pure HD
path indexing.
- The mechanism generalizes the TS→vault migration (v1→v2 is a rotation,
though v1 requires the TS PBKDF2 `decrypt`, not the vault's `decrypt`).
**Negative:**
- `decrypt` now derives the key at the version-indicated path, which means
a cache miss on an old version re-derives from the seed. This is a few
HMAC operations — negligible, but the path construction and cache lookup
add a small amount of complexity over the current "always use
`PATHS::ENCRYPTION`" approach.
- The rotation tool (CLI command or migration script) must iterate all
stored blobs and call `rotate` on each. This is an operational concern,
not a vault concern — but the vault spec should document the expected
usage pattern so the tool implementer knows the contract.
- Old version keys are always derivable (the seed doesn't change). This is
a feature (partial rotation is safe) but also means a compromised seed
allows decrypting all versions. If the seed itself is compromised, all
versions are compromised — rotation doesn't help. This is inherent to
HD derivation and not specific to this design.
## Assumptions
1. **The seed is not compromised.** If the seed is compromised, rotating
the encryption key path doesn't help — the attacker can derive all
version keys. Seed compromise requires a full mnemonic change (new
seed, re-derive everything, re-deploy). This ADR covers encryption key
rotation, not seed rotation. Seed rotation is an operational procedure
(generate new mnemonic, unlock with it, re-encrypt all data) that is
outside the vault's API.
2. **Rotation is infrequent.** The vault does not optimize for frequent
rotation (e.g., per-request key derivation). Rotation is an operational
event triggered by policy or incident. The cache and path-indexed
approach are efficient for this usage pattern.
3. **The storage system tracks which blobs to rotate.** The vault's `rotate`
method handles one blob at a time. Iterating all stored
`EncryptedData` blobs is the storage system's job (or the CLI's). The
vault doesn't know what's in storage — it only knows how to rotate a
blob it's given.
4. **v1 (TS PBKDF2) data is not rotated through the vault.** v1 data is
decrypted by the TS `decrypt()` function (PBKDF2), not the vault's
`decrypt()` (which uses HD derivation). The v1→v2 migration is a
separate tool that has access to both. Once data is at v2, future
rotations (v2→v3, etc.) use the vault's `rotate` method.
## References
- ADR-020: HD derivation for encryption keys (this ADR builds on the
version-indexed path scheme)
- OQ-22: Key rotation mechanism (resolved by this ADR)
- [encryption.md](../crates/vault/encryption.md) — AES-256-GCM, EncryptedData
- [service.md](../crates/vault/service.md) — encrypt, decrypt, rotate methods
- [mnemonic-derivation.md](../crates/vault/mnemonic-derivation.md) —
derivation paths, `PATHS::ENCRYPTION`