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 manuals and README

Browse Source 
Acked-by: Marc Hartmayer <marc@linux.ibm.com>
Reviewed-by: Christoph Schlameuss <schlameuss@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
2024-10-22 17:53:17 +02:00
committed by Jan Höppner
parent ff04f76257
commit a8a3e7d49c
11 changed files with 449 additions and 152 deletions
Download Patch File Download Diff File Expand all files Collapse all files

222
rust/pvsecret/README.md
View File

@@ -32,7 +32,7 @@ Create a new add-secret request
- **add** - **add**
<ul> <ul>
Perform an add-secret request (s390x only) Submit an add-secret request to the Ultravisor (s390x only)
</ul> </ul>
- **lock** - **lock**
@@ -50,23 +50,34 @@ List all ultravisor secrets (s390x only)
Verify that an add-secret request is sane Verify that an add-secret request is sane
</ul> </ul>
- **retrieve**
<ul>
Retrieve a secret from the UV secret store (s390x only)
</ul>
## Options ## Options
`-v`, `--verbose` `-v`, `--verbose`
<ul> <ul>
Provide more detailed output Provide more detailed output.
</ul>
`-q`, `--quiet`
<ul>
Provide less output.
</ul> </ul>
`--version` `--version`
<ul> <ul>
Print version information and exit Print version information and exit.
</ul> </ul>
`-h`, `--help` `-h`, `--help`
<ul> <ul>
Print help Print help (see a summary with '-h').
</ul> </ul>
@@ -95,12 +106,17 @@ Create a meta secret
Create an association secret Create an association secret
</ul> </ul>
- **retrievable**
<ul>
Create a retrievable secret
</ul>
### Options ### Options
`-k`, `--host-key-document <FILE>` `-k`, `--host-key-document <FILE>`
<ul> <ul>
Use FILE as a host-key document. Can be specified multiple times and must be Use FILE as a host-key document. Can be specified multiple times and must be
used at least once. specified at least once.
</ul> </ul>
@@ -114,7 +130,7 @@ the host-key document beforehand.
`-C`, `--cert <FILE>` `-C`, `--cert <FILE>`
<ul> <ul>
Use FILE as a certificate to verify the host key or keys. The certificates are Use FILE as a certificate to verify the host-key or keys. The certificates are
used to establish a chain of trust for the verification of the host-key used to establish a chain of trust for the verification of the host-key
documents. Specify this option twice to specify the IBM Z signing key and the documents. Specify this option twice to specify the IBM Z signing key and the
intermediate CA certificate (signed by the root CA). intermediate CA certificate (signed by the root CA).
@@ -123,15 +139,15 @@ intermediate CA certificate (signed by the root CA).
`--crl <FILE>` `--crl <FILE>`
<ul> <ul>
Use FILE as a certificate revocation list. The list is used to check whether a Use FILE as a certificate revocation list (CRL). The list is used to check
certificate of the chain of trust is revoked. Specify this option multiple times whether a certificate of the chain of trust is revoked. Specify this option
to use multiple CRLs. multiple times to use multiple CRLs.
</ul> </ul>
`--offline` `--offline`
<ul> <ul>
Make no attempt to download CRLs Make no attempt to download CRLs.
</ul> </ul>
@@ -146,8 +162,7 @@ specified certificate.
`--hdr <FILE>` `--hdr <FILE>`
<ul> <ul>
Specifies the header of the guest image. Can be an IBM Secure Execution image Specifies the header of the guest image. Can be an IBM Secure Execution image
created by genprotimg or an extracted IBM Secure Execution header. The header created by 'pvimg/genprotimg' or an extracted IBM Secure Execution header.
must start at a page boundary.
</ul> </ul>
@@ -162,7 +177,7 @@ behavior.
`-o`, `--output <FILE>` `-o`, `--output <FILE>`
<ul> <ul>
Write the generated request to FILE Write the generated request to FILE.
</ul> </ul>
@@ -209,15 +224,15 @@ the request.
`--flags <FLAGS>` `--flags <FLAGS>`
<ul> <ul>
Flags for the add-secret request Flags for the add-secret request.
Possible values: Possible values:
- **disable-dump**: Disables host-initiated dumping for the target guest instance - **disable-dump**: Disables host-initiated dumping for the target guest instance.
</ul> </ul>
`--user-data <FILE>` `--user-data <FILE>`
<ul> <ul>
Use the content of FILE as user-data. Passes user data defined in <FILE> through Use the content of FILE as user-data. Passes user data defined in FILE through
the add-secret request to the ultravisor. The user data can be up to 512 bytes the add-secret request to the ultravisor. The user data can be up to 512 bytes
of arbitrary data, and the maximum size depends on the size of the user-signing of arbitrary data, and the maximum size depends on the size of the user-signing
key: key:
@@ -236,19 +251,25 @@ Optional. No user-data by default.
`--user-sign-key <FILE>` `--user-sign-key <FILE>`
<ul> <ul>
Use the content of FILE as user signing key. Adds a signature calculated from 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 the key in FILE to the add-secret request. The file must be in DER or PEM format
format containing a private key. Supported are RSA 2048 & 3072-bit and containing a private key. Supported are RSA 2048 & 3072-bit and EC(secp521r1)
EC(secp521r1) keys. The firmware ignores the content, but the request tag keys. The firmware ignores the content, but the request tag protects the
protects the signature. The user-signing key signs the request. The location of signature. The user-signing key signs the request. The location of the signature
the signature is filled with zeros during the signature calculation. The request is filled with zeros during the signature calculation. The request tag also
tag also secures the signature. See man pvsecret verify for more details. secures the signature. See man pvsecret verify for more details. Optional. No
Optional. No signature by default. signature by default.
</ul>
`--use-name`
<ul>
Do not hash the name, use it directly as secret ID. Ignored for meta-secrets.
</ul> </ul>
`-h`, `--help` `-h`, `--help`
<ul> <ul>
Print help Print help (see a summary with '-h').
</ul> </ul>
@@ -265,13 +286,62 @@ of secrets.
`pvsecret create association [OPTIONS] <NAME>` `pvsecret create association [OPTIONS] <NAME>`
#### Description #### Description
Create an association secret. Use an association secret to connect a trusted I/O Create an association secret. Use an association secret to connect a trusted I/O
device to a guest. The `pvapconfig` tool provides more information about device to a guest. The 'pvapconfig' tool provides more information about
association secrets. association secrets.
#### Arguments #### Arguments
`<NAME>` `<NAME>`
<ul> <ul>
String to identify the new secret. The actual secret is set with --input-secret. String that identifies the new secret. The actual secret is set with
'--input-secret'. The name is saved in `NAME.yaml` with white-spaces mapped to
`_`.
</ul>
#### Options
`--stdout`
<ul>
Print the hashed name to stdout. The hashed name is not written to `NAME.yaml`
</ul>
`--input-secret <SECRET-FILE>`
<ul>
Path from which to read the plaintext secret. Uses a random secret if not
specified.
</ul>
`--output-secret <SECRET-FILE>`
<ul>
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
secret using '--input-secret'. Destroy the secret when it is not used anymore.
</ul>
`-h`, `--help`
<ul>
Print help (see a summary with '-h').
</ul>
### pvsecret create retrievable
#### Synopsis
`pvsecret create retrievable [OPTIONS] --secret <SECRET-FILE> --type <TYPE> <NAME>`
`pvsecret create retr [OPTIONS] --secret <SECRET-FILE> --type <TYPE> <NAME>`
#### Description
Create a retrievable secret. A retrievable secret is stored in the per-guest
storage of the Ultravisor. A SE-guest can retrieve the secret at runtime and use
it. All retrievable secrets, but the plaintext secret, are retrieved as
wrapped/protected key objects and only usable inside the current, running
SE-guest instance.
#### Arguments
`<NAME>`
<ul>
String that identifies the new secret. The actual secret is set with '--secret'.
The name is saved in `NAME.yaml` with white-spaces mapped to `_`. The name is saved in `NAME.yaml` with white-spaces mapped to `_`.
</ul> </ul>
@@ -284,24 +354,28 @@ Print the hashed name to stdout. The hashed name is not written to `NAME.yaml`
</ul> </ul>
`--input-secret <FILE>` `--secret <SECRET-FILE>`
<ul> <ul>
Path from which to read the plaintext secret. Uses a random secret if not Use SECRET-FILE as retrievable secret.
specified
</ul> </ul>
`--output-secret <FILE>` `--type <TYPE>`
<ul> <ul>
Save the generated secret as plaintext in FILE. The generated secret can be used Specify the secret type. Limitations to the input data apply depending on the
to generate add-secret requests for a different guest with the same secret using secret type.
--input-secret. Destroy the secret when it is not used anymore. 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.
- **hmac-sha**: A HMAC-SHA key. Must be a plain byte file 512, or 1024 bit long.
- **ec**: An elliptic curve private key. Must be a PEM or DER file.
</ul> </ul>
`-h`, `--help` `-h`, `--help`
<ul> <ul>
Print help Print help (see a summary with '-h').
</ul> </ul>
@@ -309,13 +383,14 @@ Print help
### Synopsis ### Synopsis
`pvsecret add <FILE>` `pvsecret add <FILE>`
### Description ### Description
Perform an add-secret request (s390x only). Perform an add-secret request using Submit an add-secret request to the Ultravisor (s390x only). Perform an
a previously generated add-secret request. Only available on s390x. add-secret request using a previously generated add-secret request. Only
available on s390x.
### Arguments ### Arguments
`<FILE>` `<FILE>`
<ul> <ul>
Specify the request to be sent Specify the request to be sent.
</ul> </ul>
@@ -325,8 +400,8 @@ Specify the request to be sent
`pvsecret lock` `pvsecret lock`
### Description ### Description
Lock the secret-store (s390x only). Lock the secret store (s390x only). After Lock the secret-store (s390x only). Lock the secret store (s390x only). After
this command executed successfully, all add-secret requests will fail. Only this command executed successfully, all subsequent add-secret requests will
available on s390x. fail. Only available on s390x.
## pvsecret list ## pvsecret list
### Synopsis ### Synopsis
@@ -339,7 +414,7 @@ Execution guest. Only available on s390x.
`<FILE>` `<FILE>`
<ul> <ul>
Store the result in FILE Store the result in FILE.
Default value: '-' Default value: '-'
</ul> </ul>
@@ -348,18 +423,18 @@ Store the result in FILE
`--format <FORMAT>` `--format <FORMAT>`
<ul> <ul>
Define the output format of the list Define the output format of the list.
Default value: 'human' Default value: 'human'
Possible values: Possible values:
- **human**: Human-focused, non-parsable output format - **human**: Human-focused, non-parsable output format.
- **yaml**: Use yaml format - **yaml**: Use yaml format.
- **bin**: Use the format the ultravisor uses to pass the list - **bin**: Use the format the ultravisor uses to pass the list.
</ul> </ul>
`-h`, `--help` `-h`, `--help`
<ul> <ul>
Print help Print help (see a summary with '-h').
</ul> </ul>
@@ -407,7 +482,7 @@ The verification process works as follows:
`<FILE>` `<FILE>`
<ul> <ul>
Specify the request to be checked Specify the request to be checked.
</ul> </ul>
@@ -435,5 +510,58 @@ contains this user-data with padded zeros if available.
`-h`, `--help` `-h`, `--help`
<ul> <ul>
Print help Print help (see a summary with '-h').
</ul>
## pvsecret retrieve
### Synopsis
`pvsecret retrieve [OPTIONS] <ID>`
`pvsecret retr [OPTIONS] <ID>`
### Description
Retrieve a secret from the UV secret store (s390x only)
### Arguments
`<ID>`
<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 hex 32-byte
unsigned big endian number string. Leading zeros are required.
</ul>
### Options
`-o`, `--output <FILE>`
<ul>
Specify the output path to place the secret value.
Default value: '-'
</ul>
`--inform <INFORM>`
<ul>
Define input type for the Secret ID.
Default value: 'yaml'
Possible values:
- **yaml**: Use a yaml file.
- **hex**: Use a hex string.
- **name**: Use a name-string. Will hash it if no secret with the name found.
</ul>
`--outform <OUTFORM>`
<ul>
Define the output format for the retrieved secret.
Default value: 'pem'
Possible values:
- **pem**: Write the secret as PEM.
- **bin**: Write the secret in binary.
</ul>
`-h`, `--help`
<ul>
Print help (see a summary with '-h').
</ul> </ul>

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

