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

Update pvattest and pvsecret mapnages and README.md

Browse Source 
Update pvattest and pvsecret mapnages and README.md, as for example the
'pvsecret create update-cck' was not documented.

Reviewed-by: Steffen Eiden <seiden@linux.ibm.com>
Signed-off-by: Marc Hartmayer <marc@linux.ibm.com>
Signed-off-by: Jan Höppner <hoeppner@linux.ibm.com>
This commit is contained in:
Marc Hartmayer
2026-02-12 15:48:55 +01:00
committed by Jan Höppner
parent df8aac7084
commit 238ca83b99
14 changed files with 167 additions and 118 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
rust/pvattest/README.md
View File

@@ -1,5 +1,5 @@
<!--
Copyright 2024 IBM Corp.
Copyright 2024, 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.
-->

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

@@ -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 <FILE> --output <FILE> --arpk <FILE> <--no-verify|--cert <FILE>>
pvattest create [OPTIONS] \-\-host\-key\-document <FILE> \-\-output <FILE> \-\-arpk <FILE> <\-\-no\-verify|\-\-cert <FILE>>
.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

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

@@ -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 <FILE> --hdr <FILE> --arpk <FILE>
pvattest verify [OPTIONS] \-\-input <FILE> \-\-hdr <FILE> \-\-arpk <FILE>
.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

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

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

44
rust/pvsecret/README.md
View File

@@ -111,6 +111,11 @@ Create an association secret
Create a retrievable secret
</ul>
- **update-cck**
<ul>
Update customer communication key
</ul>
### Options
`-k`, `--host-key-document <FILE>`
@@ -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.
</ul>
@@ -379,9 +384,30 @@ Print help (see a summary with '-h').
</ul>
### pvsecret create update-cck
#### Synopsis
`pvsecret create update-cck --secret <CCK-FILE>`
`pvsecret create cck --secret <CCK-FILE>`
#### Description
Update customer communication key. Insert a customer communication key into a
guest.
#### Options
`--secret <CCK-FILE>`
<ul>
Use CCK-FILE as new CCK.
</ul>
`-h`, `--help`
<ul>
Print help (see a summary with '-h').
</ul>
## pvsecret add
### Synopsis
`pvsecret add <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
@@ -394,6 +420,20 @@ Specify the request to be sent.
</ul>
### Options
`-f`, `--force`
<ul>
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.
</ul>
`-h`, `--help`
<ul>
Print help (see a summary with '-h').
</ul>
## pvsecret lock
### Synopsis

11
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" "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 <FILE>
pvsecret add [OPTIONS] <FILE>
.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

8
rust/pvsecret/man/pvsecret-create-association.1
View File

@@ -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 <SECRET-FILE>
\-\-input\-secret <SECRET\-FILE>
.RS 4
Path from which to read the plaintext secret. Uses a random secret if not
specified.
.RE
.RE
.PP
\-\-output\-secret <SECRET-FILE>
\-\-output\-secret <SECRET\-FILE>
.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)

4
rust/pvsecret/man/pvsecret-create-meta.1
View File

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

51
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" "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 <SECRET-FILE> --type <TYPE> <NAME>
pvsecret create retr [OPTIONS] --secret <SECRET-FILE> --type <TYPE> <NAME>
pvsecret create retrievable [OPTIONS] \-\-secret <SECRET\-FILE> \-\-type <TYPE> <NAME>
pvsecret create retr [OPTIONS] \-\-secret <SECRET\-FILE> \-\-type <TYPE> <NAME>
.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
<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
@@ -73,7 +72,7 @@ Print the hashed name to stdout. The hashed name is not written to `NAME.yaml`
.RE
.RE
.PP
\-\-secret <SECRET-FILE>
\-\-secret <SECRET\-FILE>
.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)

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

@@ -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 <CCK\-FILE>
pvsecret create update\-cck \-\-secret <CCK\-FILE>
pvsecret create cck \-\-secret <CCK\-FILE>
.fam C
.fi
.SH DESCRIPTION
@@ -20,7 +21,7 @@ Insert a customer communication key into a guest.
.PP
\-\-secret <CCK\-FILE>
.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)

22
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" "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 <FILE> --hdr <FILE> --output <FILE> <--no-verify|--cert <FILE>> <COMMAND>
pvsecret create [OPTIONS] \-\-host\-key\-document <FILE> \-\-hdr <FILE> \-\-output <FILE> <\-\-no\-verify|\-\-cert <FILE>> <COMMAND>
.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)

2
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" "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

42
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" "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] <FILE>
.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

44
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" "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] <COMMAND>
.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)