Attesting a KVM guest

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.

As of IBM® z17®, you can add secret store measurements to the attestation. After successful attestation completes, you can check the measurements.

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 SEL header from the KVM guest to be attested, see Extracting an IBM SEL 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.
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 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
```
  where:
  - -k <host_key_document> specifies the host key document.
  - -C <CA_certificate>specifies the certificate that is used to establish a chain of trust for the verification of the host key documents. Specify this option twice to specify the IBM Z signing-key certificate and the intermediate CA certificate (signed by the root CA).
  - --arpk <request_protection_key> generates a random AES-256-GCM key that protects the attestation request. Take care not to inadvertently publish this key, as the attestation could then be tampered with.
  - -o <request_file> specifies the file that contains the generated add-secret request.
  For example, to use
  - a host-key document hkd.crt.
  - a CA certificate CA.crt.
  - an IBM signing key ibmsk.crt.
  - an output file attreq.bin for the request.
  - an output file arp.key for the request protection key.
  on a trusted Linux instance, issue:
```
[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:
```
[seguest]# 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
```
  where:
  - -i <request>.bin specifies the attestation request created with the pvattest create command.
  - -o <response>.bin specifies the file to which the result of the attestation measurement is written.
  In the following example, the attestation request is called attreq.bin and 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 SEL 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 <att_resp>.bin --arpk <req_prot_key> --hdr <SEL_header>
```
  where:
  - -i <att_resp>.bin specifies the attestation response from the pvattest perform command.
  - --arpk <req_prot_key> specifies the request-protection key that is used to decrypt the request.
  - --hdr <SEL_header> specifies the header of the KVM guest.
  The command uses the request protection key that was generated during the creation and the IBM SEL 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