@@ -3,12 +3,11 @@
.\" it under the terms of the MIT license. See LICENSE for details. .\" it under the terms of the MIT license. See LICENSE for details.
.\" .\"
.TH pvsecret-add 1 "2024-05-21" "s390-tools" "UV-Secret Manual" .TH "PVSECRET-ADD" "1" "2024-12-19" "s390-tools" "UV-Secret Manual"
.nh .nh
.ad l .ad l
.SH NAME .SH NAME
\fBpvsecret add\fP - Perform an add-secret request (s390x only) pvsecret-add \- Submit an add-secret request to the Ultravisor (s390x only)
\fB
.SH SYNOPSIS .SH SYNOPSIS
.nf .nf
.fam C .fam C
@@ -16,7 +15,7 @@ pvsecret add <FILE>
.fam C .fam C
.fi .fi
.SH DESCRIPTION .SH DESCRIPTION
Perform an add-secret request using a previously generated add-secret request. Perform an add\-secret request using a previously generated add\-secret request.
Only available on s390x. Only available on s390x.
.SH OPTIONS .SH OPTIONS
.PP .PP
@@ -29,7 +28,7 @@ Specify the request to be sent.
.PP .PP
\-h, \-\-help \-h, \-\-help
.RS 4 .RS 4
Print help. Print help (see a summary with \fB\-h\fR).
.RE .RE
.RE .RE

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

