VIRT-QEMU-SEV-VALIDATE(1)

📦

version 12.8.0 · 7 versions

12.8.0 · centos-stream 10 (latest)
11.10.0 · centos-stream 9
12.6.0 · nixpkgs unstable, ubuntu stonking
10.0.0 · ubuntu noble
9.0.0 · debian bookworm
12.0.0 · fedora 44, nixos 26.05, ubuntu resolute
12.3.0 · alpine 3.24, debian trixie, fedora 43, opensuse-leap 16.0, ubuntu questing

🎀 virt-qemu-sev-validate(1) 🎀

okay bestie, this is the Virtualization Support manual page for virt-qemu-sev-validate — and yes, we're doing the whole thing, every flag and every warning, because details are the moment. 💅

🌸 NAME 🌸

virt-qemu-sev-validate — validate a domain AMD SEV launch measurement

✨ SYNOPSIS ✨

virt-qemu-sev-validate [OPTIONS]

💖 DESCRIPTION 💖

okay so this program validates the reported measurement for a domain launched with AMD SEV. If it exits with a status of zero, the guest owner can be confident that their guest OS is running under the protection offered by the SEV / SEV-ES platform. 🫶

heads up: the level of protection varies depending on the AMD SEV platform generation, and describing the differences is outside the scope of this document.

for the results of this program to be considered trustworthy, it is required to be run on a machine that is already trusted by the guest owner. That could be a machine the guest owner has direct physical control over, or it could be another virtual machine protected by AMD SEV that has already had its launch measurement validated. Running this program on the virtualization host will not produce an answer that can be trusted.

if told to connect to libvirt, it will refuse to use a libvirt connection that is local to the machine, since that cannot be trusted. For the sake of testing or demonstration purposes, however, it can be forced to run in this scenario using the --insecure flag. The result will, of course, still not be trustworthy.

🔥 OPTIONS 🔥

💅 Common options 💅

-h, --help — display command line help usage then exit.
-d, --debug — show debug information while running.
-q, --quiet — don't print information about the attestation result.

🧚 Guest state options 🧚

These options provide information about the state of the guest that needs its boot attested.

--measurement BASE64-STRING — the launch measurement reported by the hypervisor of the domain to be validated. The measurement must be 48 bytes of binary data encoded as a base64 string.
--api-major VERSION — the SEV API major version of the hypervisor the domain is running on.
--api-minor VERSION — the SEV API major version of the hypervisor the domain is running on.
--build-id ID — the SEV build ID of the hypervisor the domain is running on.
--policy POLiCY — the policy bitmask associated with the session launch data of the domain to be validated.

🎀 Guest config options 🎀

These options provide items needed to calculate the expected domain launch measurement. This will then be compared to the reported launch measurement.

-f PATH, --firmware=PATH — path to the firmware loader binary. This is the EDK2 build that knows how to initialize AMD SEV. For the validation to be trustworthy it is important that the firmware build used has no support for loading non-volatile variables from NVRAM, even if NVRAM is exposed to the guest.
-k PATH, --kernel=PATH — path to the kernel binary if doing direct kernel boot.
-r PATH, --initrd=PATH — path to the initrd binary if doing direct kernel boot. Defaults to zero length content if omitted.
-e STRING, --cmdline=STRING — string containing any kernel command line parameters used during boot of the domain. Defaults to the empty string if omitted.
-n COUNT, --num-cpus=COUNT — the number of virtual CPUs for the domain. This is required when the domain policy is set to require SEV-ES.
-0 PATH, --vmsa-cpu0=PATH — path to the VMSA initial state for the boot CPU. This is required when the domain policy is set to require SEV-ES. The file contents must be exactly 4096 bytes in length.
-1 PATH, --vmsa-cpu1=PATH — path to the VMSA initial state for the non-boot CPU. This is required when the domain policy is set to require SEV-ES and the domain has more than one CPU present. The file contents must be exactly 4096 bytes in length.
--tik PATH — TIK file for the domain. This file must be exactly 16 bytes in size and contains the unique transport integrity key associated with the domain session launch data. This is mutually exclusive with the --tk argument.
--tek PATH — TEK file for the domain. This file must be exactly 16 bytes in size and contains the unique transport encryption key associated with the domain session launch data. This is mutually exclusive with the --tk argument.
--tk PATH — TEK/TIK combined file for the domain. This file must be exactly 32 bytes in size, with the first 16 bytes containing the TEK and the last 16 bytes containing the TIK. This is mutually exclusive with the --tik and --tek arguments.

