Attestation Report Parsing

[DGonzalezVillal]

Hello everyone,

I wanted to open this discussion around how we might revamp the way the Attestation Report and related structs are currently parsed, with the goal of improving forward compatibility while preserving type safety:

Current Attestation Report Parsing: Design and Limitations

This issue documents how the attestation report is parsed today, why it works the way it does, and what limitations arise from that design—particularly around forward compatibility and reserved fields.

---

Overview

The current attestation report implementation uses strict, fully typed parsing. Each field defined in the SNP specification is decoded into a corresponding Rust type, producing a strongly typed AttestationReport structure.

This design prioritizes:

• Type safety
• Clear and discoverable APIs
• Early detection of malformed or unexpected input

---

How Parsing Works Today

• The full report buffer is read.
• Known fields are decoded into typed structures.
• Reserved fields are skipped, with validation that they contain zeroes.
• If a reserved field contains non-zero data, parsing fails by default.

Reserved fields are not stored in the AttestationReport struct and are not preserved after parsing.

---

Encoding and Round-Tripping

When encoding an AttestationReport:

• Known fields are serialized from their typed representation.
• Reserved fields are written as zeroes (or skipped).

Because reserved data is discarded during parsing, encoding the report does not guarantee byte-for-byte round-tripping, even if decoding succeeded.

---

Strengths of the Current Design

• Strong type safety
• Simple and ergonomic API for consumers
• Fail-fast behavior on malformed input
• Well suited for security-sensitive use cases that rely on strict validation

---

Limitations

1. Reserved Field Data Is Lost

If firmware repurposes reserved fields:

• The data is validated (or rejected) but not retained
• Once parsed, those bytes are no longer accessible through the typed API

Even in relaxed parsing modes, the data is still discarded.

---

2. Forward Compatibility Is Limited

New report versions may introduce:

• New semantics in reserved fields
• Fields not yet reflected in the spec or library

Under the current model:

• Strict parsing fails
• Relaxed parsing may succeed, but new data is silently dropped

---

3. Single Parsing Mode per Dependency Tree

Feature-based approaches (e.g. strict vs lax parsing):

• Apply globally across the dependency tree
• Prevent strict and relaxed consumers from coexisting in the same binary
• Can cause compatibility issues between dependent crates

---

4. Raw Data Is Outside the Typed Model

While raw report bytes may be available separately:

• The typed AttestationReport does not retain unknown or reserved data
• Consumers must manually correlate raw bytes with parsed fields

---

Summary

The current parsing model:

• Is intentionally strict and type-safe
• Discards reserved field data during parsing
• Does not support lossless forward compatibility by design

This approach works well for known report versions and strict validation use cases, but it limits:

• Forward compatibility
• Byte-exact round-tripping
• Incremental support for new firmware behavior

Addressing these concerns likely requires a more fundamental redesign (e.g. raw-backed or hybrid models), which may involve API-breaking changes and warrants a broader design discussion.

We’ve already touched on aspects of this problem in:

#370

#366

#363

[DGonzalezVillal]

@fitzthum @hyperfinitism @cschramm @tylerfanelli

I know you guys are active users of the library so getting your thoughts on this would be appreciated.

[cschramm]

#370 (comment) has good directions on a raw blob mode. I think the getter approach would be something like a struct that holds the blob and exposes fallible methods like committed_tcb that parse on demand. Zero checks for reserved areas could be another method, but not sure who'd call it and when.

#370 (comment) is a similar approach where parsing is not done on demand in getters, but the RawEntry type is basically their pre-rendered result. An obvious solution without a feature flag that breaks the crate's API would be to always use the RawEntry type. To make that more accessible for consumers not interested in the fallback, RawEntry<T> could have ways to convert to Result<T> and/or unwrap T with panics if parsing failed.

[hyperfinitism]

Below is a summary of several possible design directions, including the current approach and alternatives, with their trade-offs.

1. Keep the current approach (strict parsing + zero checks)

Current behavior:

• Determine the Attestation Report variant based on the Attestation Report version
• Determine the TCB Version variant based on CPUID / CPU_FAM_ID / CPU_MOD_ID
• Parse the binary blob into the AttestationReport structure (differences among report variants are handled per field using the Option type)
• Perform zero-checks on reserved fields and return an error if any non-zero value is found

However, from reading the code, zero-checks are currently not consistently applied to sub-structures such as TcbVersion and PlatformInfo.

If this approach is kept, then:

• Sub-structures such as TcbVersion, PlatformInfo, etc. should also perform reserved-field zero checks

A concrete example of why this matters:

• There was a past bug where a V4 report on pre-Turin CPUs incorrectly fell back to V3Turin
  • Fixing writing TCB bug and bumping to 6.2.1 #311
• However, parsing of TcbVersion did not fail because zero-check for reserved fields in TcbVersion was missing
• As a result, even though no parsing error occurred, the TCB Version field was incorrectly parsed, causing a bug that corrupted the report data
  • Bump VirTEE/sev from 6.1.0 to 6.2.1 (fixes TCB serialization bug) snpguest#98

So if we keep the current design, consistency demands that all sub-structures must apply the same strict validation rules, otherwise variant detection becomes unreliable.

2. Preserve reserved fields in the parsed structures (configurable zero check)

Another approach is to explicitly preserve reserved fields:

• Add fields to store reserved bytes in:
  • AttestationReport
  • sub-structures such as TcbVersion, GuestPolicy, PlatformInfo, Signature etc.
• Parse the binary blob including reserved fields
• Use a feature flag (e.g. unsafe_parser or lax_parser) to control whether zero checks are enforced

