From 03b73ab3f909f339a3464733f550722aa258e6b0 Mon Sep 17 00:00:00 2001 From: Steffen Eiden Date: Tue, 5 May 2026 12:57:06 +0200 Subject: [PATCH] pvsecret: Update man and Readme MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit man and README got out of sync with --help over time. Resync them. Reviewed-by: Jan Höppner Signed-off-by: Steffen Eiden Signed-off-by: Jan Höppner --- rust/pvsecret/README.md | 77 +++++++++++++++++-- rust/pvsecret/man/pvsecret-add.1 | 10 ++- .../man/pvsecret-create-retrievable.1 | 42 +++++----- .../pvsecret/man/pvsecret-create-update-cck.1 | 3 +- rust/pvsecret/man/pvsecret-create.1 | 27 +++---- rust/pvsecret/man/pvsecret-list.1 | 8 +- rust/pvsecret/man/pvsecret-retrieve.1 | 26 ++++++- rust/pvsecret/man/pvsecret-verify.1 | 19 ++++- rust/pvsecret/man/pvsecret.1 | 3 +- 9 files changed, 163 insertions(+), 52 deletions(-) diff --git a/rust/pvsecret/README.md b/rust/pvsecret/README.md index c7e9b007..4037295a 100644 --- a/rust/pvsecret/README.md +++ b/rust/pvsecret/README.md @@ -253,6 +253,28 @@ Optional. No user-data by default. +`--policy ` +
    +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. +
+ + +`--toc-policy ` +
    +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. +
+ + `--user-sign-key `
    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] ` +`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 ` +
      +Specify the request to be sent. +
    + + `-f`, `--force`
      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 ` +
        +Store the result in FILE. +
      + + `--format `
        Define the output format of the list. @@ -480,7 +514,7 @@ Print help (see a summary with '-h'). ## pvsecret verify ### Synopsis -`pvsecret verify [OPTIONS] ` +`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.
      +`` +
        +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: '-' +
      + + ### Options +`-i`, `--input ` +
        +Specify the request to be checked. +
      + + `--user-cert `
        Certificate containing a public key used to verify the user data signature. @@ -544,7 +592,6 @@ curve over a 521 bit prime field (secp521r1).
          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: '-'
        @@ -556,8 +603,8 @@ Print help (see a summary with '-h'). ## pvsecret retrieve ### Synopsis -`pvsecret retrieve [OPTIONS] ` -`pvsecret retr [OPTIONS] ` +`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.
      +`` +
        +Specify the output path to place the secret value. + Default value: '-' +
      + + ### Options +`-i`, `--input ` +
        +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. +
      + + `-o`, `--output `
        Specify the output path to place the secret value. - Default value: '-'
      diff --git a/rust/pvsecret/man/pvsecret-add.1 b/rust/pvsecret/man/pvsecret-add.1 index 57a6e278..87d7fe7a 100644 --- a/rust/pvsecret/man/pvsecret-add.1 +++ b/rust/pvsecret/man/pvsecret-add.1 @@ -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] +pvsecret add [OPTIONS] [FILE] .fam C .fi .SH DESCRIPTION @@ -25,6 +25,12 @@ Specify the request to be sent. .RE .RE +.PP +\-i, \-\-input +.RS 4 +Specify the request to be sent. +.RE +.RE .PP \-f, \-\-force .RS 4 diff --git a/rust/pvsecret/man/pvsecret-create-retrievable.1 b/rust/pvsecret/man/pvsecret-create-retrievable.1 index f37abc46..9bad0e25 100644 --- a/rust/pvsecret/man/pvsecret-create-retrievable.1 +++ b/rust/pvsecret/man/pvsecret-create-retrievable.1 @@ -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 '\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 +'\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 '\fP and then \fB'truncate \-\-size -64 '\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 '\fP and then \fB'truncate \-\-size 64 +'\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 diff --git a/rust/pvsecret/man/pvsecret-create-update-cck.1 b/rust/pvsecret/man/pvsecret-create-update-cck.1 index 33730af2..316c0cf0 100644 --- a/rust/pvsecret/man/pvsecret-create-update-cck.1 +++ b/rust/pvsecret/man/pvsecret-create-update-cck.1 @@ -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 .SH DESCRIPTION Insert a customer communication key into a guest. .SH OPTIONS + .PP \-\-secret .RS 4 diff --git a/rust/pvsecret/man/pvsecret-create.1 b/rust/pvsecret/man/pvsecret-create.1 index aa137519..14ba2db9 100644 --- a/rust/pvsecret/man/pvsecret-create.1 +++ b/rust/pvsecret/man/pvsecret-create.1 @@ -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 .RS 4 @@ -196,23 +197,23 @@ Optional. No user\-data by default. .PP \-\-policy .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 .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 diff --git a/rust/pvsecret/man/pvsecret-list.1 b/rust/pvsecret/man/pvsecret-list.1 index 4dfc3033..5b8ed8d6 100644 --- a/rust/pvsecret/man/pvsecret-list.1 +++ b/rust/pvsecret/man/pvsecret-list.1 @@ -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 +.RS 4 +Store the result in FILE. +.RE +.RE .PP \-\-format .RS 4 diff --git a/rust/pvsecret/man/pvsecret-retrieve.1 b/rust/pvsecret/man/pvsecret-retrieve.1 index 63fd7caf..ee2d6c4b 100644 --- a/rust/pvsecret/man/pvsecret-retrieve.1 +++ b/rust/pvsecret/man/pvsecret-retrieve.1 @@ -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] -pvsecret retr [OPTIONS] +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 + +.RS 4 +Specify the output path to place the secret value. +[default: '-'] +.RE +.RE +.PP +\-i, \-\-input +.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 .RS 4 Specify the output path to place the secret value. -[default: '-'] .RE .RE .PP diff --git a/rust/pvsecret/man/pvsecret-verify.1 b/rust/pvsecret/man/pvsecret-verify.1 index f67142f9..cfa1c459 100644 --- a/rust/pvsecret/man/pvsecret-verify.1 +++ b/rust/pvsecret/man/pvsecret-verify.1 @@ -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] +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 + +.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 +.RS 4 +Specify the request to be checked. +.RE +.RE .PP \-\-user\-cert .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 diff --git a/rust/pvsecret/man/pvsecret.1 b/rust/pvsecret/man/pvsecret.1 index 66b0df67..558107dd 100644 --- a/rust/pvsecret/man/pvsecret.1 +++ b/rust/pvsecret/man/pvsecret.1 @@ -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