Attesting a KVM guest

Edit online

Use attestation as evidence that the KVM guest runs in secure-execution mode. If the KVM guest was built for one particular IBM Z server, the attestation also verifies that the KVM guest runs on that specific server.

If the KVM guest was built for several servers, the attestation only verifies that the KVM guest runs on one of those servers.

Before you begin

You require the following access rights:

Access to the secure execution header of the KVM guest to be attested.
Access to the KVM guest to be attested.
On the KVM guest to be attested: You need to be able to send and receive requests and responses to the KVM guest.

You require the following input files:

A host key document of the IBM Z system where the guest to be attested runs.
The IBM Z signing-key certificate (also called a host-key-signing-key certificate) used by IBM to sign the host key document.
An intermediate CA certificate used to sign the IBM Z signing-key certificate.
The IBM Secure Execution header from the KVM guest to be attested, see Extracting an IBM Secure Execution header.
Using a trusted Linux instance, extract the header from the KVM guest image before you submit it to the cloud provider.

You require the pvattest command, which is included in your distribution. For details about the command, see pvattest - Create, perform, and verify attestation requests.

About this task

Two different Linux instances are involved:

The KVM guest to be attested. In the examples in this section, this KVM guest is called secguest.
A trusted Linux instance. In the examples in this section, this Linux instance is called trusted. This instance can be:
- A Linux instance running on IBM Z hardware. If you want to use IBM Z, the Linux instance should be a previously attested secure execution guest or be on your premises and managed by trusted personnel.
- A Linux instance running on x86 hardware. No special setup is required. If you want to use a local workstation, it must adhere to the security policies of your organization. For information about building the pvattest command, see Building pvattest on Linux on x86 hardware.
The trusted Linux instance requires the pvattest. The first attestation is typically done on a system you fully control, such as your laptop.

From the trusted Linux instance you send an attestation request from user space to the KVM guest to be attested. The ultravisor processes the request and creates a response. The response is an answer document that you retrieve, and that you must validate. This process is illustrated in Figure 1.

This figure illustrates the attestation process: an attester creates a request, copies it over, performs the attestation measurement, retrieves the result, and verifies it. — Figure 1. The process of attestation

Procedure

On your trusted Linux instance, prepare the attestation request:
1. Use the pvattest create command to create an attestation request.
  Use a command of the following form:
```
# pvattest create -k <host_key_doc>.crt --cert <CA_certificate>.crt \ 
--cert <IBM_sign_key_cert>.crt --arpk <request_protection_key> -o <request>.bin
```
  For example, using a Linux instance called trusted:
```
[trusted]# pvattest create -k hkd.crt --cert CA.crt --cert ibmsk.crt \
--arpk arp.key -o attreq.bin
```
  In this example, the attestation request is written to attreq.bin. The command generates a key that protects the request and writes it to a file, here arp.key.
2. Send the attestation request to the KVM guest to be attested.
  Use, for example, the secure-copy (scp) command to transfer the request file. For example:
```
[trusted]# scp attreq.bin seguest:
```
On the KVM guest to be attested, perform the attestation.
1. Ensure that the /dev/uv device is available.
  For example, assuming that the KVM guest to be attested is called secguest:
```
[secguest]# ls /dev/uv
/dev/uv 
```
  If the uv device is not available, use modprobe to load the uvdevice module.
```
[secguest]# modprobe --first-time uvdevice
```
2. Perform the attestation.
  Use a command of the following form:
```
# pvattest perform -i <request>.bin -o <response>.bin
```
  In the following example, the response is written to attresp.bin:
```
[seguest]# pvattest perform -i attreq.bin -o attresp.bin
```
On your trusted Linux instance:
1. Retrieve the response.
  For example, to copy the response attresp.bin to the current directory on trusted:
```
[trusted]# scp seguest:attresp.bin .
```
2. Obtain the header file or the guest image from the owner of the guest.
  For details about how to extract the header from the image, see Extracting an IBM Secure Execution header. Store the header in a file, for example hdr.bin.
3. Verify the attestation using the pvattest verify command.
  Use a command of the following form:
```
[trusted]# pvattest verify -i <resp>.bin --arpk <req_prot_key> --hdr <se_guest.hdr>
```
  The command uses the request protection key that was generated during the creation and the IBM Secure Execution header to calculate a corresponding measurement. It then verifies that the two are the same.
  For example:
```
[trusted]# pvattest verify -i attresp.bin --arpk arp.key --hdr hdr.bin
```

Results

If the result of the pvattest perform command and the calculated results match, the command ends with exit code 0. You can check this by displaying the $? variable with the echo command:

[trusted]# pvattest verify -i attresp.bin --arpk arp.key --hdr hdr.bin
[trusted]# echo $?
0

If the result of the pvattest perform command and the calculated results do not match, the command ends with an error and exit code 2:

[trusted]# pvattest verify -i wrongmeas.bin --arpk arp.key --hdr hdr.bin
ERROR: Attestation measurement verification failed:
Calculated and received attestation measurement are not the same.
[trusted]# echo $?
2