🦋 Libvirt options 🦋

These options are used when connecting to libvirt to automatically obtain state and configuration information about the domain to be attested.

-c, --connect URI — libvirt connection URI. For the validation to be trustworthy this must be a URI resolving to a remote virtualization host. This requirement can be overridden using the --insecure argument.
-o, --domain ID|NAME|UUID — domain ID, or domain name or domain UUID. Used to identify which libvirt domain is to have its launch measured. The domain must be running, and would usually have been started in a paused state, to allow validation to be performed before guest CPUs begin execution.
-i, --insecure — proceed even if usage scenario is known to be insecure. This allows the program to connect to a local libvirt hypervisor and rely on file content from the virtualization host. It also allows the validation to proceed even if the virtual machine CPUs are not in the initial paused state. The result of the validation must not be trusted.
-g, --ignore-config — do not attempt to sanity check the domain config. The default behaviour is to print out errors if identifying configuration elements in the guest XML that would invalidate the launch measurement. This can help the guest owner to understand any configuration mistakes that have been made. If the --ignore-config argument is given, this sanity checking of configuration will be skipped. The result is that the validation will likely be reported as failed.

🍓 Secret injection options 🍓

These options provide a way to inject a secret if validation of the launch measurement passes.

--inject-secret ALIAS-OR-GUID:PATH — path to a file containing a secret to inject into the guest OS. Typical usage would be to supply a password for unlocking the root filesystem full disk encryption. ALIAS can be one of the well known secrets:
- luks-key — bytes to use as a key for unlocking a LUKS key slot. GUID of 736869e5-84f0-4973-92ec-06879ce3da0b.

Alternatively, GUID refers to an arbitrary UUID of the caller's choosing. The contents of PATH are defined by the requirements of the associated GUID, and will be used as-is without modification. In particular be aware:

Avoid unwanted trailing newline characters in PATH unless mandated by the GUID.
Any trailing NUL byte must be explicitly included in PATH if mandated by the GUID.

This argument can be repeated multiple times, provided a different GUID is given for each instance.

--secret-header PATH — path to a file in which the injected secret header will be written in base64 format and later injected into the domain. This is required if there is no connection to libvirt, otherwise the secret will be directly injected.
--secret-payload PATH — path to a file in which the injected secret payload will be written in base64 format and later injected into the domain. This is required if there is no connection to libvirt, otherwise the secret will be directly injected.

🌸 EXAMPLES 🌸

Ok bestie, this is the part where it gets real — actual copy-paste-able scenarios, and honestly these ate 💅. The examples are grouped by usage model, and each model has its own security vibe, so pay attention to which one you're in, mwah.

✨ Fully offline execution ✨

So this scenario lets you validate a measurement in a completely offline state, with zero connection to the hypervisor host. None. Not even a little peek. 🙈 Every single data item you need has to be handed over as a command line parameter.

And why is that secure? Because all input data is provided by the user — you. Not the shady hypervisor. This usage model is considered secure. Slay.

🔥 Validate the measurement of a SEV guest booting from disk

# virt-qemu-sev-validate \
    --firmware OVMF.sev.fd \
    --tk this-guest-tk.bin \
    --measurement Zs2pf19ubFSafpZ2WKkwquXvACx9Wt/BV+eJwQ/taO8jhyIj/F8swFrybR1fZ2ID \
    --api-major 0 \
    --api-minor 24 \
    --build-id 13 \
    --policy 3

🦋 Validate the measurement of a SEV guest with direct kernel boot

