s390-tools/rust/pvattest

pvattest

Synopsis

pvattest [OPTIONS] <COMMAND>

Description

create, perform, and verify attestation measurements Create, perform, and verify attestation measurements for IBM Secure Execution guest systems.

Commands Overview

• create

Create an attestation measurement request

• perform

Send the attestation request to the Ultravisor (s390x only.)

• verify

Verify an attestation response

• check

Check if the attestation result matches defined policies

Options

-v, --verbose

Provide more detailed output.

-q, --quiet

Provide less output.

--version

Print version information and exit.

-h, --help

Print help (see a summary with '-h').

pvattest create

Synopsis

pvattest create [OPTIONS] --host-key-document <FILE> --output <FILE> --arpk <FILE> <--no-verify|--cert <FILE>>

Description

Create an attestation measurement request. Create attestation measurement requests to attest an IBM Secure Execution guest. Only build attestation requests in a trusted environment such as your Workstation. To avoid compromising the attestation do not publish the attestation request protection key and shred it after verification. Every 'create' will generate a new, random protection key.

Options

-k, --host-key-document <FILE>

Use FILE as a host-key document. Can be specified multiple times and must be specified at least once.

--no-verify

Disable the host-key document verification. Does not require the host-key documents to be valid. Do not use for a production request unless you verified the host-key document beforehand.

-C, --cert <FILE>

Use FILE as a certificate to verify the host-key or keys. The certificates are 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 and the intermediate CA certificate (signed by the root CA).

--crl <FILE>

Use FILE as a certificate revocation list (CRL). The list is used to check whether a certificate of the chain of trust is revoked. Specify this option multiple times to use multiple CRLs.

--offline

Make no attempt to download CRLs.

--root-ca <ROOT_CA>

Use FILE as the root-CA certificate for the verification. If omitted, the system wide-root CAs installed on the system are used. Use this only if you trust the specified certificate.

-o, --output <FILE>

Write the generated request to FILE.

-a, --arpk <FILE>

Save the protection key as unencrypted GCM-AES256 key in FILE Do not publish this key, otherwise your attestation is compromised.

--add-data <FLAGS>

Specify 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. Optional. Possible values: - **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.

-h, --help

Print help (see a summary with '-h').

pvattest perform

Synopsis

pvattest perform [OPTIONS] [IN] [OUT]

Description

Send the attestation request to the Ultravisor (s390x only.) Run a measurement of this system through ’/dev/uv’. This device must be accessible and the attestation Ultravisor facility must be present. The input must be an attestation request created with ’pvattest create’. Output will contain the original request and the response from the Ultravisor. Only available on s390x.

Arguments

<IN>

Specify the request to be sent.

<OUT>

Write the result to FILE.

Options

-i, --input <FILE>

Specify the request to be sent.

-o, --output <FILE>

Write the result to FILE.

-u, --user-data <File>

Provide up to 256 bytes of user input User-data is arbitrary user-defined data appended to the Attestation measurement. It is verified during the Attestation measurement verification. May be any arbitrary data, as long as it is less or equal to 256 bytes

-h, --help

Print help (see a summary with '-h').

pvattest verify

Synopsis

pvattest verify [OPTIONS] --input <FILE> --hdr <FILE> --arpk <FILE>

Description

Verify an attestation response. Verify that a previously generated attestation measurement of an IBM Secure Execution guest is as expected. Only verify attestation requests in a trusted environment, such as your workstation. Input must contain the response as produced by ’pvattest perform’. The protection key must be the one that was used to create the request by ’pvattest create’. Shred the protection key after the verification. The header must be the IBM Secure Execution header of the image that was attested during ’pvattest perform’. The verify command solely verifies that the Attestation measurement is correct. It does not check for the content of additional data or user data. See pvattest check for policy checks after you verified the Attestation measurement.

Options

-i, --input <FILE>

Specify the attestation response to be verified.

-o, --output <FILE>

Specify the output for the verification result.

--hdr <FILE>

Specifies the header of the guest image. Can be an IBM Secure Execution image created by genprotimg or an extracted IBM Secure Execution header. The header must start at a page boundary.

-a, --arpk <FILE>

Use FILE as the protection key to decrypt the request Do not publish this key, otherwise your attestation is compromised. Delete this key after verification.

--format <FORMAT>

Define the output format. Default value: 'yaml' Possible values: - **yaml**: Use yaml format.

-u, --user-data <FILE>

Write the user data to the FILE if any. Writes the user data, if the response contains any, to FILE The user-data is part of the attestation measurement. If the user-data is written to FILE the user-data was part of the measurement and verified. Emits a warning if the response contains no user-data.

-h, --help

Print help (see a summary with '-h').

pvattest check

Synopsis

pvattest check [OPTIONS] [IN] [OUT]

Description

Check if the attestation result matches defined policies. After the attestation verification, check whether the attestation result complies with user-defined policies.

Arguments

<IN>

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

<OUT>

Specify the output file for the check result.

Options

-i, --input <FILE>

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

-o, --output <FILE>

Specify the output file for the check result.

--format <FORMAT>

Define the output format. Default value: 'yaml' Possible values: - **yaml**: Use yaml format.

-k, --host-key-document <FILE>

Use FILE to check for 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 parameter can be specified multiple times.

--host-key-check <HOST_KEY_CHECKS>

Define the 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. Possible values: - **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, --user-data <FILE>

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

--secret <FILE>

Use FILE to include as successful Add-secret request. Checks if the Attestation response contains the hash of all specified add secret requests-tags. The hash is sensible to the order in which the secrets where added. This means that if the order of adding here different from the order the add-secret requests where sent to the UV this check will fail even though the same secrets are included in the UV secret store. Can be specified multiple times.

--secret-store-locked <BOOL>

Check whether the guests secret store is locked or not. 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.

--firmware

Check whether the firmware is supported by IBM. Requires internet access.

--firmware-check-version <FIRMWARE_CHECK_VERSION>

Specify the firmware verification request version. Default value: '1' Possible values: - **1**: Use firmware verification API request version 1.0. - **2**: Use firmware verification API request version 2.0.

--firmware-verify-url <URL>

Specify the endpoint to use for firmware version verification. Use an endpoint you trust. Requires the --firmware option.

-h, --help

Print help (see a summary with '-h').