diff --git a/README.md b/README.md index f609861..1dba904 100644 --- a/README.md +++ b/README.md @@ -2,219 +2,371 @@ `snpguest` is a Command Line Interface utility for managing an AMD SEV-SNP enabled guest. This tool allows users to interact with the AMD SEV-SNP guest firmware device enabling various operations such as: attestation, certificate management, derived key fetching, and more. -- [Usage](#usage) - - [1. help](#1-help) - - [2. certificates](#2-certificates) - - [3. display](#3-display) - - [4. fetch](#4.fetch) - - [5. key](#5-key) - - [6. report](#6-report) - - [7. verify](#7-verify) +- [Basic Usage](#basic-usage) + - [List of (Sub)commands](#list-of-subcommands) - [Global Options](#global-options) +- [Subcommand Details](#subcommand-details) + - [0. ok](#0-ok) + - [1. report](#1-report) + - [2. certificates](#2-certificates) + - [3. fetch ca](#3-fetch-ca) + - [4. fetch vcek](#4-fetch-vcek) + - [5. fetch crl](#5-fetch-crl) + - [6. verify certs](#6-verify-certs) + - [7. verify attestation](#7-verify-attestation) + - [8. key](#8-key) + - [9. display report](#9-display-report) + - [10. display key](#10-display-key) + - [11. generate measurement](#11-generate-measurement) + - [12. generate ovmf-hash](#12-generate-ovmf-hash) + - [13. generate id-block](#13-generate-id-block) + - [14. generate key-digest](#14-generate-key-digest) - [Extended Attestation Workflow](#extended-attestation-workflow) - [Regular Attestation Workflow](#regular-attestation-workflow) - [Extended Attestation Flowchart](#extended-attestation-flowchart) - [Regular Attestation Flowchart](#regular-attestation-flowchart) -- [Building](#building) - - [Ubuntu Dependencies](#ubuntu-dependencies) - - [RHEL and its compatible distributions dependencies](#rhel-and-its-compatible-distributions-dependencies) - - [openSUSE and its compatible distributions dependencies](#opensuse-and-its-compatible-distributions-dependencies) - - [Building for Azure Confidential VMs](#building-for-azure-confidential-vms) +- [Build](#build) + - [For Standard CVMs](#for-standard-cvms) + - [For Azure CVMs](#for-azure-cvms) + - [Build Dependencies](#build-dependencies) + - [Load sev-guest module](#load-sev-guest-module) - [Reporting Bugs](#reporting-bugs) -## Usage +## Basic Usage + +```bash +snpguest [GLOBAL_OPTIONS] [COMMAND] [COMMAND_ARGS] [SUBCOMMAND] [SUBCOMMAND_ARGS] +``` + +Every `snpguest` (sub)command comes with a `-h, --help` option for a description on its use. + +### List of (Sub)commands + +| Command | Subcommand | Description | +| :------ | :--------- | :---------- | +| `ok` | - | Quick local check if SEV-SNP is enabled in the guest environment. | +| `report` | - | Requests an attestation report from AMD-SP (or vTPM) | +| `certificates` | - | Requests certificates from the hypervisor memory via AMD-SP | +| `fetch` | `ca`, `vcek`, `crl` | Fetches certificates/CRLs from AMD KDS | +| `verify` | `certs`, `attestation` | Verifies certificates / attestation report | +| `key` | - | Requests the derived key from AMD-SP based on input parameters | +| `display` | `report`, `key` | Displays files in human-readable form | +| `generate` | `measurement`, `ovmf-hash`, `id-block`, `key-digest` | Calculates reference values | + +### Global Options + +Currently only one global option is available. + +| Option | Description | Default | +| :----- | :---------- | :------ | +| `-q, --quiet` | Suppresses console output. | - | -### 1. `help` +## Subcommand Details -Every `snpguest` (sub)command comes with a `--help` option for a description on its use. +### 0. `ok` -**Usage** ```bash -snpguest --help +snpguest ok ``` -### 2. `certificates` +Performs a quick local check such as CPUID and MSRs (Model Specific Registers) to see if the SEV-SNP feature appears enabled in the guest environment. -Requests the VEK certificate chain (ARK, ASK/ASVK and VCEK/VLEK) from host memory (requests extended-config). The user needs to specify the certificate encoding to store the certificates in (PEM or DER). Currently, only PEM and DER encodings are supported. All certificates will be in the same encoding. The user also needs to provide the path to the directory where the certificates will be stored. If certificates already exist in the provided directory, they will be overwritten. +Note that this command is only a sanity check and does not provide a cryptographic guarantee that the SEV-SNP is definitely valid. To obtain strict cryptographic assurance for the SEV-SNP, the user must perform remote attestation. + +This command requires that the `msr` module is loaded. + +### 1. `report` + +```bash +snpguest report $ATT_REPORT_PATH $REQUEST_FILE [OPTIONS] +``` + +Requests an attestation report from the AMD Secure Processor (ASP), and writes it to `$ATT_REPORT_PATH` as raw binary. This command is a wrapper of the `SNP_GUEST_REQUEST(MSG_REPORT_REQ)` ioctl. + +Without `-p, --platform` or `-r, --random`, the user can pass 64 bytes of data in any file format into `$REQUEST_FILE` to request an attestation report. The request file is interpreted as raw binary, and the first 64 bytes of the binary are sent to the AMD-SP as the request data. The request data will be bound to the REPORT_DATA field in the attestation report. + +With the `-r, --random` flag, this command generates a random data for the request, which will be written into `$REQUEST_FILE`. + +The `-v, --vmpl` option specifies the Virtual Machine Privilege Level (VMPL) to request an attestation report. The default value is 1. If you specify a higher privilege level (i.e. smaller VMPL value) than the actual one, a firmware error will occur. + +With the `-p, --platform` flag, this command retrieves an attestation report from vTPM NV index `0x01400001` instead of the ASP, and writes the Report Data field in the retrieved report into `$REQUEST_FILE`. This attestation route is available (and mandatory) on Microsoft Azure Confidential VMs with SEV-SNP isolation. This flag requires the `hyperv` feature (see [Install on Azure CVMs](#install-on-azure-cvms)). Currently, only the pre-generated attestation report can be retrieved. To request a (fresh) report with the user-provided request data, use any TPM2 tool to write the request data to vTPM NV index `0x01400002`, then execute this command. + +#### Arguments and Options + +| Argument/Option | Description | Default | +| :-- | :-- | :-- | +| `$ATT_REPORT_PATH` | The path where the attestation report would be stored. | *required* | +| `$REQUEST_FILE` | The path to the 64-byte request file. | *required* | +| `-v, --vmpl $VMPL` | The VMPL value the Guest is running on (0-3).| 1 | +| `-r, --random` | Generate 64 random bytes of data for the report request. | - | +| `-p, --platform` | Get an attestation report from the vTPM NV index (Only available for Azure CVMs). | - | + +#### Example + +```bash +# Request attestation report with user-provided data +snpguest report report.bin request-file.bin + +# Request attestation report with randomly generated data +snpguest report report.bin request-file.bin --random + +# Get attestation report and request data from vTPM +snpguest report report.bin request-file.bin --platform +``` + +### 2. `certificates` -**Usage** ```bash snpguest certificates $ENCODING $CERTS_DIR ``` -**Arguments** +Requests the certificate chain from the hypervisor memory via the ASP, and writes it into `$CERTS_DIR` as `$ENCODING` format (PEM or DER). This command uses the `SNP_GET_EXT_REPORT` ioctl of the ASP. + +The output depends on which certificates are cached in the hypervisor memory. Before executing this command, the host (platform owner) must fetch certificates from AMD KDS and load them into the extended configuration. Should no certificates be loaded, this command will causes a SEV-SNP guest firmware error. + +In principle, the host can cache any certificate. However, in practice, it typically caches only the leaf certificate (VCEK or VLEK) or the entire certificate chain. -- `$ENCODING` : Specifies the certificate encoding to store the certificates in (PEM or DER). +#### Arguments -- `$CERTS_DIR` : Specifies the directory to store the certificates in. This is required only when requesting an extended attestation report. +| Argument | Description | Default | +| :-- | :-- | :-- | +| `$ENCODING` | The certificate encoding to store the certificates in (PEM or DER). All certificates will be in the same encoding. | *required* | +| `$CERTS_DIR` | The directory to store the certificates in. If certificates already exist in the provided directory, they will be overwritten. | *required* | + +#### Example -**Example** ```bash snpguest certificates pem ./certs ``` -### 3. `display` +### 3. `fetch ca` -Displays files in human readable form. - -**Usage** ```bash -snpguest display +snpguest fetch ca $ENCODING $CERTS_DIR $PROCESSOR_MODEL [OPTIONS] ``` -**Subcommands** +Fetches the AMD root CA certificate (ARK) and the AMD intermediate certificate (ASK for VCEK or ASVK for VLEK) from the AMD KDS, and writes them into `$CERTS_DIR` in `$ENCODING` format (PEM or DER). + +The user must specify either the host processor model `$PROCESSOR_MODEL` (`milan`, `genoa`, `bergano`, `sienna`, `turin`) or the path to an attestation report using the `--report` option. When the report is provided, the command attempts to infer the host processor model from fields embedded in the report. Autodetection succeeds only under the following conditions: + +1. **Report Version 3 or later** + - both `CPU_FAM_ID` and `CPU_MOD_ID` is present (i.e. not missing) +2. **Report Version 2** + - the host processor model is Turin + - the `CHIP_ID` is not masked, i.e. `MASK_CHIP_ID` is zero-filled + +In the latter case, automatic detection is based on heuristics: whereas pre-Turin's `CHIP_ID` utilises the full 64 bytes, Turin's `CHIP_ID` uses only the first 8 bytes. This heuristics may not remain valid for future processors. + +The `--endorser` option specifies the type of attestation signing key (VCEK or VLEK). The default value is VCEK. + +#### Arguments and Options + +| Argument/Option | Description | Default | +| :-- | :-- | :-- | +| `$ENCODING` | The certificate encoding to store the certificates in (PEM or DER). | *required* | +| `$CERTS_DIR` | The directory to store the certificates in. | *required* | +| `$PROCESSOR_MODEL` | The host processor model (`milan`, `genoa`, `bergano`, `sienna`, `turin`). (Conflicts with `--report`) | required | +| `-r, --report` | Path to the attestation report to detect the host processor model. (Conflicts with `$PROCESSOR_MODEL`) | - | +| `-e, --endorser` | The endorser type (`vcek` or `vlek`). | `vcek` | -1. `report` +#### Example - When used for displaying a report, it prints the attestation report contents into the terminal. The user has to provide the path of the stored attestation report to display. +```bash +# Fetch CA cert chain in DER encoding for with milan with VLEK +# ark.der and asvk.der will be stored in ./certs +snpguest fetch ca der ./certs milan -e vlek - **Usage** - ```bash - snpguest display report $ATT_REPORT_PATH - ``` +# Fetch CA cert chain in PEM encoding associated with V3+ report and VCEK +# ark.pem and ask.pem will be stored in ./certs +snpguest fetch ca pem ./certs -r report.bin -e vcek +``` - **Argument** +### 4. `fetch vcek` - - `$ATT_REPORT_PATH` : Specifies the path of the stored attestation report to display. +```bash +snpguest fetch vcek $ENCODING $CERTS_DIR $ATT_REPORT_PATH [OPTIONS] +``` - **Example** - ```bash - snpguest display report attestation-report.bin - ``` +Fetches the VCEK certificate from the AMD KDS, and write it into `$CERTS_DIR` in `$ENCODING` format (PEM or DER). -2. `key` +The user must provide the path to an attestation report `$ATT_REPORT_PATH` to get the REPORTED_TCB and CHIP_ID. - When used for displaying the fetched derived key's contents, it prints the derived key in hex format into the terminal. The user has to provide the path of a stored derived key to display. +The user can specify the host processor model using the `--processor-model` option. If the processor model is not specified, the command attempts to infer the host processor model from the report contents. Processor model autodetection follows the same rules and limitations as described in +[fetch ca](#3-fetch-ca). - **Usage** +#### Arguments and Options - ```bash - snpguest display key $KEY_PATH - ``` - **Argument** +| Argument/Option | Description | Default | +| :-- | :-- | :-- | +| `$ENCODING` | The certificate encoding to store the certificates in (PEM or DER). | *required* | +| `$CERTS_DIR` | The directory to store the certificates in. | *required* | +| `$ATT_REPORT_PATH` | The path of the stored attestation report. | *required* | +| `-p, --processor-model` | The host processor model (`milan`, `genoa`, `bergano`, `sienna`, `turin`). If the report is *older than version 3*, this option must be specified. | - | - - `$KEY_PATH` : Specifies the path of the stored derived key to display. +#### Example - **Example** - ```bash - snpguest display key derived-key.bin - ``` +```bash +# Fetch VCEK certificate in PEM encoding associated with V3+ report from AMD KDS +# vcek.pem will be stored in ./certs +snpguest fetch vcek pem ./certs report.bin -### 4. `fetch` +# If the report is older than V3, manually specify the processor model +snpguest fetch vcek pem ./certs report.bin -p milan +``` -Command to Requests certificates from the KDS. +### 5. `fetch crl` -**Usage** ```bash -snpguest fetch +snpguest fetch crl $ENCODING $CERTS_DIR $PROCESSOR_MODEL [OPTIONS] ``` -**Subcommands** -1. `ca` +Fetches the Certificate Revocation List (CRL) from the AMD KDS, and writes it into `$CERTS_DIR` in `$ENCODING` format (PEM or DER). This command has completely the same interface as `snpguest fetch ca`. - Requests the certificate authority chain (ARK & ASK/ASVK) from the KDS. The user needs to specify the certificate encoding to store the certificates in (PEM or DER). Currently, only PEM and DER encodings are supported. Both certificates will be in the same encoding. The user must specify their host processor model. The user also needs to provide the path to the directory where the certificates will be stored. If the certificates already exist in the provided directory, they will be overwritten. The `--endorser` argument specifies the type of attestation signing key (defaults to VCEK). +#### Arguments and Options - **Usage** - ```bash - # Fetch CA chain of the user-provided processor model - snpguest fetch ca $ENCODING $CERTS_DIR $PROCESSOR_MODEL --endorser $ENDORSER - # Fetch CA chain of the processor-model written in the attestation report - snpguest fetch ca $ENCODING $CERTS_DIR --report $ATT_REPORT_PATH --endorser $ENDORSER - ``` - - **Arguments** - | Argument | Description | Default | - | :-- | :-- | :-- | - | `$ENCODING` | Specifies the certificate encoding to store the certificates in (PEM or DER). | required | - | `$CERTS_DIR` | Specifies the directory to store the certificates in. | required | - | `$PROCESSOR_MODEL` | Specifies the host processor model (conflict with `$ATT_REPORT_PATH`). | required | - | `-r, --report $ATT_REPORT_PATH` | Specifies the attestation report to detect the host processor model (conflict with `$PROCESSOR_MODEL`) | — | - | `-e, --endorser $ENDORSER` | Specifies the endorser type, possible values: "vcek", "vlek". | "vcek" | - - **Example** - ```bash - snpguest fetch ca der ./certs-kds milan -e vlek - ``` - ```bash - snpguest fetch ca pem ./certs-kds -r attestation-report.bin -e vcek - ``` - -2. `vcek` - - Requests the VCEK certificate from the KDS. The user needs to specify the certificate encoding to store the certificate in (PEM or DER). Currently, only PEM and DER encodings are supported. The user must specify their host processor model. The user also needs to provide the path to the directory where the VCEK will be stored and the path to a stored attestation report that will be used to request the VCEK. If the certificate already exists in the provided directory, it will be overwritten. - - **Usage** - ```bash - snpguest fetch vcek $ENCODING $CERTS_DIR $ATT_REPORT_PATH --processor-model $PROCESSOR_MODEL - ``` - - **Arguments** - | Argument | Description | Default | - | :-- | :-- | :-- | - | `$ENCODING` | Specifies the certificate encoding to store the certificates in (PEM or DER). | required | - | `$CERTS_DIR` | Specifies the directory to store the certificates in. | required | - | `$ATT_REPORT_PATH` | Specifies the path of the stored attestation report. | required | - | `-p, --processor-model $PROCESSOR_MODEL` | Specifies the host processor model. | — | - - **Example** - ```bash - snpguest fetch vcek pem ./certs-kds attestation-report.bin - ``` - -3. `crl` - - Requests the Certificate Revocation List (CRL) from the KDS. It takes the same set of arguments as `snpguest fetch ca`. The user needs to specify the encoding to store the CRL in (PEM or DER). Currently, only PEM and DER encodings are supported. The user must specify their host processor model. The user also needs to provide the path to the directory where the CRL will be stored. If the CRL already exists in the provided directory, it will be overwritten. The `--endorser` argument specifies the type of attestation signing key (defaults to VCEK). - - **Usage** - ```bash - # Fetch CRL of the user-provided processor model - snpguest fetch crl $ENCODING $CERTS_DIR $PROCESSOR_MODEL --endorser $ENDORSER - # Fetch CRL of the processor-model written in the attestation report - snpguest fetch crl $ENCODING $CERTS_DIR --report $ATT_REPORT_PATH --endorser $ENDORSER - ``` - - **Arguments** - | Argument | Description | Default | - | :-- | :-- | :-- | - | `$ENCODING` | Specifies the encoding to store the CRL in (PEM or DER). | required | - | `$CERTS_DIR` | Specifies the directory to store the CRL in. | required | - | `$PROCESSOR_MODEL` | Specifies the host processor model (conflict with `--report`). | required | - | `-r, --report $ATT_REPORT_PATH` | Specifies the attestation report to detect the host processor model (conflict with `$PROCESSOR_MODEL`) | — | - | `-e, --endorser $ENDORSER` | Specifies the endorser type, possible values: "vcek", "vlek". | "vcek" | +| Argument/Option | Description | Default | +| :-- | :-- | :-- | +| `$ENCODING` | The CRL encoding to store the CRL in (PEM or DER). | *required* | +| `$CERTS_DIR` | The directory to store the CRL in. | *required* | +| `$PROCESSOR_MODEL` | The host processor model (`milan`, `genoa`, `bergano`, `sienna`, `turin`). (Conflicts with `--report`) | required | +| `-r, --report` | Path to the attestation report to detect the host processor model. (Conflict with `$PROCESSOR_MODEL`) | - | +| `-e, --endorser` | The endorser type (`vcek` or `vlek`). | `vcek` | - Example - ```bash - snpguest fetch crl der ./certs-kds milan -e vlek - ``` - ```bash - snpguest fetch crl pem ./certs-kds -r attestation-report.bin -e vcek - ``` +#### Example -### 5. `key` +```bash +# Fetch CRL in DER encoding for milan with VLEK +# crl.der will be stored in ./certs +snpguest fetch crl der ./certs milan -e vlek -Creates the derived key based on input parameters and stores it. `$KEY_PATH` is the path to store the derived key. `$ROOT_KEY_SELECT` is the root key from which to derive the key (either "vcek" or "vmrk"). The `--guest_field_select` option specifies which Guest Field Select bits to enable as a 64-bit integer. Only the least-significant 6 bits (Message Version 1) or 7 bits (Message Version 2) are currently defined. Each of the bits from *right to left* correspond to Guest Policy, Image ID, Family ID, Measurement, SVN and TCB Version, Launch Mitigation Vector, respectively. For each bit, 0 denotes off, and 1 denotes on. The `--guest_svn` option specifies the guest SVN to mix into the key, the `--tcb_version` option specifies the TCB version to mix into the derived key, and the `--launch_mit_vector` option specifies the launch mitigation vector value to mix into the derived key. The `--vmpl` option specifies the VMPL level the Guest is running on and defaults to 1. +# Fetch CRL in PEM encoding associated with V3+ report and VCEK +# ark.pem and ask.pem will be stored in ./certs +snpguest fetch crl pem ./certs -r report.bin -e vcek +``` + +### 6. `verify certs` -**Usage** ```bash -snpguest key $KEY_PATH $ROOT_KEY_SELECT [-v, --vmpl] [-g, --guest_field_select] [-s, --guest_svn] [-t, --tcb_version] +snpguest verify certs $CERTS_DIR ``` -**Arguments** +Verifies that the provided certificate chain in `$CERTS_DIR` has been properly signed by each certificate. + +The user need to provide all three certificates in `$CERTS_DIR`, namely, the AMD root CA certificate (`ark.*`), the AMD intermediate CA certificate (`ask.*` or `asvk.*`), and the leaf certificate (`vcek.*` or `vlek.*`). + +This command then verifies that +- ARK is self-signed +- ASK (or ASVK) is signed by ARK +- VCEK (or VLEK) is signed by ASK (or ASVK) + +An error will be raised if any of the certificates fail verification. + +#### Arguments + | Argument | Description | Default | | :-- | :-- | :-- | -| `$KEY_PATH` | The path to store the derived key. | required | -| `$ROOT_KEY_SELECT` | is the root key from which to derive the key (either "vcek" or "vmrk"). | required | -| `-v, --vmpl $VMPL` | option specifies the VMPL level the Guest is running on. | 1 | -| `-g, --guest_field_select $GFS` | option specifies which Guest Field Select bits to enable as a 64-bit integer (decimal, prefixed hex or prefixed bin). | 0 | -| `-s, --guest_svn $GSVN` | option specifies the guest SVN to mix into the key (decimal, prefixed hex or prefixed bin). | 0 | -| `-t, --tcb_version $TCBV` | option specifies the TCB version to mix into the derived key (decimal, prefixed hex or prefixed bin). | 0 | -| `-l, --launch_mit_vector $LMV` | option specifies the launch mitigation vector value to mix into the derived key (decimal, prefixed hex or prefixed bin). Only available for `MSG_KEY_REQ` message version ≥ 2. | — | +| `$CERTS_DIR` | The directory where the certificates are stored in. | *required* | + +#### Example + +```bash +# Verify cert chain stored in ./certs +snpguest verify certs ./certs +``` -**Guest Field Select** +### 7. `verify attestation` + +```bash +snpguest verify attestation $CERTS_DIR $ATT_REPORT_PATH [OPTIONS] +``` + +Verifies the attestation report contents and signature using the VCEK/VLEK certificate and the given parameters. More precisely, this command performs the following verification steps: + +- Verify that the REPORTED_TCB and CHIP_ID fields in the report matches the given certificate. The `-s, --signature` option skips this step. +- Verify the report signature using the given certificate. The `-t, --tcb` option skips this step. +- (Option) Verify that each report field matches the user-provided reference value. Reference values must be provided in `0x`-prefixed hex string. Currently, the following options are supported: + + - `-r, --report-data` (64 bytes = 128 hex characters) + - `-m, --measurement` (48 bytes = 96 hex characters) + - `-d, --host-data` (32 bytes = 64 hex characters) + +The user can specify the host processor model using the `--processor-model` option. If the processor model is not specified, the command attempts to infer the host processor model from the report contents. Processor model autodetection follows the same rules and limitations as described in +[fetch ca](#3-fetch-ca). + +#### Arguments and Options + +| Argument/Option | Description | Default | +| :-- | :-- | :-- | +| `$CERTS_DIR` | The directory where the leaf certificate is stored in. | *required* | +| `$ATT_REPORT_PATH` | The path of the stored attestation report. | *required* | +| `-p, --processor-model $PROCESSOR_MODEL` | The host processor model (`milan`, `genoa`, `bergano`, `sienna`, `turin`). | - | +| `-t, --tcb` | Skip signature check. | - | +| `-s, --signature` | Skip TCB check. | - | +| `-r, --report-data` | Verify that the REPORT_DATA field in the report matches the given 64-byte data (`0x`-prefixed hex string). | - | +| `-m, --measurement` | Verify that the MEASUREMENT field in the report matches the given 48-byte data (`0x`-prefixed hex string). | - | +| `-d, --host-data` | Verify that the MEASUREMENT field in the report matches the given 32-byte data (`0x`-prefixed hex string). | - | + +#### Example + +```bash +# Verify Attestation (TCB and signature) +snpguest verify attestation ./certs report.bin + +# Verify TCB only +snpguest verify attestation ./certs report.bin --tcb + +# Verify Signature only +snpguest verify attestation ./certs report.bin --signature + +# Verify TCB, Signature and Report Data +snpguest verify attestation ./certs report.bin --report-data 0x5482c1ffe29145d47cf678f7681e3b64a89909d6cf8ec0104cfacb0b0418f005f564ad14f5c1381c99b74903a780ea340e887c9b445e9c760bf0b74115b26d45 + +# Verify TCB, Signature and Measurement +snpguest verify attestation ./certs report.bin --measurement 0xf28aac58964258d8ae0b2e88a706fc7afd0bb524f6a291ac3eedeccb73f89d7cfcf2e4fb6045e7d5201e41d1726afa02 + +# Verify TCB, Signature and Host Data +snpguest verify attestation ./certs report.bin --host-data 0x7e4a3f9c1b82a056d39f0d44e5c8a7b1f02394de6b58ac0d7e3c11af0042bd59 +``` + +### 8. `key` + +```bash +snpguest key $KEY_PATH $ROOT_KEY_SELECT [OPTIONS] +``` + +Requests the derived key from the AMD-SP based on input parameters, and stores it into `$KEY_PATH`. This command is a wrapper of the `SNP_GUEST_REQUEST(MSG_KEY_REQ)` ioctl of the AMD-SP. + +The user must specifies the root key `$ROOT_KEY_SELECT` from which to derive the key (either `vcek` or `vmrk`). + +The `--guest_field_select` option is a bit field of length 64, which specifies which data field will be mixed into the derived key. Each of the bits from *right to left* correspond to Guest Policy, Image ID, Family ID, Measurement, SVN and TCB Version, Launch Mitigation Vector, respectively. For each bit, 0 denotes off, and 1 denotes on. See also [Structure of Guest Field Select](#structure-of-guest-field-select). + +The `--vmpl` option specifies the VMPL the Guest is running on and defaults to 1. The default value is 1. If you specify a higher privilege level than is actually available (i.e. a lower VMPL value), a firmware error will occur. + +The `--guest_svn` option specifies the guest SVN to mix into the key. + +The `--tcb_version` option specifies the TCB version to mix into the derived key (must not exceed the committed TCB) + +The `--launch_mit_vector` option specifies the launch mitigation vector value to mix into the derived key. + +Note that the launch mitigation vector is only available for `MSG_KEY_REQ` message version ≥ 2. + +#### Arguments and Options + +| Argument/Option | Description | Default | +| :-- | :-- | :-- | +| `$KEY_PATH` | The path to store the derived key. | *required* | +| `$ROOT_KEY_SELECT` | The root key from which to derive the key (either `vcek` or `vmrk`). | *required* | +| `-v, --vmpl` | The VMPL value the Guest is running on. | 1 | +| `-g, --guest_field_select` | Guest Field Select bits to enable as a 64-bit integer (decimal, `0x`-prefixed hex or `0b`-prefixed bin). | 0 | +| `-s, --guest_svn` | Specifies the guest SVN to mix into the key (decimal, prefixed hex or prefixed bin). | 0 | +| `-t, --tcb_version` | Specifies the TCB version to mix into the derived key (decimal, prefixed hex or prefixed bin). Must not exceed the commited TCB. | 0 | +| `-l, --launch_mit_vector` | Specifies the launch mitigation vector value to mix into the derived key (decimal, prefixed hex or prefixed bin). Only available for `MSG_KEY_REQ` message version ≥ 2. | — | + +#### Structure of Guest Field Select | Bit | Field | Note | | :-- | :-- | :-- | -| 63:7 | (Reserved) | Currently not supported. | +| 63:7 | (Reserved) | Currently unused. | | 6 (MSB) | Launch MIT Vector | Set to 0 if not specified; supported for `MSG_KEY_REQ` message version ≥ 2. | | 5 | TCB Version | | | 4 | SVN | | @@ -228,131 +380,224 @@ For example, all of - `--guest_field_select 0x31` - `--guest_field_select 0b110001` -denote the following specification: -``` -Guest Policy:On (1), -Image ID:Off (0), +denote the following selection: + +```plaintext +Guest Policy: On (1), +Image ID: Off (0), Family ID: Off (0), Measurement: Off (0), -SVN:On (1), -TCB Version:On (1), -Launch MIT Vector: Off (none). +SVN: On (1), +TCB Version: On (1), +Launch MIT Vector: Off or None (0). ``` -**Example** +#### Example + ```bash # Creating and storing a derived key snpguest key derived-key.bin vcek --guest_field_select 0b110001 --guest_svn 2 --tcb_version 1 --vmpl 3 ``` -### 6. `report` +### 9. `display report` -Requests an attestation report from the host and writes it to a file with the provided request data and VMPL. The attestation report is written in binary format to the specified report path. The user can pass 64 bytes of data in any file format into `$REQUEST_FILE` to request the attestation report. This data will be bound to the REPORT_DATA field of the attestation report. The `--random` flag can be used to generate and use random data for the request, which will be written into `$REQUEST_FILE`. For Microsoft Azure Confidential VM, the `--platform` flag is required to get an attestation report from the vTPM. With this flag, the request data provided by the hypervisor will be written into the `$REQUEST_FILE`. `VMPL` is an optional parameter that defaults to 1. +```bash +snpguest display report $ATT_REPORT_PATH +``` + +Prints the attestation report contents into the terminal. The user has to provide the path of a stored attestation report `$ATT_REPORT_PATH` to display. + +#### Arguments + +| Argument | Description | Default | +| :-- | :-- | :-- | +| `$ATT_REPORT_PATH` | The path of the stored attestation report to display. | *required* | + +#### Example + +```bash +snpguest display report report.bin +``` + +### 10. `display key` -**Usage** ```bash -snpguest report $ATT_REPORT_PATH $REQUEST_FILE [-v, --vmpl] [-r, --random] [-p, --platform] +snpguest display key $KEY_PATH ``` -**Arguments** +Prints the derived key in hex format into the terminal. The user has to provide the path of a stored derived key `$KEY_PATH` to display. + +#### Arguments + | Argument | Description | Default | | :-- | :-- | :-- | -| `$ATT_REPORT_PATH` | Specifies the path where the attestation report would be stored. | required | -| `$REQUEST_FILE` | Specifies the path to the 64-byte request file.
• With `-r` flag, 64 random bytes will be written.
• With `-p` flag, writes 64 bytes provided by the hypervisor will be written.
• Without flags, the existing file contents are read as-is. | required | -| `-v, --vmpl $VMPL` | option specifies the VMPL level the Guest is running on.| 1 | -| `-r, --random` | Generate 64 random bytes of data for the report request. | false | -| `-p, --platform` | Fetch an attestation report from the vTPM NV index (Only available for Azure CVMs). | false | +| `$KEY_PATH` | The path of the stored derived key to display. | *required* | + +#### Example + +```bash +snpguest display key derived-key.bin +``` + +### 11. `generate measurement` -**Example** ```bash -# Requesting Attestation Report with user-generated data -snpguest report attestation-report.bin request-file.bin -# Requesting Attestation Report using random data -snpguest report attestation-report.bin random-request-file.bin --random -# Get Pregenerated Attestation Report and Request Data from vTPM -snpguest report attestation-report.bin platform-request-file.bin --platform +snpguest generate measurement [OPTIONS] ``` -### 7. `verify` +Calculates an expected launch digest measurement of secure guest, and prints it into the terminal or stores it into the specified path. + +Every parameter passed in is used to calculate this measurement, but the user does not need to provide every parameter. + +The only mandatory parameters are the `-o, --ovmf` parameter which is a path to the ovmf file used to launch the secure guest, and provide the guest vCPU type. + +There are 3 ways to provide the vCPU type, and the 3 of them are mutually exclusive (will get an error if the user tries to use more than one method): +- `--vcpu-type` A string with the vcpu-type used to launch the secure guest +- `--vcpu-sig` The signature of the vcpu-type used to launch the secure guest +- `--vcpu-family, --vcpu-model, --vcpu-stepping` The family, model and stepping of the vcpu used to launch the secure guest. Family, model and stepping have to be used together, if they're not all provided together an error will be raised. + +If the user provides the `-k, --kernel` parameter to calculate the measurement, they also need to provide `-i, --initrd` and `-a, --append`. + +There were kernel features added that affect the result of the measurement if those are enabled. With the `-g, --guest-features` parameter the user can provide which of this features are enabled in their kernel. -Verifies certificates and the attestation report. +The `-g, --guest-features` can be a hex or decimal number that cover the features enabled. For information on the guest-features bitfield checkout [virtee/sev/src/measurement/vmsa.rs](https://github.com/virtee/sev/blob/main/src/measurement/vmsa.rs). + +A user can use a pre-calculated ovmf-hash using `--ovmf-hash`, but the ovmf file still has to be provided. + +The calculated measurement will be printed in the console. If the user wishes to store the measurement value they can provide a file path with `-m, --measurement-file` and the measurement will get written there. + +If the global `-q, --quiet` flag is used, nothing will be printed out. + +#### Options + +| Option | Description | Default | +| :-- | :-- | :-- | +| `-v, --vcpus` | Number of guest vCPUs. | 1 | +| `--vcpu-type` | Type of guest vCPU. Either this parameter, `--vcpu-sig`, or the triplet (`--vcpu-family`, `--vcpu-model`, `--vcpu-stepping`) must be specified. (Conflicts with the other `--vcpu-*` parameters) | *required* | +| `--vcpu-sig` | Guest vCPU signature value. (Conflicts with the other `--vcpu-*` options) | - | +| `--vcpu-family`, `--vcpu-model`, `--vcpu-stepping` | Guest vCPU family, model, and stepping. When specifying the vCPU type using these options, all three options must be specified. (Conflicts with `--vcpu-type` and `--vcpu-sig`) | - | +| `--vmm-type` | Guest VMM type (QEMU, EC2, KRUN). | - | +| `-o, --ovmf` | OVMF file path to calculate measurement from. Either this option or `--ovmf-hash` must be specified. (Conflicts with `--ovmf-hash`) | *required* | +| `-k, --kernel` | Kernel file path to calculate measurement from. | - | +| `-i, --initrd` | Initrd file path to calculate measurement from. (Requires `--kernel`) | - | +| `-a, --append` | Kernel command line to calculate measurement from. (Requires `--kernel`) | - | +| `-g, --guest-features` | Decimal or prefixed-hex representation of the guest kernel features expected to be included. | `0x1` | +| `--ovmf-hash` | Precalculated hash of the OVMF binary. (Conflicts with `--ovmf`) | - | +| `-f, --output-format` | Output format (`base64` or `hex`). | `hex` | +| `-m, --measurement-file` | Optional file path where measurement value can be stored in. | stdout | + +#### List of vCPU types + +Currently the following vCPU types are available. The vCPU signature value can be calculated from the cprresponding vCPU (family, model, stepping). For details, see [AMD's CPUID Specification](https://www.amd.com/content/dam/amd/en/documents/archived-tech-docs/design-guides/25481.pdf). + +| vcpu_type | vcpu_family | vcpu_model | vcpu_stepping | +| :-- | :-- | :-- | :-- | +| `epyc` | 23 | 1 | 2 | +| `epyc-v1` | | | | +| `epyc-v2` | | | | +| `epyc-ibpb` | | | | +| `epyc-v3` | | | | +| `epyc-v4` | | | | +| `epyc-rome` | 23 | 49 | 0 | +| `epyc-rome-v1` | | | | +| `epyc-rome-v2` | | | | +| `epyc-rome-v3` | | | | +| `epyc-milan` | 25 | 1 | 1 | +| `epyc-milan-v1` | | | | +| `epyc-milan-v2` | | | | +| `epyc-genoa` | 25 | 17 | 0 | +| `epyc-genoa-v1` | | | | + +### 12. `generate ovmf-hash` -**Usage** ```bash -snpguest verify +snpguest generate ovmf-hash [OPTIONS] ``` -**Subcommands** -1. `certs` +Calculates the hash of an ovmf file. + +The user must specify the OVMF file using the `-o, --ovmf` option. - Verifies that the provided certificate chain has been properly signed by each certificate. The user needs to provide a directory where all three certificates (ARK, ASK/ASVK and VCEK/VLEK) are stored. An error will be raised if any of the certificates fail verification. +The user can specify the output format using the `-f, --output-format` option: "hex" or "base64" (default: "hex"). - **Usage** - ```bash - snpguest verify certs $CERTS_DIR - ``` - **Argument** +The hash will be printed in the console, if the user wishes to store the hash value they can provide a file path with `--hash-file` and the hash will get written there. - - `$CERTS_DIR` : Specifies the directory where the certificates are stored in. +If the global `-q, --quiet` flag is used, nothing will be printed out. - **Example** - ```bash - snpguest verify certs ./certs - ``` +#### Options -2. `attestation` +| Option | Description | Default | +| :-- | :-- | :-- | +| `-o, --ovmf` | Path to OVMF file to calculate hash from | *required* | +| `-f, --output-format` | Output format (`hex` or `base64`) | `hex` | +| `--hash-file` | Optional file where hash value can be stored in | stdout | - Verifies the contents of the Attestation Report using the VCEK/VLEK certificate. The user needs to provide the path to the directory containing the VCEK/VLEK certificate and the path to a stored attestation report to be verified. An error will be raised if the attestation verification fails at any point. The user can use the `-t, --tcb` flag to only validate the TCB contents of the report and the `-s, --signature` flag to only validate the report's signature. +### 13. `generate id-block` - **Usage** - ```bash - snpguest verify attestation $CERTS_DIR $ATT_REPORT_PATH [-t, --tcb] [-s, --signature] [-m, --measurement] [-d, --host-data] [-r, --report-data] - ``` - **Arguments** +```bash +snpguest generate id-block $ID_BLOCK_KEY $AUTH_KEY $LAUNCH_DIGEST [OPTIONS] +``` - - `$CERTS_DIR` : Specifies the directory where the certificates are stored in. +Calculates an id-block and auth-block for a secure guest. - - `$ATT_REPORT_PATH` : Specifies the path of the stored attestation report. +The user needs to provide a path to two different EC P-384 keys `$ID_BLOCK_KEY` and `$AUTH_KEY` in PEM or DER format. One will be for the id-block the other for the auth-block. - **Options** +The user also needs to provide the launch digest `$LAUNCH_DIGEST` (in either hex or base64 format) of the secure guest. The user can generate the launch digest using the `generate measurement` command. - - `-t, --tcb`: Verify the Reported TCB section of the report only. - - `-s, --signature`: Verify the signature of the report only. - - `-m, --measurement`: Verify the measurement from the attestation report. - - `-d, --host-data`: Verify the host-data from the attestation report. - - `-r, --report-data`: Verify the report-data from the attestation report. +The user can provide optional id's for further verification using the `-f, --family-id` and `-m, image-id` paramerters. Each parameter is 16 raw bytes (default: 0s). - **Example** - ```bash - # Verify Attestation - snpguest verify attestation ./certs attestation-report.bin - # Verify Attestation Reported TCB only - snpguest verify attestation ./certs attestation-report.bin --tcb - # Verify Attestation Signature only - snpguest verify attestation ./certs attestation-report.bin --signature - # Verify Attestation Measurement only - snpguest verify attestation --measurement 0xf28aac58964258d8ae0b2e88a706fc7afd0bb524f6a291ac3eedeccb73f89d7cfcf2e4fb6045e7d5201e41d1726afa02 /home/amd/certs /home/amd/report.bin - # Verify Attestation host-data only - snpguest verify attestation --host-data 0x7e4a3f9c1b82a056d39f0d44e5c8a7b1f02394de6b58ac0d7e3c11af0042bd59 /home/amd/certs /home/amd/report.bin - # Verify Attestation report-data only - snpguest verify attestation --report-data 0x5482c1ffe29145d47cf678f7681e3b64a89909d6cf8ec0104cfacb0b0418f005f564ad14f5c1381c99b74903a780ea340e887c9b445e9c760bf0b74115b26d45 /home/amd/certs /home/amd/report.bin - ``` +The user can provide the security version number of the guest using `-s, --svn` (default: 0). -### Global Options +The user can specify the launch policy of the guest using the `-p, --policy` parameter. The policy can be provided in either hex or decimal format. It will default to 0x30000. For more information on the guest-policy, see [SEV-SNP Firmware ABI Specification](https://www.amd.com/content/dam/amd/en/documents/developer/56860.pdf). -- **-q, --quiet**: Suppress console output. +The blocks will be printed in the console, if the user wishes to store the blocks values they can provide a file path with `-i, --id-file` for the id-block and `-a, --auth-file` for the auth-block. + +If the global `-q, --quiet` flag is used, nothing will be printed out. + +The digest will be printed in the console. If the user wishes to store the digest value they can provide a file path with [-d, --key-digest-file]. + +#### Arguments and Options + +| Argument/Option | Description | Default | +| :-- | :-- | :-- | +| `$ID_BLOCK_KEY` | Path to the Id-Block key | *required* | +| `$AUTH_KEY` | Path to the Auth-Block key | *required* | +| `$LAUNCH_DIGEST` | Guest launch measurement in either Base64 encoding or hex (if hex prefix with 0x) | *required* | +| `-f, --family-id` | Family ID of the guest provided by the guest owner (16 bytes) | 0s | +| `-m, --image-id` | Image ID of the guest provided by the guest owner (16 bytes) | 0s | +| `-v, --version` | Id-Block version. Currently only version 1 is available | 1 | +| `-s, --svn` | SVN of the guest | 0 | +| `-p, --policy` | Launch policy of the guest. Can provide in decimal or hex format. | 0x30000 | +| `-i, --id-file` | Optional file where the Id-Block value can be stored in | stdout | +| `-a, --auth-info-file` | Optional file where the Auth-Block value can be stored in | stdout | + +### 14. `generate key-digest` -**Usage** ```bash -snpguest -q +snpguest generate key-digest $KEY_PATH [-d, --key-digest-file] ``` -### [Extended Attestation Workflow](#extended-attestation-flowchart) +Generates an SEV key digest for a provided EC P-384 key. -**Step 1.** Request the attestation report by providing the two mandatory parameters - `$ATT_REPORT_PATH` which is the path pointing to where the user wishes to store the attestation report and `$REQUEST_FILE` which is the path pointing to where the request file used to request the attestation report is stored. The optional parameter \[`-v, --vmpl`\] specifies the vmpl level for the attestation report and is set to 1 by default. The flag \[`-r, --random`\] generates random data to be used as request data for the attestation report. Lastly, the flag \[`-p, --platform`\] obtains both the attestation report and the request data from the platform (only available for a Microsoft Azure CVM where Hyper-V guest is enabled). +User needs to provide a path to the key `$KEY_PATH`. The key has to be an EC P-384 key in either PEM or DER format. + +The digest will be printed in the console. If the user wishes to store the digest value they can provide a file path with `-d, --key-digest-file`. + +If the global `-q, --quiet` flag is used, nothing will be printed out. + +#### Arguments and Options + +| Argument/Option | Description | Default | +| :-- | :-- | :-- | +| `$KEY_PATH` | Path to key to generate hash for | *required* | +| `-d, --key-digest-file` | File to store the key digest in | stdout | + +## [Extended Attestation Workflow](#extended-attestation-flowchart) + +**Step 1.** Request the attestation report by providing the two mandatory parameters - `$ATT_REPORT_PATH` which is the path pointing to where the user wishes to store the attestation report and `$REQUEST_FILE` which is the path pointing to where the request file used to request the attestation report is stored. The optional parameter `-v, --vmpl` specifies the vmpl level for the attestation report and is set to 1 by default. The flag `-r, --random` generates random data to be used as request data for the attestation report. Lastly, the flag `-p, --platform` obtains both the attestation report and the request data from the platform (only available for a Microsoft Azure CVM where Hyper-V guest is enabled). ```bash -snpguest report $ATT_REPORT_PATH $REQUEST_FILE [-v, --vmpl] [-r, --random] [-p, --platform] +snpguest report $ATT_REPORT_PATH $REQUEST_FILE [-v, --vmpl] $VMPL [-r, --random] [-p, --platform] ``` **Step 2.** Request certificates from the extended memory by providing the two mandatory parameters - `$ENCODING` which specifies whether to use PEM or DER encoding to store the certificates and $CERTS_DIR which specifies the path in the user's directory where the certificates will be saved. @@ -369,18 +614,18 @@ In some environments, only the VCEK/VLEK certificate can be obtained. In this ca snpguest verify certs $CERTS_DIR ``` -**Step 4.** Verify the attestation by providing the two mandatory parameters - `$CERTS_DIR` which specifies the path in the user's directory where the certificates were saved from Step 2 and `$ATT_REPORT_PATH` which is the path pointing to the stored attestation report which the user wishes to verify. The optional parameters \[`-t, --tcb`\] is used to verify just the Reported TCB contents of the attestaion report and \[`-s, --signature`\] is used to verify just the signature of the attestaion report. +**Step 4.** Verify the attestation by providing the two mandatory parameters - `$CERTS_DIR` which specifies the path in the user's directory where the certificates were saved from Step 2 and `$ATT_REPORT_PATH` which is the path pointing to the stored attestation report which the user wishes to verify. The optional parameters `-t, --tcb` is used to verify just the Reported TCB contents of the attestaion report and `-s, --signature` is used to verify just the signature of the attestaion report. ```bash snpguest verify attestation $CERTS_DIR $ATT_REPORT_PATH [-t, --tcb] [-s, --signature] ``` -### [Regular Attestation Workflow](#regular-attestation-flowchart) +## [Regular Attestation Workflow](#regular-attestation-flowchart) -**Step 1.** Request the attestation report by providing the two mandatory parameters - `$ATT_REPORT_PATH` which is the path pointing to where the user wishes to store the attestation report and `$REQUEST_FILE` which is the path pointing to where the request file used to request the attestation report is stored. The optional parameter \[`-v, --vmpl`\] specifies the vmpl level for the attestation report and is set to 1 by default. The flag \[`-r, --random`\] generates random data to be used as request data for the attestation report. Lastly, the flag \[`-p, --platform`\] obtains both the attestation report and the request data from the platform (only available for a Microsoft Azure CVM where Hyper-V guest is enabled). +**Step 1.** Request the attestation report by providing the two mandatory parameters - `$ATT_REPORT_PATH` which is the path pointing to where the user wishes to store the attestation report and `$REQUEST_FILE` which is the path pointing to where the request file used to request the attestation report is stored. The optional parameter `-v, --vmpl` specifies the vmpl level for the attestation report and is set to 1 by default. The flag `-r, --random` generates random data to be used as request data for the attestation report. Lastly, the flag `-p, --platform` obtains both the attestation report and the request data from the platform (only available for a Microsoft Azure CVM where Hyper-V guest is enabled). ```bash -snpguest report $ATT_REPORT_PATH $REQUEST_FILE [-v, --vmpl] [-r, --random] [-p, --platform] +snpguest report $ATT_REPORT_PATH $REQUEST_FILE [-v, --vmpl] $VMPL [-r, --random] [-p, --platform] ``` **Step 2.** Request AMD Root Key (ARK) and AMD SEV Key (ASK) (or AMD SEV-VLEK Key (ASVK) for VLEK) from the AMD Key Distribution Service (KDS) by providing the three mandatory parameters - `$ENCODING` which specifies whether to use PEM or DER encoding to store the certificates, `$CERTS_DIR` which specifies the path in the user's directory where the certificates will be saved, and `$PROCESSOR_MODEL` - which specifies the AMD Processor model for which the certificates are to be fetched. The optional `-e, --endorser` argument specifies the type of attestation signing key (defaults to VCEK). @@ -389,7 +634,7 @@ snpguest report $ATT_REPORT_PATH $REQUEST_FILE [-v, --vmpl] [-r, --random] [-p, snpguest fetch ca $ENCODING $CERTS_DIR $PROCESSOR_MODEL [-e, --endorser] $ENDORSER ``` -**Step 3.** Request the Versioned Chip Endorsement Key (VCEK) from the AMD Key Distribution Service (KDS) by providing the three mandatory parameters - `$ENCODING` which specifies whether to use PEM or DER encoding to store the certificates, `$CERTS_DIR` which specifies the path in the user's directory where the certificates will be saved, and `$ATT_REPORT_PATH` which is the path pointing to the stored attestation report for detecting Chip ID and Reported TCB Version. The optional \[`-p, --processor-model`\] argument specifies the AMD Processor model for which the certificates are to be fetched. +**Step 3.** Request the Versioned Chip Endorsement Key (VCEK) from the AMD Key Distribution Service (KDS) by providing the three mandatory parameters - `$ENCODING` which specifies whether to use PEM or DER encoding to store the certificates, `$CERTS_DIR` which specifies the path in the user's directory where the certificates will be saved, and `$ATT_REPORT_PATH` which is the path pointing to the stored attestation report for detecting Chip ID and Reported TCB Version. The optional `-p, --processor-model` argument specifies the AMD Processor model for which the certificates are to be fetched. ```bash snpguest fetch vcek $ENCODING $CERTS_DIR $ATT_REPORT_PATH [-p, --processor-model] $PROCESSOR_MODEL @@ -401,7 +646,7 @@ snpguest fetch vcek $ENCODING $CERTS_DIR $ATT_REPORT_PATH [-p, --processor-model snpguest verify certs $CERTS_DIR ``` -**Step 5.** Verify the attestation by providing the two mandatory parameters - `$CERTS_DIR` which specifies the path in the user's directory where the certificates were saved from Step 2 and `$ATT_REPORT_PATH` which is the path pointing to the stored attestation report which the user wishes to verify. The optional parameters \[`-t, --tcb`\] is used to verify just the Reported TCB contents of the attestaion report and \[`-s, --signature`\] is used to verify just the signature of the attestaion report. +**Step 5.** Verify the attestation by providing the two mandatory parameters - `$CERTS_DIR` which specifies the path in the user's directory where the certificates were saved from Step 2 and `$ATT_REPORT_PATH` which is the path pointing to the stored attestation report which the user wishes to verify. The optional parameters `-t, --tcb` is used to verify just the Reported TCB contents of the attestaion report and `-s, --signature` is used to verify just the signature of the attestaion report. ```bash snpguest verify attestation $CERTS_DIR $ATT_REPORT_PATH [-t, --tcb] [-s, --signature] @@ -412,43 +657,80 @@ snpguest verify attestation $CERTS_DIR $ATT_REPORT_PATH [-t, --tcb] [-s, --signa ## Regular Attestation Flowchart ![alt text](https://github.com/virtee/snpguest/blob/main/docs/regular.PNG?raw=true) -## Building +## Build + +### For Standard CVMs + +```bash +# Build +git clone https://github.com/virtee/snpguest +cd snpguest +cargo build -r + +# Install from the repository +cargo install --git https://github.com/virtee/snpguest + +# Install from crate.io +cargo install snpguest +``` + +### For Azure CVMs + +On Azure CVMs, all communication between the guest OS and AMD-SP is proxied by the OpenHCL paravisor. The native `/dev/sev-guest` interface is hidden from the guest OS. The user must specify the `--platform` flag to get an attestation report; this flag is available only in builds compiled with the `hyperv` feature. + +```bash +# Install additional dependencies +sudo apt update +sudo apt install -y pkg-config libtss2-dev + +# Build +git clone https://github.com/virtee/snpguest +cd snpguest +cargo build -r --features hyperv + +# Install from the repository +cargo install --git https://github.com/virtee/snpguest --features hyperv + +# Install from crate.io +cargo install snpguest --features hyperv +``` + +### Build Dependencies + +Some packages may need to be installed on the guest system in order to build `snpguest`. -Some packages may need to be installed on the host system in order to build `snpguest`. +#### Rust ```bash -#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 Dependencies + +#### Ubuntu Dependencies ```bash sudo apt install build-essential ``` -### RHEL and its compatible distributions Dependencies +#### RHEL and its compatible distributions Dependencies ```bash sudo dnf groupinstall "Development Tools" "Development Libraries" ``` -### openSUSE and its compatible distributions Dependencies +#### openSUSE and its compatible distributions Dependencies ```bash sudo zypper in -t pattern "devel_basis" ``` -### Building for Azure Confidential VMs -On Azure CVMs with AMD SEV-SNP, the paravisor fetches the report from AMD-SP once at VM boot time, and stores it in the vTPM NV index. The native `/dev/sev-guest` interface is hidden from the guest OS, so the guest OS must retrieve the report from the vTPM NV index using the `--platform` flag, which is available only in builds compiled with the `hyperv` feature. +### Load sev-guest module + +In some guest environments, the device `/dev/sev-guest` does not created by default. In such cases, make sure that the kernel supports SEV-SNP, then load the sev-guest module. ```bash -git clone https://github.com/virtee/snpguest -cd ./snpguest -cargo build -r --features hyperv +modprobe sev-guest +ls -l /dev/sev-guest ``` ## Reporting Bugs diff --git a/docs/snpguest.1.adoc b/docs/snpguest.1.adoc index 7ffcc34..779251f 100644 --- a/docs/snpguest.1.adoc +++ b/docs/snpguest.1.adoc @@ -14,13 +14,13 @@ SYNOPSIS DESCRIPTION ----------- -snpguest is a CLI utility for navigating and interacting with the AMD SEV-SNP -guest firmware device of a guest system. +snpguest is a CLI utility for navigating and interacting with the AMD SEV-SNP guest firmware device of a guest system. GLOBAL OPTIONS -------------- -*-q, --quiet*:: Don't print any output to the console. +*-q, --quiet*:: + Don't print any output to the console. COMMANDS @@ -28,137 +28,165 @@ COMMANDS *snpguest report*:: usage: snpguest report $ATT_REPORT_PATH $REQUEST_FILE [-v, --vmpl] $VMPL [-r, --random] [-p, --platform] - Requests an attestation report from the host and writes it in a file with the provided request data and vmpl. - Will write the contents of the attestation report in binary format into the specified report path. - A path for the attestation report must be provided. - User can pass 64 bytes of data in raw binary format into $REQUEST_FILE in order to use that data to request the attestation report. - The user can use the --random flag to generate and use random data for request data. - For Microsoft Hyper-V guests, a user can use the --platform flag to use the request data that was pre-generated - from the platform. Currently, for Hyper-V guests, --platform is required, as there is no ability to write - request data for the attestation report. - If --random is used, the random data was will be written in raw bytes into $REQUEST_FILE, instead of reading from that file. - For Microsoft Hyper-V guests, a user can use the --platform flag to use the request data that was pre-generated - from the platform. Currently, for Hyper-V guests, --platform is required, as there is no ability to write - request data for the attestation report. - The pre-generated data will be taken from the platform attestation report and then written in raw byte format into $REQUEST_FILE. - VMPL is an optional parameter and it defaults to 1. + Requests an attestation report from the AMD Secure Processor (ASP), and writes it to $ATT_REPORT_PATH as raw binary. This command is a wrapper of the SNP_GUEST_REQUEST(MSG_REPORT_REQ) ioctl. + Without [-p, --platform] or [-r, --random], the user can pass 64 bytes of data in any file format into $REQUEST_FILE to request an attestation report. The request file is interpreted as raw binary, and the first 64 bytes of the binary are sent to the AMD-SP as the request data. The request data will be bound to the REPORT_DATA field in the attestation report. + With the [-r, --random] flag, this command generates a random data for the request, which will be written into $REQUEST_FILE. + The [-v, --vmpl] option specifies the Virtual Machine Privilege Level (VMPL) to request an attestation report. The default value is 1. If you specify a higher privilege level (i.e. smaller VMPL value) than the actual one, a firmware error will occur. + With the [-p, --platform] flag, this command retrieves an attestation report from vTPM instead of the ASP, and writes the Report Data field in the retrieved report into $REQUEST_FILE. This attestation route is available (and mandatory) on Microsoft Azure Confidential VMs with SEV-SNP isolation. This flag requires the `hyperv` feature. Currently, only the pre-generated attestation report can be retrieved with this command. + + arguments: + $ATT_REPORT_PATH: Specifies the path where the attestation report would be stored. + $REQUEST_FILE: Specifies the path to the 64-byte request file. options: - -h, --help show a help message. - -p, --platform Use platform generated 64 bytes of data to pass for the report request (Only available for Hyper-V). - -r, --random Generate 64 random bytes of data to pass for the report request (Not available for Hyper-V). - -v, --vmpl Specify a different vmpl level for the attestation report (defaults to 1). + -h, --help: show a help message. + -v, --vmpl: specify the VMPL level the Guest is running on (default: 1). + -r, --random: Generate 64 random bytes of data for the report request. + -p, --platform: Get an attestation report from the vTPM NV index (Only available for Azure CVMs). *snpguest certificates*:: usage: snpguest certificates $ENCODING $CERTS_DIR - Requests the certificate chain (ASK, ARK & VCEK) from host memory (requests extended-config). - The user needs to specify the certificate encoding they would like store the certs in [PEM | DER]. - Currently only PEM and DER encondings are supported. - All of the certs will be in the same encoding. - The user also needs to provide the path to the directory where the certs will be stored. - If the certificate already exists in the provided directory, it will be overwritten. - The attestation report will be ingored for this request, to request and store an attestation report use the "report" command. + Requests the VEK certificate chain (ARK, ASK/ASVK and VCEK/VLEK) from host memory (requests extended-config). + The user needs to specify the certificate encoding to store the certificates in (PEM or DER). Currently, only PEM and DER encodings are supported. + All certificates will be in the same encoding. + The user also needs to provide the path to the directory where the certificates will be stored. + If certificates already exist in the provided directory, they will be overwritten. + + arguments: + $ENCODING: Specify the certificate encoding to store the certificates in (PEM or DER). + $CERTS_DIR: Specify the directory to store the certificates in. options: - -h, --help show a help message + -h, --help: show a help message *snpguest fetch ca*:: - usage: snpguest fetch ca $ENCODING $CERTS_DIR $PROCESSOR_MODEL [-r, --report] $ATT_REPORT_PATH [-E --endorser] $ENDORSEMENT - - Requests the certificate authority chain (ARK & ASK) from the KDS. - The user needs to specify the certificate encoding they would like to store the certs in [PEM | DER]. - Currently, only PEM and DER encodings are supported. - Both certificates will be in the same encoding. - The user needs to provide the path to the directory where the certs will be stored. - If the certificates already exist in the provided directory, they will be overwritten. - The user must either pass a V3 attestation report or manually specify the host processor model using the --processor_model flag. - This ensures the correct CA certificates for attestation are retrieved from the KDS. [Milan | Genoa | Bergamo | Siena | Turin] - Lastly, the user may specify the endorser they would like the CA chain for using the --endorser flag. [VCEK | VLEK] - It will default to VCEK. + usage: snpguest fetch ca $ENCODING $CERTS_DIR $PROCESSOR_MODEL [-r, --report] $ATT_REPORT_PATH [-e, --endorser] $ENDORSEMENT + + Requests the certificate authority chain (ARK & ASK/ASVK) from the KDS. + The user needs to specify the certificate encoding to store the certificates in (PEM or DER). Both certificates will be in the same encoding. + The user also needs to provide the path to the directory where the certificates will be stored. If the certificates already exist in the provided directory, they will be overwritten. + The user must specify either the host processor model or the path to an attestation report using the [-r, --report] option. When the report is provided, the command attempts to infer the host processor model from fields embedded in the report. + The [-e, --endorser] option specifies the type of attestation signing key (defaults to VCEK). + + arguments: + $ENCODING: Specify the certificate encoding to store the certificates in (PEM or DER). + $CERTS_DIR: Specify the directory to store the certificates in. + $PROCESSOR_MODEL: Specify the host processor model (conflict with --report). options: - -h, --help show a help message - -p, -processor_model Specify processor model to retrieve the CA certificates for. - -e, --enodorse Specify the endorser type to get the Ca certificates for. (defaults to: VCEK) + -h, --help: show a help message + -r, --report: Specify the attestation report to detect the host processor model (conflict with $PROCESSOR_MODEL). + -e, --endorser: Specify the endorser type, possible values: "vcek", "vlek" (default: "vcek"). *snpguest fetch vcek*:: - usage: snpguest fetch vcek $ENCODING $CERTS_DIR $ATT_REPORT_PATH [-p, --processor_model] $PROCESSOR_MODEL + usage: snpguest fetch vcek $ENCODING $CERTS_DIR $ATT_REPORT_PATH [-p, --processor-model] $PROCESSOR_MODEL Requests the VCEK certificate from the KDS. - The user needs to specify the certificate encoding they would like store the cert in [PEM | DER]. - Currently only PEM and DER encondings are supported. - The user needs to provide the path to the directory where the VCEK will be stored. - If the certificate already exists in the provided directory, it will be overwritten. - The user must either pass a V3 attestation report or manually specify the host processor model using the --processor_model flag. - This ensures the correct VCEK certificate for attestation is retrieved from the KDS. [Milan | Genoa | Bergamo | Siena | Turin] + The user needs to specify the certificate encoding to store the certificate in (PEM or DER). Currently, only PEM and DER encodings are supported. The user also needs to provide the path to the directory where the VCEK will be stored. If the certificate already exists in the provided directory, it will be overwritten. + To get the REPORTED_TCB and CHIP_ID, the user needs to provide the path to a stored attestation report. + The user can specify the host processor model using the [-p, --processor-model] option. If the processor model is not specified, the command attempts to infer the host processor model from the report contents. + + arguments: + $ENCODING: Specify the certificate encoding to store the certificates in (PEM or DER). + $CERTS_DIR: Specify the directory to store the certificates in. + $ATT_REPORT_PATH: Specify the path of the stored attestation report. options: - -h, --help show a help message - -p, --processor_model Specify processor model to retrieve the VCEK certificates for. + -h, --help: show a help message + -p, --processor-model: Specify the host processor model. + +*snpguest fetch crl*:: + usage: snpguest fetch crl $ENCODING $CERTS_DIR $PROCESSOR_MODEL [-r, --report] $ATT_REPORT_PATH [-e, --endorser] $ENDORSEMENT + + Requests the Certificate Revocation List (CRL) from the KDS. + It takes the same set of arguments as snpguest fetch ca. + The user needs to specify the encoding to store the CRL in (PEM or DER). + The user also needs to provide the path to the directory where the CRL will be stored. If the CRL already exists in the provided directory, it will be overwritten. + The user must either specify the host processor model or pass an attestation report using the [-r, --report] flag. + When the report is provided, the command attempts to infer the host processor model from fields embedded in the report. + The [-e, --endorser] option specifies the type of attestation signing key (defaults to VCEK). + + arguments: + $ENCODING: Specify the encoding to store the CRL in (PEM or DER). + $CERTS_DIR: Specify the directory to store the CRL in. + $PROCESSOR_MODEL: Specify the host processor model (conflict with --report). + + options: + -h, --help: show a help message + -r, --report: Specify the attestation report to detect the host processor model (conflict with $PROCESSOR_MODEL). + -e, --endorser: Specify the endorser type, possible values: "vcek", "vlek" (default: "vcek"). + -*snpguest guest verify certs*:: +*snpguest verify certs*:: usage: snpguest verify certs $CERTS_DIR Verifies that the provided certificate chain has been properly signed by each certificate. - The user needs to provide a directory were all 3 of the certificates are stored (ARK,ASK and VCEK). - Error will be raised if any of the certificates fails verification. + The user needs to provide a directory where all three certificates (ARK, ASK/ASVK and VCEK/VLEK) are stored. + An error will be raised if any of the certificates fail verification. + + argument: + $CERTS_DIR: Specify the directory where the certificates are stored in. options: - -h, --help show a help message + -h, --help: show a help message *snpguest verify attestation*:: - usage: snpguest verify attestation $CERTS_DIR $ATT_REPORT_PATH [-p, --processor_model] $PROCESSOR_MODEL [-t, --tcb] [-s, --signature] - - Verifies the contents of the Attestation Report using a VEK certificate. - The user needs to provide the path to the directory containing the VEK certificate. - The tool will automatically recognize whether it's a VLEK or VCEK. - If both a VLEK and a VCEK are in the directory, then the VCEK will be used. - The user also needs to provide the path to a stored attestation report to be verified. - If the report is not version 3 or newer, then the user can specify the cpu model to verify using the --processor_model flag. - If no processor model is passed, and the report is a version 2, then the verification will be treated as a Genoa or older verification. - An error will be raised if the attestation verification fails at any point. - The user can use the [-t, --tcb] flag to only validate the tcb contents of the report. - The user can use the [-s, --signature] flag to only validate the report signature. - The user can use the [-m, --measurement] flag to verify that the measurement in the attestation - report matches the expected measurement value (prefix with 0x for hex, without prefix it assumes - decimal values). - The user can use the [-d, --host-data] flag to verify that the host-data in the attestation - report matches the expected host-data value (prefix with 0x for hex, without prefix it assumes - decimal values). - The user can use the [-r, --report-data] flag to verify that the report-data in the attestation - report matches the expected report-data value (prefix with 0x for hex, without prefix it assumes - decimal values). - If the optional flags are not passed, just the signature will be verified. + usage: snpguest verify attestation $CERTS_DIR $ATT_REPORT_PATH [-p, --processor-model] $PROCESSOR_MODEL [-t, --tcb] [-s, --signature] + Verifies the contents of the Attestation Report using the VCEK/VLEK certificate. + The user needs to provide the path to the directory containing the VCEK/VLEK certificate and the path to a stored attestation report to be verified. + An error will be raised if the attestation verification fails at any point. + The user can specify the host processor model using the [-p, --processor-model] option. If the processor model is not specified, the command attempts to infer the host processor model from the report contents. + The user can use the [-t, --tcb] flag to skip the signature validation. + The user can use the [-s, --signature] flag to skip the reported TCB validation. + The user can use the [-m, --measurement] flag to verify that the measurement in the attestation report matches the expected measurement value (prefix with 0x for hex). + The user can use the [-d, --host-data] flag to verify that the host-data in the attestation report matches the expected host-data value (prefix with 0x for hex). + The user can use the [-r, --report-data] flag to verify that the report-data in the attestation report matches the expected report-data value (prefix with 0x for hex). + + arguments: + $CERTS_DIR: Specify the directory where the certificates are stored in. + $ATT_REPORT_PATH: Specify the path of the stored attestation report. + options: - -h, --help show a help message - -p, --processor_model Specify the processor model to use for verification - -t, --tcb verify the tcb section of the report only - -s, --signature verify the signature of the report only - -m, --measurement provide an expected measurement to verify the measurement field in the attestation report - -d, --host-data provide the expected host-data to verify the host-data field in the attestation report - -r, --report-data provide the expected report-data to verify the report-data in the attestation report + -h, --help: show a help message + -p, --processor-model: Specify the host processor model. + -t, --tcb: Skip the signature validation + -s, --signature: Skip the reported TCB validation + -m, --measurement: provide an expected measurement to verify the measurement field in the attestation report + -d, --host-data: provide the expected host-data to verify the host-data field in the attestation report + -r, --report-data: provide the expected report-data to verify the report-data in the attestation report *snpguest key*:: - usage: snpguest key $KEY_PATH $ROOT_KEY_SELECT [-g, --guest_field_select] [-s, --guest_svn] [-t, --tcb_version] [-v, --vmpl] + usage: snpguest key $KEY_PATH $ROOT_KEY_SELECT [-v, --vmpl] $VMPL [-g, --guest_field_select] $GFS [-s, --guest_svn] $GSVN [-t, --tcb_version] $TCBV [-l, --launch_mit_vector] $LMV - Creates the derived key based on input parameters and stores it. - $KEY_PATH is the path to store the derived key. - $ROOT_KEY_SELECT is the root key from which to derive the key. Input either "vcek" or "vmrk". - The --guest_field_select option specifies which Guest Field Select bits to enable. It is a 6 digit binary string. For each bit, 0 denotes off and 1 denotes on. - The least significant (rightmost) bit is Guest Policy followed by Image ID, Family ID, Measurement, SVN, TCB Version which is the most significant (leftmost) bit. - example: snpguest key $KEY_PATH $ROOT_KEY_SELECT --guest_field_select 100001 (Denotes Guest Policy:On, Image ID:Off, Family ID:Off, Measurement:Off, SVN:Off, TCB Version:On) - The --guest_svn specifies the guest SVN to mix into the key. Must not exceed the guest SVN provided at launch in the ID block. - The --tcb_version specified the TCB version to mix into the derived key. Must not exceed CommittedTcb. + Requests the derived key from the AMD-SP based on input parameters, and stores it into $KEY_PATH. This command is a wrapper of the SNP_GUEST_REQUEST(MSG_KEY_REQ) ioctl of the AMD-SP. + The user must specifies the root key $ROOT_KEY_SELECT from which to derive the key (either "vcek" or "vmrk"). + The [-g, --guest_field_select] option is a bit field of length 64, which specifies which data field will be mixed into the derived key. Each of the bits from right to left correspond to Guest Policy, Image ID, Family ID, Measurement, SVN and TCB Version, Launch Mitigation Vector, respectively. For each bit, 0 denotes off, and 1 denotes on. + The [-v, --vmpl] option specifies the VMPL the Guest is running on and defaults to 1. The default value is 1. If you specify a higher privilege level than is actually available (i.e. a lower VMPL value), a firmware error will occur. + The [-g, --guest_svn] option specifies the guest SVN to mix into the key. + The [-t, --tcb_version] option specifies the TCB version to mix into the derived key (must not exceed the committed TCB) + The [-l, --launch_mit_vector] option specifies the launch mitigation vector value to mix into the derived key. + Note that the launch mitigation vector is only available for the MSG_KEY_REQ message version 2 or later. + arguments: + $KEY_PATH: Specify the path to store the derived key. + $ROOT_KEY_SELECT: Specify the root key from which to derive the key (either "vcek" or "vmrk"). options: - -h, --help show a help message - -g, --guest_field_select Specify which Guest Field Select bits to enable. - -s, --guest_svn Specify the guest SVN to mix into the key. - -t, --tcb_version Specify the TCB version to mix into the derived key. - -v, --vmpl Specify VMPL level the Guest is running on. Defaults to 1. + -h, --help: show a help message + -v, --vmpl: specify the VMPL level the Guest is running on (default: 1). + -g, --guest_field_select Specify which Guest Field Select bits to enable as a 64-bit integer (decimal, prefixed hex or prefixed bin) (default: 0). + -s, --guest_svn: Specify the guest SVN to mix into the key (decimal, prefixed hex or prefixed bin) (default: 0). + -t, --tcb_version: Specify the TCB version to mix into the derived key (decimal, prefixed hex or prefixed bin) (default: 0). Must not exceed the commited TCB. + -l, --launch_mit_vector: Specify the launch mitigation vector value to mix into the derived key (decimal, prefixed hex or prefixed bin). Only available for MSG_KEY_REQ message version 2 or later. + +*snpguest ok*:: + usage: snpguest ok + + Performs a quick local check such as CPUID and MSRs (Model Specific Registers) to see if the SEV-SNP feature appears enabled in the guest environment. + Note that this command is only a sanity check and does not provide a cryptographic guarantee that the SEV-SNP is definitely valid. To obtain strict cryptographic assurance for the SEV-SNP, the user must perform remote attestation. + This command requires that the `msr` module is loaded. *snpguest generate measurement*:: usage: snpguest generate measurement [-v, --vcpus] [--vcpu-type] [--vcpu-sig] [--vcpu-family] [--vcpu-model] [--vcpu-stepping] [-t, --vmm-type] [-o ,--ovmf] [-k, --kernel] @@ -175,100 +203,111 @@ COMMANDS If the user provides the [-k, --kernel] parameter to calculate the measurement, they also need to provide [-i, --initrd] and [-a, --append]. There were kernel features added that affect the result of the measurement if those are enabled. With the [-g, --guest-features] parameter the user can provide which of this features are enabled in their kernel. The [-g, --guest-features] can be a hex or decimal number that cover the features enabled. - For information on the guest-features bitfield checkout: https://github.com/virtee/sev/blob/a3c91d7b6e742c1b5685a7e0c1e5464819527b06/src/measurement/vmsa.rs#L139 + For information on the guest-features bitfield checkout: https://github.com/virtee/sev/blob/main/src/measurement/vmsa.rs A user can use a pre-calculated ovmf-hash using [--ovmf-hash], but the ovmf file still has to be provided. - The calculated measurement will be printed in the console, if the user wishes to store the measurement value they can provide a file path with [-m, --measurement-file] and the measurement will get written there. + The calculated measurement will be printed in the console. If the user wishes to store the measurement value they can provide a file path with [-m, --measurement-file] and the measurement will get written there. If the [--quiet] flag is used, nothing will be printed out. options: - -h, --help Show a help message - -v, --vcpus Number of guest vcpus [default: 1] - --vcpu-type 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) + -h, --help Show a help message + -v, --vcpus Number of guest vcpus [default: 1] + --vcpu-type 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 Guest vcpu signature value - --vcpu-family Guest vcpu family - --vcpu-model Guest vcpu model - --vcpu-stepping Guest vcpu stepping + --vcpu-family Guest vcpu family + --vcpu-model Guest vcpu model + --vcpu-stepping Guest vcpu stepping -t, --vmm-type Type of guest vmm (QEMU, ec2, KRUN) [default: QEMU] - -o, --ovmf OVMF file to calculate measurement from - -k, --kernel Kernel file to calculate measurement from - -i, --initrd Initrd file to calculate measurement from - -a, --append Kernel command line in string format to calculate measurement from - -g, --guest-features Hex representation of the guest kernel features expected to be included [default: 0x1] - --ovmf-hash Precalculated hash of the OVMF binary - -f, --output-format Output format (base64, hex). [default: hex] - -m, --measurement-file Optional file path where the measurement value can be stored in + -o, --ovmf OVMF file to calculate measurement from + -k, --kernel Kernel file to calculate measurement from + -i, --initrd Initrd file to calculate measurement from + -a, --append Kernel command line in string format to calculate measurement from + -g, --guest-features Hex representation of the guest kernel features expected to be included [default: 0x1] + --ovmf-hash Precalculated hash of the OVMF binary + -f, --output-format Output format (base64, hex). [default: hex] + -m, --measurement-file Optional file path where the measurement value can be stored in *snpguest generate ovmf-hash*:: usage: snpguest generate ovmf-hash [-o, --ovmf] [-f, --output--format] [--hash-file] Calculates the hash of an ovmf file. - User only needs to provide the file they want the hash for. - The hash will be printed in the console, if the user wishes to store the hash value they can provide a file path with [--hash-file] and the hash will get written there. - If the [--quiet] flag is used, nothing will be printed out. + The user must specify the OVMF file using the [-o, --ovmf] option. + The user can specify the output format using the [-f, --output-format] option: "hex" or "base64" (default: "hex"). + The hash will be printed in the console. If the user wishes to store the hash value they can provide a file path with [--hash-file] and the hash will get written there. + If the global [-q, --quiet] flag is used, nothing will be printed out. options: - -h, --help Show a help message - -o, --ovmf OVMF file to generate hash for - -f, --output-format Output format (base64, hex). [default: hex] - --hash-file Optional file path where the hash value can be stored in + -h, --help: Show a help message + -o, --ovmf: OVMF file to generate hash for + -f, --output-format: Output format (hex, base64). [default: hex] + --hash-file: Optional file path where the hash value can be stored in *snpguest generate id-block*:: - usage: snpguest generate id-block $ID-BLOCK-KEY $AUTH-KEY $LAUNCH-DIGEST [-f, --family-id] [-m, --image-id] [-v, --version] [-s, --svn] [-p, --policy] + usage: snpguest generate id-block $ID_BLOCK_KEY $AUTH_KEY $LAUNCH_DIGEST [-f, --family-id] [-m, --image-id] [-v, --version] [-s, --svn] [-p, --policy] [-i, --id-file] [-a, --auth-file] Calculates an id-block and auth-block for a secure guest. User needs to provide a path to two different EC p384 keys in pem or der format. One will be for the id-block the other for the auth-block. The user will also need to provide the launch digest (in either hex or base64 format) of the secure guest. The user can generate the launch digest using the "generate measurement" command. - The user can provide optional id's for further verification using the [-f, --family-id] and [-m, image-id] paramerters. - The user can provide the security version number of the guest using [-s, --svn]. - The user can specify the launch policy of the guest using the [-p, --policy] parameter.. + The user can provide optional id's for further verification using the [-f, --family-id] and [-m, image-id] paramerters. Each parameter is 16 raw bytes (default: 0s). + The user can provide the security version number of the guest using [-s, --svn] (default: 0). + The user can specify the launch policy of the guest using the [-p, --policy] parameter. The policy can be provided in either hex or decimal format. It will default to 0x30000. - For more information on the guest-policy, you can refer to: https://www.amd.com/content/dam/amd/en/documents/epyc-technical-docs/specifications/56860.pdf#page=27 - The blocks will be printed in the console, if the user wishes to store the blocks values they can provide a file path with [-i, --id-file] for the id-block - and [-a, --auth-file] for the auth-block. - If the [--quiet] flag is used, nothing wibe printed out. + For more information on the guest-policy, see https://www.amd.com/content/dam/amd/en/documents/developer/56860.pdf + The blocks will be printed in the console. If the user wishes to store the blocks values they can provide a file path with [-i, --id-file] for the id-block and [-a, --auth-file] for the auth-block. + If the global [-q, --quiet] flag is used, nothing will be printed out. + + arguments: + $ID_BLOCK_KEY The path to the Id-Block key + $AUTH_KEY The path to the Auth-Block key + $LAUNCH_DIGEST Guest launch measurement in either Base64 encoding or hex (if hex prefix with 0x) options: - -h, --help Show a help message - -f, --family-id Family ID of the guest provided by the guest owner. Has to be 16 characters + -h, --help Show a help message + -f, --family-id Family ID of the guest provided by the guest owner. Has to be 16 characters -m, --image-id Image ID of the guest provided by the guest owner. Has to be 16 characters - -v, --version Id-Block version. Currently only version 1 is available - -s, --svn SVN (SECURITY VERSION NUMBER) of the guest - -p, --policy Launch policy of the guest. Can provide in decimal or hex format - -i, --id-file Optional file where the Id-Block value can be stored in + -v, --version Id-Block version. Currently only version 1 is available + -s, --svn SVN (SECURITY VERSION NUMBER) of the guest + -p, --policy Launch policy of the guest. Can provide in decimal or hex format + -i, --id-file Optional file where the Id-Block value can be stored in -a, --auth-file Optional file where the Auth-Block value can be stored in *snpguest generate key-digest*:: - usage: snpguest generate key-digest $KEY-PATH [-d, --key-digest-file] + usage: snpguest generate key-digest $KEY_PATH [-d, --key-digest-file] Generates an SEV key digest for a provided EC p384 key. - User needs to provide a path to the key + User needs to provide a path to the key. The key has to be a EC p384 key in either pem or der format. - The digest will be printed in the console, if the user wishes to store the digest value they can provide a file path with [-d, --key-digest-file] - If the [--quiet] flag is used, nothing wibe printed out. + The digest will be printed in the console. If the user wishes to store the digest value they can provide a file path with [-d, --key-digest-file]. + If the global [-q, --quiet] flag is used, nothing will be printed out. options: - -h, --help Show a help message - -d, --key-digest-file File to store the key digest in + -h, --help Show a help message + -d, --key-digest-file File to store the key digest in -*snpguest guest display report*:: +*snpguest display report*:: usage: snpguest display report $ATT_REPORT_PATH - Prints the attestation report contents into terminal. - The user has to provide a path to a stored attestation report to display. + When used for displaying a report, it prints the attestation report contents into the terminal. + The user has to provide the path of the stored attestation report to display. + + argument: + $ATT_REPORT_PATH Specify the path of the stored attestation report to display. options: - -h, --help show a help message + -h, --help show a help message -*snpguest guest display key*:: +*snpguest display key*:: usage: snpguest display key $KEY_PATH - Prints the derived key contents in hex format into terminal. + When used for displaying the fetched derived key's contents, it prints the derived key in hex format into the terminal. The user has to provide the path of a stored derived key to display. + argument: + $KEY_PATH Specify the path of the stored derived key to display. + options: - -h, --help show a help message + -h, --help show a help message *