From ae5e1bf398178788d86bf33edd9c5d56bd8784d2 Mon Sep 17 00:00:00 2001 From: Bugs5382 <12115015+Bugs5382@users.noreply.github.com> Date: Sat, 14 Nov 2026 16:23:30 -0500 Subject: [PATCH] docs(security): say that CA keys stay in the TPM and a network HSM is out of scope Closes #42 Signed-off-by: Bugs5382 <12115015+Bugs5382@users.noreply.github.com> --- apps/docs/docs/concepts/tpm-sealed-keys.md | 12 ++++++++++++ apps/site/app/content/trust/controls.ts | 14 ++++++++------ apps/site/app/content/trust/trust.test.ts | 7 +++---- 3 files changed, 23 insertions(+), 10 deletions(-) diff --git a/apps/docs/docs/concepts/tpm-sealed-keys.md b/apps/docs/docs/concepts/tpm-sealed-keys.md index c3b5cdf..3a4922a 100644 --- a/apps/docs/docs/concepts/tpm-sealed-keys.md +++ b/apps/docs/docs/concepts/tpm-sealed-keys.md @@ -96,6 +96,18 @@ The `kms` mode is in the code, but no reference deployment has run it, and the i The node reads `state_key.mode` from the staged config on its first boot, when it formats the state partition. After that it reads the mode from the partition's LUKS2 header on every boot, so the mode chosen at install stays, whatever `STATEKEY` a later image was built with. A `config apply` that names a different `state_key.mode` is refused with `FailedPrecondition` and nothing is stored. To change the mode, reinstall the node. ::: +## A network HSM is out of scope + +CA keys live only in the node's own TPM (or, in the software modes above, on its encrypted state partition). CryptOS does not support keeping a CA key in a network HSM or behind a PKCS#11 device, and it is not planned. + +The reason is the property this page is about: the CA key is made inside the node's TPM and signs there, so no other machine, network path or vendor library ever holds or touches it. An external HSM would add a second custodian for the key and a third-party PKCS#11 module on the signing path, which CryptOS keeps off it. + +`kms` mode is not HSM support. It only has an external key management service encrypt the **state key**, the key that unlocks the state partition. The CA key is still generated in software and stored on that partition, and the KMS never holds it or signs with it. If you need the CA key itself held by an HSM, CryptOS is not the right fit for that CA today. + +:::caution[Do not read `kms` as a way to put the CA key in an HSM] +Pointing `state_key.kms.endpoint` at an HSM-backed KMS protects the disk's unlock key only. The CA key stays in software on the encrypted partition, and `cryptosctl ca export-key` still exports it. +::: + ## What it doesn't do yet - **Sharing a TPM key between nodes.** The key is created so it can't be duplicated to another TPM, so there is no second node that can sign with the same key. diff --git a/apps/site/app/content/trust/controls.ts b/apps/site/app/content/trust/controls.ts index 92fd20f..9b38881 100644 --- a/apps/site/app/content/trust/controls.ts +++ b/apps/site/app/content/trust/controls.ts @@ -272,14 +272,16 @@ export const controls: Control[] = [ area: "keys", title: "No network HSM for CA keys", statement: - "CA keys live only in the node's own TPM; a network HSM or PKCS#11 device for CA keys is out of scope. The kms mode wraps only the state disk's key with an external KMS. Saying so plainly in the docs is planned.", - status: "planned", - evidence: [], - gaps: [ + "CA keys live only in the node's own TPM; a network HSM or PKCS#11 device for CA keys is out of scope. The kms mode wraps only the state disk's key with an external KMS, and keeps the CA key in software.", + status: "not-planned", + reason: + "The CA key is made inside the node's TPM and never leaves it. A network HSM would add a second key custodian and a third-party PKCS#11 module on the signing path, which the node keeps off it.", + evidence: [ { repo: "website", - number: 42, - title: "Say that CA keys stay in the TPM and a network HSM is out of scope", + path: "apps/docs/docs/concepts/tpm-sealed-keys.md", + kind: "doc", + detail: "A network HSM is out of scope", }, ], }, diff --git a/apps/site/app/content/trust/trust.test.ts b/apps/site/app/content/trust/trust.test.ts index 9638a49..f15e746 100644 --- a/apps/site/app/content/trust/trust.test.ts +++ b/apps/site/app/content/trust/trust.test.ts @@ -42,18 +42,17 @@ test("control ids are unique and every control sits in a known area", () => { ); }); -test("the register holds 61 controls: 38 implemented, 8 partial, 11 planned, 4 not planned", () => { +test("the register holds 61 controls: 38 implemented, 8 partial, 10 planned, 5 not planned", () => { assert.deepEqual(countByStatus(controls), { implemented: 38, partial: 8, - planned: 11, - "not-planned": 4, + planned: 10, + "not-planned": 5, }); }); test("each design-intent control is planned and linked to the issue that tracks it", () => { const tracked: Record = { - "KEY-6": "website#42", "AUD-5": "cryptos-node#408", "REC-5": "cryptos-node#407", "SUP-9": "cryptos-node#406",