@@ -3,12 +3,11 @@
.\" it under the terms of the MIT license. See LICENSE for details. .\" it under the terms of the MIT license. See LICENSE for details.
.\" .\"
.TH pvsecret-create-association 1 "2024-05-21" "s390-tools" "UV-Secret Manual" .TH "PVSECRET-CREATE-ASSOCIATION" "1" "2024-12-19" "s390-tools" "UV-Secret Manual"
.nh .nh
.ad l .ad l
.SH NAME .SH NAME
\fBpvsecret create association\fP - Create an association secret pvsecret-create-association \- Create an association secret
\fB
.SH SYNOPSIS .SH SYNOPSIS
.nf .nf
.fam C .fam C
@@ -17,14 +16,14 @@ pvsecret create association [OPTIONS] <NAME>
.fi .fi
.SH DESCRIPTION .SH DESCRIPTION
Use an association secret to connect a trusted I/O device to a guest. The Use an association secret to connect a trusted I/O device to a guest. The
`pvapconfig` tool provides more information about association secrets. \fBpvapconfig\fR tool provides more information about association secrets.
.SH OPTIONS .SH OPTIONS
.PP .PP
<NAME> <NAME>
.RS 4 .RS 4
String to identify the new secret. The actual secret is set with String that identifies the new secret. The actual secret is set with
\fB--input-secret\fR. The name is saved in `NAME.yaml` with white-spaces mapped \fB\-\-input\-secret\fR. The name is saved in `NAME.yaml` with white\-spaces
to `_`. mapped to `_`.
.RE .RE
.RE .RE
@@ -35,24 +34,25 @@ Print the hashed name to stdout. The hashed name is not written to `NAME.yaml`
.RE .RE
.RE .RE
.PP .PP
\-\-input-secret <FILE> \-\-input\-secret <SECRET-FILE>
.RS 4 .RS 4
Path from which to read the plaintext secret. Uses a random secret if not Path from which to read the plaintext secret. Uses a random secret if not
specified. specified.
.RE .RE
.RE .RE
.PP .PP
\-\-output-secret <FILE> \-\-output\-secret <SECRET-FILE>
.RS 4 .RS 4
Save the generated secret as plaintext in FILE. The generated secret can be used Save the generated secret as plaintext in SECRET\-FILE. The generated secret can
to generate add-secret requests for a different guest with the same secret using be used to generate add\-secret requests for a different guest with the same
\fB--input-secret\fR. Destroy the secret when it is not used anymore. secret using \fB\-\-input\-secret\fR. Destroy the secret when it is not used
anymore.
.RE .RE
.RE .RE
.PP .PP
\-h, \-\-help \-h, \-\-help
.RS 4 .RS 4
Print help. Print help (see a summary with \fB\-h\fR).
.RE .RE
.RE .RE

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

