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

pvsecret: Update man and Readme

Browse Source 
man and README got out of sync with --help over time.
Resync them.

Reviewed-by: Jan Höppner <hoeppner@linux.ibm.com>
Signed-off-by: Steffen Eiden <seiden@linux.ibm.com>
Signed-off-by: Jan Höppner <hoeppner@linux.ibm.com>
This commit is contained in:
Steffen Eiden
2026-05-05 12:57:06 +02:00
committed by Jan Höppner
parent 080a6678fb
commit 03b73ab3f9
9 changed files with 163 additions and 52 deletions
Download Patch File Download Diff File Expand all files Collapse all files

77
rust/pvsecret/README.md
View File

@@ -253,6 +253,28 @@ Optional. No user-data by default.
</ul>
`--policy <FILE>`
<ul>
Links an Add‑Secret-Request (ASR) to a policy file. This option embeds a
PolicyReference in the ASR user data field. The PolicyReference includes the
relative file path and the SHA‑512 hash of the policy file, allowing the
policy’s integrity to be verified.
This option conflicts with --user-data, because both options use the same user
data field in the ASR structure.
</ul>
`--toc-policy <FILE>`
<ul>
Adds the AES‑GCM authentication tag to a TOC policy file. This option appends
the AES‑GCM authentication tag to the specified TOC policy file. This allows
the TOC policy to maintain a list of all ASR MAC tags for completeness
verification during boot. During verification, the TOC checks the MAC tags
against this list to ensure that all expected ASRs are present and unmodified.
</ul>
`--user-sign-key <FILE>`
<ul>
Use the content of FILE as user signing key. Adds a signature calculated from
@@ -407,7 +429,7 @@ Print help (see a summary with '-h').
## pvsecret add
### Synopsis
`pvsecret add [OPTIONS] <FILE>`
`pvsecret add [OPTIONS] [FILE]`
### Description
Submit an add-secret request to the Ultravisor (s390x only). Perform an
add-secret request using a previously generated add-secret request. Only
@@ -422,6 +444,12 @@ Specify the request to be sent.
### Options
`-i`, `--input <FILE>`
<ul>
Specify the request to be sent.
</ul>
`-f`, `--force`
<ul>
Force the addition of add-secret requests. Add an add-secret request even if
@@ -461,6 +489,12 @@ Store the result in FILE.
### Options
`-o`, `--output <FILE>`
<ul>
Store the result in FILE.
</ul>
`--format <FORMAT>`
<ul>
Define the output format of the list.
@@ -480,7 +514,7 @@ Print help (see a summary with '-h').
## pvsecret verify
### Synopsis
`pvsecret verify [OPTIONS] <FILE>`
`pvsecret verify [OPTIONS] [FILE] [FILE]`
### Description
Verifies that the given request is an Add-Secret request by testing for some
values to be present. If the request contains signed user-data, the signature
@@ -526,8 +560,22 @@ Specify the request to be checked.
</ul>
`<FILE>`
<ul>
Store the result in FILE If the request contained abirtary user-data the output
contains this user-data with padded zeros if available.
Default value: '-'
</ul>
### Options
`-i`, `--input <FILE>`
<ul>
Specify the request to be checked.
</ul>
`--user-cert <FILE>`
<ul>
Certificate containing a public key used to verify the user data signature.
@@ -544,7 +592,6 @@ curve over a 521 bit prime field (secp521r1).
<ul>
Store the result in FILE If the request contained abirtary user-data the output
contains this user-data with padded zeros if available.
Default value: '-'
</ul>
@@ -556,8 +603,8 @@ Print help (see a summary with '-h').
## pvsecret retrieve
### Synopsis
`pvsecret retrieve [OPTIONS] <ID>`
`pvsecret retr [OPTIONS] <ID>`
`pvsecret retrieve [OPTIONS] [ID] [FILE]`
`pvsecret retr [OPTIONS] [ID] [FILE]`
### Description
Retrieve a secret from the UV secret store (s390x only)
### Arguments
@@ -574,12 +621,30 @@ retrieved.
</ul>
`<FILE>`
<ul>
Specify the output path to place the secret value.
Default value: '-'
</ul>
### Options
`-i`, `--input <FILE>`
<ul>
Specify the secret ID to be retrieved. Input type depends on '--inform'. If
`yaml` (default) is specified, it must be a yaml created by the create
subcommand of this tool. If `hex` is specified, it must be a 32 byte handle
encodes in hexadecimal. Leading zeros are required. If there are multiple
secrets in the store with the same Id there are no guarantees on which specific
secret is retrieved. Use --inform=idx to make sure a specific secret is
retrieved.
</ul>
`-o`, `--output <FILE>`
<ul>
Specify the output path to place the secret value.
Default value: '-'
</ul>

