virtee/sev-snp-measure
GitHub: virtee/sev-snp-measure
用于计算 AMD SEV/SEV-ES/SEV-SNP 机密计算虚拟机启动度量值的 Python 命令行工具与库。
Stars: 73 | Forks: 22
# sev-snp-measure
## 范围
用于计算以下项预期度量值的命令行工具和 Python 库：
用于机密计算的 AMD SEV/SEV-ES/SEV-SNP 客户机 VM。
## 安装
### 通过 pip
从 pip 安装：
```
pip install sev-snp-measure
```
这将安装 `sevsnpmeasure` 包和 `sev-snp-measure` 命令行脚本。
### 通过 Github
克隆 Github 仓库并直接从本地目录运行脚本：
```
git clone https://github.com/virtee/sev-snp-measure.git
cd sev-snp-measure
./sev-snp-measure.py --help
```
## 命令行用法
### sev-snp-measure
```
$ sev-snp-measure --help
usage: sev-snp-measure [-h] [--version] [-v] --mode {sev,seves,snp,snp:ovmf-hash,snp:svsm}
[--vcpus N] [--vcpu-type CPUTYPE] [--vcpu-sig VALUE] [--vcpu-family FAMILY]
[--vcpu-model MODEL] [--vcpu-stepping STEPPING] [--vmm-type VMMTYPE] --ovmf
PATH [--kernel PATH] [--initrd PATH] [--append CMDLINE]
[--guest-features VALUE] [--output-format {hex,base64}]
[--snp-ovmf-hash HASH] [--dump-vmsa] [--svsm PATH]
[--vars-size SIZE | --vars-file PATH]
Calculate AMD SEV/SEV-ES/SEV-SNP guest launch measurement
options:
-h, --help show this help message and exit
--version show program's version number and exit
-v, --verbose
--mode {sev,seves,snp,snp:ovmf-hash,snp:svsm}
Guest mode
--vcpus N Number of guest vcpus
--vcpu-type CPUTYPE Type of guest vcpu (EPYC, EPYC-v1, EPYC-v2, EPYC-IBPB, EPYC-v3, EPYC-v4,
EPYC-Rome, EPYC-Rome-v1, EPYC-Rome-v2, EPYC-Rome-v3, EPYC-Milan, EPYC-
Milan-v1, EPYC-Milan-v2, EPYC-Genoa, EPYC-Genoa-v1)
--vcpu-sig VALUE Guest vcpu signature value
--vcpu-family FAMILY Guest vcpu family
--vcpu-model MODEL Guest vcpu model
--vcpu-stepping STEPPING
Guest vcpu stepping
--vmm-type VMMTYPE Type of guest vmm (QEMU, ec2, gce)
--ovmf PATH OVMF file to calculate hash from
--kernel PATH Kernel file to calculate hash from
--initrd PATH Initrd file to calculate hash from (use with --kernel)
--append CMDLINE Kernel command line to calculate hash from (use with --kernel)
--guest-features VALUE
Hex representation of the guest kernel features expected to be included
(defaults to 0x1); see README.md for possible values
--output-format {hex,base64}
Measurement output format
--snp-ovmf-hash HASH Precalculated hash of the OVMF binary (hex string)
--dump-vmsa Write measured VMSAs to vmsa.bin (seves, snp, and snp:svsm modes only)
snp:svsm Mode:
AMD SEV-SNP with Coconut-SVSM. This mode additionally requires --svsm and either --vars-file
or --vars-size to be set.
--svsm PATH SVSM binary
--vars-size SIZE Size of the OVMF_VARS file in bytes (conflicts with --vars-file)
--vars-file PATH OVMF_VARS file (conflicts with --vars-size)
```
### 示例：SNP 模式
```
$ sev-snp-measure --mode snp --vcpus=1 --vcpu-type=EPYC-v4 --ovmf=OVMF.fd --kernel=vmlinuz --initrd=initrd.img --append="console=ttyS0 loglevel=7"
1c8bf2f320add50cb22ca824c17f3fa51a7a4296a4a3113698c2e31b50c2dcfa7e36dea3ebc3a9411061c30acffc6d5a
```
### 示例：SNP:SVSM 模式
```
$ sev-snp-measure \
--mode snp:svsm \
--vmm-type=QEMU \
--vcpus=4 \
--vcpu-type=EPYC-v4 \
--ovmf=OVMF_CODE.fd \
--svsm=svsm.bin --vars-file=OVMF_VARS.fd
3447e476b226e317890a350003b56ee17becb48d1dc25dd6b5819a1192df3238f50cda0f0216bd5ae2a992ad7ab961c4
```
### snp-create-id-block
```
$ snp-create-id-block --help
usage: snp-create-id-block [-h] [--measurement VALUE] [--idkey PATH] [--authorkey PATH]
Calculate AMD SEV-SNP guest id block
optional arguments:
-h, --help show this help message and exit
--measurement VALUE Guest launch measurement in Base64 encoding
--idkey PATH id private key file
--authorkey PATH author private key file
```
## 编程用法
通过 pip 安装 `sev-snp-measure` 包后，您可以从另一个 Python 应用程序调用它：
```
from sevsnpmeasure import guest,id_block
from sevsnpmeasure import vcpu_types
from sevsnpmeasure.sev_mode import SevMode
ld = guest.calc_launch_digest(SevMode.SEV_SNP, vcpus_num, vcpu_types.CPU_SIGS["EPYC-v4"],
ovmf_path, kernel_path, initrd_path, cmdline_str, guest_features)
print("Calculated measurement:", ld.hex())
block = id_block.snp_calc_id_block(ld,"id_key_file","author_key_file")
print("Calculated id block in base64", block)
```
## 选择客户机 CPU 类型
对于 SEV-ES 和 SEV-SNP，当您使用 QEMU vmm 时，初始 CPU 状态 (VMSA) 在 edx 寄存器中包含客户机 CPU 签名。因此，使用不同类型的客户机 CPU 启动 VM 将修改 VMSA 的内容，从而修改计算出的度量值。
您可以使用 `--vcpu-type`、`--vcpu-sig` 或 `--vcpu-family`、`--vcpu-model` 和 `--vcpu-stepping` 的组合来选择客户机 CPU 类型。例如，以下 3 次调用是相同的：
1. `sev-snp-measure --vcpu-type=EPYC-v4 ...`
2. `sev-snp-measure --vcpu-sig=0x800f12 ...`
3. `sev-snp-measure --vcpu-family=23 --vcpu-model=1 --vcpu-stepping=2 ...`
## SEV-SNP 客户机特性字段值
在 Linux Kernel 6.6 版本之前，默认值始终计算为 `0x1`，因为内核仅支持 `SNPActive`。Linux Kernel 6.6 发布后，提供了额外的特性，其中一些默认启用。因此，新的默认值是 `0x21`，即 `SNPActive + DebugSwap`。其他可能的组合可以通过下表生成 64 位十六进制值来推导：
| 位字段 | 描述 |
|:---------:|:------------:|
| 0 | SNPActive |
| 1 | vTOM |
| 2 | ReflectVC |
| 3 | RestrictedInjection |
| 4 | AlternateInjection |
| 5 | DebugSwap |
| 6 | PreventHostIBS |
| 7 | BTBIsolation |
| 8 | VmplSSS |
| 9 | SecureTSC |
| 10 | VmgexitParameter |
| 11 | Reserved, SBZ |
| 12 | IbsVirtualization |
| 13 | Reserved, SBZ |
| 14 | VmsaRegProt |
| 15 | SmtProtection |
| 63:16 | Reserved, SBZ |
## 预计算的 OVMF 哈希
SEV-SNP 摘要分多个步骤生成，每个步骤都有一个摘要输出。利用该摘要输出，您可以在这些步骤中的任何一步停止，并在稍后继续生成完整摘要。这些步骤包括：
1. OVMF
2. （可选）-kernel、-initrd、-append 参数
3. 所有 vCPU 的初始状态
在仅发生微小 OVMF 更改的情况下，您可能不希望将完整的 OVMF 二进制文件复制到验证系统。在这种情况下，您可以在 `OVMF` 步骤之后截断摘要计算，并使用其哈希值代替完整的二进制文件。
要生成哈希值，请使用 `--mode snp:ovmf-hash` 参数：
```
$ sev-snp-measure --mode snp:ovmf-hash --ovmf OVMF.fd
cab7e085874b3acfdbe2d96dcaa3125111f00c35c6fc9708464c2ae74bfdb048a198cb9a9ccae0b3e5e1a33f5f249819
```
在另一台只能访问较旧但兼容的 OVMF 二进制文件的机器上，您可以随后再次摄入该哈希值以生成完整的度量值：
```
$ sev-snp-measure --mode snp --vcpus=1 --vcpu-type=EPYC-v4 --ovmf=OVMF.fd.old --ovmf-hash cab7e[...]
d52697c3e056fb8d698d19cc29adfbed5a8ec9170cb9eb63c2ac957d22b4eb647e25780162036d063a0cf418b8830acc
```
## 相关项目
* [sev-snp-measure-go](https://github.com/virtee/sev-snp-measure-go)：sev-snp-measure 的 Go 语言移植版
* libvirt 工具：[virt-dom-sev-validate](https://gitlab.com/berrange/libvirt/-/blob/lgtm/tools/virt-dom-sev-validate.py)，
[virt-dom-sev-vmsa-tool](https://gitlab.com/berrange/libvirt/-/blob/lgtm/tools/virt-dom-sev-vmsa-tool.py)
* [sev Rust crate](https://github.com/virtee/sev) 和 [snpguest CLI tool](https://github.com/virtee/snpguest)
* [snp-digest-rs](https://github.com/slp/snp-digest-rs)
* AMD [sev-tool](https://github.com/AMDESE/sev-tool)、[sev-guest](https://github.com/AMDESE/sev-guest)
和 [sev-utils](https://github.com/amd/sev-utils)
* [go-sev-guest](https://github.com/google/go-sev-guest)
## 开发
运行所有单元测试：
```
pip install -r requirements.txt
make test
```
检查单元测试覆盖率：
```
pip install coverage
make coverage
# 查看 htmlcov/ 中的 HTML 覆盖率报告
```
检查 Python 类型提示：
```
pip install mypy
make typecheck
```
检查 Python 编码风格：
```
pip install flake8
make lint
```
## 说明
如果您有任何疑问或问题，可以[在此处](https://github.com/virtee/sev-snp-measure/issues/new)创建新 issue
欢迎提交 Pull requests！
## 许可证
Apache 2.0 license。
标签：AMD SEV, OVMF, Python, SEV-ES, SEV-SNP, TEE, VMSA, 内存加密, 可信执行环境, 固件测量, 完整性度量, 开源库, 搜索引擎爬虫, 数据隐私, 无后门, 机密计算, 生成式AI安全, 硬件安全, 虚拟机, 身份验证强制, 远程证明, 逆向工具