snpguest

snpguest 是一个用于管理 AMD SEV-SNP 启用客户端的命令行界面工具。此工具允许用户与 AMD SEV-SNP 客户端固件设备交互，实现各种操作，如：证明、证书管理、密钥提取等。

• 用法
  • 1. help
  • 2. certificates
  • 3. display
  • 4. fetch
  • 5. key
  • 6. report
  • 7. verify
• 扩展证明工作流
• 常规证明工作流
• 全局选项
• 扩展证明流程图
• 常规证明流程图
• 构建
  • Ubuntu 依赖
  • RHEL 及其兼容版本依赖
• 报告错误

用法

1. help

每个 snpguest (子)命令都带有一个 --help 选项，用于描述其用法。

用法

snpguest --help

2. certificates

从主机内存请求证书链（ASK、ARK & VCEK）（请求扩展配置）。用户需要指定存储证书的编码（PEM 或 DER）。目前仅支持 PEM 和 DER 编码。所有证书将使用相同的编码。用户还需要提供存储证书的目录路径。如果提供的目录中已存在证书，则将覆盖它们。

用法

snpguest certificates $ENCODING $CERTS_DIR

参数

• $ENCODING : 指定存储证书的编码（PEM 或 DER）。

• $CERTS_DIR : 指定存储证书的目录。当请求扩展证明报告时，这是必需的。

示例

snpguest certificates pem ./certs

3. display

以人类可读的形式显示文件。

用法

snpguest display <SUBCOMMAND>

子命令

1. report

   当用于显示报告时，它会将认证报告内容打印到终端。用户必须提供存储的认证报告的路径以进行显示。

   用法

   snpguest display report $ATT_REPORT_PATH
   

   参数

   • $ATT_REPORT_PATH：指定要显示的存储的认证报告的路径。

   示例

   snpguest display report attestation-report.bin
   

2. 键

   当用于显示获取的派生密钥内容时，它会将派生密钥以十六进制格式打印到终端。用户必须提供存储的派生密钥的路径以进行显示。

   用法

   snpguest display key $KEY_PATH
   

   参数

   • $KEY_PATH：指定要显示的存储的派生密钥的路径。

   示例

   snpguest display key derived-key.bin
   

4. fetch

命令用于从KDS请求证书。

用法

snpguest fetch <SUBCOMMAND>

子命令

1. ca

   从KDS请求证书授权链（ARK & ASK）。用户需要指定证书编码以将证书存储（PEM或DER）。目前，仅支持PEM和DER编码。两个证书将使用相同的编码。用户必须指定其主机处理器模型。用户还需要提供存储证书的目录路径。如果提供的目录中已存在证书，则它们将被覆盖。

   用法

   snpguest fetch ca $ENCODING $PROCESSOR_MODEL $CERTS_DIR
   

   参数

   • $ENCODING : 指定存储证书的编码（PEM 或 DER）。

   • $PROCESSOR_MODEL：指定主机处理器模型。

   • $CERTS_DIR：指定存储证书的目录。

   示例

   snpguest fetch ca der milan ./certs-kds
   

2. vcek

   从KDS请求VCEK证书。用户需要指定存储证书的证书编码（PEM或DER）。目前，仅支持PEM和DER编码。用户必须指定其主机处理器模型。用户还需要提供VCEK将存储的目录路径以及用于请求VCEK的存储的认证报告的路径。如果提供的目录中已存在证书，则它将被覆盖。

   用法

   snpguest fetch vcek $ENCODING $PROCESSOR_MODEL $CERTS_DIR $ATT_REPORT_PATH
   

   参数

   • $ENCODING : 指定存储证书的编码（PEM 或 DER）。

   • $PROCESSOR_MODEL：指定主机处理器模型。

   • $CERTS_DIR：指定存储证书的目录。

   • $ATT_REPORT_PATH：指定存储的认证报告的路径。

   示例

   snpguest fetch vcek der milan ./certs-kds attestation-report.bin
   

5. key

根据输入参数创建派生密钥并存储。 $KEY_PATH 是存储派生密钥的路径。 $ROOT_KEY_SELECT 是用于派生密钥的根密钥（"vcek"或"vmrk"）。 --guest_field_select 选项指定作为6位二进制字符串启用的Guest Field Select位。从左到右的6位分别对应Guest策略、图像ID、家族ID、测量、SVN和TCB版本。对于每个位，0表示关闭，1表示开启。 --guest_svn 选项指定要混合到密钥中的guest SVN，而 --tcb_version 选项指定要混合到派生密钥中的TCB版本。 --vmpl 选项指定Guest运行的VMPL级别，默认为1。