10
rust/pvsecret/man/pvsecret-add.1
View File

@@ -3,7 +3,7 @@
.\" it under the terms of the MIT license. See LICENSE for details.
.\"
.TH "PVSECRET-ADD" "1" "2026-02-12" "s390-tools" "UV\-Secret Manual"
.TH "PVSECRET-ADD" "1" "2026-05-19" "s390-tools" "UV\-Secret Manual"
.nh
.ad l
.SH NAME
@@ -11,7 +11,7 @@ pvsecret-add \- Submit an add-secret request to the Ultravisor (s390x only)
.SH SYNOPSIS
.nf
.fam C
pvsecret add [OPTIONS] <FILE>
pvsecret add [OPTIONS] [FILE]
.fam C
.fi
.SH DESCRIPTION
@@ -25,6 +25,12 @@ Specify the request to be sent.
.RE
.RE
.PP
\-i, \-\-input <FILE>
.RS 4
Specify the request to be sent.
.RE
.RE
.PP
\-f, \-\-force
.RS 4

42
rust/pvsecret/man/pvsecret-create-retrievable.1
View File

@@ -3,7 +3,7 @@
.\" it under the terms of the MIT license. See LICENSE for details.
.\"
.TH "PVSECRET-CREATE-RETRIEVABLE" "1" "2026-02-12" "s390-tools" "UV\-Secret Manual"
.TH "PVSECRET-CREATE-RETRIEVABLE" "1" "2026-05-20" "s390-tools" "UV\-Secret Manual"
.nh
.ad l
.SH NAME
@@ -29,30 +29,30 @@ the following curves: secp256r1, secp384r1, secp521r1, ed25519, or ed448.
\fBHMAC\-SHA preprocessing\fP
.RS 2
The \fBHMAC\-SHA\fP key supplied in the plain bytes file is the key \fBK_0\fP
as of \fBFIPS\-198\-1\fP, i.e. the key \fBK\fP after any necessary
pre\-processing. The pre\-processing must be performed by the user prior to
creating the retrievable secret.
.PP Pre\-processing means that if the key \fBK\fP is shorter than the block
size of the to\-be\-used HMAC digest, then the key must be padded with binary
zeros to the right up to the block size. The block size of SHA\-224 and
SHA\-256 is 512 bits (64 bytes) and the bock size of SHA\-384 and SHA\-512 is
1024 bits (128 bytes). Such padding can for example be achieved by using the
\fBtruncate\fP command with the desired size in bytes, e.g. \fB'truncate
\-\-size 64 <key\-file>'\fP for creating a \fBK_0\fP key for HMAC\-SHA\-224
and HMAC\-SHA\-256.
The \fBHMAC\-SHA\fP key supplied in the plain bytes file is the key \fBK_0\fP as
of \fBFIPS\-198\-1\fP, i.e. the key \fBK\fP after any necessary pre\-processing.
The pre\-processing must be performed by the user prior to creating the
retrievable secret.
.PP Pre\-processing means that if the key \fBK\fP is shorter than the block size
of the to\-be\-used HMAC digest, then the key must be padded with binary zeros
to the right up to the block size. The block size of SHA\-224 and SHA\-256 is
512 bits (64 bytes) and the bock size of SHA\-384 and SHA\-512 is 1024 bits (128
bytes). Such padding can for example be achieved by using the \fBtruncate\fP
command with the desired size in bytes, e.g. \fB'truncate \-\-size 64
<key\-file>'\fP for creating a \fBK_0\fP key for HMAC\-SHA\-224 and
HMAC\-SHA\-256.
.PP
In case key \fBK\fP is longer than the block size of the to\-be\-used HMAC
digest, then key \fBK\fP must first be hashed with the to\-be\-used HMAC
digest, and the result must then be padded with binary zeros to the right up to
the block size of the digest. This can be achieved by using the following
OpenSSL command followed by the \fBtruncate\fP command: \fB'openssl sha256
\-binary \-out <key2\-file> <key\-file>'\fP and then \fB'truncate \-\-size
64 <key2\-file>'\fP for creating a \fBK_0\fP key for HMAC\-SHA\-256.
digest, then key \fBK\fP must first be hashed with the to\-be\-used HMAC digest,
and the result must then be padded with binary zeros to the right up to the
block size of the digest. This can be achieved by using the following OpenSSL
command followed by the \fBtruncate\fP command: \fB'openssl sha256 \-binary
\-out <key2\-file> <key\-file>'\fP and then \fB'truncate \-\-size 64
<key2\-file>'\fP for creating a \fBK_0\fP key for HMAC\-SHA\-256.
.PP
\fBATTENTION:\fP The digest used for hashing the key \fBK\fP must be the exact
same as the later to\-be\-used HMAC digest! If the pre\-processing and the
HMAC calculation use different digests, then a wrong MAC is calculated!
same as the later to\-be\-used HMAC digest! If the pre\-processing and the HMAC
calculation use different digests, then a wrong MAC is calculated!
.RE
.SH OPTIONS

