rust/pvattest: Update manuals and README

Signed-off-by: Steffen Eiden <seiden@linux.ibm.com>

rust/pvattest/README.md

@@ -25,28 +25,34 @@ Send the attestation request to the Ultravisor
 Verify an attestation response
 </ul>
 
-- **version**
+- **check**
 <ul>
-Print version information and exit
+Check if the attestation result matches defined policies
 </ul>
 
 ## Options
 
 `-v`, `--verbose`
 <ul>
-Provide more detailed output
+Provide more detailed output.
+</ul>
+
+
+`-q`, `--quiet`
+<ul>
+Provide less output.
 </ul>
 
 
 `--version`
 <ul>
-Print version information and exit
+Print version information and exit.
 </ul>
 
 
 `-h`, `--help`
 <ul>
-Print help (see a summary with '-h')
+Print help (see a summary with '-h').
 </ul>
 
 
@@ -54,7 +60,7 @@ Print help (see a summary with '-h')
 ### 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
+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
@@ -79,7 +85,7 @@ the host-key document beforehand.
 
 `-C`, `--cert <FILE>`
 <ul>
-Use FILE as a certificate to verify the host key or keys. The certificates are
+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).
@@ -96,7 +102,7 @@ to use multiple CRLs.
 
 `--offline`
 <ul>
-Make no attempt to download CRLs
+Make no attempt to download CRLs.
 </ul>
 
 
@@ -110,11 +116,11 @@ specified certificate.
 
 `-o`, `--output <FILE>`
 <ul>
-Write the generated request to FILE
+Write the generated request to FILE.
 </ul>
 
 
-`--arpk <FILE>`
+`-a`, `--arpk <FILE>`
 <ul>
 Save the protection key as unencrypted GCM-AES256 key in FILE Do not publish
 this key, otherwise your attestation is compromised.
@@ -123,47 +129,43 @@ this key, otherwise your attestation is compromised.
 
 `--add-data <FLAGS>`
 <ul>
-Specify-additional data for the request. Additional data is provided by the
+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
-</ul>
-
-
-`-v`, `--verbose`
-<ul>
-Provide more detailed output
+        - **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.
 </ul>
 
 
 `-h`, `--help`
 <ul>
-Print help (see a summary with '-h')
+Print help (see a summary with '-h').
 </ul>
 
 
 ## pvattest perform
 ### Synopsis
-`pvattest perform [OPTIONS] [INPUT] [OUTPUT]`
+`pvattest perform [OPTIONS] [IN] [OUT]`
 ### Description
-Send the attestation request to the Ultravisor Run a measurement of this system
+Send the attestation request to the Ultravisor. 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.
 ### Arguments
 
-`<INPUT>`
+`<IN>`
 <ul>
-Specify the request to be sent
+Specify the request to be sent.
 </ul>
 
 
-`<OUTPUT>`
+`<OUT>`
 <ul>
-Write the result to FILE
+Write the result to FILE.
 </ul>
 
 
@@ -178,15 +180,9 @@ equal to 256 bytes
 </ul>
 
 
-`-v`, `--verbose`
-<ul>
-Provide more detailed output
-</ul>
-
-
 `-h`, `--help`
 <ul>
-Print help (see a summary with '-h')
+Print help (see a summary with '-h').
 </ul>
 
 
@@ -194,7 +190,7 @@ Print help (see a summary with '-h')
 ### Synopsis
 `pvattest verify [OPTIONS] --input <FILE> --hdr <FILE> --arpk <FILE>`
 ### Description
-Verify an attestation response Verify that a previously generated attestation
+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
@@ -206,13 +202,13 @@ perform’
 
 `-i`, `--input <FILE>`
 <ul>
-Specify the attestation request to be verified
+Specify the attestation response to be verified.
 </ul>
 
 
 `-o`, `--output <FILE>`
 <ul>
-Specify the output for the verification result
+Specify the output for the verification result.
 </ul>
 
 
@@ -224,7 +220,7 @@ must start at a page boundary.
 </ul>
 
 
-`--arpk <FILE>`
+`-a`, `--arpk <FILE>`
 <ul>
 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.
@@ -233,10 +229,10 @@ otherwise your attestation is compromised. Delete this key after verification.
 
 `--format <FORMAT>`
 <ul>
-Define the output format
+Define the output format.
     Default value: 'yaml'
     Possible values:
-        - **yaml**: Use yaml format
+        - **yaml**: Use yaml format.
 </ul>
 
 
@@ -245,17 +241,112 @@ Define the output format
 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
-</ul>
-
-
-`-v`, `--verbose`
-<ul>
-Provide more detailed output
+verified. Emits a warning if the response contains no user-data.
 </ul>
 
 
 `-h`, `--help`
 <ul>
