Skip to contentSkip to conversation

docs/interop: Extend firmware schema for SVSM

PATCH In review Oliver Steffen 2 participants 7 messages Jan 23

lore
Share & tools
lore
#0 lore raw

cover docs/interop: Extend firmware schema for SVSM

Extend the firmware metadata JSON schema to support Secure VM Service Module (SVSM) firmware images. Parts of these changes can be useful for describing other (confidential) firmware types as well.

This series adds:
- An entry in the FirmwareFeature enum indicating a virtual (emulated) TPM devices offered by the firmware (Coconut SVSM provides one)
- An entry in the FirmwareOSInterface enum indicating support of the SVSM guest interface
- A new top-level array to store associated digest values
- Add structures to describe AMD SEV-SNP launch digests.

For attesting a confidential virtual machine, the verifier needs to know the expected launch digest. This new format allows us to add this information to a metadata file and include it in distribution packages of confidential firmware images.

Oliver Steffen (3):
docs/interop: Add vtpm feature firmware.json docs/interop: Add AMD SEV-SNP SVSM interface to firmware.json docs/interop: Add firmware digests to schema

 docs/interop/firmware.json | 94 ++++++++++++++++++++++++++++++++++++--
 1 file changed, 91 insertions(+), 3 deletions(-)
Signature · 1 line
2.52.0
#1 lore raw

PATCH 1/3 docs/interop: Add vtpm feature firmware.json

Some firmwares provide a virtual (emulated) TPM device to the guest. Add a corresponding "vtpm" item to the FirmwareFeature enum to reflect that.

---
 docs/interop/firmware.json | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)
docs/interop/firmware.json +3 -1
index da0362a2c0..12eb1fd79c 100644
@@ -222,6 +222,8 @@
 #     loading the firmware into flash the 'stateless' setup should be
 #     used.  It is recommened to load the firmware into memory though.
 #
+# @vtpm: The firmware provides a virtual TPM device.
+#
 # Since: 3.0
 ##
 { 'enum' : 'FirmwareFeature',
@@ -230,7 +232,7 @@
              'intel-tdx',
              'enrolled-keys', 'requires-smm',
              'secure-boot', 'host-uefi-vars',
-             'verbose-dynamic', 'verbose-static' ] }
+             'verbose-dynamic', 'verbose-static', 'vtpm' ] }
 
 ##
 # @FirmwareFormat:
Signature · 1 line
2.52.0
#2 lore raw

Re: [PATCH 1/3] docs/interop: Add vtpm feature firmware.json

Quoted 3 lines · Oliver Steffen

Some firmwares provide a virtual (emulated) TPM device to the guest. Add a corresponding "vtpm" item to the FirmwareFeature enum to reflect that.

I'm wondering whenever it makes sense to be more specific here, i.e. pick 'svsm-vtpm' as name, or even 'svsm-vtpm-ephemeral'. Specifically because a (future) vtpm with persistence has some additional requirements such as some storage device for svsm, so libvirt needs to know those details ...

take care,
Gerd

#3 lore raw

PATCH 2/3 docs/interop: Add AMD SEV-SNP SVSM interface to firmware.json

In reply to Oliver Steffen

AMD SEV-SNP defines a guest to Secure VM Service Module (SVSM) firmware
[1] interface. Add a corresponding item to the FirmwareOSInterface enum.

[1]
https://docs.amd.com/api/khub/documents/Al5Q~fSl~kWKkJ3zC0vk_g/content

---
 docs/interop/firmware.json | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)
docs/interop/firmware.json +3 -1
index 12eb1fd79c..dabfa692fd 100644
@@ -40,10 +40,12 @@
 #     example, firmware built from the edk2 (EFI Development Kit II)
 #     project usually provides this interface.
 #
+# @svsm: AMD SEV-SNP Secure VM Service Module (SVSM) guest protocol.
+#
 # Since: 3.0
 ##
 { 'enum' : 'FirmwareOSInterface',
-  'data' : [ 'bios', 'openfirmware', 'uboot', 'uefi' ] }
+  'data' : [ 'bios', 'openfirmware', 'svsm', 'uboot', 'uefi' ] }
 
 ##
 # @FirmwareDevice:
Signature · 1 line
2.52.0
#5 lore raw

PATCH 3/3 docs/interop: Add firmware digests to schema

In reply to Oliver Steffen

Add a new optional top-level array called "digests" to the firmware JSON metadata schema. This can be used to attach different kinds of digests/hash values associated with the firmware image to the metadata file. The entries in the array are of a fixed type of JSON object, which describes the kind of digest, the hash algorithm used, as well as the value itself.

The only kind of supported digest type for now is the expected launch digest for confidential VMs running on AMD SEV-SNP. The list of allowed types can be extended in the future as needed to support other use-cases.

---
 docs/interop/firmware.json | 86 +++++++++++++++++++++++++++++++++++++-
 1 file changed, 85 insertions(+), 1 deletion(-)
