kata-containers/s390-tools
1
0
Fork 0
mirror of https://github.com/ibm-s390-linux/s390-tools.git synced 2026-08-05 02:14:52 +00:00
Code Issues Packages Projects Releases Wiki Activity

pvattest: Fix various man page issues

Browse Source 
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:<standard input>: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 <seiden@linux.ibm.com>
Signed-off-by: Jan Höppner <hoeppner@linux.ibm.com>
This commit is contained in:
Jan Höppner
2025-03-12 15:54:43 +01:00
parent 4fe6025b18
commit c93b74b527
5 changed files with 70 additions and 75 deletions
Download Patch File Download Diff File Expand all files Collapse all files

51
rust/pvattest/man/pvattest-check.1
View File

@@ -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] <IN> <OUT>
.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
<IN>
@@ -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 <FILE>
\-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.
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>
\-\-host\-key\-check <HOST_KEY_CHECKS>
.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 <FILE>
\-u, \-\-user\-data <FILE>
.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 <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
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 <BOOL>
\-\-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 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 <URL>
\-\-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.
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

45
rust/pvattest/man/pvattest-create.1
View File

@@ -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 <FILE>
\-k, \-\-host\-key\-document <FILE>
.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 <FILE>
.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>
\-\-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 <FILE>
.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 <FLAGS>
\-\-add\-data <FLAGS>
.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

13
rust/pvattest/man/pvattest-perform.1
View File

@@ -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 <File>
\-u, \-\-user\-data <File>
.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

19
rust/pvattest/man/pvattest-verify.1
View File

@@ -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 <FILE>
\-u, \-\-user\-data <FILE>
.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

17
rust/pvattest/man/pvattest.1
View File

@@ -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