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

rust/pvsecret: Update man files and help

Browse Source 
Add subcommands in the man description. Add description for the help option.
Fix some minor wording issues.
Add the curve type  in the --user-data option of create.

Acked-by: Marc Hartmayer <mhartmay@linux.ibm.com>
Signed-off-by: Steffen Eiden <seiden@linux.ibm.com>
This commit is contained in:
Steffen Eiden
2024-05-03 11:35:17 +02:00
parent d016ec129d
commit 636d2d571b
9 changed files with 145 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files

40
rust/pvsecret/README.md
View File

@@ -1,5 +1,5 @@
<!--
Copyright 2023 IBM Corp.
Copyright 2023, 2024 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.
-->
@@ -64,6 +64,12 @@ Print version information and exit
</ul>
`-h`, `--help`
<ul>
Print help
</ul>
## pvsecret create
### Synopsis
`pvsecret create [OPTIONS] --host-key-document <FILE> --hdr <FILE> --output <FILE> <--no-verify|--cert <FILE>> <COMMAND>`
@@ -196,8 +202,8 @@ the request.
Use the content of FILE as the Configuration Unique ID. The file must contain
exactly 128 bit of data or a yaml with a `cuid` entry. If specified, the value
must match the Config-UID from the attestation result of that guest. If not
specified, the CUID will be ignored by the Ultravisor during the verification
of the request.
specified, the CUID will be ignored by the Ultravisor during the verification of
the request.
</ul>
@@ -229,8 +235,8 @@ Optional. No user-data by default.
`--user-sign-key <FILE>`
<ul>
Use the content of FILE as user signing key. Adds a signature defined calculated
from the key in <FILE> to the add-secret request. The file must be in DER or PEM
Use the content of FILE as user signing key. Adds a signature calculated from
the key in <FILE> to the add-secret request. The file must be in DER or PEM
format containing a private key. Supported are RSA 2048 & 3072-bit and
EC(secp521r1) keys. The firmware ignores the content, but the request tag
protects the signature. The user-signing key signs the request. The location of
@@ -240,6 +246,12 @@ Optional. No signature by default.
</ul>
`-h`, `--help`
<ul>
Print help
</ul>
### pvsecret create meta
#### Synopsis
`pvsecret create meta`
@@ -287,6 +299,12 @@ to generate add-secret requests for a different guest with the same secret using
</ul>
`-h`, `--help`
<ul>
Print help
</ul>
## pvsecret add
### Synopsis
`pvsecret add <FILE>`
@@ -339,6 +357,12 @@ Define the output format of the list
</ul>
`-h`, `--help`
<ul>
Print help
</ul>
## pvsecret verify
### Synopsis
`pvsecret verify [OPTIONS] <FILE>`
@@ -407,3 +431,9 @@ 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>
`-h`, `--help`
<ul>
Print help
</ul>

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

@@ -1,9 +1,9 @@
.\" Copyright 2023 IBM Corp.
.\" Copyright 2023, 2024 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-add 1 "2024-01-30" "s390-tools" "UV-Secret Manual"
.TH pvsecret-add 1 "2024-05-21" "s390-tools" "UV-Secret Manual"
.nh
.ad l
.SH NAME
@@ -26,6 +26,12 @@ Specify the request to be sent.
.RE
.RE
.PP
\-h, \-\-help
.RS 4
Print help.
.RE
.RE
.SH "SEE ALSO"
.sp

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

@@ -1,9 +1,9 @@
.\" Copyright 2023 IBM Corp.
.\" Copyright 2023, 2024 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-association 1 "2024-01-30" "s390-tools" "UV-Secret Manual"
.TH pvsecret-create-association 1 "2024-05-21" "s390-tools" "UV-Secret Manual"
.nh
.ad l
.SH NAME
@@ -49,6 +49,12 @@ to generate add-secret requests for a different guest with the same secret using
\fB--input-secret\fR. Destroy the secret when it is not used anymore.
.RE
.RE
.PP
\-h, \-\-help
.RS 4
Print help.
.RE
.RE
.SH "SEE ALSO"
.sp

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

@@ -1,9 +1,9 @@
.\" Copyright 2023 IBM Corp.
.\" Copyright 2023, 2024 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 1 "2024-01-30" "s390-tools" "UV-Secret Manual"
.TH pvsecret-create 1 "2024-05-21" "s390-tools" "UV-Secret Manual"
.nh
.ad l
.SH NAME
@@ -26,6 +26,21 @@ 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
.SH "PVSECRET CREATE COMMANDS"
.PP
\fBmeta\fR
.RS 4
Create a meta secret
.RE
.PP
\fBassociation\fR
.RS 4
Create an association secret
.RE
.SH OPTIONS
.PP
\-k, \-\-host-key-document <FILE>
@@ -133,8 +148,8 @@ the request.
Use the content of FILE as the Configuration Unique ID. The file must contain
exactly 128 bit of data or a yaml with a `cuid` entry. If specified, the value
must match the Config-UID from the attestation result of that guest. If not
specified, the CUID will be ignored by the Ultravisor during the verification
of the request.
specified, the CUID will be ignored by the Ultravisor during the verification of
the request.
.RE
.RE
.PP
@@ -169,8 +184,8 @@ Optional. No user-data by default.
.PP
\-\-user-sign-key <FILE>
.RS 4
Use the content of FILE as user signing key. Adds a signature defined calculated
from the key in <FILE> to the add-secret request. The file must be in DER or PEM
Use the content of FILE as user signing key. Adds a signature calculated from
the key in <FILE> to the add-secret request. The file must be in DER or PEM
format containing a private key. Supported are RSA 2048 & 3072-bit and
EC(secp521r1) keys. The firmware ignores the content, but the request tag
protects the signature. The user-signing key signs the request. The location of
@@ -179,6 +194,12 @@ tag also secures the signature. See man pvsecret verify for more details.
Optional. No signature by default.
.RE
.RE
.PP
\-h, \-\-help
.RS 4
Print help.
.RE
.RE
.SH "SEE ALSO"
.sp

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