@@ -1,14 +1,13 @@
.\" Copyright 2023 IBM Corp. .\" Copyright 2023, 2024 IBM Corp.
.\" s390-tools is free software; you can redistribute it and/or modify .\" s390-tools is free software; you can redistribute it and/or modify
.\" it under the terms of the MIT license. See LICENSE for details. .\" it under the terms of the MIT license. See LICENSE for details.
.\" .\"
.TH pvsecret-create-meta 1 "2024-01-30" "s390-tools" "UV-Secret Manual" .TH "PVSECRET-CREATE-META" "1" "2024-12-19" "s390-tools" "UV-Secret Manual"
.nh .nh
.ad l .ad l
.SH NAME .SH NAME
\fBpvsecret create meta\fP - Create a meta secret pvsecret-create-meta \- Create a meta secret
\fB
.SH SYNOPSIS .SH SYNOPSIS
.nf .nf
.fam C .fam C

74
rust/pvsecret/man/pvsecret-create-retrievable.1 Normal file
View File

@@ -0,0 +1,74 @@
.\" 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-CREATE-RETRIEVABLE" "1" "2024-12-19" "s390-tools" "UV-Secret Manual"
.nh
.ad l
.SH NAME
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>
.fam C
.fi
.SH DESCRIPTION
A retrievable secret is stored in the per\-guest storage of the Ultravisor. A
SE\-guest can retrieve the secret at runtime and use it. All retrievable
secrets, but the plaintext secret, are retrieved as wrapped/protected key
objects and only usable inside the current, running SE\-guest instance.
.SH OPTIONS
.PP
<NAME>
.RS 4
String that identifies the new secret. The actual secret is set with
\fB\-\-secret\fR. The name is saved in `NAME.yaml` with white\-spaces mapped to
`_`.
.RE
.RE
.PP
\-\-stdout
.RS 4
Print the hashed name to stdout. The hashed name is not written to `NAME.yaml`
.RE
.RE
.PP
\-\-secret <SECRET-FILE>
.RS 4
Use SECRET\-FILE as retrievable secret.
.RE
.RE
.PP
\-\-type <TYPE>
.RS 4
Specify the secret type. Limitations to the input data apply depending on the
secret type.
Possible values:
.RS 4
\- \fBplain\fP: A plaintext secret. Can be any file up to 8190 bytes long.
\- \fBaes\fP: An AES key. Must be a plain byte file 128, 192, or 256 bit long.
\- \fBaes-xts\fP: An AES-XTS key. Must be a plain byte file 512, or 1024 bit long.
\- \fBhmac-sha\fP: A HMAC-SHA key. Must be a plain byte file 512, or 1024 bit long.
\- \fBec\fP: An elliptic curve private key. Must be a PEM or DER file.
.RE
.RE
.PP
\-h, \-\-help
.RS 4
Print help (see a summary with \fB\-h\fR).
.RE
.RE
.SH "SEE ALSO"
.sp
\fBpvsecret\fR(1) \fBpvsecret-create\fR(1)

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