用法

snpguest key $KEY_PATH $ROOT_KEY_SELECT [-g, --guest_field_select] [-s, --guest_svn] [-t, --tcb_version] [-v, --vmpl]

参数

• $KEY_PATH：存储派生密钥的路径。

• $ROOT_KEY_SELECT : 是用于派生密钥的根密钥（可以是 "vcek" 或 "vmrk"）。

选项

• --guest_field_select : 选项指定要启用的Guest Field Select位，以6位二进制字符串的形式表示。对于每个位，0表示关闭，1表示开启。

  For example, `--guest_field_select 100001` denotes 
  
  Guest Policy:On (1), 
  
  Image ID:Off (0), 
  
  Family ID:Off (0), 
  
  Measurement:Off (0), 
  
  SVN:Off (0), 
  
  TCB Version:On (1). 
  

• --guest_svn : 选项指定要混入密钥的Guest SVN。

• --tcb_version : 选项指定要混入派生密钥的TCB版本。

• --vmpl : 选项指定Guest运行的VMPL级别，默认为1。

示例

# Creating and storing a derived key
snpguest key derived-key.bin vcek --guest_field_select 100001 --guest_svn 2 --tcb_version 1 --vmpl 3

6. report

从主机请求证明报告并将其写入包含提供请求数据和VMPL的文件。证明报告以二进制格式写入指定的报告路径。用户可以将64字节数据以任何文件格式传递给$REQUEST_FILE以请求证明报告。可以使用--random标志生成和使用随机数据作为请求，对于Microsoft Hyper-V虚拟机，需要使用--platform标志来使用预生成的请求数据。从虚拟机管理程序生成的数据将写入到$REQUEST_FILE中提供的文件。VMPL是一个可选参数，默认为1。在Hyper-V中，--random不可用，因为请求数据已预生成。

用法

snpguest report $ATT_REPORT_PATH $REQUEST_FILE [-v, --vmpl] [-r, --random] [-p, --platform]

参数

• $ATT_REPORT_PATH : 指定证明报告存储的路径。

• $REQUEST_FILE : 存储从虚拟机管理程序生成数据的文件。

选项

• -r, --random: 为报告请求生成64个随机字节的数据（在Hyper-V中不可用）。
• -p, --platform : 使用平台提供的64字节数据作为请求报告（仅适用于Hyper-V）。
• -v, --vmpl : 选项指定Guest运行的VMPL级别，默认为1。

示例

# Requesting Attestation Report with user-generated data
snpguest report attestation-report.bin request-file.txt
# Requesting Attestation Report using random data
snpguest report attestation-report.bin random-request-file.txt --random
# Requesting Attestation Report using platform data
snpguest report attestation-report.bin platform-request-file.txt --platform

7. verify

验证证书和证明报告。

用法

snpguest verify <SUBCOMMAND>

子命令

1. certs

   验证提供的证书链是否已由每个证书正确签名。用户需要提供一个目录，其中存储了所有三个证书（ARK、ASK和VCEK）。如果任何证书验证失败，将引发错误。

   用法

   snpguest verify certs $CERTS_DIR
   

   参数

   • $CERTS_DIR : 指定存储证书的目录。

   示例

   snpguest verify certs ./certs
   

2. attestation

   使用VCEK证书验证声明报告的内容。用户需要提供包含VCEK证书的目录路径以及要验证的存储声明报告的路径。如果在任何点上声明验证失败，将引发错误。用户可以使用-t, --tcb标志仅验证报告的TCB内容，以及-s, --signature标志仅验证报告的签名。

   用法

   snpguest verify attestation $CERTS_DIR $ATT_REPORT_PATH [-t, --tcb] [-s, --signature]
   

   参数

   • $CERTS_DIR : 指定存储证书的目录。

   • $ATT_REPORT_PATH：指定存储的认证报告的路径。

   选项

   • -t, --tcb：仅验证报告的TCB部分。
   • -s, --signature：仅验证报告的签名。

   示例

   # Verify Attestation
   snpguest verify attestation ./certs attestation-report.bin
   # Verify Attestation Signature only
   snpguest verify attestation ./certs attestation-report.bin --signature
   

