147 lines
4.4 KiB
Markdown
147 lines
4.4 KiB
Markdown
|
# Shade V3.2 — At-Rest Storage Encryption
|
|||
|
|
|
|||
|
|
**Status:** Implementert (0.4.0) — `@shade/storage-encrypted`, `@shade/keychain`,
|
|||
|
|
`shade migrate-storage`, `shade rotate-storage-key`
|
|||
|
|
**Effort:** L (4–8 uker)
|
|||
|
|
**Forrige:** V3.1
|
|||
|
|
**Adresserer:** V2.1 §2
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Mål
|
|||
|
|
|
|||
|
|
Opt-in beskyttelse av sensitiv state — identity-nøkler, session-state, valgfri
|
|||
|
|
stream-resume-secret — med nøkler som **ikke** ligger i klartekst i databasen.
|
|||
|
|
Trusselmodellen sier i dag eksplisitt at en stjålet DB eksponerer private
|
|||
|
|
nøkler; dette løser det for deploys som velger å aktivere det.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Scope
|
|||
|
|
|
|||
|
|
### Inn
|
|||
|
|
|
|||
|
|
- Ny `EncryptedStorageProvider`-wrapper som dekorerer `SQLiteStorage` /
|
|||
|
|
`PostgresStorage`.
|
|||
|
|
- Per-rad AES-256-GCM på sensitive felter (`identity_*`, `session_*`,
|
|||
|
|
valgfritt `stream_state.streamSecret`).
|
|||
|
|
- KDF-pluggin (default `scrypt` fra `@noble/hashes`) for passphrase-basert
|
|||
|
|
master-nøkkel.
|
|||
|
|
- Tre nøkkelkilder ut av boksen:
|
|||
|
|
1. **Passphrase + KDF** — utvikler oppgir secret ved oppstart.
|
|||
|
|
2. **OS keychain** — macOS Keychain, Linux libsecret, Windows Credential
|
|||
|
|
Vault (Node-only).
|
|||
|
|
3. **App-injected key** — appens egen kode forsyner 32-byte nøkkel (mest
|
|||
|
|
fleksibel).
|
|||
|
|
- Migrasjons-CLI: `shade migrate-storage --encrypt --key-source=...`.
|
|||
|
|
- Trusselmodell-oppdatering: "når enabled, hva er fortsatt udekket" — memory
|
|||
|
|
compromise, swap, runtime-tap.
|
|||
|
|
|
|||
|
|
### Ut
|
|||
|
|
|
|||
|
|
- Browser/IndexedDB at-rest (egen pakke, vurderes etter V3.8).
|
|||
|
|
- HSM/Secure Enclave (separate driver senere).
|
|||
|
|
- "Always-on by default" — vi flyger opt-in for å ikke bryte eksisterende
|
|||
|
|
deploys.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Design
|
|||
|
|
|
|||
|
|
### Krypteringsenhet
|
|||
|
|
|
|||
|
|
- Per-rad AEAD: `nonce(12) || ciphertext || tag(16)`.
|
|||
|
|
- `nonce = HKDF(rowKey, "shade-row-nonce-v1" || tableName || pk)[..12]` —
|
|||
|
|
deterministisk per (tabell, pk) for å unngå nonce-reuse uten å lagre nonce
|
|||
|
|
separat. Endring av (tabell, pk) → re-encryption.
|
|||
|
|
- AAD binder `tableName || columnName || pk` så feltombytting blokkeres.
|
|||
|
|
|
|||
|
|
### Nøkkelhierarki
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
masterKey (fra kilde — passphrase / keychain / app-injected)
|
|||
|
|
│
|
|||
|
|
├─ HKDF("shade-storage-v1") → storageKey (32 bytes)
|
|||
|
|
│ │
|
|||
|
|
│ └─ HKDF(storageKey, table || column) → fieldKey
|
|||
|
|
│
|
|||
|
|
└─ HKDF("shade-storage-version-v1") → versjonsnøkkel (rotasjon)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Migrasjon
|
|||
|
|
|
|||
|
|
1. CLI leser ukryptert DB.
|
|||
|
|
2. Skriver rad-for-rad-kryptering til ny `_v2`-tabell.
|
|||
|
|
3. Atomisk rename + drop gammel.
|
|||
|
|
4. Backup `.bak`-fil etterlatt i samme dir.
|
|||
|
|
|
|||
|
|
### Rotasjon
|
|||
|
|
|
|||
|
|
- `shade rotate-storage-key --new-source=...` re-krypterer med ny masterKey.
|
|||
|
|
- Online ratchet (les med gammel, skriv med ny) for store DB.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Leveranser
|
|||
|
|
|
|||
|
|
### Pakker
|
|||
|
|
|
|||
|
|
- Ny modul: `@shade/storage-encrypted` (re-export over SQLite/PG).
|
|||
|
|
- Utvidelse i `@shade/cli`: `migrate-storage`, `rotate-storage-key`.
|
|||
|
|
- Hjelpe-pakke: `@shade/keychain` (Node-only, valgfri peer-dep) for OS-keychain.
|
|||
|
|
|
|||
|
|
### Tester
|
|||
|
|
|
|||
|
|
- Unit: KDF-derivasjon, nonce-determinisme, AAD-binding.
|
|||
|
|
- Integration: full lifecycle på SQLite + PG; start/stopp; krasj under
|
|||
|
|
migrasjon.
|
|||
|
|
- Tamper: bit-flip i ciphertext / AAD / nonce → dekrypterings-feil.
|
|||
|
|
- Vector-fil: kryss-sjekk masterKey → fieldKey-derivasjon mot
|
|||
|
|
`test-vectors/storage-encryption.json`.
|
|||
|
|
|
|||
|
|
### Dokumentasjon
|
|||
|
|
|
|||
|
|
- `docs/storage-encryption.md` — full guide.
|
|||
|
|
- `THREAT-MODEL.md` — ny kolonne "with at-rest enabled".
|
|||
|
|
- Migrasjonsnotat i `MIGRATION.md`.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Akseptansekriterier
|
|||
|
|
|
|||
|
|
- [ ] Eksisterende ukryptert deploy fortsetter uten endringer (opt-in).
|
|||
|
|
- [ ] `shade migrate-storage --encrypt` migrerer en levende SQLite uten
|
|||
|
|
datatap, verifisert med dump-diff.
|
|||
|
|
- [ ] Rotasjon kan gjøres uten downtime > 5 s for små DB.
|
|||
|
|
- [ ] Wrong passphrase / wrong key → klar feilmelding, ikke krasj.
|
|||
|
|
- [ ] Test-vectors deles med Android-implementasjonen (V3.5 forplikter at
|
|||
|
|
vector-filen kjøres der).
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Avhengigheter
|
|||
|
|
|
|||
|
|
- V3.1 — `THREAT-MODEL.md` skal være lenket til testene først, så vi kan
|
|||
|
|
utvide tabellen.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Risiko
|
|||
|
|
|
|||
|
|
**Datatap.** En migrasjon som krasjer halvveis kan etterlate korrupt DB.
|
|||
|
|
Mitigeres ved:
|
|||
|
|
|
|||
|
|
- Atomic-rename + `.bak`-fil.
|
|||
|
|
- Dry-run-modus (`--dry-run` validerer all dekryptering før skriving).
|
|||
|
|
- Refuser å starte hvis WAL har uncommitted writes.
|
|||
|
|
|
|||
|
|
**Nøkkeltap = totaltap.** Hvis bruker mister passphrase = ingen tilgang.
|
|||
|
|
Dokumenter klart, og pek på V3.10 (Social Recovery) som langtidsløsning.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Migrasjon
|
|||
|
|
|
|||
|
|
0.3.x deploys er ukrypterte → fortsatt ukrypterte. Aktivering er én
|
|||
|
|
CLI-kommando. Backwards-kompatibel.
|