From c93b74b527ebb7762eb6841e8e70a9dc9e718bda Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20H=C3=B6ppner?= Date: Wed, 12 Mar 2025 15:54:43 +0100 Subject: [PATCH] pvattest: Fix various man page issues MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The pvattest man pages are generated mostly from the rust doc entries within the tool. Some escape sequences and whatis-entries are incorrect as found by different linter: $ man --warnings -E UTF-8 -l -Tutf8 -Z ./rust/pvattest/man/pvattest-create.1 troff::23: warning: macro 'create'' not defined $ lexgrog -w -m rust/pvattest/man/pvattest-verify.1 rust/pvattest/man/pvattest-verify.1: parse failed Fix this by regenerating the man pages with correct escape sequences and whatis-entries. Github-ID: https://github.com/ibm-s390-linux/s390-tools/issues/170 Reviewed-by: Steffen Eiden Signed-off-by: Jan Höppner --- rust/pvattest/man/pvattest-check.1 | 51 ++++++++++++++-------------- rust/pvattest/man/pvattest-create.1 | 45 ++++++++++++------------ rust/pvattest/man/pvattest-perform.1 | 13 ++++--- rust/pvattest/man/pvattest-verify.1 | 19 +++++------ rust/pvattest/man/pvattest.1 | 17 +++++----- 5 files changed, 70 insertions(+), 75 deletions(-) diff --git a/rust/pvattest/man/pvattest-check.1 b/rust/pvattest/man/pvattest-check.1 index f933cc26..5a6d828f 100644 --- a/rust/pvattest/man/pvattest-check.1 +++ b/rust/pvattest/man/pvattest-check.1 @@ -1,14 +1,13 @@ -.\" Copyright 2024 IBM Corp. +.\" Copyright 2024, 2025 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-12-05" "s390-tools" "Attestation Manual" +.TH "PVATTEST-CHECK" "1" "2025-03-12" "s390-tools" "Attestation Manual" .nh .ad l .SH NAME -\fBpvattest check\fP - Check if the attestation result matches defined policies -\fB +pvattest-check \- Check if the attestation result matches defined policies .SH SYNOPSIS .nf .fam C @@ -17,7 +16,7 @@ pvattest check [OPTIONS] .fi .SH DESCRIPTION After the attestation verification, check whether the attestation result -complies with user-defined policies. +complies with user\-defined policies. .SH OPTIONS .PP @@ -40,37 +39,37 @@ Define the output format. Possible values: .RS 4 -- \fByaml\fP: Use yaml format. +\- \fByaml\fP: Use yaml format. .RE .RE .PP -\-k, \-\-host-key-document +\-k, \-\-host\-key\-document .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. +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\-check .RS 4 -Define the host-key check policy By default, all host-key hashes are checked, +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. +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. +\- \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. +\- \fBboot-key-hash\fP: Check the host-key used to the boot the image. .RE .RE .PP -\-u, \-\-user-data +\-u, \-\-user\-data .RS 4 Check if the provided user data matches the data from the attestation response. .RE @@ -78,23 +77,23 @@ Check if the provided user data matches the data from the attestation response. .PP \-\-secret .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 +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 +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 +\-\-secret\-store\-locked .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 in the correct order. If the attestation response does not +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. +Required if add\-secret\-requests are specified. .RE .RE .PP @@ -104,16 +103,16 @@ Check whether the firmware is supported by IBM. Requires internet access. .RE .RE .PP -\-\-firmware-verify-url +\-\-firmware\-verify\-url .RS 4 Specify the endpoint to use for firmware version verification. Use an endpoint -you trust. Requires the \fB--firmware\fR option. +you trust. Requires the \-\-firmware option. .RE .RE .PP \-h, \-\-help .RS 4 -Print help (see a summary with '-h'). +Print help (see a summary with \fB\-h\fR). .RE .RE diff --git a/rust/pvattest/man/pvattest-create.1 b/rust/pvattest/man/pvattest-create.1 index 083a572d..55ae2efa 100644 --- a/rust/pvattest/man/pvattest-create.1 +++ b/rust/pvattest/man/pvattest-create.1 @@ -1,14 +1,13 @@ -.\" Copyright 2024 IBM Corp. +.\" Copyright 2024, 2025 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-create 1 "2024-12-05" "s390-tools" "Attestation Manual" +.TH "PVATTEST-CREATE" "1" "2025-03-12" "s390-tools" "Attestation Manual" .nh .ad l .SH NAME -\fBpvattest create\fP - Create an attestation measurement request -\fB +pvattest-create \- Create an attestation measurement request .SH SYNOPSIS .nf .fam C @@ -20,28 +19,28 @@ 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. +\fBcreate\fR will generate a new, random protection key. .SH OPTIONS .PP -\-k, \-\-host-key-document +\-k, \-\-host\-key\-document .RS 4 -Use FILE as a host-key document. Can be specified multiple times and must be +Use FILE as a host\-key document. Can be specified multiple times and must be specified at least once. .RE .RE .PP -\-\-no-verify +\-\-no\-verify .RS 4 -Disable the host-key document verification. Does not require the host-key +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. +the host\-key document beforehand. .RE .RE .PP \-C, \-\-cert .RS 4 -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 +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). .RE @@ -61,11 +60,11 @@ Make no attempt to download CRLs. .RE .RE .PP -\-\-root-ca +\-\-root\-ca .RS 4 -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. +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. .RE .RE .PP @@ -77,12 +76,12 @@ Write the generated request to FILE. .PP \-a, \-\-arpk .RS 4 -Save the protection key as unencrypted GCM-AES256 key in FILE Do not publish +Save the protection key as unencrypted GCM\-AES256 key in FILE Do not publish this key, otherwise your attestation is compromised. .RE .RE .PP -\-\-add-data +\-\-add\-data .RS 4 Specify additional data for the request. Additional data is provided by the Ultravisor and returned during the attestation request and is covered by the @@ -90,20 +89,20 @@ attestation measurement. Can be specified multiple times. Optional. Possible values: .RS 4 -- \fBphkh-img\fP: Request the public host-key-hash of the key that decrypted the SE-image as additional-data. +\- \fBphkh-img\fP: Request the public host-key-hash of the key that decrypted the SE-image as additional-data. -- \fBphkh-att\fP: Request the public host-key-hash of the key that decrypted the attestation request as additional-data. +\- \fBphkh-att\fP: Request the public host-key-hash of the key that decrypted the attestation request as additional-data. -- \fBsecret-store-hash\fP: Request a hash over all successful Add-secret requests and the lock state as additional-data. +\- \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. +\- \fBfirmware-state\fP: Request the state of the firmware as additional-data. .RE .RE .PP \-h, \-\-help .RS 4 -Print help (see a summary with '-h'). +Print help (see a summary with \fB\-h\fR). .RE .RE diff --git a/rust/pvattest/man/pvattest-perform.1 b/rust/pvattest/man/pvattest-perform.1 index 1c60008b..e053dde5 100644 --- a/rust/pvattest/man/pvattest-perform.1 +++ b/rust/pvattest/man/pvattest-perform.1 @@ -1,14 +1,13 @@ -.\" Copyright 2024 IBM Corp. +.\" Copyright 2024, 2025 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-perform 1 "2024-11-18" "s390-tools" "Attestation Manual" +.TH "PVATTEST-PERFORM" "1" "2025-03-12" "s390-tools" "Attestation Manual" .nh .ad l .SH NAME -\fBpvattest perform\fP - Send the attestation request to the Ultravisor -\fB +pvattest-perform \- Send the attestation request to the Ultravisor .SH SYNOPSIS .nf .fam C @@ -35,9 +34,9 @@ Write the result to FILE. .RE .PP -\-u, \-\-user-data +\-u, \-\-user\-data .RS 4 -Provide up to 256 bytes of user input User-data is arbitrary user-defined data +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 @@ -46,7 +45,7 @@ equal to 256 bytes .PP \-h, \-\-help .RS 4 -Print help (see a summary with '-h'). +Print help (see a summary with \fB\-h\fR). .RE .RE diff --git a/rust/pvattest/man/pvattest-verify.1 b/rust/pvattest/man/pvattest-verify.1 index 7520a508..2bf8c56e 100644 --- a/rust/pvattest/man/pvattest-verify.1 +++ b/rust/pvattest/man/pvattest-verify.1 @@ -1,14 +1,13 @@ -.\" Copyright 2024 IBM Corp. +.\" Copyright 2024, 2025 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-verify 1 "2024-12-05" "s390-tools" "Attestation Manual" +.TH "PVATTEST-VERIFY" "1" "2025-03-12" "s390-tools" "Attestation Manual" .nh .ad l .SH NAME -\fBpvattest verify\fP - Verify an attestation response -\fB +pvattest-verify \- Verify an attestation response .SH SYNOPSIS .nf .fam C @@ -62,23 +61,23 @@ Define the output format. Possible values: .RS 4 -- \fByaml\fP: Use yaml format. +\- \fByaml\fP: Use yaml format. .RE .RE .PP -\-u, \-\-user-data +\-u, \-\-user\-data .RS 4 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. +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 \-h, \-\-help .RS 4 -Print help (see a summary with '-h'). +Print help (see a summary with \fB\-h\fR). .RE .RE diff --git a/rust/pvattest/man/pvattest.1 b/rust/pvattest/man/pvattest.1 index b1808458..26a6a823 100644 --- a/rust/pvattest/man/pvattest.1 +++ b/rust/pvattest/man/pvattest.1 @@ -1,14 +1,13 @@ -.\" Copyright 2024 IBM Corp. +.\" Copyright 2024, 2025 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 1 "2024-11-18" "s390-tools" "Attestation Manual" +.TH "PVATTEST" "1" "2025-03-12" "s390-tools" "Attestation Manual" .nh .ad l .SH NAME -\fBpvattest\fP - create, perform, and verify attestation measurements -\fB +pvattest \- create, perform, and verify attestation measurements .SH SYNOPSIS .nf .fam C @@ -21,28 +20,28 @@ guest systems. .SH "PVATTEST COMMANDS" .PP -\fBcreate\fR +\fBpvattest-create(1)\fR .RS 4 Create an attestation measurement request .RE .PP -\fBperform\fR +\fBpvattest-perform(1)\fR .RS 4 Send the attestation request to the Ultravisor .RE .PP -\fBverify\fR +\fBpvattest-verify(1)\fR .RS 4 Verify an attestation response .RE .PP -\fBcheck\fR +\fBpvattest-check(1)\fR .RS 4 Check if the attestation result matches defined policies .RE @@ -69,7 +68,7 @@ Print version information and exit. .PP \-h, \-\-help .RS 4 -Print help (see a summary with '-h'). +Print help (see a summary with \fB\-h\fR). .RE .RE