@@ -3,12 +3,11 @@
.\" it under the terms of the MIT license. See LICENSE for details. .\" it under the terms of the MIT license. See LICENSE for details.
.\" .\"
.TH pvsecret-create 1 "2024-05-21" "s390-tools" "UV-Secret Manual" .TH "PVSECRET-CREATE" "1" "2024-12-19" "s390-tools" "UV-Secret Manual"
.nh .nh
.ad l .ad l
.SH NAME .SH NAME
\fBpvsecret create\fP - Create a new add-secret request pvsecret-create \- Create a new add-secret request
\fB
.SH SYNOPSIS .SH SYNOPSIS
.nf .nf
.fam C .fam C
@@ -29,39 +28,46 @@ bound to the Configuration Unique ID from \fBpvattest\fR using \fB--cuid\fR
.SH "PVSECRET CREATE COMMANDS" .SH "PVSECRET CREATE COMMANDS"
.PP .PP
\fBmeta\fR \fBpvsecret create-meta(1)\fR
.RS 4 .RS 4
Create a meta secret Create a meta secret
.RE .RE
.PP .PP
\fBassociation\fR \fBpvsecret create-association(1)\fR
.RS 4 .RS 4
Create an association secret Create an association secret
.RE .RE
.PP
\fBpvsecret create-retrievable(1)\fR
.RS 4
Create a retrievable secret
.RE
.SH OPTIONS .SH OPTIONS
.PP .PP
\-k, \-\-host-key-document <FILE> \-k, \-\-host\-key\-document <FILE>
.RS 4 .RS 4
Use FILE as a host-key document. Can be specified multiple times and must be Use FILE as a host\-key document. Can be specified multiple times and must be
used at least once. specified at least once.
.RE .RE
.RE .RE
.PP .PP
\-\-no-verify \-\-no\-verify
.RS 4 .RS 4
Disable the host-key document verification. Does not require the host-key Disable the host\-key document verification. Does not require the host\-key
documents to be valid. Do not use for a production request unless you verified documents to be valid. Do not use for a production request unless you verified
the host-key document beforehand. the host\-key document beforehand.
.RE .RE
.RE .RE
.PP .PP
\-C, \-\-cert <FILE> \-C, \-\-cert <FILE>
.RS 4 .RS 4
Use FILE as a certificate to verify the host key or keys. The certificates are Use FILE as a certificate to verify the host\-key or keys. The certificates are
used to establish a chain of trust for the verification of the host-key used to establish a chain of trust for the verification of the host\-key
documents. Specify this option twice to specify the IBM Z signing key and the documents. Specify this option twice to specify the IBM Z signing key and the
intermediate CA certificate (signed by the root CA). intermediate CA certificate (signed by the root CA).
.RE .RE
@@ -69,9 +75,9 @@ intermediate CA certificate (signed by the root CA).
.PP .PP
\-\-crl <FILE> \-\-crl <FILE>
.RS 4 .RS 4
Use FILE as a certificate revocation list. The list is used to check whether a Use FILE as a certificate revocation list (CRL). The list is used to check
certificate of the chain of trust is revoked. Specify this option multiple times whether a certificate of the chain of trust is revoked. Specify this option
to use multiple CRLs. multiple times to use multiple CRLs.
.RE .RE
.RE .RE
.PP .PP
@@ -81,27 +87,26 @@ Make no attempt to download CRLs.
.RE .RE
.RE .RE
.PP .PP
\-\-root-ca <ROOT_CA> \-\-root\-ca <ROOT_CA>
.RS 4 .RS 4
Use FILE as the root-CA certificate for the verification. If omitted, the system Use FILE as the root\-CA certificate for the verification. If omitted, the
wide-root CAs installed on the system are used. Use this only if you trust the system wide\-root CAs installed on the system are used. Use this only if you
specified certificate. trust the specified certificate.
.RE .RE
.RE .RE
.PP .PP
\-\-hdr <FILE> \-\-hdr <FILE>
.RS 4 .RS 4
Specifies the header of the guest image. Can be an IBM Secure Execution image Specifies the header of the guest image. Can be an IBM Secure Execution image
created by genprotimg or an extracted IBM Secure Execution header. The header created by \fBpvimg/genprotimg\fR or an extracted IBM Secure Execution header.
must start at a page boundary.
.RE .RE
.RE .RE
.PP .PP
\-f, \-\-force \-f, \-\-force
.RS 4 .RS 4
Force the generation of add-secret requests on IBM Secure Execution guests. If Force the generation of add\-secret requests on IBM Secure Execution guests. If
the program detects that it is running on an IBM Secure Execution guest, it the program detects that it is running on an IBM Secure Execution guest, it
denies the generation of add-secret requests. The force flag overwrites this denies the generation of add\-secret requests. The force flag overwrites this
behavior. behavior.
.RE .RE
.RE .RE
@@ -112,7 +117,7 @@ Write the generated request to FILE.
.RE .RE
.RE .RE
.PP .PP
\-\-extension-secret <FILE> \-\-extension\-secret <FILE>
.RS 4 .RS 4
Use the content of FILE as an extension secret. The file must be exactly 32 Use the content of FILE as an extension secret. The file must be exactly 32
bytes long. If this request is the first, all subsequent requests must have the bytes long. If this request is the first, all subsequent requests must have the
@@ -124,7 +129,7 @@ request.
.PP .PP
\-\-cck <FILE> \-\-cck <FILE>
.RS 4 .RS 4
Use the content of FILE as the customer-communication key (CCK) to derive the Use the content of FILE as the customer\-communication key (CCK) to derive the
extension secret. The file must contain exactly 32 bytes of data. If the target extension secret. The file must contain exactly 32 bytes of data. If the target
guest was started with bit 1 of the secret control flag set, the ultravisor also guest was started with bit 1 of the secret control flag set, the ultravisor also
derives the secret from the CCK. Otherwise, the ultravisor interprets the derives the secret from the CCK. Otherwise, the ultravisor interprets the
@@ -133,13 +138,13 @@ all requests.
.RE .RE
.RE .RE
.PP .PP
\-\-cuid-hex <HEXSTRING> \-\-cuid\-hex <HEXSTRING>
.RS 4 .RS 4
Use HEXSTRING as the Configuration Unique ID. Must be a hex 128-bit unsigned big Use HEXSTRING as the Configuration Unique ID. Must be a hex 128\-bit unsigned
endian number string. Leading zeros must be provided. If specified, the value big endian number string. Leading zeros must be provided. If specified, the
must match with the Config-UID from the attestation result of that guest. If not value must match with the Config\-UID from the attestation result of that guest.
specified, the CUID will be ignored by the ultravisor during the verification of If not specified, the CUID will be ignored by the ultravisor during the
the request. verification of the request.
.RE .RE
.RE .RE
.PP .PP
@@ -147,7 +152,7 @@ the request.
.RS 4 .RS 4
Use the content of FILE as the Configuration Unique ID. The file must contain 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 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 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 specified, the CUID will be ignored by the Ultravisor during the verification of
the request. the request.
.RE .RE
@@ -155,52 +160,58 @@ the request.
.PP .PP
\-\-flags <FLAGS> \-\-flags <FLAGS>
.RS 4 .RS 4
Flags for the add-secret request. Flags for the add\-secret request.
Possible values: Possible values:
.RS 4 .RS 4
- \fBdisable-dump\fP: Disables host-initiated dumping for the target guest instance. \- \fBdisable-dump\fP: Disables host-initiated dumping for the target guest instance.
.RE .RE
.RE .RE
.PP .PP
\-\-user-data <FILE> \-\-user\-data <FILE>
.RS 4 .RS 4
Use the content of FILE as user-data. Passes user data defined in <FILE> through Use the content of FILE as user\-data. Passes user data defined in FILE through
the add-secret request to the ultravisor. The user data can be up to 512 bytes the add\-secret request to the ultravisor. The user data can be up to 512 bytes
of arbitrary data, and the maximum size depends on the size of the user-signing of arbitrary data, and the maximum size depends on the size of the user\-signing
key: key:
- No key: user data can be 512 bytes. \- No key: user data can be 512 bytes.
- EC(secp521r1) 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. \- RSA 3072 key: user data can be 128 bytes.
The firmware ignores this data, but the request tag protects the user-data. The firmware ignores this data, but the request tag protects the user\-data.
Optional. No user-data by default. Optional. No user\-data by default.
.RE .RE
.RE .RE
.PP .PP
\-\-user-sign-key <FILE> \-\-user\-sign\-key <FILE>
.RS 4 .RS 4
Use the content of FILE as user signing key. Adds a signature calculated from 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 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 format containing a private key. Supported are RSA 2048 & 3072\-bit and
EC(secp521r1) keys. The firmware ignores the content, but the request tag 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 protects the signature. The user\-signing key signs the request. The location of
the signature is filled with zeros during the signature calculation. The request the signature is filled with zeros during the signature calculation. The request
tag also secures the signature. See man pvsecret verify for more details. tag also secures the signature. See man pvsecret verify for more details.
Optional. No signature by default. Optional. No signature by default.
.RE .RE
.RE .RE
.PP .PP
\-\-use\-name
.RS 4
Do not hash the name, use it directly as secret ID. Ignored for meta\-secrets.
.RE
.RE
.PP
\-h, \-\-help \-h, \-\-help
.RS 4 .RS 4
Print help. Print help (see a summary with \fB\-h\fR).
.RE .RE
.RE .RE
.SH "SEE ALSO" .SH "SEE ALSO"
.sp .sp
\fBpvsecret\fR(1) \fBpvsecret-create-meta\fR(1) \fBpvsecret-create-association\fR(1) \fBpvsecret\fR(1) \fBpvsecret-create-meta\fR(1) \fBpvsecret-create-association\fR(1) \fBpvsecret-create-retrievable\fR(1)

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

