snphost

snphost is a Command Line Interface (CLI) utility designed for administrators managing AMD SEV-SNP enabled host systems. This tool facilitates interaction with the AMD SEV-SNP firmware device, enabling various operations such as certificate management and attestation processes.

• Usage
  • 1. help
  • 2. export
  • 3. import
  • 4. ok
  • 5. fetch
  • 6. show
  • 7. commit
  • 8. config
  • 9. verify
• Building
  • Ubuntu Dependencies
  • RHEL and Compatible Distributions Dependencies
  • openSUSE and Compatible Distributions Dependencies
• Common Workflows
• Reporting Bugs

Usage

1. help

Every snphost command and subcommand comes with a --help option that provides a description of its usage.

Usage:

snphost --help

or for a specific subcommand:

snphost <subcommand> --help

2. export

Deserializes a GHCB formatted cert chain file into individual certificates. The user must specify the desired encoding format (der or pem) for the certificates, the file where the GHCB cert chain is stored in, and the target directory path where to store the deserialized certs. This command is useful for looking at the individual certs that will be used for an extended attestation.

Usage:

snphost export [der|pem] CERT-FILE DIR-PATH

Example:

snphost export pem ghcb-certs.bin ./certs

3. import

Converts a certificate chain into a GHCB formatted file for extended attestation. This formatted file can then be provided to QEMU to perform extended attestation on guests. Currently, only the ASK, ASVK, ARK, VCEK, and VLEK certificates are supported for serialization.

Usage:

snphost import DIR-PATH CERT-FILE

Example:

snphost import ./certs ghcb-certs.bin

4. ok

Probes host system to confirm SEV-SNP support.

Usage:

snphost ok

5. fetch

Command to request certificates from the KDS.

Usage:

snphost fetch <subcommand>

Subcommands:

1. ca

Fetches the Certificate Authority (CA) chain corresponding to the host CPU generation and writes the encoded certificates to the specified directory. Users must specify the desired encoding format (der or pem).

Usage:

snphost fetch ca [der|pem] DIR-PATH

Example:

snphost fetch ca pem ./certs

2. vcek

Fetches the Versioned Chip Endorsement Key (VCEK) corresponding to the host CPU generation and writes the encoded certificate to the specified directory. Users must specify the desired encoding format (der or pem). The URL of the VCEK can be explicitly set. If not explicitly set, the URL will be generated based on firmware data.

Usage:

snphost fetch vcek [der|pem] DIR-PATH [url]

Example:

snphost fetch vcek pem ./certs

3. crl

Fetches the latest Certificate Revocation List (CRL) for the host CPU generation.

snphost fetch crl DIR-PATH

Example:

snphost fetch crl ./crl-dir

6. show

Display information about the SEV-SNP platform.

Usage:

snphost show <subcommands>

Subcommands:

1. guests

Lists all active guests.

Usage:

snphost show guests

2. identifier

Displays the unique CPU identifier.

Usage:

snphost show identifier

3. tcb

Shows the current platform and reported Trusted Computing Base (TCB) version.

Usage:

snphost show tcb

4. vcek-url

Displays the URL for fetching VCEK.

Usage:

snphost show vcek-url

5. version

Prints the platform's SEV-SNP firmware version`.

Usage:

snphost show version

7. commit

This command commits the current firmware and SNP platform config versions to the PSP.

Note: This can't be undone and will not allow rollbacks to older versions.

Usage:

snphost commit

8. config

Subcommands to manage the host machine's configuration.

Usage:

snphost config <subcommand>

Subcommands

1. set

This command allows the user to change the config of the SNP platform. The user can provide the desired versions of the different TCB paramerters they would like to modify. The command will change the reported values by the PSP. In order to have this changes commited, the user would have to use snphost commit. The user can also provide a new mask-chip value that will change the mask chip bit field values in the config.

Usage:

snphost config set BOOTLOADER TEE SNP-FW MICROCODE MASK-CHIP [FMC]

Example:

snphost config set 10 0 23 25 0

2.reset

This command resets the SEV-SNP platform. This will clear all persistent data managed by the platform and reset the platform configuration to its last committed version.

Usage:

snphost config reset 

Example:

snphost config reset

9. verify

Reads the certificates in a directory and verifies the certificate chain, ensuring its integrity and authenticity. This command is essential for validating the trustworthiness of the certificates that can be then passed to complete attestation.

Usage:

snphost verify DIR-PATH

Example:

snphost verify ./certs

Building

Some packages may need to be installed on the host system in order to build snphost.

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

