From 238ca83b99b18603105862b2cf06c70f2900e27e Mon Sep 17 00:00:00 2001 From: Marc Hartmayer Date: Thu, 12 Feb 2026 15:48:55 +0100 Subject: [PATCH] Update pvattest and pvsecret mapnages and README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Update pvattest and pvsecret mapnages and README.md, as for example the 'pvsecret create update-cck' was not documented. Reviewed-by: Steffen Eiden Signed-off-by: Marc Hartmayer Signed-off-by: Jan Höppner --- rust/pvattest/README.md | 2 +- rust/pvattest/man/pvattest-create.1 | 10 ++-- rust/pvattest/man/pvattest-verify.1 | 14 ++--- rust/pvattest/man/pvattest.1 | 18 +++---- rust/pvsecret/README.md | 44 +++++++++++++++- rust/pvsecret/man/pvsecret-add.1 | 11 +++- .../man/pvsecret-create-association.1 | 8 +-- rust/pvsecret/man/pvsecret-create-meta.1 | 4 +- .../man/pvsecret-create-retrievable.1 | 51 +++++++++---------- .../pvsecret/man/pvsecret-create-update-cck.1 | 13 ++--- rust/pvsecret/man/pvsecret-create.1 | 22 ++++---- rust/pvsecret/man/pvsecret-retrieve.1 | 2 +- rust/pvsecret/man/pvsecret-verify.1 | 42 +++++++-------- rust/pvsecret/man/pvsecret.1 | 44 ++++++++-------- 14 files changed, 167 insertions(+), 118 deletions(-) diff --git a/rust/pvattest/README.md b/rust/pvattest/README.md index 9d4f0751..a8041e6b 100644 --- a/rust/pvattest/README.md +++ b/rust/pvattest/README.md @@ -1,5 +1,5 @@ diff --git a/rust/pvattest/man/pvattest-create.1 b/rust/pvattest/man/pvattest-create.1 index 55ae2efa..09452b11 100644 --- a/rust/pvattest/man/pvattest-create.1 +++ b/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" "2025-03-12" "s390-tools" "Attestation Manual" +.TH "PVATTEST-CREATE" "1" "2026-02-12" "s390-tools" "Attestation Manual" .nh .ad l .SH NAME @@ -11,7 +11,7 @@ pvattest-create \- Create an attestation measurement request .SH SYNOPSIS .nf .fam C -pvattest create [OPTIONS] --host-key-document --output --arpk <--no-verify|--cert > +pvattest create [OPTIONS] \-\-host\-key\-document \-\-output \-\-arpk <\-\-no\-verify|\-\-cert > .fam C .fi .SH DESCRIPTION @@ -107,15 +107,15 @@ Print help (see a summary with \fB\-h\fR). .RE .SH EXAMPLES -Create an attestation request with the protection key 'arp.key', write the request to 'arcb.bin', and verify the host-key document using the CA-signed key 'DigiCertCA.crt' and the intermediate key 'IbmSigningKey.crt'. +Create an attestation request with the protection key 'arp.key', write the request to 'arcb.bin', and verify the host\-key document using the CA\-signed key 'DigiCertCA.crt' and the intermediate key 'IbmSigningKey.crt'. .PP .nf .fam C - $ pvattest create \-k hkd.crt -\-\arpk arp.key \-o attreq.bin \-\-cert DigiCertCA.crt \-\-cert IbmSigningKey.crt + $ pvattest create \-k hkd.crt \-\-\arpk arp.key \-o attreq.bin \-\-cert DigiCertCA.crt \-\-cert IbmSigningKey.crt .fam T .fi -Create an attestation request with the protection key 'arp.key', write the request to 'arcb.bin', verify the host-key document using the CA-signed key 'DigiCertCA.crt' and the intermediate key 'IbmSigningKey.crt', and instead of downloading the certificate revocation list use certificate revocation lists 'DigiCertCA.crl', 'IbmSigningKey.crl', and 'rootCA.crl'. +Create an attestation request with the protection key 'arp.key', write the request to 'arcb.bin', verify the host\-key document using the CA\-signed key 'DigiCertCA.crt' and the intermediate key 'IbmSigningKey.crt', and instead of downloading the certificate revocation list use certificate revocation lists 'DigiCertCA.crl', 'IbmSigningKey.crl', and 'rootCA.crl'. .PP .nf .fam C diff --git a/rust/pvattest/man/pvattest-verify.1 b/rust/pvattest/man/pvattest-verify.1 index 2bf8c56e..6ce75ed2 100644 --- a/rust/pvattest/man/pvattest-verify.1 +++ b/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" "2025-03-12" "s390-tools" "Attestation Manual" +.TH "PVATTEST-VERIFY" "1" "2026-02-12" "s390-tools" "Attestation Manual" .nh .ad l .SH NAME @@ -11,7 +11,7 @@ pvattest-verify \- Verify an attestation response .SH SYNOPSIS .nf .fam C -pvattest verify [OPTIONS] --input --hdr --arpk +pvattest verify [OPTIONS] \-\-input \-\-hdr \-\-arpk .fam C .fi .SH DESCRIPTION @@ -83,25 +83,25 @@ Print help (see a summary with \fB\-h\fR). .SH EXIT STATUS .TP 8 -.B 0 - Attestation Verified +.B 0 \- Attestation Verified Attesatation measurement verified successfully. Measured guest is in Secure Execution mode. .RE .TP 8 -.B 1 - Program Error +.B 1 \- Program Error Something went wrong during the local calculation or receiving of the measurement value. Refer to the error message. .RE .TP 8 -.B 2 - Attestation NOT Verified +.B 2 \- Attestation NOT Verified Attesation measurement calculation does not match the received value. Measured guest is very likely not in Secure Execution mode. .RE .SH EXAMPLES -To verify a measurement in 'measurement.bin' with the protection key 'arp.kep' and SE-guest header 'se_guest.hdr'. +To verify a measurement in 'measurement.bin' with the protection key 'arp.kep' and SE\-guest header 'se_guest.hdr'. .PP .nf .fam C - $ pvattest verify --input attresp.bin --arpk arp.key --hdr se_guest.hdr + $ pvattest verify \-\-input attresp.bin \-\-arpk arp.key \-\-hdr se_guest.hdr .fam T .fi diff --git a/rust/pvattest/man/pvattest.1 b/rust/pvattest/man/pvattest.1 index 26a6a823..b9112065 100644 --- a/rust/pvattest/man/pvattest.1 +++ b/rust/pvattest/man/pvattest.1 @@ -3,7 +3,7 @@ .\" it under the terms of the MIT license. See LICENSE for details. .\" -.TH "PVATTEST" "1" "2025-03-12" "s390-tools" "Attestation Manual" +.TH "PVATTEST" "1" "2026-02-12" "s390-tools" "Attestation Manual" .nh .ad l .SH NAME @@ -20,28 +20,28 @@ guest systems. .SH "PVATTEST COMMANDS" .PP -\fBpvattest-create(1)\fR +\fBpvattest\-create(1)\fR .RS 4 Create an attestation measurement request .RE .PP -\fBpvattest-perform(1)\fR +\fBpvattest\-perform(1)\fR .RS 4 Send the attestation request to the Ultravisor .RE .PP -\fBpvattest-verify(1)\fR +\fBpvattest\-verify(1)\fR .RS 4 Verify an attestation response .RE .PP -\fBpvattest-check(1)\fR +\fBpvattest\-check(1)\fR .RS 4 Check if the attestation result matches defined policies .RE @@ -83,7 +83,7 @@ Create the request on a trusted system. .fam T .fi -On the SE-guest, \fIperform\fP the attestation. +On the SE\-guest, \fIperform\fP the attestation. .PP .nf .fam C @@ -91,7 +91,7 @@ On the SE-guest, \fIperform\fP the attestation. .fam T .fi -On a trusted system, \fIverify\fP that the response is correct. Here, the protection key from the creation and the SE-guest’s header is used to \fIverify\fP the measurement. +On a trusted system, \fIverify\fP that the response is correct. Here, the protection key from the creation and the SE\-guest’s header is used to \fIverify\fP the measurement. .PP .nf .fam C @@ -102,7 +102,7 @@ On a trusted system, \fIverify\fP that the response is correct. Here, the protec .fam T .fi -If the measurements do not match \fBpvattest\fP exits with code 2 and emits an error message. The SE-guest attestation failed. +If the measurements do not match \fBpvattest\fP exits with code 2 and emits an error message. The SE\-guest attestation failed. .PP .nf .fam C @@ -116,4 +116,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-check\fR(1) +\fBpvattest\-create\fR(1) \fBpvattest\-perform\fR(1) \fBpvattest\-verify\fR(1) \fBpvattest\-check\fR(1) diff --git a/rust/pvsecret/README.md b/rust/pvsecret/README.md index b2be7d8e..c7e9b007 100644 --- a/rust/pvsecret/README.md +++ b/rust/pvsecret/README.md @@ -111,6 +111,11 @@ Create an association secret Create a retrievable secret +- **update-cck** +
    +Update customer communication key +