# virt-qemu-sev-validate \
    --firmware OVMF.sev.fd \
    --kernel vmlinuz-5.11.12 \
    --initrd initramfs-5.11.12 \
    --cmdline "root=/dev/vda1" \
    --tk this-guest-tk.bin \
    --measurement Zs2pf19ubFSafpZ2WKkwquXvACx9Wt/BV+eJwQ/taO8jhyIj/F8swFrybR1fZ2ID \
    --api-major 0 \
    --api-minor 24 \
    --build-id 13 \
    --policy 3

🎀 Validate the measurement of a SEV-ES SMP guest booting from disk

# virt-qemu-sev-validate \
    --firmware OVMF.sev.fd \
    --num-cpus 2 \
    --vmsa-cpu0 vmsa0.bin \
    --vmsa-cpu1 vmsa1.bin \
    --tk this-guest-tk.bin \
    --measurement Zs2pf19ubFSafpZ2WKkwquXvACx9Wt/BV+eJwQ/taO8jhyIj/F8swFrybR1fZ2ID \
    --api-major 0 \
    --api-minor 24 \
    --build-id 13 \
    --policy 7

💜 Validate the measurement of a SEV-ES SMP guest booting from disk, with automatically constructed VMSA

Bestie, notice the --policy 7 AND that --num-cpus 2 sitting right there with the CPU family/model/stepping doing the VMSA construction for you. Iconic.

# virt-qemu-sev-validate \
    --firmware OVMF.sev.fd \
    --num-cpus 2 \
    --cpu-family 23 \
    --cpu-model 49 \
    --cpu-stepping 0 \
    --tk this-guest-tk.bin \
    --measurement Zs2pf19ubFSafpZ2WKkwquXvACx9Wt/BV+eJwQ/taO8jhyIj/F8swFrybR1fZ2ID \
    --api-major 0 \
    --api-minor 24 \
    --build-id 13 \
    --policy 7

🍓 Validate the measurement of a SEV guest booting from disk and inject a disk password on success

Um, injecting a secret? Very main character energy. Look at all those secret flags. 🤫

# virt-qemu-sev-validate \
    --firmware OVMF.sev.fd \
    --tk this-guest-tk.bin \
    --measurement Zs2pf19ubFSafpZ2WKkwquXvACx9Wt/BV+eJwQ/taO8jhyIj/F8swFrybR1fZ2ID \
    --api-major 0 \
    --api-minor 24 \
    --build-id 13 \
    --policy 3 \
    --inject-secret 736869e5-84f0-4973-92ec-06879ce3da0b:passwd.txt \
    --secret-header secret-header.b64 \
    --secret-payload secret-payload.b64

The secret-header.b64 and secret-payload.b64 files can now be sent to the virtualization host for injection. Go off, you little courier 🫶

🌈 Fetch from remote libvirt 🌈

This scenario lets you fetch certain data from a remote hypervisor via a connection to libvirt. It's giving debugging assist — it analyses the guest configuration and reports anything that could invalidate the measurement of the guest. 🕵️‍♀️

Is it secure? Yes bestie, this usage model is considered secure, because the limited information obtained from the untrusted hypervisor cannot be used to change the result. The math doesn't care about their lies, periodt.

🔥 Validate the measurement of a SEV guest booting from disk

# virt-qemu-sev-validate \
    --connect qemu+ssh://root@some.remote.host/system \
    --firmware OVMF.sev.fd \
    --tk this-guest-tk.bin \
    --domain fedora34x86_64

🦋 Validate the measurement of a SEV guest with direct kernel boot

# virt-qemu-sev-validate \
    --connect qemu+ssh://root@some.remote.host/system \
    --firmware OVMF.sev.fd \
    --kernel vmlinuz-5.11.12 \
    --initrd initramfs-5.11.12 \
    --cmdline "root=/dev/vda1" \
    --tk this-guest-tk.bin \
    --domain fedora34x86_64

🎀 Validate the measurement of a SEV-ES SMP guest booting from disk