-Print help (see a summary with '-h')
+Print help (see a summary with '-h').
+</ul>
+
+
+## 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>`
+<ul>
+Specify the attestation response to check whether the policies are validated.
+</ul>
+
+
+`<OUT>`
+<ul>
+Specify the output file for the check result.
+</ul>
+
+
+### Options
+
+`--format <FORMAT>`
+<ul>
+Define the output format.
+    Default value: 'yaml'
+    Possible values:
+        - **yaml**: Use yaml format.
+</ul>
+
+
+`-k`, `--host-key-document <FILE>`
+<ul>
+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.
+</ul>
+
+
+`--host-key-check <HOST_KEY_CHECKS>`
+<ul>
+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.
+</ul>
+
+
+`-u`, `--user-data <FILE>`
+<ul>
+Check if the provided user data matches the data from the attestation response.
+</ul>
+
+
+`--secret <FILE>`
+<ul>
+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.
+</ul>
+
+
+`--secret-store-locked <BOOL>`
+<ul>
+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. If the attestation response does not contain a secret store
+hash, this check fails.
+
+Required if add-secret-requests are specified.
+</ul>
+
+
+`--firmware`
+<ul>
+Check whether the firmware is on an IBM supported version. Requires internet
+access.
+</ul>
+
+
+`--firmware-verify-url <URL>`
+<ul>
+Specify the endpoint to use for firmware version verification. Use an endpoint
+you trust. Requires the --firmware option.
+</ul>
+
+
+`-h`, `--help`
+<ul>
+Print help (see a summary with '-h').
 </ul>

rust/pvattest/man/pvattest-check.1

@@ -0,0 +1,123 @@
+.\" Copyright 2024 IBM Corp.
+.\" s390-tools is free software; you can redistribute it and/or modify
+.\" it under the terms of the MIT license. See LICENSE for details.
+.\"
+
+.TH pvattest-check 1 "2024-11-18" "s390-tools" "Attestation Manual"
+.nh
+.ad l
+.SH NAME
+\fBpvattest check\fP - Check if the attestation result matches defined policies
+\fB
+.SH SYNOPSIS
+.nf
+.fam C
+pvattest check [OPTIONS] <IN> <OUT>
+.fam C
+.fi
+.SH DESCRIPTION
+After the attestation verification, check whether the attestation result
+complies with user-defined policies.
+.SH OPTIONS
+.PP
+<IN>
+.RS 4
+Specify the attestation response to check whether the policies are validated.
+.RE
+.RE
+.PP
+<OUT>
+.RS 4
+Specify the output file for the check result.
+.RE
+.RE
+
+.PP
+\-\-format <FORMAT>
+.RS 4
+Define the output format.
+[default: 'yaml']
+
+Possible values:
+.RS 4
+- \fByaml\fP: Use yaml format.
+
+.RE
+.RE
+.PP
+\-k, \-\-host-key-document <FILE>
+.RS 4
+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.
+.RE
+.RE
+.PP
+\-\-host-key-check <HOST_KEY_CHECKS>
+.RS 4
+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:
+.RS 4
+- \fBatt-key-hash\fP: Check the host-key used for the attestation request.
+
+- \fBboot-key-hash\fP: Check the host-key used to the boot the image.
+
+.RE
+.RE
+.PP
+\-u, \-\-user-data <FILE>
+.RS 4
+Check if the provided user data matches the data from the attestation response.
+.RE
+.RE
+.PP
+\-\-secret <FILE>
+.RS 4
+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.
+.RE
+.RE
+.PP
+\-\-secret-store-locked <BOOL>
+.RS 4
+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. If the attestation response does not contain a secret store
+hash, this check fails.
+
+Required if add-secret-requests are specified.
+.RE
+.RE
+.PP
+\-\-firmware
+.RS 4
+Check whether the firmware is on an IBM supported version. Requires internet
+access.
+.RE
+.RE
+.PP
+\-\-firmware-verify-url <URL>
+.RS 4
+Specify the endpoint to use for firmware version verification. Use an endpoint
+you trust. Requires the \fB--firmware\fR option.
+.RE
+.RE
+.PP
+\-h, \-\-help
+.RS 4
+Print help (see a summary with '-h').
+.RE
+.RE
+
+.SH "SEE ALSO"
+.sp
+\fBpvattest\fR(1)

rust/pvattest/man/pvattest-create.1

@@ -3,7 +3,7 @@
 .\" it under the terms of the MIT license. See LICENSE for details.
 .\"
 
-.TH pvattest-create 1 "2024-05-15" "s390-tools" "Attestation Manual"
+.TH pvattest-create 1 "2024-11-18" "s390-tools" "Attestation Manual"
 .nh
 .ad l
 .SH NAME