Ubuntu Dependencies

sudo apt install build-essential

RHEL and its compatible distributions Dependencies

sudo dnf groupinstall "Development Tools" "Development Libraries"

openSUSE and its compatible distributions Dependencies

sudo zypper in -t pattern "devel_basis"

After installing the necessary dependencies, clone the snphost repository and build the project:

git clone https://github.com/virtee/snphost.git
cargo build --release
cd snphost/target/release

The compiled binary will be located in the target/release directory.

Common Workflows

This section outlines common workflows for configuring and using snphost effectively on a host system with AMD SEV-SNP enabled.

1. Changing the SNP Configuration

To change the configuration of the SNP firmware, use the config set command followed by commit.

Usage:

snphost config set BOOTLOADER TEE SNP-FW MICROCODE MASK-CHIP

In Turin and higher generations use,

snphost config set BOOTLOADER TEE SNP-FW MICROCODE MASK-CHIP FMC

This command is used to configure the TCB parameters and the Mask Chip value for the AMD SEV-SNP platform. The configuration consists of two main parts: setting the TCB values and setting the Mask Chip value.

Part 1. TCB Parameters

BOOTLOADER, TEE, SNP-FW, MICROCODE, FMC (Optional and applicable only to Turin and newer chips.) To view the current values of these fields, you can run:

snphost show tcb

Example Output:

Reported TCB: TCB Version:
  Microcode:   25
  SNP:         23
  TEE:         0
  Boot Loader: 10
  FMC:         None

Platform TCB: TCB Version:
  Microcode:   25
  SNP:         23
  TEE:         0
  Boot Loader: 10
  FMC:         None

With the config set command, you can change these values to an older version, but not to a newer version. Attempting to set a newer version will result in a failure. Further, the config set command will change the Reported TCB. The Platform TCB will change only when you commit your changes.

Part 2. Mask Chip ID

The Mask Chip can be set to a value between 0 and 3, corresponding to its binary counterpart:

0 - 00
1 - 01
2 - 10
3 - 11

These values toggle the MASK-CHIP-KEY and MASK-CHIP-ID settings:

Bit 0: MASK-CHIP-ID
Bit 1: MASK-CHIP-KEY

For example, if you pass 2:

Bit 0 is 0, meaning MASK-CHIP-ID is disabled.
Bit 1 is 1, meaning MASK-CHIP-KEY is enabled.

To set the TCB parameters and Mask Chip, you can use the following command:

Example:

snphost config set 10 0 23 25 0

In this example,

10 is the Bootloader version.
0 is the TEE version.
23 is the SNP Firmware level.
25 is the Microcode level.
0 is the Mask Chip value which disables both mask chip id and mask chip key.

This command will update the values.

To commit these changes to firmware, you must use the snphost commit command by running:

snphost commit

Note: Commit changes config permanently. You can't roll back to your previous version. Do Not commit values unless you are absolutely sure.

---

2. Resetting Config Changes

To discard uncommitted configuration changes and revert to the last committed state:

snphost config reset

Workflow:

snphost config set 10 0 23 25 0
# decide to discard changes
snphost config reset

This is useful for reverting accidental or experimental changes before they are made permanent.

---

3. Extended Attestation Flow

Note: This was the workflow used to set-up the host for extended attestation, this functionality is currently unavailable in upstream kernel, and it's subject to change

This flow demonstrates fetching host certificates, verifying the certs, importing them into the correct gchb format, and passing them to QEMU for extended guest attestation.

# Fetch certificates from KDS
snphost fetch ca pem ./certs
snphost fetch vcek pem ./certs

# Verify the certificate chain (optional but recommended)
snphost verify ./certs

# Serialize to GHCB format for QEMU
snphost import ./certs ghcb-certs.bin

# (Optional) To inspect GHCB-formatted file contents:
snphost export pem ghcb-certs.bin ./decoded-certs

Use with QEMU:

You can now pass ghcb-certs.bin to QEMU via the sev-snp-certs option:

qemu-system-x86_64 \
  ... \
  -object sev-snp-guest,id=sev0,sev-snp-certs=ghcb-certs.bin \
  ...

The certificates can now be retrieved in the guest using extended attestation.

Reporting Bugs

If you encounter any issues or bugs while using snphost, please report them by opening an issue by clicking here. Provide a detailed description of the problem, including steps to reproduce the issue and any relevant system information. This will help the maintainers address the problem more effectively.

---

Note: This README is structured similarly to the snpguest README to maintain consistency across related projects.