# virt-qemu-sev-validate \
    --connect qemu+ssh://root@some.remote.host/system \
    --firmware OVMF.sev.fd \
    --num-cpus 2 \
    --vmsa-cpu0 vmsa0.bin \
    --vmsa-cpu1 vmsa1.bin \
    --tk this-guest-tk.bin \
    --domain fedora34x86_64

💜 Validate the measurement of a SEV-ES SMP guest booting from disk, with automatically constructed VMSA

# virt-qemu-sev-validate \
    --connect qemu+ssh://root@some.remote.host/system \
    --firmware OVMF.sev.fd \
    --cpu-family 23 \
    --cpu-model 49 \
    --cpu-stepping 0 \
    --tk this-guest-tk.bin \
    --domain fedora34x86_64

🍓 Validate the measurement of a SEV guest booting from disk and inject a disk password on success

# virt-qemu-sev-validate \
    --connect qemu+ssh://root@some.remote.host/system \
    --firmware OVMF.sev.fd \
    --tk this-guest-tk.bin \
    --domain fedora34x86_64 \
    --inject-secret 736869e5-84f0-4973-92ec-06879ce3da0b:passwd.txt

🧚 Fetch from local libvirt 🧚

Ok so. THIS one pulls all data</> from the local hypervisor via a libvirt connection. But — and I need you to hear me — it is only to be used for the purpose of testing, debugging, or demonstrations, because running on the local hypervisor is not a secure scenario. 😭

Bestie warning: to enable this usage, the --insecure flag must be specified. No flag, no vibes, no validation. That's the deal. 💀

Given a pointer to the libvirt guest to validate, all information needed to perform a validation — except the TIK/TEK pair — can be acquired automatically. Not the TIK/TEK though. You bring those yourself. 👑

🔥 Validate the measurement of a SEV guest booting from disk

# virt-qemu-sev-validate \
    --insecure \
    --tk this-guest-tk.bin \
    --domain fedora34x86_64

🦋 Validate the measurement of a SEV guest with direct kernel boot

# virt-qemu-sev-validate \
    --insecure \
    --tk this-guest-tk.bin \
    --domain fedora34x86_64

🎀 Validate the measurement of a SEV-ES SMP guest booting from disk

# virt-qemu-sev-validate \
    --insecure \
    --vmsa-cpu0 vmsa0.bin \
    --vmsa-cpu1 vmsa1.bin \
    --tk this-guest-tk.bin \
    --domain fedora34x86_64

💜 Validate the measurement of a SEV-ES SMP guest booting from disk, with automatically constructed VMSA

# virt-qemu-sev-validate \
    --insecure \
    --tk this-guest-tk.bin \
    --domain fedora34x86_64

🍓 Validate the measurement of a SEV guest booting from disk and inject a disk password on success

# virt-qemu-sev-validate \
    --insecure \
    --tk this-guest-tk.bin \
    --domain fedora34x86_64 \
    --inject-secret 736869e5-84f0-4973-92ec-06879ce3da0b:passwd.txt

And that's the local-libvirt flex — remember, --insecure or it doesn't happen, and it's for testing/debugging/demos only, not for actually trusting your local hypervisor. Stay safe out there 🫶✨

🕵️ COMMON MISTAKES CHECKLIST 🕵️

okay so bestie, real talk: configuring a guest and validating its boot measurement is genuinely a lot of moving parts, which means you're honestly very likely to run into this little jumpscare:

ERROR: Measurement does not match, VM is not trustworthy

and like… that message is giving full doom, but ngl in most cases the "failure" is just you mis-configuring the guest, or handing the tool the wrong info when you try to validate it. 😭 So here's the checklist — go through these in order and you'll have the best possible shot at actually diagnosing what's wrong. 💅

Check the VM configuration for the DH certificate and session blob in the libvirt guest XML.

The content for these fields should be in base64 format, which is what sevctl session generates. Other tools may generate the files in binary format, so make sure it's been correctly converted to base64. ✨