扩展证明工作流

步骤1。 通过提供两个必填参数请求声明报告 - $ATT_REPORT_PATH，它指向用户希望存储声明报告的位置的路径，以及$REQUEST_FILE，它指向用于请求声明报告的请求文件的存储路径。可选参数[-v, --vmpl]指定声明报告的vmpl级别，默认设置为1。[-r, --random]生成用于声明报告请求数据的随机数据。最后，[-p, --platform]从平台获取请求数据。当用户期望平台提供声明报告的请求数据时，Microsoft Hyper-V是必需的。

snpguest report $ATT_REPORT_PATH $REQUEST_FILE [-v, --vmpl] [-r, --random] [-p, --platform]

步骤2。 通过提供两个必填参数请求证书 - $ENCODING指定是否使用PEM或DER编码存储证书，以及$CERTS_DIR指定用户目录中证书将被保存的路径。

snpguest certificates $ENCODING $CERTS_DIR

步骤3。 通过提供$CERTS_DIR，即步骤2中保存证书的用户目录中的路径，来验证从扩展内存获得的证书。

snpguest verify certs $CERTS_DIR

步骤4。 通过提供两个必填参数来验证声明 - $CERTS_DIR指定步骤2中保存证书的用户目录中的路径，以及$ATT_REPORT_PATH指向用户希望验证的存储声明报告的路径。可选参数[-t, --tcb]用于仅验证声明报告的TCB内容，而[-s, --signature]用于仅验证声明报告的签名。

snpguest verify attestation $CERTS_DIR $ATT_REPORT_PATH [-t, --tcb] [-s, --signature]

常规证明工作流

步骤1。 通过提供两个必填参数请求声明报告 - $ATT_REPORT_PATH，它指向用户希望存储声明报告的位置的路径，以及$REQUEST_FILE，它指向用于请求声明报告的请求文件的存储路径。可选参数[-v, --vmpl]指定声明报告的vmpl级别，默认设置为1。[-r, --random]生成用于声明报告请求数据的随机数据。最后，[-p, --platform]从平台获取请求数据。当用户期望平台提供声明报告的请求数据时，Microsoft Hyper-V是必需的。

snpguest report $ATT_REPORT_PATH $REQUEST_FILE [-v, --vmpl] [-r, --random] [-p, --platform]

步骤2。 通过提供三个必填参数从AMD密钥分发服务（KDS）请求AMD根密钥（ARK）和AMD SEV密钥（ASK） - $ENCODING指定是否使用PEM或DER编码存储证书，$PROCESSOR_MODEL指定要获取证书的AMD处理器型号，以及$CERTS_DIR指定用户目录中证书将被保存的路径。

snpguest fetch ca $ENCODING $PROCESSOR_MODEL $CERTS_DIR

步骤 3. 通过提供三个必填参数请求AMD密钥分发服务（KDS）的版本化芯片证书密钥（VCEK） - $ENCODING，指定是否使用PEM或DER编码存储证书；$PROCESSOR_MODEL，指定要获取证书的AMD处理器型号；$CERTS_DIR，指定证书将在用户目录中保存的路径。

snpguest fetch vcek $ENCODING $PROCESSOR_MODEL $CERTS_DIR $ATT_REPORT_PATH

步骤 4. 通过提供指定步骤2中保存证书的用户目录路径的$CERTS_DIR来验证证书。

snpguest verify certs $CERTS_DIR

步骤 5. 通过提供两个必填参数来验证证明 - $CERTS_DIR，指定步骤2中保存证书的用户目录路径；$ATT_REPORT_PATH，指向用户希望验证的存储证明报告的路径。可选参数[-t, --tcb]用于仅验证证明报告中TCB内容，[-s, --signature]用于仅验证证明报告的签名。

snpguest verify attestation $CERTS_DIR $ATT_REPORT_PATH [-t, --tcb] [-s, --signature]

全局选项

• -q, --quiet：抑制控制台输出。

扩展证明流程图

常规证明流程图

构建

为了构建snpguest，可能在主机系统上需要安装某些软件包。

#Rust Installation
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"

#Building snpguest after cloning
cargo build -r

Ubuntu 依赖

sudo apt install build-essential

RHEL及其兼容发行版的依赖关系

sudo dnf groupinstall "Development Tools" "Development Libraries"

报告错误

请将所有错误报告到Github snpguest存储库。