diff --git a/cryptpilot-fde/docs/quick-start.md b/cryptpilot-fde/docs/quick-start.md index 256f33a..73bb3a1 100644 --- a/cryptpilot-fde/docs/quick-start.md +++ b/cryptpilot-fde/docs/quick-start.md @@ -207,7 +207,89 @@ This configuration is suitable for: - ✅ Want to reduce decryption performance overhead for rootfs - ❌ Not suitable when rootfs contains sensitive configurations or keys -## Example 3: Encrypt a Real System Disk +### Calculate Reference Values + +Calculate reference values for measure-only mode: + +```sh +cryptpilot-fde show-reference-value --disk ./encrypted.qcow2 +``` + +The output contains multiple measurement values (kernel, initrd, cmdline, etc.), all of which need to be imported to RVPS. + +## Example 3: Measure-Only rootfs + UKI Mode + +UKI (Unified Kernel Image) mode packages the kernel, initrd, and boot parameters into a single EFI executable. Combined with measure-only rootfs (no encryption), it enables fast boot and simplified remote attestation. + +> [!NOTE] +> **UKI Mode Features:** +> - Single UKI file contains all boot components +> - Measure-only without encryption for faster boot +> - Reference value contains only UKI measurement, simpler verification +> - Suitable for scenarios requiring fast boot and simplified attestation + +### Configuration + +Create UKI mode configuration (rootfs not encrypted, delta encrypted): + +```sh +mkdir -p ./config_dir +cat << EOF > ./config_dir/fde.toml +[rootfs] +delta_location = "disk" +# rootfs not encrypted, measure only + +[delta] +integrity = true + +[delta.encrypt.exec] +command = "echo" +args = ["-n", "AAAaaawewe222"] +EOF +``` + +**Configuration Explanation:** + +- `[rootfs]`: Root filesystem measure-only without encryption + - `delta_location = "disk"`: Writable overlay stored on delta partition + - No `encrypt` configuration: rootfs uses dm-verity integrity protection +- `[delta]`: Delta partition encrypted + - Protects user data and system changes + +### Encrypt and Generate UKI Image + +```sh +cryptpilot-convert --in ./aliyun_3_x64_20G_nocloud_alibase_20251030.qcow2 \ + --out ./uki-encrypted.qcow2 \ + -c ./config_dir/ \ + --rootfs-no-encryption \ + --uki-mode +``` + +**Parameter Explanation:** + +- `--rootfs-no-encryption`: rootfs measure-only without encryption +- `--uki-mode`: Generate UKI unified kernel image + +### Calculate Reference Values + +UKI mode reference values contain only UKI measurement, making verification simpler: + +```sh +cryptpilot-fde show-reference-value --disk ./uki-encrypted.qcow2 +``` + +Example output: + +```json +{ + "measurement.uki.SHA-384": [ + "a46e162a57e072be7f660e65504477c646acf6b3bfea4ffc0e3a8ee4f2c2726c2284c8bf1ec2b3bd95b204fe7f4e899c" + ] +} +``` + +## Example 5: Encrypt a Real System Disk For production systems, you need to encrypt a real disk. @@ -259,7 +341,7 @@ cryptpilot-convert --device /dev/nvme2n1 \ 4. **Re-bind the disk** to the original instance and boot from it. -## Example 4: Using KBS Provider (Production) +## Example 6: Using KBS Provider (Production) For production environments, use Key Broker Service with remote attestation. @@ -306,7 +388,7 @@ When booting, the system will: 4. If verified, KBS returns the decryption key 5. System decrypts and boots -## Example 5: Using KMS Provider (Cloud-Managed) +## Example 7: Using KMS Provider (Cloud-Managed) For Alibaba Cloud users, use KMS for centralized key management. diff --git a/cryptpilot-fde/docs/quick-start_zh.md b/cryptpilot-fde/docs/quick-start_zh.md index 19fd5b1..3b41dd1 100644 --- a/cryptpilot-fde/docs/quick-start_zh.md +++ b/cryptpilot-fde/docs/quick-start_zh.md @@ -207,7 +207,89 @@ cryptpilot-convert --in ./aliyun_3_x64_20G_nocloud_alibase_20251030.qcow2 \ - ✅ 希望减少解密 rootfs 的性能开销 - ❌ 不适合 rootfs 中包含敏感配置或密钥的场景 -## 示例 3:加密真实系统磁盘 +### 计算参考值 + +计算仅度量模式的参考值: + +```sh +cryptpilot-fde show-reference-value --disk ./encrypted.qcow2 +``` + +输出包含多个度量值(kernel、initrd、cmdline 等),需要全部导入到 RVPS。 + +## 示例 3:rootfs 不加密仅度量 + UKI 模式 + +UKI(Unified Kernel Image)模式将内核、initrd 和启动参数打包为单个 EFI 可执行文件,配合不加密仅度量的 rootfs,可实现快速启动和简化的远程证明。 + +> [!NOTE] +> **UKI 模式特点:** +> - 单一 UKI 文件包含所有启动组件 +> - 仅度量不加密,启动更快 +> - 参考值只包含 UKI 度量值,验证更简单 +> - 适合需要快速启动和简化证明的场景 + +### 配置 + +创建 UKI 模式配置(rootfs 不加密,delta 加密): + +```sh +mkdir -p ./config_dir +cat << EOF > ./config_dir/fde.toml +[rootfs] +delta_location = "disk" +# rootfs 不加密,仅度量 + +[delta] +integrity = true + +[delta.encrypt.exec] +command = "echo" +args = ["-n", "AAAaaawewe222"] +EOF +``` + +**配置说明:** + +- `[rootfs]`:根文件系统仅度量不加密 + - `delta_location = "disk"`:可写差异层存储在 delta 分区 + - 无 `encrypt` 配置:rootfs 使用 dm-verity 完整性保护 +- `[delta]`:delta 分区加密 + - 保护用户数据和系统变更 + +### 加密并生成 UKI 镜像 + +```sh +cryptpilot-convert --in ./aliyun_3_x64_20G_nocloud_alibase_20251030.qcow2 \ + --out ./uki-encrypted.qcow2 \ + -c ./config_dir/ \ + --rootfs-no-encryption \ + --uki-mode +``` + +**参数说明:** + +- `--rootfs-no-encryption`:rootfs 仅度量不加密 +- `--uki-mode`:生成 UKI 统一内核镜像 + +### 计算参考值 + +UKI 模式的参考值仅包含 UKI 度量值,验证更简单: + +```sh +cryptpilot-fde show-reference-value --disk ./uki-encrypted.qcow2 +``` + +输出示例: + +```json +{ + "measurement.uki.SHA-384": [ + "a46e162a57e072be7f660e65504477c646acf6b3bfea4ffc0e3a8ee4f2c2726c2284c8bf1ec2b3bd95b204fe7f4e899c" + ] +} +``` + +## 示例 5:加密真实系统磁盘 对于生产系统,你需要加密真实磁盘。 @@ -259,7 +341,7 @@ cryptpilot-convert --device /dev/nvme2n1 \ 4. **重新绑定磁盘**到原始实例并从其启动。 -## 示例 4:使用 KBS 提供者(生产环境) +## 示例 6:使用 KBS 提供者(生产环境) 对于生产环境,使用带有远程证明的密钥代理服务。 @@ -306,7 +388,7 @@ cryptpilot-convert --device /dev/nvme2n1 \ 4. 如果验证通过,KBS 返回解密密钥 5. 系统解密并启动 -## 示例 5:使用 KMS 提供者(云托管) +## 示例 7:使用 KMS 提供者(云托管) 对于阿里云用户,使用 KMS 进行集中式密钥管理。 diff --git a/cryptpilot-fde/docs/reference-value.md b/cryptpilot-fde/docs/reference-value.md new file mode 100644 index 0000000..7a47d85 --- /dev/null +++ b/cryptpilot-fde/docs/reference-value.md @@ -0,0 +1,141 @@ +# Reference Value User Guide + +This document explains how to generate reference values in different boot modes (GRUB and UKI), understand their meanings, and import them into the Trustee service. + +## What are Reference Values + +Reference values are cryptographic hashes generated by measuring system components during the Trusted Execution Environment (TEE) boot process. These values are used for: + +- **Integrity Verification**: Confirming system components have not been tampered with +- **Remote Attestation**: Proving system state to remote verifiers +- **Secure Boot**: Ensuring only trusted systems can boot + +## Calculating Reference Values + +### Calculation Command + +Use the `cryptpilot-fde show-reference-value` command to calculate reference values for encrypted images: + +```sh +cryptpilot-fde show-reference-value --disk ./encrypted.qcow2 +``` + +### GRUB Mode Reference Values + +GRUB mode uses traditional boot loaders, and reference values contain multiple components: + +```json +{ + "kernel_cmdline": [ + "grub_kernel_cmdline /vmlinuz-5.10.134...", + "grub_kernel_cmdline (hd0,gpt3)/boot/vmlinuz-5.10.134..." + ], + "measurement.kernel_cmdline.SHA-384": [ + "749727fcda2c85df2a901f438da9196233f532cd19fb256f7243acfa930280a2fd9418320bcf87cc8e556fcd7988238a", + "eb8dfc74e60ede2a3ece37f735db47ece9688458fe3d07ae6a87e0e7e03bf68aabaac534cecc0391af5244fe45336257" + ], + "measurement.kernel.SHA-384": [ + "fd4099ae8fdd986173d0fdbe5b06537d8b24f3ed2dc0804407d2061a4e0a9dd73f79a2dae36e34ddc580b919af15f173" + ], + "measurement.initrd.SHA-384": [ + "c9ffc25975c0aacf507402bb4c75344b53c005a027620cf774ef93845edc416a5b20b48213b6d4fe3a54f3ca8b7cb4f2" + ], + "measurement.grub.SHA-384": [ + "1c6b41cc5f1e08dff906e381580dc5c200b3c4785f3910682c74fd2ac0421f324216165478595b5e799d2b2134d22b75" + ], + "measurement.shim.SHA-384": [ + "06647f7cd6b1f00433713e895077c986641bfb6bdd3de989575b4fdc34fe557f26990c414158c772393a27732f959dc5" + ] +} +``` + +**GRUB Mode Reference Value Fields:** + +| Field | Description | +|-------|-------------| +| `kernel_cmdline` | Kernel boot parameters (plaintext) | +| `measurement.kernel_cmdline.SHA-384` | SHA-384 hash of kernel boot parameters | +| `measurement.kernel.SHA-384` | SHA-384 hash of kernel image | +| `measurement.initrd.SHA-384` | SHA-384 hash of initrd image | +| `measurement.grub.SHA-384` | SHA-384 hash of GRUB bootloader | +| `measurement.shim.SHA-384` | SHA-384 hash of Shim (secure boot proxy) | + +### UKI Mode Reference Values + +UKI (Unified Kernel Image) mode packages the kernel, initrd, and boot parameters into a single EFI executable, resulting in simpler reference values: + +```json +{ + "measurement.uki.SHA-384": [ + "a46e162a57e072be7f660e65504477c646acf6b3bfea4ffc0e3a8ee4f2c2726c2284c8bf1ec2b3bd95b204fe7f4e899c" + ] +} +``` + +**UKI Mode Reference Value Fields:** + +| Field | Description | +|-------|-------------| +| `measurement.uki.SHA-384` | SHA-384 hash of UKI file (contains kernel, initrd, cmdline) | + +## Importing Reference Values to Trustee + +### Prerequisites + +Install the Trustee RVPS tool: + +```sh +# Download rvps-tool from Trustee repository +wget https://github.com/confidential-containers/trustee/releases/download/v0.10.0/rvps-tool +chmod +x rvps-tool +``` + +### Import Reference Values to Trustee + +Both GRUB and UKI modes can import the entire reference value file at once: + +```sh +# Read and encode the reference value file +REFERENCE_FILE="./reference-value.json" +provenance=$(cat $REFERENCE_FILE | base64 --wrap=0) + +# Create registration request +cat << EOF > ./register-request.json +{ + "version": "0.1.0", + "type": "sample", + "payload": "$provenance" +} +EOF + +# Import to RVPS +rvps-tool register --path ./register-request.json +``` + +## Verifying Reference Values + +After importing, you can verify the reference values: + +```sh +# List all registered reference values +rvps-tool list + +# Query specific reference value +rvps-tool query --name "measurement.uki.SHA-384" +``` + +## Frequently Asked Questions + +### Q: Why does UKI mode have only one reference value? + +A: UKI packages the kernel, initrd, and boot parameters into a single EFI executable file. During boot, it is measured as a whole, resulting in only one measurement value. + +### Q: Can I verify only some reference values? + +A: Not recommended. In GRUB mode, there are multiple components. Although you can modify the `reference-value.json` file to import only desired reference values, it is recommended to verify all components. Missing any component reduces security. In UKI mode, there is only one measurement value, which must be verified. + +## References + +- [Trustee RVPS Documentation](https://github.com/confidential-containers/trustee/tree/main/rvps) +- [Quick Start Guide](quick-start.md) +- [Boot Process Details](boot.md) diff --git a/cryptpilot-fde/docs/reference-value_zh.md b/cryptpilot-fde/docs/reference-value_zh.md new file mode 100644 index 0000000..a3ef745 --- /dev/null +++ b/cryptpilot-fde/docs/reference-value_zh.md @@ -0,0 +1,141 @@ +# 参考值(Reference Value)使用指南 + +本文档介绍如何在不同启动模式(GRUB 和 UKI)下生成参考值、理解参考值含义,以及将参考值导入 Trustee 服务。 + +## 什么是参考值 + +参考值(Reference Value)是可信执行环境(TEE)在启动过程中对系统组件进行度量(measurement)得到的哈希值。这些值用于: + +- **完整性验证**:确认系统组件未被篡改 +- **远程证明**:向远程验证者证明系统状态 +- **安全启动**:确保只有受信任的系统才能启动 + +## 参考值计算 + +### 计算命令 + +使用 `cryptpilot-fde show-reference-value` 命令计算加密镜像的参考值: + +```sh +cryptpilot-fde show-reference-value --disk ./encrypted.qcow2 +``` + +### GRUB 模式参考值 + +GRUB 模式使用传统的引导加载程序,参考值包含多个组件: + +```json +{ + "kernel_cmdline": [ + "grub_kernel_cmdline /vmlinuz-5.10.134...", + "grub_kernel_cmdline (hd0,gpt3)/boot/vmlinuz-5.10.134..." + ], + "measurement.kernel_cmdline.SHA-384": [ + "749727fcda2c85df2a901f438da9196233f532cd19fb256f7243acfa930280a2fd9418320bcf87cc8e556fcd7988238a", + "eb8dfc74e60ede2a3ece37f735db47ece9688458fe3d07ae6a87e0e7e03bf68aabaac534cecc0391af5244fe45336257" + ], + "measurement.kernel.SHA-384": [ + "fd4099ae8fdd986173d0fdbe5b06537d8b24f3ed2dc0804407d2061a4e0a9dd73f79a2dae36e34ddc580b919af15f173" + ], + "measurement.initrd.SHA-384": [ + "c9ffc25975c0aacf507402bb4c75344b53c005a027620cf774ef93845edc416a5b20b48213b6d4fe3a54f3ca8b7cb4f2" + ], + "measurement.grub.SHA-384": [ + "1c6b41cc5f1e08dff906e381580dc5c200b3c4785f3910682c74fd2ac0421f324216165478595b5e799d2b2134d22b75" + ], + "measurement.shim.SHA-384": [ + "06647f7cd6b1f00433713e895077c986641bfb6bdd3de989575b4fdc34fe557f26990c414158c772393a27732f959dc5" + ] +} +``` + +**GRUB 模式参考值字段说明:** + +| 字段 | 说明 | +|------|------| +| `kernel_cmdline` | 内核启动参数(明文) | +| `measurement.kernel_cmdline.SHA-384` | 内核启动参数的 SHA-384 哈希值 | +| `measurement.kernel.SHA-384` | 内核镜像的 SHA-384 哈希值 | +| `measurement.initrd.SHA-384` | initrd 镜像的 SHA-384 哈希值 | +| `measurement.grub.SHA-384` | GRUB 引导程序的 SHA-384 哈希值 | +| `measurement.shim.SHA-384` | Shim(安全启动代理)的 SHA-384 哈希值 | + +### UKI 模式参考值 + +UKI(Unified Kernel Image)模式将内核、initrd 和启动参数打包为单个 EFI 可执行文件,参考值更简洁: + +```json +{ + "measurement.uki.SHA-384": [ + "a46e162a57e072be7f660e65504477c646acf6b3bfea4ffc0e3a8ee4f2c2726c2284c8bf1ec2b3bd95b204fe7f4e899c" + ] +} +``` + +**UKI 模式参考值字段说明:** + +| 字段 | 说明 | +|------|------| +| `measurement.uki.SHA-384` | UKI 文件的 SHA-384 哈希值(包含内核、initrd、cmdline) | + +## 导入参考值到 Trustee + +### 准备工作 + +安装 Trustee RVPS 工具: + +```sh +# 从 Trustee 仓库下载 rvps-tool +wget https://github.com/confidential-containers/trustee/releases/download/v0.10.0/rvps-tool +chmod +x rvps-tool +``` + +### 导入参考值到 Trustee + +无论是 GRUB 还是 UKI 模式,都可以一次性导入整个参考值文件: + +```sh +# 读取参考值文件并编码 +REFERENCE_FILE="./reference-value.json" +provenance=$(cat $REFERENCE_FILE | base64 --wrap=0) + +# 创建注册请求 +cat << EOF > ./register-request.json +{ + "version": "0.1.0", + "type": "sample", + "payload": "$provenance" +} +EOF + +# 导入到 RVPS +rvps-tool register --path ./register-request.json +``` + +## 验证参考值 + +导入后,可以验证参考值是否正确: + +```sh +# 列出所有已注册的参考值 +rvps-tool list + +# 查询特定参考值 +rvps-tool query --name "measurement.uki.SHA-384" +``` + +## 常见问题 + +### Q: 为什么 UKI 模式只有一个参考值? + +A: UKI 将内核、initrd 和启动参数打包为单个 EFI 可执行文件,启动时作为一个整体进行度量,因此只有一个度量值。 + +### Q: 可以只验证部分参考值吗? + +A: 不建议。GRUB 模式下有多个组件,虽然可以修改参考值`reference-value.json`文件仅导入想要的参考值,但建议所有组件都验证,缺少任何一个都会降低安全性。UKI 模式下只有一个度量值,必须验证。 + +## 参考 + +- [Trustee RVPS 文档](https://github.com/confidential-containers/trustee/tree/main/rvps) +- [快速开始指南](quick-start_zh.md) +- [启动过程详解](boot_zh.md)