+ ### Options `-k`, `--host-key-document ` @@ -367,7 +372,7 @@ secret type. Possible values: - **plain**: A plaintext secret. Can be any file up to 8190 bytes long. - **aes**: An AES key. Must be a plain byte file 128, 192, or 256 bit long. - - **aes-xts**: An AES-XTS key. Must be a plain byte file 512, or 1024 bit long. + - **aes-xts**: An AES-XTS key. Must be a plain byte file 256, or 512 bit long. - **hmac-sha**: A HMAC-SHA key. Must be a plain byte file 512, or 1024 bit long. Special care is required when creating HMAC-SHA keys. For more Information refer to the DESCRIPTION section of the man file. - **ec**: An elliptic curve private key. Must be a PEM or DER file. @@ -379,9 +384,30 @@ Print help (see a summary with '-h'). +### pvsecret create update-cck +#### Synopsis +`pvsecret create update-cck --secret ` +`pvsecret create cck --secret ` +#### Description +Update customer communication key. Insert a customer communication key into a +guest. +#### Options + +`--secret ` +
    +Use CCK-FILE as new CCK. +
+ + +`-h`, `--help` +
    +Print help (see a summary with '-h'). +
+ + ## pvsecret add ### Synopsis -`pvsecret add ` +`pvsecret add [OPTIONS] ` ### Description Submit an add-secret request to the Ultravisor (s390x only). Perform an add-secret request using a previously generated add-secret request. Only @@ -394,6 +420,20 @@ Specify the request to be sent. +### Options + +`-f`, `--force` +
    +Force the addition of add-secret requests. Add an add-secret request even if +there is already a secret with the same ID in the secret store. +