@@ -1,9 +1,9 @@
.\" Copyright 2023 IBM Corp.
.\" Copyright 2023, 2024 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-list 1 "2024-01-30" "s390-tools" "UV-Secret Manual"
.TH pvsecret-list 1 "2024-05-21" "s390-tools" "UV-Secret Manual"
.nh
.ad l
.SH NAME
@@ -41,6 +41,12 @@ Possible values:
- \fBbin\fP: Use the format the ultravisor uses to pass the list.
.RE
.RE
.PP
\-h, \-\-help
.RS 4
Print help.
.RE
.RE

4
rust/pvsecret/man/pvsecret-lock.1
View File

@@ -1,9 +1,9 @@
.\" Copyright 2023 IBM Corp.
.\" Copyright 2024 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-lock 1 "2024-01-30" "s390-tools" "UV-Secret Manual"
.TH pvsecret-lock 1 "2024-05-15" "s390-tools" "UV-Secret Manual"
.nh
.ad l
.SH NAME

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

@@ -1,9 +1,9 @@
.\" Copyright 2023 IBM Corp.
.\" Copyright 2023, 2024 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-verify 1 "2024-01-30" "s390-tools" "UV-Secret Manual"
.TH pvsecret-verify 1 "2024-05-21" "s390-tools" "UV-Secret Manual"
.nh
.ad l
.SH NAME
@@ -108,6 +108,12 @@ contains this user-data with padded zeros if available.
[default: '-']
.RE
.RE
.PP
\-h, \-\-help
.RS 4
Print help.
.RE
.RE
.SH EXAMPLES
.PP
@@ -115,7 +121,7 @@ Create the add-secret request on a trusted system with signed user datai similar
.PP
.RS
.IP trusted:~$ 12
pvsecret create -k hkd.crt --cert CA.crt --cert ibmsk.crt --hdr pvimage -o addsecreq.bin --user-data user_data --user-sign-key usr_sgn_key.priv.pem association EXAMPLE
pvsecret create \-k hkd.crt \-\-cert CA.crt \-\-cert ibmsk.crt \-\-hdr pvimage \-o addsecreq.bin \-\-user\-data user_data \-\-user\-sign\-key usr_sgn_key.priv.pem association EXAMPLE
.RE
.RS
Successfully generated the request
@@ -123,11 +129,11 @@ 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 printed to stdout (if \fI--output\fP was not specified) and \fFSuccesfully verified the request.\fP is printed to stderr.
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 \fFSuccesfully verified the request.\fP is printed to stderr.
.PP
.RS
.IP seguest:~$ 12
pvsecret verify --user-cert user_cert.pem -o addsecreq.bin
pvsecret verify \-\-user\-cert user_cert.pem \-o addsecreq.bin
.RE
.RS
some example user-data

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

@@ -1,9 +1,9 @@
.\" Copyright 2023 IBM Corp.
.\" Copyright 2023, 2024 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 1 "2024-01-30" "s390-tools" "UV-Secret Manual"
.TH pvsecret 1 "2024-05-21" "s390-tools" "UV-Secret Manual"
.nh
.ad l
.SH NAME
@@ -33,6 +33,42 @@ 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
\fBcreate\fR
.RS 4
Create a new add-secret request
.RE
.PP
\fBadd\fR
.RS 4
Perform an add-secret request (s390x only)
.RE
.PP
\fBlock\fR
.RS 4
Lock the secret-store (s390x only)
.RE
.PP
\fBlist\fR
.RS 4
List all ultravisor secrets (s390x only)
.RE
.PP
\fBverify\fR
.RS 4
Verify that an add-secret request is sane
.RE
.SH OPTIONS
.PP
\-v, \-\-verbose
@@ -46,6 +82,12 @@ Provide more detailed output.
Print version information and exit.
.RE
.RE
.PP
\-h, \-\-help
.RS 4
Print help.
.RE
.RE
.SH EXAMPLES
.PP
@@ -56,7 +98,7 @@ contains name and id of the secret.
.PP
.nf
.fam C
trusted:~$ pvsecret create -k hkd.crt --cert CA.crt --cert ibmsk.crt --hdr pvimage -o addsecreq.bin association EXAMPLE
trusted:~$ pvsecret create \-k hkd.crt \-\-cert CA.crt \-\-cert ibmsk.crt \-\-hdr pvimage \-o addsecreq.bin association EXAMPLE
Successfully generated the request
Successfully wrote association info to 'EXAMPLE.yaml'
.fam T

2
rust/pvsecret/src/cli.rs
View File

@@ -119,7 +119,7 @@ pub struct CreateSecretOpt {
/// user data can be up to 512 bytes of arbitrary data, and the maximum size depends on the
/// size of the user-signing key:
/// - No key: user data can be 512 bytes.
/// - EC or RSA 2048 keys: user data can be 256 bytes.
/// - EC(secp521r1) or RSA 2048 keys: user data can be 256 bytes.
/// - RSA 3072 key: user data can be 128 bytes.
///
/// The firmware ignores this data, but the request tag protects the user-data. Optional. No