From 17ccb89b3be82e64dcfb2d586f5c9f4d34e9ebf9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hans-J=C3=BCrgen=20Sch=C3=B6nig?= Date: Wed, 24 Jun 2026 13:55:32 +0200 Subject: [PATCH] docs: highlight encryption-key location, backup, and override (#8) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Addresses #8 — make key custody impossible to miss: - Encryption tutorial + FAQ now state where the local KEK lives (kek.bin in the keyring directory, /keyring; doctor prints the resolved path), warn prominently that losing it makes every backup under it unrecoverable, tell operators to back the keyring directory up separately, and document the PG_HARDSTORAGE_KEYRING_DIR override (the "parameter to change the key dir" the issue asked for already exists as that env var). - Fixed a stale "GCP/Azure/Vault KMS slated for v0.5+" note in the encryption tutorial (those providers ship today) and a missed AES-256-GCM-SIV-as-default line in the FAQ (ships plain AES-256-GCM). Closes #8. --- CHANGELOG.md | 10 +++++++ docs/faq.md | 33 +++++++++++++++++------- docs/tutorials/encryption-walkthrough.md | 19 +++++++++++--- 3 files changed, 50 insertions(+), 12 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5dc9a2f..a940635 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -28,6 +28,16 @@ anchoring, skill signing, and the FIPS image are now clearly marked roadmap. Download / verify examples use a `VERSION` variable so they no longer go stale. +### Documentation: highlight encryption-key custody (#8) + +The encryption tutorial and FAQ now state plainly where the local KEK +lives (`kek.bin` in the keyring directory), that losing it makes every +backup under it unrecoverable, that the keyring directory must be backed +up separately from the repository, and that `PG_HARDSTORAGE_KEYRING_DIR` +overrides its location (with `pg_hardstorage doctor` reporting the +resolved path). Also corrected a stale "GCP/Azure/Vault KMS slated for +v0.5+" note (those providers ship today). + ### Packaging: wire container-image publishing (GHCR) The release pipeline can now build and publish multi-arch (amd64/arm64) diff --git a/docs/faq.md b/docs/faq.md index e5e7616..5b40807 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -329,11 +329,25 @@ guidance and sizing rules of thumb. #### Where is the KEK stored? -Wherever you point the encryption plugin: AWS KMS, GCP -KMS, Azure Key Vault, HashiCorp Vault Transit, or — for -single-host dev — an `aes-256-gcm` keyring directory. -HSM (PKCS#11) lands in the v1.0 build flavour. Reference: -[KEKRef schemes](reference/cli/pg_hardstorage_kms.md); +With a cloud KMS scheme (AWS KMS, GCP KMS, Azure Key +Vault, HashiCorp Vault Transit) the KEK never leaves the +provider — pg_hardstorage only stores a reference. With the +local `aes-256-gcm` scheme the KEK is a 32-byte file, +`kek.bin`, in the **keyring directory** (`/keyring` +— e.g. `/etc/pg_hardstorage/keyring` for a system install, +under your user config dir otherwise). Run `pg_hardstorage +doctor` for the resolved path; override it with the +`PG_HARDSTORAGE_KEYRING_DIR` environment variable. HSM +(PKCS#11) is available in the `pkcs11` / FIPS build flavour. + +!!! danger "Back up your local KEK" + `kek.bin` unwraps every backup made under it. If you + lose the keyring directory you **cannot restore** — back + it up separately from the repository, or use a cloud KMS + scheme so custody isn't a single local file. The signing + keypair lives in the same directory. + +Reference: [KEKRef schemes](reference/kekref-schemes.md); explanation: [envelope encryption](explanation/envelope-encryption.md). @@ -361,10 +375,11 @@ and #### What encryption algorithm does pg_hardstorage use? -AES-256-GCM-SIV (RFC 8452, nonce-misuse resistant) by -default. AES-256-GCM with a random 96-bit nonce in FIPS -mode (BoringCrypto's FIPS module doesn't yet ship GCM-SIV -acceleration). Per-chunk key derived as +AES-256-GCM (random 96-bit nonce) is the cipher shipping +today; AES-256-GCM-SIV (RFC 8452, nonce-misuse resistant) +is the planned default once a validated implementation +lands (the Go standard library and BoringCrypto's FIPS +module don't ship GCM-SIV). Per-chunk key derived as `HKDF-SHA256(BDEK, info=chunk_hash)`; see [envelope encryption](explanation/envelope-encryption.md). diff --git a/docs/tutorials/encryption-walkthrough.md b/docs/tutorials/encryption-walkthrough.md index 58f066c..2dfe870 100644 --- a/docs/tutorials/encryption-walkthrough.md +++ b/docs/tutorials/encryption-walkthrough.md @@ -26,9 +26,22 @@ copy lands in the manifest. There are two KEK schemes shipped today: `KMS:Encrypt` / `KMS:Decrypt` against the configured key. Good for fleets that already centralise key custody. -Other cloud KMS providers (`gcp-kms://`, `azure-key-vault://`, -`vault-transit://`) are slated for v0.5+; `kms shred`, -`kms rotate`, and PKCS#11 / TPM2 binding land in the same window. +GCP KMS (`gcp-kms://`), Azure Key Vault (`azure-key-vault://`), and +HashiCorp Vault Transit (`vault-transit://`) ship as well, and +`kms shred` (crypto-shred) is available today. PKCS#11 / TPM2 (HSM) +binding ships in the `pkcs11` / FIPS build flavour. + +!!! danger "Back up your keys — you cannot restore without them" + With the local `local:default` scheme, `kek.bin` in the keyring + directory unwraps **every** backup. Lose the keyring directory and + your encrypted backups are **mathematically unrecoverable** — the + same effect `kms shred` produces on purpose. Find the resolved path + with `pg_hardstorage doctor`, override it with the + `PG_HARDSTORAGE_KEYRING_DIR` environment variable, and **back the + keyring directory up separately from the repository**, with at least + the care you'd give a database password. The Ed25519 signing keypair + lives in the same directory. For production, prefer a cloud KMS + scheme so key custody isn't a single local file. ---