@@ -40,7 +40,7 @@ the host-key document beforehand.
 .PP
 \-C, \-\-cert <FILE>
 .RS 4
-Use FILE as a certificate to verify the host key or keys. The certificates are
+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).
@@ -84,7 +84,7 @@ this key, otherwise your attestation is compromised.
 .PP
 \-\-add-data <FLAGS>
 .RS 4
-Specify-additional data for the request. Additional data is provided by the
+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.
 
@@ -94,12 +94,10 @@ Possible values:
 
 - \fBphkh-att\fP: Request the public host-key-hash of the key that decrypted the attestation request as additional-data.
 
-.RE
-.RE
-.PP
-\-v, \-\-verbose
-.RS 4
-Provide more detailed output.
+- \fBsecret-store-hash\fP: Request a hash over all successful Add-secret requests and the lock state as additional-data.
+
+- \fBfirmware-state\fP: Request the state of the firmware as additional-data.
+
 .RE
 .RE
 .PP

rust/pvattest/man/pvattest-perform.1

@@ -3,7 +3,7 @@
 .\" it under the terms of the MIT license. See LICENSE for details.
 .\"
 
-.TH pvattest-perform 1 "2024-05-15" "s390-tools" "Attestation Manual"
+.TH pvattest-perform 1 "2024-11-18" "s390-tools" "Attestation Manual"
 .nh
 .ad l
 .SH NAME
@@ -12,7 +12,7 @@
 .SH SYNOPSIS
 .nf
 .fam C
-pvattest perform [OPTIONS] [INPUT] [OUTPUT]
+pvattest perform [OPTIONS] [IN] [OUT]
 .fam C
 .fi
 .SH DESCRIPTION
@@ -22,13 +22,13 @@ must be an attestation request created with ’pvattest create’. Output will
 contain the original request and the response from the Ultravisor.
 .SH OPTIONS
 .PP
-<INPUT>
+<IN>
 .RS 4
 Specify the request to be sent.
 .RE
 .RE
 .PP
-<OUTPUT>
+<OUT>
 .RS 4
 Write the result to FILE.
 .RE
@@ -44,12 +44,6 @@ equal to 256 bytes
 .RE
 .RE
 .PP
-\-v, \-\-verbose
-.RS 4
-Provide more detailed output.
-.RE
-.RE
-.PP
 \-h, \-\-help
 .RS 4
 Print help (see a summary with '-h').

rust/pvattest/man/pvattest-verify.1

@@ -3,7 +3,7 @@
 .\" it under the terms of the MIT license. See LICENSE for details.
 .\"
 
-.TH pvattest-verify 1 "2024-05-15" "s390-tools" "Attestation Manual"
+.TH pvattest-verify 1 "2024-11-18" "s390-tools" "Attestation Manual"
 .nh
 .ad l
 .SH NAME
@@ -27,7 +27,7 @@ the image that was attested during ’pvattest perform’
 .PP
 \-i, \-\-input <FILE>
 .RS 4
-Specify the attestation request to be verified.
+Specify the attestation response to be verified.
 .RE
 .RE
 .PP
@@ -69,13 +69,7 @@ Possible values:
 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
-.RE
-.RE
-.PP
-\-v, \-\-verbose
-.RS 4
-Provide more detailed output.
+verified. Emits a warning if the response contains no user-data.
 .RE
 .RE
 .PP

rust/pvattest/man/pvattest.1

@@ -3,7 +3,7 @@
 .\" it under the terms of the MIT license. See LICENSE for details.
 .\"
 
-.TH pvattest 1 "2024-05-15" "s390-tools" "Attestation Manual"
+.TH pvattest 1 "2024-11-18" "s390-tools" "Attestation Manual"
 .nh
 .ad l
 .SH NAME
@@ -42,9 +42,9 @@ Verify an attestation response
 
 .PP
 
-\fBversion\fR
+\fBcheck\fR
 .RS 4
-Print version information and exit
+Check if the attestation result matches defined policies
 .RE
 
 .SH OPTIONS
@@ -55,6 +55,12 @@ Provide more detailed output.
 .RE
 .RE
 .PP
+\-q, \-\-quiet
+.RS 4
+Provide less output.
+.RE
+.RE
+.PP
 \-\-version
 .RS 4
 Print version information and exit.
@@ -111,4 +117,4 @@ If the measurements do not match \fBpvattest\fP exits with code 2 and emits an e
 .fi
 .SH "SEE ALSO"
 .sp
-\fBpvattest-create\fR(1) \fBpvattest-perform\fR(1) \fBpvattest-verify\fR(1)
+\fBpvattest-create\fR(1) \fBpvattest-perform\fR(1) \fBpvattest-verify\fR(1) \fBpvattest-check\fR(1)