3
rust/pvsecret/man/pvsecret-create-update-cck.1
View File

@@ -3,7 +3,7 @@
.\" it under the terms of the MIT license. See LICENSE for details.
.\"
.TH "PVSECRET-CREATE-UPDATE-CCK" "1" "2026-02-12" "s390-tools" "UV\-Secret Manual"
.TH "PVSECRET-CREATE-UPDATE-CCK" "1" "2026-05-20" "s390-tools" "UV\-Secret Manual"
.nh
.ad l
.SH NAME
@@ -18,6 +18,7 @@ pvsecret create cck \-\-secret <CCK\-FILE>
.SH DESCRIPTION
Insert a customer communication key into a guest.
.SH OPTIONS
.PP
\-\-secret <CCK\-FILE>
.RS 4

27
rust/pvsecret/man/pvsecret-create.1
View File

@@ -3,7 +3,7 @@
.\" it under the terms of the MIT license. See LICENSE for details.
.\"
.TH "PVSECRET-CREATE" "1" "2026-02-12" "s390-tools" "UV\-Secret Manual"
.TH "PVSECRET-CREATE" "1" "2026-05-19" "s390-tools" "UV\-Secret Manual"
.nh
.ad l
.SH NAME
@@ -55,6 +55,7 @@ Update customer communication key
.RE
.SH OPTIONS
.PP
\-k, \-\-host\-key\-document <FILE>
.RS 4
@@ -196,23 +197,23 @@ Optional. No user\-data by default.
.PP
\-\-policy <FILE>
.RS 4
Links an add\-secret request to a policy file.
This option embeds a reference to a policy in the add\-secret request user data field. The
reference includes the relative file path and the SHA-512 hash of the
policy file, enabling verification of the policy file’s integrity.
This option conflicts with \fB\-\-user\-data\fR, because both options use the
same user data field in the add\-secret request structure.
Links an Add‑Secret\-Request (ASR) to a policy file. This option embeds a
PolicyReference in the ASR user data field. The PolicyReference includes the
relative file path and the SHA‑512 hash of the policy file, allowing the
policy’s integrity to be verified.
This option conflicts with \-\-user\-data, because both options use the same
user data field in the ASR structure.
.RE
.RE
.PP
\-\-toc\-policy <FILE>
.RS 4
Adds the AES\-GCM authentication tag to a table-of-contents (TOC) policy file.
This option appends the AES\-GCM authentication tag to the specified TOC policy
file. This allows the TOC policy to maintain a list of all add\-secret request MAC tags for
completeness verification during boot. During verification, the TOC checks the
AES\-GCM tags against this list to ensure that all expected add\-secret request are present and
unmodified.
Adds the AES‑GCM authentication tag to a TOC policy file. This option appends
the AES‑GCM authentication tag to the specified TOC policy file. This allows
the TOC policy to maintain a list of all ASR MAC tags for completeness
verification during boot. During verification, the TOC checks the MAC tags
against this list to ensure that all expected ASRs are present and unmodified.
.RE
.RE
.PP

8
rust/pvsecret/man/pvsecret-list.1
View File

