openanolis · imlk0 · Mar 26, 2026 · Mar 26, 2026
diff --git 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
@@ -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
@@ -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)