Check the VM configuration policy value matches the session blob.

The <policy> value in libvirt guest XML has to match the value passed to the sevctl session command. If these are mismatched then the guest won't even start, and QEMU will show an error like:

sev_launch_start: LAUNCH_START ret=1 fw_error=11 'Bad measurement'

Check the correct TIK/TEK keypair are passed.

The TIK/TEK keypair are uniquely tied to each DH cert and session blob. Make sure that the TIK/TEK keypair passed to this program are the ones matched to the DH cert and session blob configured for the libvirt guest XML. This is one of the most common mistakes. 🫠 Also double-check that the TIK and TEK files are not swapped.

Check the firmware binary matches the one used to boot.

The firmware binary content is part of the data covered by the launch measurement. Ensure that the firmware binary passed to this program matches the one used to launch the guest. Heads up: the hypervisor host will periodically get software updates which introduce a new firmware binary version. 👀

Check the kernel, initrd and cmdline match the one used to boot.

If the guest is configured to use direct kernel boot, check that the kernel, initrd and cmdline passed to this program match the ones used to boot the guest. In the kernel cmdline whitespace must be preserved exactly, including any leading or trailing spaces. yeah. every single space. 💀

Check whether the kernel hash measurement is enabled.

The kernelHashes property in the libvirt guest XML controls whether hashes of the kernel, initrd and cmdline content are covered by the boot measurement. If enabled, then the matching content must be passed to this program. If disabled, then the content must NOT be passed.

Check that the correct measurement hash is passed.

The measurement hash includes a nonce, so it will be different on every boot attempt. So when validating the measurement it's important to make sure the most recent measurement is used. ⭐

Check the correct VMSA blobs / CPU SKU values for the host are used.

The VMSA blobs provide the initial register state for the boot CPU and any additional CPUs. One of the registers encodes the CPU SKU (family, model, stepping) of the physical host CPU. Make sure that the VMSA blob used for validation is one that matches the SKU of the host the guest is booted on. Passing the CPU SKU values directly to the tool can reduce the likelihood of using the wrong ones. 🎀

Check the CPU count is correct.

When passing VMSA blobs for SEV-ES guests, the number of CPUs present will influence the measurement result. Ensure that the correct vCPU count is used corresponding to the guest boot attempt.

Best practice is to run this tool in completely offline mode and pass all information as explicit command line parameters. 💖 When debugging failures, though, it can be useful to tell it to connect to libvirt and fetch information. If connecting to a remote libvirt instance, it will fetch any information that can be trusted, which is the basic VM launch state data. It'll also sanity check the XML configuration to identify some common mistakes. And if the --insecure flag is passed it can extract some configuration information and use that for the attestation process.

If the mistake still can't be identified, then this tool can be run on the virtualization host. In that scenario the only three command line parameters required are for the TIK, TEK and libvirt domain name. It should be able to automatically determine all the other information required. If it still reports a failure, that points very strongly to the TIK/TEK pair not matching the configured DH certificate and session blob. 🔥

The --debug flag will display hashes and/or hex dumps for various pieces of information used in the attestation process. Comparing the --debug output from running on the hypervisor host against that obtained when running in offline mode can give further guidance on which parameter is inconsistent. ✨

As mentioned earlier in this document, bear in mind that in general any attestation answers obtained from running on the hypervisor host should not be trusted. So if a configuration mistake is identified it is strongly recommended to re-run the attestation in offline mode on a trusted machine. 😤 no cap, trust the offline run.

🚦 EXIT STATUS 🚦

Upon successful attestation of the launch measurement, an exit status of 0 will be set. slay. 👑

Upon failure to attest the launch measurement one of the following codes will be set:

1 — Guest measurement did not validate.

Assuming the inputs to this program are correct, the virtual machine launch has been compromised and it should not be trusted henceforth. 😨

2 — Usage scenario cannot be supported.

The way in which this program has been invoked prevent it from being able to validate the launch measurement.

3 — Usage scenario is not secure.