@@ -3,7 +3,7 @@
.\" it under the terms of the MIT license. See LICENSE for details.
.\"
.TH "PVSECRET-LIST" "1" "2024-12-19" "s390-tools" "UV-Secret Manual"
.TH "PVSECRET-LIST" "1" "2026-05-19" "s390-tools" "UV\-Secret Manual"
.nh
.ad l
.SH NAME
@@ -26,6 +26,12 @@ Store the result in FILE.
.RE
.RE
.PP
\-o, \-\-output <FILE>
.RS 4
Store the result in FILE.
.RE
.RE
.PP
\-\-format <FORMAT>
.RS 4

26
rust/pvsecret/man/pvsecret-retrieve.1
View File

@@ -3,7 +3,7 @@
.\" it under the terms of the MIT license. See LICENSE for details.
.\"
.TH "PVSECRET-RETRIEVE" "1" "2026-02-12" "s390-tools" "UV\-Secret Manual"
.TH "PVSECRET-RETRIEVE" "1" "2026-05-20" "s390-tools" "UV\-Secret Manual"
.nh
.ad l
.SH NAME
@@ -11,8 +11,8 @@ pvsecret-retrieve \- Retrieve a secret from the UV secret store (s390x only)
.SH SYNOPSIS
.nf
.fam C
pvsecret retrieve [OPTIONS] <ID>
pvsecret retr [OPTIONS] <ID>
pvsecret retrieve [OPTIONS] [ID] [FILE]
pvsecret retr [OPTIONS] [ID] [FILE]
.fam C
.fi
.SH DESCRIPTION
@@ -35,12 +35,30 @@ secret is retrieved. Use \-\-inform=idx to make sure a specific secret is
retrieved.
.RE
.RE
.PP
<FILE>
.RS 4
Specify the output path to place the secret value.
[default: '-']
.RE
.RE
.PP
\-i, \-\-input <FILE>
.RS 4
Specify the secret ID to be retrieved. Input type depends on \fB\-\-inform\fR.
If `yaml` (default) is specified, it must be a yaml created by the create
subcommand of this tool. If `hex` is specified, it must be a 32 byte handle
encodes in hexadecimal. Leading zeros are required. If there are multiple
secrets in the store with the same Id there are no guarantees on which specific
secret is retrieved. Use \-\-inform=idx to make sure a specific secret is
retrieved.
.RE
.RE
.PP
\-o, \-\-output <FILE>
.RS 4
Specify the output path to place the secret value.
[default: '-']
.RE
.RE
.PP

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

@@ -3,7 +3,7 @@
.\" it under the terms of the MIT license. See LICENSE for details.
.\"
.TH "PVSECRET-VERIFY" "1" "2026-02-12" "s390-tools" "UV\-Secret Manual"
.TH "PVSECRET-VERIFY" "1" "2026-05-19" "s390-tools" "UV\-Secret Manual"
.nh
.ad l
.SH NAME
@@ -11,7 +11,7 @@ pvsecret-verify \- Verify that an add-secret request is sane
.SH SYNOPSIS
.nf
.fam C
pvsecret verify [OPTIONS] <FILE>
pvsecret verify [OPTIONS] [FILE] [FILE]
.fam C
.fi
.SH DESCRIPTION
@@ -86,7 +86,21 @@ verify the signature of the request but the last 16 bytes
Specify the request to be checked.
.RE
.RE
.PP
<FILE>
.RS 4
Store the result in FILE If the request contained abirtary user\-data the output
contains this user\-data with padded zeros if available.
[default: '-']
.RE
.RE
.PP
\-i, \-\-input <FILE>
.RS 4
Specify the request to be checked.
.RE
.RE
.PP
\-\-user\-cert <FILE>
.RS 4
@@ -104,7 +118,6 @@ curve over a 521 bit prime field (secp521r1).
.RS 4
Store the result in FILE If the request contained abirtary user\-data the output
contains this user\-data with padded zeros if available.
[default: '-']
.RE
.RE
.PP

3
rust/pvsecret/man/pvsecret.1
View File

@@ -3,7 +3,7 @@
.\" it under the terms of the MIT license. See LICENSE for details.
.\"
.TH "PVSECRET" "1" "2026-02-12" "s390-tools" "UV\-Secret Manual"
.TH "PVSECRET" "1" "2026-05-20" "s390-tools" "UV\-Secret Manual"
.nh
.ad l
.SH NAME
@@ -76,6 +76,7 @@ Retrieve a secret from the UV secret store (s390x only)
.RE
.SH OPTIONS
.PP
\-v, \-\-verbose
.RS 4