Skip to main content

Crate sev_snp

Crate sev_snp 

Source
Expand description

Safe Rust bindings for the Linux AMD SEV-SNP guest API.

Inside an SEV-SNP virtual machine, the AMD secure processor will sign statements about the VM and derive keys that never leave the chip. This crate exposes everything the Linux guest interface offers, over both kernel transports, with no unsafe required of the caller.

§Getting started

use sev_snp::Firmware;

let fw = Firmware::open()?;
let report = fw.report(&[0u8; 64])?;

println!("measurement: {:x?}", report.measurement());
println!("running on {}", report.product().unwrap());

§What the guest can ask for

§Portability across Zen 3, Zen 4 and Zen 5

The guest request protocol is identical on every SEV-SNP part, so the calls in this crate need no per-generation branching. Two things do vary, and both are handled without asking the caller which machine they are on:

  • Report version. Reports are always AttestationReport::SIZE bytes; newer revisions only claim space older ones reserved. Fields introduced later — cpuid_fms in version 3, launch_mit_vector in version 5 — return Option. Report version tracks firmware level, not silicon, so a Zen 3 machine on current firmware emits version 5 reports.
  • TCB version layout. TcbVersion means different things on different processors: Zen 5 inserts an FMC security version number that Zen 3 and Zen 4 do not have. The raw value is always preserved, and TcbVersion::decode splits it correctly for a given Product — which reports from version 3 onwards carry themselves.

Bitfields such as GuestPolicy and PlatformInfo name the bits this crate knows and expose the rest through unknown_bits, so a report from firmware newer than this crate parses rather than fails.

§Transports and features

Linux exposes guest requests through both /dev/sev-guest (5.19 and later) and configfs-TSM (6.7 and later). Firmware::open uses whichever are present, preferring configfs for reports because it can detect a concurrent writer, and requiring /dev/sev-guest for key derivation because configfs does not implement it. See the backend module for the full comparison.

Each transport is a cargo feature, both on by default. Turning one off compiles it out entirely, along with anything only it needed:

  • configfs — the configfs-TSM transport. Reports only.
  • sev-guest — the /dev/sev-guest transport. Adds key derivation and firmware status codes, and pulls in libc.

Selecting neither is a compile error. Selecting only configfs leaves a crate with no dependencies at all, compiled under forbid(unsafe_code) — useful for a verifier or a report-only agent that wants no unsafe anywhere in what it builds.

Anything a build cannot do is absent rather than failing at run time: without sev-guest there is no Firmware::derive_key, no key module and no Transport::Ioctl, so code that needs them fails to compile instead of reaching production and returning an error. Write against both feature sets the way examples/attest.rs does, with a #[cfg] around the parts that need a particular transport.

§Trust boundary

A report is only evidence once its signature has been checked against AMD’s certificate chain, and the freshness of report_data confirmed. This crate obtains and parses reports; it deliberately performs no cryptographic verification and fetches nothing from the network, so that the verifying party can be a different machine running code of its own choosing. Treat everything a report says as unverified until you have done that.

What this crate does check, because a guest can do it without any cryptography and a caller who skips it has no way to notice:

  • The response answers this request. REPORT_DATA and the privilege level are echoed by the firmware, so both are compared against what was asked for and a mismatch is Error::Mismatch, never a returned report.
  • The interface is really SEV-SNP. configfs-TSM is shared with TDX and others, so the provider name is checked once at open; anything else is Error::WrongProvider rather than a foreign quote parsed as a report.
  • The response is shaped like a report. The version is bounded above as well as below, and a host-supplied certificate blob is bounded in size and entry count before any of it is decoded.

Modules§

backend
The two kernel interfaces to the SEV-SNP guest firmware.
certs
The certificate table returned alongside an extended attestation report.
detect
Detecting SEV, SEV-ES and SEV-SNP support from inside the guest.
error
Errors returned by this crate.
keysev-guest
Hardware-bound key derivation.
policy
Bitfields carried inside an attestation report.
report
The SEV-SNP attestation report.
tcb
Processor identification and TCB version decoding.

Structs§

AttestationReport
A parsed SEV-SNP attestation report.
CertTable
The endorsement chain accompanying an extended report.
Certificate
One entry from the certificate table.
DerivedKeysev-guest
A 32-byte key derived by the secure processor.
EcdsaP384Signature
An ECDSA P-384 signature in AMD’s wire format.
ExtendedReport
An attestation report together with the endorsement chain that verifies it.
Firmware
A handle to the SEV-SNP guest firmware.
FirmwareVersion
A major.minor.build firmware version.
Fms
A processor family/model/stepping triple as reported by CPUID(1).EAX.
GuestPolicy
The launch policy the guest owner pinned at VM start.
KeyFieldssev-guest
The facts mixed into a derived key.
KeyRequestsev-guest
A request for a hardware-derived key.
PlatformInfo
Host platform configuration at the time the report was signed.
ReportRequest
A request for an attestation report.
SignerInfo
How the report was signed and what the host chose to reveal.
TcbParts
The named security version numbers inside a TCB_VERSION.
TcbVersion
A raw 64-bit TCB_VERSION.

Enums§

CertKind
Which certificate in the endorsement chain an entry holds.
Error
Anything that can go wrong talking to the SEV-SNP firmware.
FirmwareError
Status codes returned by the AMD secure processor.
ParseError
A response did not match the layout this crate expects.
Product
An AMD EPYC generation, as far as the SEV-SNP ABI cares about it.
RootKeysev-guest
Which chip-held secret to derive from.
SignatureAlgo
The algorithm used to sign the report.
SigningKey
Which key signed the attestation report.
TcbLayout
Which byte order a TCB_VERSION uses.
Transport
Which kernel interface a backend speaks.
VmmError
Errors raised by the hypervisor rather than the firmware.

Traits§

GuestBackend
A kernel interface capable of issuing SEV-SNP guest requests.

Type Aliases§

Result
Result alias used throughout the crate.