The way in which this program has been invoked means that the result of any launch measurement validation will not be secure.

The program can be reinvoked with --insecure argument to force a validation, however, the results of this should not be trusted. This should only be used for testing, debugging or demonstration purposes, never in a production deployment. 🙈

4 — Domain has incorrect configuration to be measured.

The way in which the guest has been configured prevent this program from being able to validate the launch measurement. Note that in general the guest configuration reported by the hypervisor is not trustworthy, so it is possible this error could be a false positive designed to cause a denial of service. 💀

This program can be reinvoked with the --ignore-config argument to skip the sanity checks on the domain XML. This will likely result in it failing with an exit code of 1 indicating the measurement is invalid.

5 — Domain is in incorrect state to be measured.

The domain has to be running in order to validate a launch measurement. 🏃‍♀️

6 — unexpected error occurred in the code.

A logic flaw in this program means it is unable to complete the validation of the measurement. This is a bug which should be reported to the maintainers. 🐛

✍️ AUTHOR ✍️

Daniel P. Berrangé

🐛 BUGS 🐛

Please report all bugs you discover. This should be done via either:

the mailing list

https://libvirt.org/contact.html

the bug tracker

https://libvirt.org/bugs.html

Alternatively, you may report bugs to your software distributor / vendor. 🫶

📜 LICENSE 📜

virt-qemu-sev-validate is distributed under the terms of the GNU LGPL v2.1+. This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 😌

👀 SEE ALSO 👀

virsh(1)
SEV launch security usage
https://libvirt.org/

and that's the whole page bestie, VIRT-QEMU-SEV-VALIDATE(1) — go forth and validate responsibly 💅✨🦋

📦 where this page comes from

centos-stream 10: libvirt-client-qemu 12.8.0-1.el10 · GPL-2.0-or-later AND LGPL-2.1-only AND LGPL-2.1-or-later AND OFL-1.1
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-06: a language model's rewrite of the original, under its terms

VIRT-QEMU-SEV-VALIDATE(1)

🎀 virt-qemu-sev-validate(1) 🎀

🌸 NAME 🌸

✨ SYNOPSIS ✨

💖 DESCRIPTION 💖

🔥 OPTIONS 🔥

💅 Common options 💅

🧚 Guest state options 🧚

🎀 Guest config options 🎀

🦋 Libvirt options 🦋

🍓 Secret injection options 🍓

🌸 EXAMPLES 🌸

✨ Fully offline execution ✨

🔥 Validate the measurement of a SEV guest booting from disk

🦋 Validate the measurement of a SEV guest with direct kernel boot

🎀 Validate the measurement of a SEV-ES SMP guest booting from disk

💜 Validate the measurement of a SEV-ES SMP guest booting from disk, with automatically constructed VMSA

🍓 Validate the measurement of a SEV guest booting from disk and inject a disk password on success

🌈 Fetch from remote libvirt 🌈

🔥 Validate the measurement of a SEV guest booting from disk

🦋 Validate the measurement of a SEV guest with direct kernel boot

🎀 Validate the measurement of a SEV-ES SMP guest booting from disk

💜 Validate the measurement of a SEV-ES SMP guest booting from disk, with automatically constructed VMSA

🍓 Validate the measurement of a SEV guest booting from disk and inject a disk password on success

🧚 Fetch from local libvirt 🧚

🔥 Validate the measurement of a SEV guest booting from disk

🦋 Validate the measurement of a SEV guest with direct kernel boot

🎀 Validate the measurement of a SEV-ES SMP guest booting from disk

💜 Validate the measurement of a SEV-ES SMP guest booting from disk, with automatically constructed VMSA

🍓 Validate the measurement of a SEV guest booting from disk and inject a disk password on success

🕵️ COMMON MISTAKES CHECKLIST 🕵️

🚦 EXIT STATUS 🚦

✍️ AUTHOR ✍️

🐛 BUGS 🐛

©️ COPYRIGHT ©️

📜 LICENSE 📜

👀 SEE ALSO 👀