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
- Attestation reports — a signed statement covering
the launch measurement, the guest policy, the platform’s firmware versions
and 64 bytes of caller-supplied data. Fetch one with
Firmware::report. - Endorsement certificates — the chain that verifies the
report’s signature, when the host provisioned one. See
Firmware::extended_report. - Derived keys — reproducible key material bound to any
combination of the chip, the firmware version, and the guest image. See
Firmware::derive_keyand thekeymodule. - Capability detection — what the processor supports, and whether this process is in fact running inside an SNP guest.
§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::SIZEbytes; newer revisions only claim space older ones reserved. Fields introduced later —cpuid_fmsin version 3,launch_mit_vectorin version 5 — returnOption. Report version tracks firmware level, not silicon, so a Zen 3 machine on current firmware emits version 5 reports. - TCB version layout.
TcbVersionmeans 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, andTcbVersion::decodesplits it correctly for a givenProduct— 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-guesttransport. Adds key derivation and firmware status codes, and pulls inlibc.
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_DATAand the privilege level are echoed by the firmware, so both are compared against what was asked for and a mismatch isError::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::WrongProviderrather 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.
- key
sev-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§
- Attestation
Report - A parsed SEV-SNP attestation report.
- Cert
Table - The endorsement chain accompanying an extended report.
- Certificate
- One entry from the certificate table.
- Derived
Key sev-guest - A 32-byte key derived by the secure processor.
- Ecdsa
P384 Signature - An ECDSA P-384 signature in AMD’s wire format.
- Extended
Report - An attestation report together with the endorsement chain that verifies it.
- Firmware
- A handle to the SEV-SNP guest firmware.
- Firmware
Version - A
major.minor.buildfirmware version. - Fms
- A processor family/model/stepping triple as reported by
CPUID(1).EAX. - Guest
Policy - The launch policy the guest owner pinned at VM start.
- KeyFields
sev-guest - The facts mixed into a derived key.
- KeyRequest
sev-guest - A request for a hardware-derived key.
- Platform
Info - Host platform configuration at the time the report was signed.
- Report
Request - A request for an attestation report.
- Signer
Info - 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§
- Cert
Kind - Which certificate in the endorsement chain an entry holds.
- Error
- Anything that can go wrong talking to the SEV-SNP firmware.
- Firmware
Error - Status codes returned by the AMD secure processor.
- Parse
Error - 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.
- RootKey
sev-guest - Which chip-held secret to derive from.
- Signature
Algo - The algorithm used to sign the report.
- Signing
Key - Which key signed the attestation report.
- TcbLayout
- Which byte order a
TCB_VERSIONuses. - Transport
- Which kernel interface a backend speaks.
- VmmError
- Errors raised by the hypervisor rather than the firmware.
Traits§
- Guest
Backend - A kernel interface capable of issuing SEV-SNP guest requests.
Type Aliases§
- Result
- Result alias used throughout the crate.