+ + +`-h`, `--help` +
    +Print help (see a summary with '-h'). +
+ ## pvsecret lock ### Synopsis diff --git a/rust/pvsecret/man/pvsecret-add.1 b/rust/pvsecret/man/pvsecret-add.1 index 5ac54a91..57a6e278 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" "2024-12-19" "s390-tools" "UV-Secret Manual" +.TH "PVSECRET-ADD" "1" "2026-02-12" "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 +pvsecret add [OPTIONS] .fam C .fi .SH DESCRIPTION @@ -25,6 +25,13 @@ Specify the request to be sent. .RE .RE +.PP +\-f, \-\-force +.RS 4 +Force the addition of add\-secret requests. Add an add\-secret request even if +there is already a secret with the same ID in the secret store. +.RE +.RE .PP \-h, \-\-help .RS 4 diff --git a/rust/pvsecret/man/pvsecret-create-association.1 b/rust/pvsecret/man/pvsecret-create-association.1 index 87a411e5..3ee7e945 100644 --- a/rust/pvsecret/man/pvsecret-create-association.1 +++ b/rust/pvsecret/man/pvsecret-create-association.1 @@ -3,7 +3,7 @@ .\" it under the terms of the MIT license. See LICENSE for details. .\" -.TH "PVSECRET-CREATE-ASSOCIATION" "1" "2024-12-19" "s390-tools" "UV-Secret Manual" +.TH "PVSECRET-CREATE-ASSOCIATION" "1" "2026-02-12" "s390-tools" "UV\-Secret Manual" .nh .ad l .SH NAME @@ -34,14 +34,14 @@ Print the hashed name to stdout. The hashed name is not written to `NAME.yaml` .RE .RE .PP -\-\-input\-secret +\-\-input\-secret .RS 4 Path from which to read the plaintext secret. Uses a random secret if not specified. .RE .RE .PP -\-\-output\-secret +\-\-output\-secret .RS 4 Save the generated secret as plaintext in SECRET\-FILE. The generated secret can be used to generate add\-secret requests for a different guest with the same @@ -58,4 +58,4 @@ Print help (see a summary with \fB\-h\fR). .SH "SEE ALSO" .sp -\fBpvsecret\fR(1) \fBpvsecret-create\fR(1) +\fBpvsecret\fR(1) \fBpvsecret\-create\fR(1) diff --git a/rust/pvsecret/man/pvsecret-create-meta.1 b/rust/pvsecret/man/pvsecret-create-meta.1 index 78a57a22..78428add 100644 --- a/rust/pvsecret/man/pvsecret-create-meta.1 +++ b/rust/pvsecret/man/pvsecret-create-meta.1 @@ -3,7 +3,7 @@ .\" it under the terms of the MIT license. See LICENSE for details. .\" -.TH "PVSECRET-CREATE-META" "1" "2024-12-19" "s390-tools" "UV-Secret Manual" +.TH "PVSECRET-CREATE-META" "1" "2026-02-12" "s390-tools" "UV\-Secret Manual" .nh .ad l .SH NAME @@ -19,4 +19,4 @@ Use a meta secret to carry flags to the ultravisor without having to provide an actual secret value. Meta secrets do not appear in the list of secrets. .SH "SEE ALSO" .sp -\fBpvsecret\fR(1) \fBpvsecret-create\fR(1) +\fBpvsecret\fR(1) \fBpvsecret\-create\fR(1) diff --git a/rust/pvsecret/man/pvsecret-create-retrievable.1 b/rust/pvsecret/man/pvsecret-create-retrievable.1 index 4e2e6990..f37abc46 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" "2025-02-28" "s390-tools" "UV-Secret Manual" +.TH "PVSECRET-CREATE-RETRIEVABLE" "1" "2026-02-12" "s390-tools" "UV\-Secret Manual" .nh .ad l .SH NAME @@ -11,8 +11,8 @@ pvsecret-create-retrievable \- Create a retrievable secret .SH SYNOPSIS .nf .fam C -pvsecret create retrievable [OPTIONS] --secret --type -pvsecret create retr [OPTIONS] --secret --type +pvsecret create retrievable [OPTIONS] \-\-secret \-\-type +pvsecret create retr [OPTIONS] \-\-secret \-\-type .fam C .fi .SH DESCRIPTION @@ -29,31 +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 @@ -73,7 +72,7 @@ Print the hashed name to stdout. The hashed name is not written to `NAME.yaml` .RE .RE .PP -\-\-secret +\-\-secret .RS 4 Use SECRET\-FILE as retrievable secret. .RE @@ -107,4 +106,4 @@ Print help (see a summary with \fB\-h\fR). .SH "SEE ALSO" .sp -\fBpvsecret\fR(1) \fBpvsecret-create\fR(1) +\fBpvsecret\fR(1) \fBpvsecret\-create\fR(1) diff --git a/rust/pvsecret/man/pvsecret-create-update-cck.1 b/rust/pvsecret/man/pvsecret-create-update-cck.1 index 90d9f4d6..33730af2 100644 --- a/rust/pvsecret/man/pvsecret-create-update-cck.1 +++ b/rust/pvsecret/man/pvsecret-create-update-cck.1 @@ -1,17 +1,18 @@ -.\" Copyright 2025 IBM Corp. +.\" Copyright 2025, 2026 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 "PVSECRET-CREATE-UPDATE-CCK" "1" "2025-02-19" "s390-tools" "UV-Secret Manual" +.TH "PVSECRET-CREATE-UPDATE-CCK" "1" "2026-02-12" "s390-tools" "UV\-Secret Manual" .nh .ad l .SH NAME -pvsecret-create-update-cck \- Update customer communication key. +pvsecret-create-update-cck \- Update customer communication key .SH SYNOPSIS .nf .fam C -pvsecret create update-cck [OPTIONS] \-\-secret +pvsecret create update\-cck \-\-secret +pvsecret create cck \-\-secret .fam C .fi .SH DESCRIPTION @@ -20,7 +21,7 @@ Insert a customer communication key into a guest. .PP \-\-secret .RS 4 -Use CCK\-FILE as new CCK +Use CCK\-FILE as new CCK. .RE .RE .PP @@ -32,4 +33,4 @@ Print help (see a summary with \fB\-h\fR). .SH "SEE ALSO" .sp -\fBpvsecret\fR(1) \fBpvsecret-create\fR(1) +\fBpvsecret\fR(1) \fBpvsecret\-create\fR(1) diff --git a/rust/pvsecret/man/pvsecret-create.1 b/rust/pvsecret/man/pvsecret-create.1 index 4b296905..2372c92c 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" "2025-04-25" "s390-tools" "UV-Secret Manual" +.TH "PVSECRET-CREATE" "1" "2026-02-12" "s390-tools" "UV\-Secret Manual" .nh .ad l .SH NAME @@ -11,43 +11,45 @@ pvsecret-create \- Create a new add-secret request .SH SYNOPSIS .nf .fam C -pvsecret create [OPTIONS] --host-key-document --hdr --output <--no-verify|--cert > +pvsecret create [OPTIONS] \-\-host\-key\-document \-\-hdr \-\-output <\-\-no\-verify|\-\-cert > .fam C .fi .SH DESCRIPTION -Create add-secret requests for IBM Secure Execution guests. Only create these +Create add\-secret requests for IBM Secure Execution guests. Only create these requests in a trusted environment, such as your workstation. The \fBpvattest create\fR command creates a randomly generated key to protect the request. The generated requests can then be added on an IBM Secure Execution guest using \fBpvsecret add\fR. The guest can then use the secrets with the use case depending on the secret type. Such a request is bound to a specific IBM Secure Execution image specified with -\fB--hdr\fR. Optionally, the request can be bound to a specific instance when -bound to the Configuration Unique ID from \fBpvattest\fR using \fB--cuid\fR +\fB\-\-hdr\fR. Optionally, the request can be bound to a specific instance when +bound to the Configuration Unique ID from \fBpvattest\fR using \fB\-\-cuid\fR .SH "PVSECRET CREATE COMMANDS" .PP -\fBpvsecret create-meta(1)\fR +\fBpvsecret create\-meta(1)\fR .RS 4 Create a meta secret .RE .PP -\fBpvsecret create-association(1)\fR +\fBpvsecret create\-association(1)\fR .RS 4 Create an association secret .RE .PP -\fBpvsecret create-retrievable(1)\fR +\fBpvsecret create\-retrievable(1)\fR .RS 4 Create a retrievable secret .RE -\fBpvsecret create-update-cck(1)\fR +.PP + +\fBpvsecret create\-update\-cck(1)\fR .RS 4 Update customer communication key .RE @@ -219,4 +221,4 @@ Print help (see a summary with \fB\-h\fR). .SH "SEE ALSO" .sp -\fBpvsecret\fR(1) \fBpvsecret-create-meta\fR(1) \fBpvsecret-create-association\fR(1) \fBpvsecret-create-retrievable\fR(1) +\fBpvsecret\fR(1) \fBpvsecret\-create\-meta\fR(1) \fBpvsecret\-create\-association\fR(1) \fBpvsecret\-create\-retrievable\fR(1) \fBpvsecret\-create\-update\-cck\fR(1) diff --git a/rust/pvsecret/man/pvsecret-retrieve.1 b/rust/pvsecret/man/pvsecret-retrieve.1 index 832279a9..63fd7caf 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" "2025-04-17" "s390-tools" "UV-Secret Manual" +.TH "PVSECRET-RETRIEVE" "1" "2026-02-12" "s390-tools" "UV\-Secret Manual" .nh .ad l .SH NAME diff --git a/rust/pvsecret/man/pvsecret-verify.1 b/rust/pvsecret/man/pvsecret-verify.1 index adbc098c..f67142f9 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" "2024-12-19" "s390-tools" "UV-Secret Manual" +.TH "PVSECRET-VERIFY" "1" "2026-02-12" "s390-tools" "UV\-Secret Manual" .nh .ad l .SH NAME @@ -16,10 +16,10 @@ pvsecret verify [OPTIONS] .fi .SH DESCRIPTION .PP -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 is -verified with the provided key. Outputs the arbitrary user-data. All data in the -request is in big endian. +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 +is verified with the provided key. Outputs the arbitrary user\-data. All data in +the request is in big endian. .PP \fIverify\fP checks the following: .RS @@ -31,31 +31,31 @@ file .IP \[bu] 2 The request version is supported by the binary .IP \[bu] 2 -If user-data contains a signature, verify the signature using a public +If user\-data contains a signature, verify the signature using a public key .RE .PP The content of bytes 6&7 of the request define which kind -of user-data the request contains. +of user\-data the request contains. .IP \fB0x0000\fP 8 -no user-data (512 bytes zero) +no user\-data (512 bytes zero) .IP \fB0x0001\fP 8 -512 bytes user-data +512 bytes user\-data .IP \fB0x0002\fP 8 -265 bytes user-data| 139 bytes ecdsa signature | 5 bytes reserved | 2 bytes +265 bytes user\-data| 139 bytes ecdsa signature | 5 bytes reserved | 2 bytes signature size | ... .IP \fB0x0003\fP 8 -256 bytes user-data | 256 bytes rsa2048 signature +256 bytes user\-data | 256 bytes rsa2048 signature .IP \fB0x0004\fP 8 -128 bytes user-data | 384 bytes rsa3072 signature +128 bytes user\-data | 384 bytes rsa3072 signature .PP -The actual user-data may be less than the capacity. If less data was provided +The actual user\-data may be less than the capacity. If less data was provided during \fIcreate\fP zeros are appended. . -For type 2-4 The signature is calculated as follows: +For type 2\-4 The signature is calculated as follows: .RS .IP "1." 3 -The request is generated with the user-data in place and zeros for the +The request is generated with the user\-data in place and zeros for the signature data. .IP "2." 3 The signature is calculated for the request. The signature signs the @@ -116,10 +116,10 @@ Print help (see a summary with \fB\-h\fR). .SH EXAMPLES .PP -Create the add-secret request on a trusted system with signed user data similar +Create the add\-secret request on a trusted system with signed user data similar to the example for \fBpvsecret\fR. Let's assume there are three more files -present. \fIuser_data\fR contains ascii "some example user-data", a private -user-signing key e.g. rsa3072 \fIusr_sgn_key.priv.pem\fR, and a certificate +present. \fIuser_data\fR contains ascii "some example user\-data", a private +user\-signing key e.g. rsa3072 \fIusr_sgn_key.priv.pem\fR, and a certificate containing the corresponding public key to the private rsa3072 key \fIuser_cert.pem\fR. .PP @@ -135,8 +135,8 @@ Successfully generated the request Successfully wrote association info to 'EXAMPLE.yaml' .RE -For example, on the SE-guest, perform \fIverify\fP on the request to verify the -user-signature and the saneness of the request. On success, The user-data is +For example, on the SE\-guest, perform \fIverify\fP on the request to verify the +user\-signature and the saneness of the request. On success, The user\-data is printed to stdout (if \fI\-\-output\fP was not specified) and \fBSuccesfully verified the request.\fR is printed to stderr. .PP @@ -145,7 +145,7 @@ verified the request.\fR is printed to stderr. pvsecret verify \-\-user\-cert user_cert.pem \-o addsecreq.bin .RE .RS -some example user-data +some example user\-data .br Successfully verified the request .RE diff --git a/rust/pvsecret/man/pvsecret.1 b/rust/pvsecret/man/pvsecret.1 index f5a41df4..66b0df67 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" "2024-12-19" "s390-tools" "UV-Secret Manual" +.TH "PVSECRET" "1" "2026-02-12" "s390-tools" "UV\-Secret Manual" .nh .ad l .SH NAME @@ -16,7 +16,7 @@ pvsecret [OPTIONS] .fi .SH DESCRIPTION Use \fBpvsecret\fR to manage secrets for IBM Secure Execution guests. -\fBpvsecret\fR can \fIcreate\fR add-secret requests on any architecture. On +\fBpvsecret\fR can \fIcreate\fR add\-secret requests on any architecture. On s390x systems, use \fBpvsecret\fR to \fIadd\fR the secrets to the ultravisor secret store, \fIlist\fR all secrets in the secret store, or \fIlock\fR the secret store to prevent any modifications in the future. @@ -28,49 +28,49 @@ Create requests only on trusted systems that are not the IBM Secure Execution guest where you want to inject the secrets. This approach prevents the secrets from being in cleartext on the guest. For extra safety, do an attestation with \fBpvattest\fR of your guest beforehand, and include the configuration UID in -the secret request using \fB--cuid\fR. Refer to \fBpvsecret-add\fR(1) for more -information. For all certificates, revocation lists, and host-key documents, -both the PEM and DER input formats are supported. +the secret request using \fB\-\-cuid\fR. Refer to \fBpvsecret\-add\fR(1) for +more information. For all certificates, revocation lists, and host\-key +documents, both the PEM and DER input formats are supported. .SH "PVSECRET COMMANDS" .PP -\fBpvsecret-create(1)\fR +\fBpvsecret\-create(1)\fR .RS 4 -Create a new add-secret request +Create a new add\-secret request .RE .PP -\fBpvsecret-add(1)\fR +\fBpvsecret\-add(1)\fR .RS 4 -Submit an add-secret request to the Ultravisor (s390x only) +Submit an add\-secret request to the Ultravisor (s390x only) .RE .PP -\fBpvsecret-lock(1)\fR +\fBpvsecret\-lock(1)\fR .RS 4 -Lock the secret-store (s390x only) +Lock the secret\-store (s390x only) .RE .PP -\fBpvsecret-list(1)\fR +\fBpvsecret\-list(1)\fR .RS 4 List all ultravisor secrets (s390x only) .RE .PP -\fBpvsecret-verify(1)\fR +\fBpvsecret\-verify(1)\fR .RS 4 -Verify that an add-secret request is sane +Verify that an add\-secret request is sane .RE .PP -\fBpvsecret-retrieve(1)\fR +\fBpvsecret\-retrieve(1)\fR .RS 4 Retrieve a secret from the UV secret store (s390x only) .RE @@ -103,9 +103,9 @@ Print help (see a summary with \fB\-h\fR). .SH EXAMPLES .PP -Create the add-secret request on a trusted system. The program generates two -files. \fBaddsecreq.bin\fR contains the add-secret request. \fBEXAMPLE.yaml\fR -contains the non-confidential information about the generated secret. It +Create the add\-secret request on a trusted system. The program generates two +files. \fBaddsecreq.bin\fR contains the add\-secret request. \fBEXAMPLE.yaml\fR +contains the non\-confidential information about the generated secret. It contains name and id of the secret. .PP .nf @@ -115,7 +115,7 @@ contains name and id of the secret. Successfully wrote association info to 'EXAMPLE.yaml' .fam T .fi -On the SE-guest, \fIadd\fP the secret from request to the secret store. +On the SE\-guest, \fIadd\fP the secret from request to the secret store. .PP .nf .fam C @@ -124,7 +124,7 @@ On the SE-guest, \fIadd\fP the secret from request to the secret store. .fam T .fi -On the SE-guest, \fIlist\fP the secrets currently stored. +On the SE\-guest, \fIlist\fP the secrets currently stored. .PP .nf .fam C @@ -136,7 +136,7 @@ On the SE-guest, \fIlist\fP the secrets currently stored. .fam T .fi -On the SE-guest, \fIlock\fP the secret store. +On the SE\-guest, \fIlock\fP the secret store. .PP .nf .fam C @@ -150,4 +150,4 @@ On the SE-guest, \fIlock\fP the secret store. .fi .SH "SEE ALSO" .sp -\fBpvsecret-create\fR(1) \fBpvsecret-add\fR(1) \fBpvsecret-lock\fR(1) \fBpvsecret-list\fR(1) \fBpvsecret-verify\fR(1) \fBpvsecret-retrieve\fR(1) +\fBpvsecret\-create\fR(1) \fBpvsecret\-add\fR(1) \fBpvsecret\-lock\fR(1) \fBpvsecret\-list\fR(1) \fBpvsecret\-verify\fR(1) \fBpvsecret\-retrieve\fR(1)