An intermediate option is also possible:

• Always perform zero checks
• Switch between error vs warning via a feature flag

On TCB Version

The raw TcbVersion format differs significantly between pre-Turin and post-Turin CPUs. This may make reserved-field handling somewhat complex.

One possible mitigation:

• Model TcbVersion as an enum, e.g.
  • TcbVersionV1 (pre-Turin)
  • TcbVersionV2 (post-Turin)
• Each variant explicitly contains its own reserved-field storage

Trade-offs

• Type safety is preserved
• The public API changes minimally (or not at all)
• Forward compatibility is improved
• Implementation complexity increases, but the design remains explicit and principled

Overall, this feels like a reasonable balance between strict validation, forward compatibility, and API stability.

3. Treat the report as an opaque binary blob and parse on demand

In this approach:

• The attestation report is stored primarily as a raw binary blob
• Parsing into typed structures happens only when explicitly requested

Pros

• Maximum forward compatibility
• Future extensions do not break parsing

Cons

• Significant loss of type safety
• Substantial API changes
• Users must verify the integrity of reports at their own risk

As already mentioned in the discussion, this is the most flexible option, but also the most disruptive.

Summary

• Option 1 is viable only if strict validation is applied consistently, including all sub-structures
• Option 2 offers a good compromise: strong typing, configurable strictness, and better forward compatibility
• Option 3 maximizes future-proofing but sacrifices type safety and API stability

Personally, I think Option 2 strikes the best balance for the current sev crate, but all three are defensible depending on the project's priorities.

[npmccallum]

This analysis focuses on process and not on actors and is therefore incomplete. The question is not "How do we parse this?" but "WHO needs to parse it and WHY?"

I suspect this will reveal the following...

Actors

1. The verifier parses it to do verification. This verification parsing is two-phase:

A. Minimal parsing is performed just to determine the metadata related to the signing process. Then the signature is verified using this metadata. There's an important rule here: signing must be validated before parsing untrusted data.

B. Once the remaining data is signed, the verifier will extract the known fields from the version and perform semantic validation.

2. Most intermediaries will NOT parse the attestation report, and will pass it on as an opaque blob within another structure.

3. Debugging tools may parse the attestation report on host to extract information. This is often helpful in conformance testing and setup validation. Therefore, there is no need to validate the whole attestation report with the careful two-stage process required by the verifier. Nevertheless, the verifier's two stage validation will also work for this purpose.

Proposal

1. A parsing API should be separate API from the fetching API. The parsing API should implement the verifier's two-stage parsing: (a) extract signing metadata and validate signature (b) parse remaining values.

2. A guest attestation report fetching API, if provided, should deal only in binary blobs. This way intermediaries don't need to parse in order to get the attestation report. However, I also suspect that with the new sysfs interface for attestation fetching, no API is needed. Programmers can use the existing file IO APIs to acquire an attestation report.

Putting this altogether, this is basically a more well-defined version of Option 3 from @hyperfinitism.

Objections

1. Doesn't this lose type safety? - No. The users who access the data fields get type safety through the parsing API. Intermediaries who treat it like a blob have no need for field-level type safety.

2. Substantial API changes - Yes, this is a problem. However, you have versioning to help you. Users who are willing to modify for the new API can upgrade. We can maintain both in parallel for a while.

3. What about reserved field? - This proposal simplifies the API significantly because there is no serialization at all. Parsing is delayed until time of use. Reserved fields can be ignored or validated as zero (my preference).

4. What about new fields? Forwards compatibility requires parser changes! - Yes. That sucks. It is also unsolvable without self-describing formats. We should do that in the future. But we don't have that today.

5. What about TcbVersion? Parsing this sucks. - Yes, it does. It is a historical mistake that cannot be fixed without self-describing formats.

6. Doesn't this force debug/test code to do the double-parsing strategy? - No. You can have two related APIs. One API handles only the inner parsing. One API handles only the outer parsing. Two stage verification uses the second one and then the first one. Intermediaries can just extract the inner bytes without validating the signature and pass them directly to the first API.

[DGonzalezVillal]

Thank you for the complete response @npmccallum

As additional context, the request/fetch API already returns the attestation report as raw bytes (currently as a Vec). This was originally done to avoid coupling callers to a fixed report size, since at the time we weren’t certain whether future report versions might grow.

For example:

  /// Requests an attestation report from the AMD Secure Processor. The `message_version`
/// will default to `1` if `None` is specified.
pub fn get_report(
    &mut self,
    message_version: Option<u32>,
    data: Option<[u8; 64]>,
    vmpl: Option<u32>,
) -> Result<Vec<u8>, UserApiError> {
    ...
   // response is the response struct and report is already in bytes
    Ok(response.report.to_vec())
}

Similarly, get_ext_report() returns the report bytes plus optional certificate data.

Given that fetching already yields an opaque blob, the main question seems to be how we model and expose parsing on top of that.

One possible direction would be to introduce a RawReport (or RawAttestationReport) type that explicitly represents an unparsed report. Intermediaries could pass this around without interpretation, while verifiers and tools could opt into parsing.

From there:

• A conversion (e.g. TryFrom) could perform signature verification and populate a typed representation

• Parsing and validation APIs could be layered on top of the raw form

• Field access would remain gated on library support for that report version, preserving type safety

• Forward compatibility improves by delaying parsing until the point of use

In that model, the fetch API could either:

• continue returning Vec, or

• return a RawAttestationReport wrapper to make the “opaque blob” semantics explicit

Do you think there’s value in introducing a RawAttestationReport type at the API boundary, or is returning a Vec sufficient as long as parsing is clearly separated?