A tool to calculate the launch measurement for the directives in an IGVM file and to optionally create a signed version of the IGVM file.
When starting a guest configured using an IGVM file, the directives in the IGVM are use to populate initial guest memory and describe the initial guest state. This configuration is measured by the isolation technology, such as SEV-SNP or TDX and results in a launch digest that can be remotely verified using an attestation report.
In order to ensure the integrity of a build that is packed in IGVM, it is necessary to be able to pre-calculate the measurement of the file to obtain the expected launch digest. This can then be compared with the actual launch measurement in the attestation report to ensure the initial guest state is as expected.
Given an IGVM file, igvmmeasure parses the directives in the file and calculates the launch digest. This can either be output as a hexadecimal string, or igvmmeasure can be used to create a signed IGVM file that contains directives that instruct an IGVM loader, such as the loader integrated into QEMU to provide a signed measurement to the platform which is then verified at guest launch.
There are some restrictions on the contents of an IGVM file when using QEMU with KVM which impose some rules on the directives in the IGVM file. This is due to the way the initial guest state is passed from QEMU user mode to KVM in the kernel. Therefore, IGVM files for this virtualization stack must conform to these rules.
Passing the --check-kvm option to igvmmeasure will result in some basic checks
being performed on the directives in the file during the measurement process.
This can be use to help diagnose measurement mismatches, or to abort the IGVM
build process if a non-conformant file is generated.
igvmmeasure [OPTIONS] <INPUT> <COMMAND>
<INPUT>
The filename of the input IGVM file to measure
-v, --verbose Print verbose output
-c, --check-kvm Check that the IGVM file conforms to QEMU/KVM restrictions
-p, --platform <PLATFORM> Platform to calculate the launch measurement for [default: sev-snp] [possible values: sev-snp]
-n, --native-zero Determine how to pages that contain only zeroes in the IGVM file
-h, --help Print help (see more with '--help')
igvmmeasure can either measure and IGVM file and display the output in the
console, or it can generate a measurement that is added as a signed ID block for
SEV-SNP into a signed copy of the input IGVM file. The operation is selected via
one of these commands:
measure Measure the input file and print the measurement to the console
sign Measure the input file and generate a new output file containing a
signature suitable for the target platform. For SEV-SNP this
generates an IGVM_VHT_SNP_ID_BLOCK directive in the output file
Each command has its own specific options:
measure
-i, --ignore-idblock
If an ID block is present within the IGVM file then by default an
error will be generated if the expected measurement differs from the
calculated measurement. If this option is set then the expected
measurement in the ID block is ignored.
-b, --bare
Bare output only, consisting of just the digest as a hex string
sign
--output <OUTPUT>
Output filename of the signed IGVM file that will be created
--id-key <ID_KEY>
Filename of the private key that is used to sign the contents of the
ID block. For SEV-SNP platforms, this should be an ECDSA P-384 key.
You can create a key using:
$ openssl ecparam -name secp384r1 -genkey -noout -out
--author-key <AUTHOR_KEY>
Filename of the author private key that is used to sign the public
part of the id_key. For SEV-SNP platforms, this should be an ECDSA
P-384 key. You can create a key using:
$ openssl ecparam -name secp384r1 -genkey -noout -out
The author key is option. See the SEV-SNP documentation for more
information.
An IGVM file can be signed using igvmmeasure to generate an output file that contains a signed ID block for SEV-SNP.
There are two of keys that are used during the signing process:
The key that is used to sign the launch digest. The public portion of the key is stored in the IGVM file with the launch measurement and signature to allow the SEV-SNP platform to validate the expected measurement before checking the measurement matches that actual configuration of the guest.
The key that is used to sign the public id-key. This allows the SEV-SNP platform to check the validity of the public key that is used to verify the launch measurement. The author-key is optional and is ignored by the platform if not provided.
An id-key and author-key can be generated using openssl:
openssl ecparam -name secp384r1 -genkey -noout -out testkeys/id_key.pem
openssl ecparam -name secp384r1 -genkey -noout -out testkeys/author_key.pem
Once the keys have been generated, the IGVM file can be signed:
igvmmeasure igvm_file sign --output igvm_file_signed --id-key testkeys/id_key.pem --author-key testkeys/author_key.pem