docs/interop/firmware.json +85 -1
index dabfa692fd..46d6b431c0 100644
@@ -426,6 +426,53 @@
                       'memory' : 'FirmwareMappingMemory',
                       'igvm'   : 'FirmwareMappingIgvm' } }
 
+##
+# @FirmwareDigestType:
+#
+# Type of digest.
+#
+# @amd-sev-snp-launch: AMD SEV-SNP launch digest.
+##
+{ 'enum': 'FirmwareDigestType',
+  'data': [ 'amd-sev-snp-launch' ] }
+
+##
+# @AmdSevSnpLaunchHashAlg:
+#
+# Hash algorithms used for AMD SEV-SNP launch digests.
+#
+# @sha384: SHA-384
+##
+{ 'enum': 'AmdSevSnpLaunchHashAlg',
+  'data': [ 'sha384' ] }
+
+##
+# @AmdSevSnpLaunchDigest:
+#
+# Description of a launch digest as used by AMD SEV-SNP
+#
+# @hash-alg: Hashing algorithm
+#
+# @value: Digest value as hex string
+##
+{ 'struct' : 'AmdSevSnpLaunchDigest',
+  'data'   : { 'hash-alg' : 'AmdSevSnpLaunchHashAlg',
+               'value'    : 'str' } }
+
+##
+# @FirmwareDigest:
+#
+# Digests associated with the firmware image
+#
+# For example launch digests for attestation of confidential VMs.
+#
+# @type: Kind of digest.
+##
+{ 'union'         : 'FirmwareDigest',
+  'base'          : { 'type' : 'FirmwareDigestType' },
+  'discriminator' : 'type',
+  'data'          : { 'amd-sev-snp-launch' : 'AmdSevSnpLaunchDigest' } }
+
 ##
 # @Firmware:
 #
@@ -512,6 +559,10 @@
 #     debugging purposes only, and management software shall
 #     explicitly ignore it.
 #
+# @digests: (optional) Digest information associated with the
+#     firmware image, for example launch digests for confidential
+#     virtualization.
+#
 # Since: 3.0
 #
 # .. qmp-example::
@@ -713,6 +764,38 @@
 #             "-D DEBUG_PRINT_ERROR_LEVEL=0x80000000"
 #         ]
 #     }
+#
+#     {
+#        "description": "Coconut SVSM for QEMU under AMD SEV-SNP",
+#        "interface-types": [
+#            "uefi",
+#            "svsm"
+#         ],
+#        "mapping": {
+#           "device": "igvm",
+#           "filename": "/usr/share/coconut-svsm/coconut-qemu.igvm"
+#        },
+#        "targets": [
+#           {
+#              "architecture": "x86_64",
+#              "machines": [
+#                  "pc-q35-*"
+#              ]
+#           }
+#        ],
+#        "features": [
+#           "amd-sev-snp",
+#           "vtpm"
+#        ],
+#        "tags": [],
+#        "digests": [
+#           {
+#             "type": "amd-sev-snp-launch",
+#             "hash-alg": "sha384",
+#             "value": "ec664e889ed6c1b2763cacf7899d95b7f347373eb982e523419feea3aa362d891b3bf025f292267a5854049091789c3e"
+#           }
+#        ]
+#     }
 ##
 { 'struct' : 'Firmware',
   'data'   : { 'description'     : 'str',
@@ -720,4 +803,5 @@
                'mapping'         : 'FirmwareMapping',
                'targets'         : [ 'FirmwareTarget' ],
                'features'        : [ 'FirmwareFeature' ],
-               'tags'            : [ 'str' ] } }
+               'tags'            : [ 'str' ],
+               '*digests'        : [ 'FirmwareDigest' ] } }
Signature · 1 line
2.52.0
#6 lore raw

Re: [PATCH 3/3] docs/interop: Add firmware digests to schema

Hi,

docs/interop/firmware.json line 447

Quoted 9 lines
docs/interop/firmware.json +9 -0
+##
+# @AmdSevSnpLaunchHashAlg:
+#
+# Hash algorithms used for AMD SEV-SNP launch digests.
+#
+# @sha384: SHA-384
+##
+{ 'enum': 'AmdSevSnpLaunchHashAlg',
+  'data': [ 'sha384' ] }

Hmm. When it comes to extending this: Do we want be very strict, like this, and have a per-type list of digests?

One possible extension which comes to mind is the 'platform-code' digest measured into TPMs (pcr0). The possible hash algorithms here are everything supported by the TPM, i.e. sha1, sha256, sha384, sha512. I think for something new introduced in 2026 we can ignore sha1, leaving the other three on the table.

So one option would be to add a TPMHashAlg enum for this (sticking to the theme).

The alternative approach would be to have a common 'FirmwareHashAlg' for all types. Would make the structs below a bit simpler, the AmdSevSnpLaunchDigest is not needed then and FirmwareDigest can be a simple struct instead of a union. On the other hand it would allow some invalid combinations such as sha256 for amd-snp launch digest.

Opinions?

take care,
Gerd