pvattest - Create, perform, and verify attestation requests

Edit online

Use the pvattest command to create an attestation request, perform an attestation measurement, and verify the result.

pvattest syntax

Where:

create <options>: On a trusted Linux instance, creates an attestation request, see pvattest create for details.
perform <options>: On a KVM guest running in secure execution mode, performs an attestation measurement, see pvattest perform for details.
verify <options>: On a trusted Linux instance, compares calculated and measured attestation results, see pvattest verify for details.
check <options>: Check if the attestation result matches defined policies, see pvattest check for details.
-h or --help: Optional: displays short information about command usage. Specify after the main command for general help and after a sub-command for help specific to that command.
-v or --verbose: Optional: displays verbose messages.
--version: Optional: displays version information.

pvattest create

where:

-k

specifies the host key document.

-a <req_protection_key> or --arpk=<req_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 <output_file> or --output-file=<output_file>

specifies the file that contains the created request.

-C <certificate> or --cert=<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).

Ignored when --no-verify is specified.

--crl=<revoked_certificates>

Optional: specifies a list of revoked certificates.

--no-verify

Creates the request without verifying the host key document.

Warning: Working with an unverified host key document makes your KVM guest vulnerable to man-in-the-middle attacks.

--add-data <flags>

Optional. Specifies additional data for the request. Additional data is provided by the ultravisor and returned during the attestation request and is covered by the attestation measurement. Can be specified multiple times. Valid values are:

phkh-img: Request the public host-key-hash of the key that decrypted the SE-image as additional-data.
phkh-att: Request the public host-key-hash of the key that decrypted the attestation request as additional-data.
secret-store-hash: Request a hash over all successful add-secret requests and the lock state as additional-data.
firmware-state: Request the state of the firmware as additional-data.

--offline

Optional: does not download certificate-revocation lists. Every certificate requires a list of revoked certificates. If you specify --offline, specify one --crl for every -C.

--root-ca=<trusted_CA_certificate>

Optional: specifies a trusted root CA to use instead of one of the root CAs that are installed on the system.

Examples: These examples illustrate common uses for pvattest create.

A typical attestation request requires the following input:
- A host key document in hkd.crt
- A CA certificate, here from DigiCert, in DigiCertCA.crt
- The IBM Z signing-key certificate in SigningKey.crt
To create the attestation request, issue:
```
# pvattest create -k hkd.crt -C DigiCertCA.crt -C SigningKey.crt -a arp.key -o arcb.bin
```
This example generates the following output:
- A request protection key in arp.key
- An attestation request in arcb.bin
To create an attestation request without downloading revoked certificate lists, but instead use local lists specified with --crl, issue:
```
# pvattest create -k hkd.crt -C DigiCertCA.crt -C IbmSigningKey.crt --offline \ 
--crl DigiCertCA.crl --crl IbmSigningKey.crl --crl rootCA.crl -a arp.key -o arcb.bin
```
The example generates the same output as the previous one.
To create an attestation request on a test system, without verifying the host key document.
Warning: Use only for testing or when the host key document is already verified.
```
# pvattest create -k hkd.crt --no-verify --arpk arp.key -o arcb.bin
```

pvattest perform

Where:

-i <input_file> or --input=<input_file>: specifies the attestation request created with the pvattest create command.
-o <result_file> or --output=<result_file>: specifies the file to which the result of the attestation measurement is written.

Example:

To perform an attestation with a request attreq.bin and receive the output in attresp.bin, issue:
```
# pvattest perform -i attreq.bin -o attresp.bin
```

pvattest verify

Where:

-i <input_file> or --input=<input_file>: specifies the attestation request created to be verified.
-o <output_file> or --output=<output_file>: writes the verification result to the specified file.
--hdr=<header_file>: specifies the header of the KVM guest to be attested .
-a or --arpk=<req_protection_key>: specifies the request-protection key that is used to decrypt the request.
--format <format>: defines the output format. The default is yaml.
-u or --user-data <file>: writes any user data in the response to the file. The user data is part of the attestation measurement and verified when written. A warning is emitted if the response contains no user data.

Example:

To verify an attestation with the response from pvattest perform in attresp.bin, the request protection key generated by pvattest create in arp.key, and the header in hdr.bin, issue:
```
# pvattest verify -i attresp.bin --arpk arp.key --hdr hdr.bin
```

pvattest check

Where:

<input_file>

specifies the attestation response to check whether the policies are validated.

<output_file>

contains the result of the check in YAML format.

--format <output_format>

defines the output format of the check result file. Valid value for <output_format> is yaml, which is also the default.

-k or --host-key-document <hkd_file>

specifies a host-key document. Verifies that the attestation response contains the host-key hash of one of the specified host keys. The check fails if none of the host-keys match the hash in the response. This option can be specified multiple times.

--host-key-check <host_key_checks>

specifies a host-key-check policy. By default, all host-key hashes are checked, and it is not considered a failure if a hash is missing from the attestation response. Use this policy switch to trigger a failure if no corresponding hash is found. Requires at least one host-key document. Valid checks are:

att-key-hash: Check the host-key used for the attestation request.
boot-key-hash: Check the host-key used to the boot the image.

-u or --user-data <user_data_file>

checks if the provided user data matches the data from the attestation response.

--secret <secret_file>

specifies a successful add-secret request. The command checks if the attestation response contains the hash of all specified add-secret-request tags. The hash is sensitive to the order in which the secrets where added. Hence, if the order of adding here is different from the order in which the add-secret requests where sent to the ultravisor, this check fails even though the same secrets are included in the secret store. Can be specified multiple times.

--secret-store-locked <BOOL>

checks whether the guest's secret store is locked. Compares the hash of the secret store state to the one calculated by this option and optionally specified add-secret-requests in the correct order. If the attestation response does not contain a secret store hash, this check fails. Required if add-secret requests are specified. Valid values are: true or false.

Example:

To check a measurement after successful attestation, issue:
```
# pvattest check attresp.bin checkresult.yaml \
-secret=add-secret-req.bin,addsecret-req2.bin -secret-store-locked true 
```
where:
- attresp.bin is the attestation response.
- checkresult.yaml will contain the result of the check.
- -secret=add-secret-req.bin,addsecret-req2.bin specifies two add-secret requests to be checked.
- -secret-store-locked true specifies that the secret store state is locked.