Update guest-attestation-confidential-virtual-machines-design.md

[hyperfinitism]

Correct the formatting of the Attestation Report (stored in NV index 0x01400001) and the Runtime Data.

[prmerger-automator]

@hyperfinitism : Thanks for your contribution! The author(s) and reviewer(s) have been notified to review your proposed change. @Mishih

[learn-build-service-prod]

Learn Build status updates of commit 0c63041:

✅ Validation status: passed

File	Status	Preview URL	Details
articles/confidential-computing/guest-attestation-confidential-virtual-machines-design.md	✅Succeeded

For more details, please refer to the build report.

[v-regandowner]

@mingweishih - Can you review the proposed changes?

IMPORTANT: When the changes are ready for publication, adding a #sign-off comment is the best way to signal that the PR is ready for the review team to merge.

#label:"aq-pr-triaged"
@MicrosoftDocs/public-repo-pr-review-team

[hyperfinitism]

Test

Within Azure CVM (SEV-SNP), the following commands were run to extract and dump the start of the report binary:

sudo tpm2_nvread -C o 0x01400001 > ./report.bin
xxd -g1 -l 32 -s 1216 report.bin

Results

 000004c0: 6a 04 00 00 01 00 00 00 02 00 00 00 01 00 00 00  j...............
 000004d0: 56 04 00 00 7b 22 6b 65 79 73 22 3a 5b 7b 22 6b  V...{"keys":[{"k

Offset (bytes)	Hex (Little Endian)	Decimal	Description
1216	6a 04 00 00	1130	Size of Runtime Data
1220	01 00 00 00	1	Format Version
1224	02 00 00 00	2	Report Type: SEV-SNP
1228	01 00 00 00	1	Hash Algorithm: SHA-256
1232	56 04 00 00	1110	Size of Runtime Claims

Correct Report Format

Name	Offset (bytes)	Size (bytes)	Description
Data Size	1216	4	Runtime Data Size
Version	1220	4	Format Version
Report Type	1224	4	Hardware Report Type
Hash Type	1228	4	Hash Algorithm
Claims Size	1232	4	Runtime Claims Size
Runtime Claims	1236	variable length	Runtime Claims

[mingweishih]

The proposed changes is actually the same as the original format. Not clear on why we need this .

[hyperfinitism]

@mingweishih

Thanks for the quick review!

Differences

1. The current doc describes the Data Size field as the size of Runtime Claims.

   • In reality, this field represents the size of Runtime Data (offset 1216–1219), not the size of Runtime Claims.

2. The current doc omits the Claims Size field at offset 1232–1235.

3. The current doc states that the Runtime Claims JSON begins at byte 1232.

   • However, it actually starts at byte 1236, after the Claims Size field.

Report format in the current document

Name	Offset (bytes)	Size (bytes)	Description
Header	0	32	Report Header
Report Payload	32	1184	Hardware Report
Data Size	1216	4	Runtime Claims Size.
Version	1220	4	Format Version
Report Type	1224	4	Hardware Report Type
Hash Type	1228	4	Hash Algorithm
Runtime Claims	1232	variable length	Runtime Claims

Correct report format

Name	Offset (bytes)	Size (bytes)	Description	Difference
Header	0	32	Report Header
Report Payload	32	1184	Hardware Report
Data Size	1216	4	Runtime Data Size	Description differs (Data vs Claims)
Version	1220	4	Format Version
Report Type	1224	4	Hardware Report Type
Hash Type	1228	4	Hash Algorithm
Claims Size	1232	4	Runtime Claims Size	Was omitted
Runtime Claims	1236	variable length	Runtime Claims	Offset differs (1236 vs 1232)

[mingweishih]

@mingweishih

Thanks for the quick review!

Differences

1. The current doc describes the Data Size field as the size of Runtime Claims.

   • In reality, this field represents the size of Runtime Data (offset 1216–1219), not the size of Runtime Claims.

2. The current doc omits the Claims Size field at offset 1232–1235.

3. The current doc states that the Runtime Claims JSON begins at byte 1232.

   • However, it actually starts at byte 1236, after the Claims Size field.

Report format in the current document

Name Offset (bytes) Size (bytes) Description
Header 0 32 Report Header
Report Payload 32 1184 Hardware Report
Data Size 1216 4 Runtime Claims Size.
Version 1220 4 Format Version
Report Type 1224 4 Hardware Report Type
Hash Type 1228 4 Hash Algorithm
Runtime Claims 1232 variable length Runtime Claims

Correct report format

Name Offset (bytes) Size (bytes) Description Difference
Header 0 32 Report Header
Report Payload 32 1184 Hardware Report
Data Size 1216 4 Runtime Data Size Description differs (Data vs Claims)
Version 1220 4 Format Version
Report Type 1224 4 Hardware Report Type
Hash Type 1228 4 Hash Algorithm
Claims Size 1232 4 Runtime Claims Size Was omitted
Runtime Claims 1236 variable length Runtime Claims Offset differs (1236 vs 1232)

Runtime Claims’s offset is 1232, which is correct. The confusion here is that the size of the claims is in the first 4 bytes of the claim structure (which is the same as your change from the overall layout).

[hyperfinitism]

Problem

The Attestation Report table currently mis‐labels one field and omits another, so three different byte counts are conflated.
The current doc conflates three different lengths.

Field	Actual meaning & sample value	What the doc says	Consequence
Data Size @ 0x4C0 (1216)	Length of all Runtime Data (1130 B)	“Size of Runtime Claims”	JSON parser consumes 20 B beyond payload → hash mismatch; attestation fails
Claims Size @ 0x4D0 (1232)	Length of Runtime Claims payload (1110 B)	Not documented	–
Runtime Claims @ 0x4D4 (1236)	{"keys": … } (JSON)	Shown as starting at 1232	Parser sees 4-byte binary length then { → garbage prefix V...{ → hash mismatch; attestation fails

Note that in the current documentation, the Runtime Claims field starts at byte 1232 and represents Runtime Claims in JSON Format. There is no mention of the first 4 bytes of this field representing the size of Runtime Claims.

Moreover, the current documentation describes the Data Size field as the size of Runtime Claims; this field actually represents the size of Runtime Data (minus Data Size field).

Why it matters

• Anyone who follows the table literally (in the current doc) will seek to 1232 and treat the length integer (56 04 00 00 in Hex) as the first four characters of JSON.
• Their runtime claims hash therefore covers the wrong region (ill-formed JSON) and SEV-SNP report verifier will reject the report.

Fix (this PR)

1. Correct the description of Data Size field from the size of Runtime Claims to the size of Runtime Data.
2. Insert missing Claims Size field at 1232 (4 B)
3. Shift Runtime Claims field from 1232 → 1236.

[mingweishih]

Thanks for the clarification. In this case can you just update the Runtime Data table? That is, retain the 0 - 4 as data size, and add the claim size field after hash type.

[hyperfinitism]

I have addressed your suggestion. I've reverted the changes to the Attestation Report Format table and restored it to its original form. All edits now only apply to the Runtime Data Format table, per your request. Please let me know if there’s anything else you’d like adjusted!

[learn-build-service-prod]

Learn Build status updates of commit 0753a16:

✅ Validation status: passed

File	Status	Preview URL	Details
articles/confidential-computing/guest-attestation-confidential-virtual-machines-design.md	✅Succeeded

For more details, please refer to the build report.

[v-dirichards]

@mingweishih Could you review this proposed update to your article and enter #sign-off in a comment if it's ready to merge?

Thanks!

[mingweishih]

#sign-off

[prmerger-automator]

Invalid command: '#sign-off'. Only the assigned author of one or more file in this PR can sign off. @Mishih