@@ -3,12 +3,11 @@
.\" it under the terms of the MIT license. See LICENSE for details. .\" it under the terms of the MIT license. See LICENSE for details.
.\" .\"
.TH pvsecret-list 1 "2024-05-21" "s390-tools" "UV-Secret Manual" .TH "PVSECRET-LIST" "1" "2024-12-19" "s390-tools" "UV-Secret Manual"
.nh .nh
.ad l .ad l
.SH NAME .SH NAME
\fBpvsecret list\fP - List all ultravisor secrets (s390x only) pvsecret-list \- List all ultravisor secrets (s390x only)
\fB
.SH SYNOPSIS .SH SYNOPSIS
.nf .nf
.fam C .fam C
@@ -16,8 +15,8 @@ pvsecret list [OPTIONS] [FILE]
.fam C .fam C
.fi .fi
.SH DESCRIPTION .SH DESCRIPTION
Lists the IDs of all non-null secrets currently stored in the ultravisor for the Lists the IDs of all non\-null secrets currently stored in the ultravisor for
currently running IBM Secure Execution guest. Only available on s390x. the currently running IBM Secure Execution guest. Only available on s390x.
.SH OPTIONS .SH OPTIONS
.PP .PP
<FILE> <FILE>
@@ -35,18 +34,18 @@ Define the output format of the list.
Possible values: Possible values:
.RS 4 .RS 4
- \fBhuman\fP: Human-focused, non-parsable output format. \- \fBhuman\fP: Human-focused, non-parsable output format.
- \fByaml\fP: Use yaml format. \- \fByaml\fP: Use yaml format.
- \fBbin\fP: Use the format the ultravisor uses to pass the list. \- \fBbin\fP: Use the format the ultravisor uses to pass the list.
.RE .RE
.RE .RE
.PP .PP
\-h, \-\-help \-h, \-\-help
.RS 4 .RS 4
Print help. Print help (see a summary with \fB\-h\fR).
.RE .RE
.RE .RE

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

@@ -3,12 +3,11 @@
.\" it under the terms of the MIT license. See LICENSE for details. .\" it under the terms of the MIT license. See LICENSE for details.
.\" .\"
.TH pvsecret-lock 1 "2024-05-15" "s390-tools" "UV-Secret Manual" .TH "PVSECRET-LOCK" "1" "2024-12-19" "s390-tools" "UV-Secret Manual"
.nh .nh
.ad l .ad l
.SH NAME .SH NAME
\fBpvsecret lock\fP - Lock the secret-store (s390x only) pvsecret-lock \- Lock the secret-store (s390x only)
\fB
.SH SYNOPSIS .SH SYNOPSIS
.nf .nf
.fam C .fam C
@@ -17,7 +16,7 @@ pvsecret lock
.fi .fi
.SH DESCRIPTION .SH DESCRIPTION
Lock the secret store (s390x only). After this command executed successfully, Lock the secret store (s390x only). After this command executed successfully,
all add-secret requests will fail. Only available on s390x. all subsequent add\-secret requests will fail. Only available on s390x.
.SH "SEE ALSO" .SH "SEE ALSO"
.sp .sp
\fBpvsecret\fR(1) \fBpvsecret\fR(1)

77
rust/pvsecret/man/pvsecret-retrieve.1 Normal file
View File

@@ -0,0 +1,77 @@
.\" 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-RETRIEVE" "1" "2024-12-19" "s390-tools" "UV-Secret Manual"
.nh
.ad l
.SH NAME
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>
.fam C
.fi
.SH DESCRIPTION
Retrieve a secret from the UV secret store (s390x only)
.SH OPTIONS
.PP
<ID>
.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 hex 32\-byte
unsigned big endian number string. Leading zeros are required.
.RE
.RE
.PP
\-o, \-\-output <FILE>
.RS 4
Specify the output path to place the secret value.
[default: '-']
.RE
.RE
.PP
\-\-inform <INFORM>
.RS 4
Define input type for the Secret ID.
[default: 'yaml']
Possible values:
.RS 4
\- \fByaml\fP: Use a yaml file.
\- \fBhex\fP: Use a hex string.
\- \fBname\fP: Use a name-string. Will hash it if no secret with the name found.
.RE
.RE
.PP
\-\-outform <OUTFORM>
.RS 4
Define the output format for the retrieved secret.
[default: 'pem']
Possible values:
.RS 4
\- \fBpem\fP: Write the secret as PEM.
\- \fBbin\fP: Write the secret in binary.
.RE
.RE
.PP
\-h, \-\-help
.RS 4
Print help (see a summary with \fB\-h\fR).
.RE
.RE
.SH "SEE ALSO"
.sp
\fBpvsecret\fR(1)

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

@@ -3,12 +3,11 @@
.\" it under the terms of the MIT license. See LICENSE for details. .\" it under the terms of the MIT license. See LICENSE for details.
.\" .\"
.TH pvsecret-verify 1 "2024-05-21" "s390-tools" "UV-Secret Manual" .TH "PVSECRET-VERIFY" "1" "2024-12-19" "s390-tools" "UV-Secret Manual"
.nh .nh
.ad l .ad l
.SH NAME .SH NAME
\fBpvsecret verify\fP - Verify that an add-secret request is sane pvsecret-verify \- Verify that an add-secret request is sane
\fB
.SH SYNOPSIS .SH SYNOPSIS
.nf .nf
.fam C .fam C
@@ -89,12 +88,12 @@ Specify the request to be checked.
.RE .RE
.PP .PP
\-\-user-cert <FILE> \-\-user\-cert <FILE>
.RS 4 .RS 4
Certificate containing a public key used to verify the user data signature. Certificate containing a public key used to verify the user data signature.
Specifies a public key used to verify the user-data signature. The file must be Specifies a public key used to verify the user\-data signature. The file must be
a X509 certificate in DSA or PEM format. The certificate must hold the public a X509 certificate in DSA or PEM format. The certificate must hold the public
EC, RSA 2048, or RSA 3072 key corresponding to the private user-key used during EC, RSA 2048, or RSA 3072 key corresponding to the private user\-key used during
`create`. No chain of trust is established. Ensuring that the certificate can be `create`. No chain of trust is established. Ensuring that the certificate can be
trusted is the responsibility of the user. The EC key must use the NIST/SECG trusted is the responsibility of the user. The EC key must use the NIST/SECG
curve over a 521 bit prime field (secp521r1). curve over a 521 bit prime field (secp521r1).
@@ -103,15 +102,15 @@ curve over a 521 bit prime field (secp521r1).
.PP .PP
\-o, \-\-output <FILE> \-o, \-\-output <FILE>
.RS 4 .RS 4
Store the result in FILE If the request contained abirtary user-data the output Store the result in FILE If the request contained abirtary user\-data the output
contains this user-data with padded zeros if available. contains this user\-data with padded zeros if available.
[default: '-'] [default: '-']
.RE .RE
.RE .RE
.PP .PP
\-h, \-\-help \-h, \-\-help
.RS 4 .RS 4
Print help. Print help (see a summary with \fB\-h\fR).
.RE .RE
.RE .RE

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

@@ -3,12 +3,11 @@
.\" it under the terms of the MIT license. See LICENSE for details. .\" it under the terms of the MIT license. See LICENSE for details.
.\" .\"
.TH pvsecret 1 "2024-05-21" "s390-tools" "UV-Secret Manual" .TH "PVSECRET" "1" "2024-12-19" "s390-tools" "UV-Secret Manual"
.nh .nh
.ad l .ad l
.SH NAME .SH NAME
\fBpvsecret\fP - Manage secrets for IBM Secure Execution guests pvsecret \- Manage secrets for IBM Secure Execution guests
\fB
.SH SYNOPSIS .SH SYNOPSIS
.nf .nf
.fam C .fam C
@@ -36,39 +35,46 @@ both the PEM and DER input formats are supported.
.SH "PVSECRET COMMANDS" .SH "PVSECRET COMMANDS"
.PP .PP
\fBcreate\fR \fBpvsecret-create(1)\fR
.RS 4 .RS 4
Create a new add-secret request Create a new add-secret request
.RE .RE
.PP .PP
\fBadd\fR \fBpvsecret-add(1)\fR
.RS 4 .RS 4
Perform an add-secret request (s390x only) Submit an add-secret request to the Ultravisor (s390x only)
.RE .RE
.PP .PP
\fBlock\fR \fBpvsecret-lock(1)\fR
.RS 4 .RS 4
Lock the secret-store (s390x only) Lock the secret-store (s390x only)
.RE .RE
.PP .PP
\fBlist\fR \fBpvsecret-list(1)\fR
.RS 4 .RS 4
List all ultravisor secrets (s390x only) List all ultravisor secrets (s390x only)
.RE .RE
.PP .PP
\fBverify\fR \fBpvsecret-verify(1)\fR
.RS 4 .RS 4
Verify that an add-secret request is sane Verify that an add-secret request is sane
.RE .RE
.PP
\fBpvsecret-retrieve(1)\fR
.RS 4
Retrieve a secret from the UV secret store (s390x only)
.RE
.SH OPTIONS .SH OPTIONS
.PP .PP
\-v, \-\-verbose \-v, \-\-verbose
@@ -77,6 +83,12 @@ Provide more detailed output.
.RE .RE
.RE .RE
.PP .PP
\-q, \-\-quiet
.RS 4
Provide less output.
.RE
.RE
.PP
\-\-version \-\-version
.RS 4 .RS 4
Print version information and exit. Print version information and exit.
@@ -85,7 +97,7 @@ Print version information and exit.
.PP .PP
\-h, \-\-help \-h, \-\-help
.RS 4 .RS 4
Print help. Print help (see a summary with \fB\-h\fR).
.RE .RE
.RE .RE
@@ -138,4 +150,4 @@ On the SE-guest, \fIlock\fP the secret store.
.fi .fi
.SH "SEE ALSO" .SH "SEE ALSO"
.sp .sp
\fBpvsecret-create\fR(1) \fBpvsecret-add\fR(1) \fBpvsecret-lock\fR(1) \fBpvsecret-list\fR(1) \fBpvsecret-verify\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)