Skip to content

docs(cryptpilot-fde): explain dm-verity/dm-crypt layering order rationale - #135

Merged
imlk0 merged 1 commit into
masterfrom
doc-layering-rationale
Sep 14, 2026
Merged

imlk0 merged 1 commit into
masterfrom
doc-layering-rationale

Conversation

@imlk0

@imlk0 imlk0 commented Sep 14, 2026

Copy link
Copy Markdown
Collaborator

Summary

Adds a design note to the boot architecture docs (cryptpilot-fde/docs/boot.md and boot_zh.md) explaining the layering order of dm-verity and dm-crypt when rootfs encryption is enabled.

Context

When rootfs encryption is enabled, CryptPilot layers dm-crypt below dm-verity (decrypt-then-verify): dm-crypt sits close to the disk (decryption) and dm-verity sits close to the filesystem (verifying plaintext), with the Merkle hash tree built over plaintext.

This order was chosen over the alternative (verity-over-ciphertext, i.e. Encrypt-then-MAC) for two practical reasons:

  1. Key rotation cost — Because the root_hash is computed over plaintext, it is independent of the encryption key. Rotating keys or re-encrypting does not require rebuilding the hash tree.
  2. Multi-tenant remote attestation — A single golden reference value can attest multiple instances that are each encrypted with a different key, which simplifies reference-value management in the confidential-computing multi-tenant scenario.

The note also documents the alternative Encrypt-then-MAC order and its trade-offs (stricter authenticate-before-decrypt composition, but key rotation forces a full hash-tree rebuild and the root_hash becomes key-dependent) for completeness.

Files changed

  • cryptpilot-fde/docs/boot.md — English note
  • cryptpilot-fde/docs/boot_zh.md — Chinese note

Docs-only change; no code or behavior impact.

@ostest-bot

Copy link
Copy Markdown

@imlk0 ,您好,您的请求已接收,请耐心等待结果。

@ostest-bot

Copy link
Copy Markdown

@imlk0 ,您好,未检测到有镜像需要构建,如需重新检测请评论 /start 。

…nale

Add a design note to the boot architecture docs explaining why CryptPilot
layers dm-crypt below dm-verity (decrypt-then-verify, with the hash tree
built over plaintext). The choice is driven by two practical considerations:
key rotation does not require rebuilding the hash tree, and a single reference
value can attest instances encrypted with different keys. Also document the
alternative Encrypt-then-MAC order (verity over ciphertext) and its trade-offs
for completeness.
@imlk0
imlk0 force-pushed the doc-layering-rationale branch from edd4af9 to 95a603b Compare September 14, 2026 03:11
@ostest-bot

Copy link
Copy Markdown

@imlk0 ,您好,您的请求已接收,请耐心等待结果。

@ostest-bot

Copy link
Copy Markdown

@imlk0 ,您好,未检测到有镜像需要构建,如需重新检测请评论 /start 。

@imlk0
imlk0 merged commit 95a603b into master Sep 14, 2026
9 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants