diff --git a/rust/pvsecret/README.md b/rust/pvsecret/README.md index e1808444..4015dacc 100644 --- a/rust/pvsecret/README.md +++ b/rust/pvsecret/README.md @@ -4,11 +4,13 @@ s390-tools is free software; you can redistribute it and/or modify it under the terms of the MIT license. See LICENSE for details. --> # pvsecret +## Synopsis +`pvsecret [OPTIONS] ` ## Description Use **pvsecret** to manage secrets for IBM Secure Execution guests. **pvsecret** can **create** add-secret requests on any architecture. On s390x systems, use **pvsecret** to **add** the secrets to the ultravisor secret store, **list** all -secrets in the secret store, or lock the secret store to prevent any +secrets in the secret store, or **lock** the secret store to prevent any modifications in the future. The ultravisor secret store stores secrets for the IBM Secure Execution guest. @@ -18,193 +20,211 @@ 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 **pvattest** of your guest beforehand, and include the configuration UID in the -secret request using **--cuid**. Refer to **pvsecret-add**(1) for more -information. For all certificates, revocation lists, and host-key documents, -both the PEM and DER input formats are supported. +secret request using **--cuid**. Refer to **pvsecret-add** for more information. +For all certificates, revocation lists, and host-key documents, both the PEM and +DER input formats are supported. - -## Synopsis -`pvsecret [OPTIONS] ` ## Commands Overview - - **create** - Create a new add-secret request - - **add** - Repeat an add-secret request (s390x only) - - **lock** - Lock the secret-store (s390x only) - - **list** - List all ultravisor secrets (s390x only) +- **create** + + +- **add** + + +- **lock** + + +- **list** + + ## Options `-v`, `--verbose` `--version` ## pvsecret create +### Synopsis +`pvsecret create [OPTIONS] --host-key-document --hdr --output <--no-verify|--cert > ` ### Description Create add-secret requests for IBM Secure Execution guests. Only create these requests in a trusted environment, such as your workstation. The **pvattest create** command creates a randomly generated key to protect the request. The generated requests can then be added on an IBM Secure Execution guest using -**pvsecret add**. The guest can then use the secrets with the use case -depending on the secret type. - +**pvsecret add**. 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 -**--hdr**. Optionally, the request can be bound to a specific instance when +**--hdr**. Optionally, the request can be bound to a specific instance when bound to the Configuration Unique ID from **pvattest** using **--cuid** - -### Synopsis -`pvsecret create [OPTIONS] --host-key-document --hdr --output <--no-verify|--cert > ` ### Commands Overview - - **meta** - 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 - - **association** - Use an association secret to connect a trusted I/O device to a guest. The - `pvapconfig` tool provides more information about association secrets +- **meta** +
    +Create a meta secret +
+ +- **association** +
    +Create an association secret +
### Options `-k`, `--host-key-document `
    - Use FILE as a host-key document. Can be specified multiple times and must be - used at least once. +Use FILE as a host-key document. Can be specified multiple times and must be +used at least once.
+ `--no-verify`
    - 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 the host-key document beforehand. +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 +the host-key document beforehand.
+ `-C`, `--cert `
    - 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 - documents. Specify this option twice to specify the IBM Z signing key and - the intermediate CA certificate (signed by the root CA). +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 +documents. Specify this option twice to specify the IBM Z signing key and the +intermediate CA certificate (signed by the root CA).
+ `--crl `
    - Use FILE as a certificate revocation list. The list is used to check whether - a certificate of the chain of trust is revoked. Specify this option multiple - times to use multiple CRLs. +Use FILE as a certificate revocation list. The list is used to check whether a +certificate of the chain of trust is revoked. Specify this option multiple times +to use multiple CRLs.
+ `--offline`
    - Make no attempt to download CRLs +Make no attempt to download CRLs
+ `--root-ca `
    - Use FILE as the root-CA certificate for the verification. If omitted, the - system-wide root CAs installed on the system are used. Use this only if you - trust the specified certificate. +Use FILE as the root-CA certificate for the verification. If omitted, the system +wide-root CAs installed on the system are used. Use this only if you trust the +specified certificate.
+ `--hdr `
    - 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 must start at a page boundary. +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 +must start at a page boundary.
+ `-f`, `--force`
    - 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 denies the generation of add-secret requests. The force flag overwrites - this behavior. +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 +denies the generation of add-secret requests. The force flag overwrites this +behavior.
+ `-o`, `--output `
    - Write the generated request to FILE +Write the generated request to FILE
+ `--extension-secret `
    - 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 same extension secret. Only makes sense if bit 1 of the secret control - flags of the IBM Secure Execution header is 0. Otherwise the ultravisor - rejects the request. +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 +same extension secret. Only makes sense if bit 1 of the secret control flags of +the IBM Secure Execution header is 0. Otherwise the ultravisor rejects the +request.
+ `--cck `
    - 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 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 extension secret as a normal one. This still works if you - use the same CCK for all requests. +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 +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 +extension secret as a normal one. This still works if you use the same CCK for +all requests.
`--cuid-hex `
    - Use HEXSTRING as the Configuration Unique ID. Must be a hex 128-bit unsigned - big endian number string. Leading zeros must be provided. If specified, the - value must match with 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. +Use HEXSTRING as the Configuration Unique ID. Must be a hex 128-bit unsigned big +endian number string. Leading zeros must be provided. If specified, the value +must match with 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.
+ `--cuid `
    - Use the content of FILE as the Configuration Unique ID. The file must - contain exactly 128 bit of data, a hex string, 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. +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.
+ `--flags `
    - Flags for the add-secret request. - +Flags for the add-secret request Possible values: - - disable-dump: Disables host-initiated dumping for the target guest - instance + - **disable-dump**: Disables host-initiated dumping for the target guest instance
### pvsecret create meta -#### Description -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. - - #### Synopsis `pvsecret create meta` +#### Description +Create a meta secret. 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. ### pvsecret create association -#### Description -Use an association secret to connect a trusted I/O device to a guest. The -`pvapconfig` tool provides more information about association secrets. - #### Synopsis `pvsecret create association [OPTIONS] ` +#### Description +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 +association secrets. #### Arguments ``
    - String to identify the new secret. The actual secret is set with - --input-secret. The name is saved in `NAME.yaml` with white-spaces - mapped to `_`. +String to identify the new secret. The actual secret is set with --input-secret. +The name is saved in `NAME.yaml` with white-spaces mapped to `_`.
@@ -212,73 +232,72 @@ Use an association secret to connect a trusted I/O device to a guest. The `--stdout`
    - Print the hashed name to stdout. The hashed name will not be written to - `NAME.yaml` +Print the hashed name to stdout. The hashed name is not written to `NAME.yaml`
`--input-secret `
    - Path from which to read the plaintext secret. Uses a random secret if not - specified. +Path from which to read the plaintext secret. Uses a random secret if not +specified
`--output-secret `
    - Save the generated secret as plaintext in 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. +Save the generated secret as plaintext in 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.
## pvsecret add -### Description -Perform an add-secret request using a previously generated add-secret request. -Only available on s390x. - - ### Synopsis `pvsecret add ` +### Description +Perform an add-secret request (s390x only). Perform an add-secret request using +a previously generated add-secret request. Only available on s390x. ### Arguments ``
    - Specify the request to be sent +Specify the request to be sent
+ ## pvsecret lock -### Description -Lock the secret store (s390x only). After this command executed successfully, -all add-secret requests will fail. Only available on s390x. - - ### Synopsis `pvsecret lock` +### Description +Lock the secret-store (s390x only). Lock the secret store (s390x only). After +this command executed successfully, all add-secret requests will fail. Only +available on s390x. ## pvsecret list -### Description -Lists the IDs of all non-null secrets currently stored in the ultravisor for the -currently running IBM Secure Execution guest. Only available on s390x. - ### Synopsis `pvsecret list [OPTIONS] [FILE]` +### Description +List all ultravisor secrets (s390x only). Lists the IDs of all non-null secrets +currently stored in the ultravisor for the currently running IBM Secure +Execution guest. Only available on s390x. ### Arguments ``
    - Store the result in FILE. Default value: '-' +Store the result in FILE + Default value: '-'
### Options `--format ` - Define the output format of the list. Default value: 'human' - +
    +Define the output format of the list + Default value: 'human' Possible values: - - human: Human-focused, non-parsable output format - - yaml: Use yaml format - - bin: Use the format the ultravisor uses to pass the list + - **human**: Human-focused, non-parsable output format + - **yaml**: Use yaml format + - **bin**: Use the format the ultravisor uses to pass the list +
diff --git a/rust/pvsecret/man/pvsecret-add.1 b/rust/pvsecret/man/pvsecret-add.1 index 812ba08f..96a94e40 100644 --- a/rust/pvsecret/man/pvsecret-add.1 +++ b/rust/pvsecret/man/pvsecret-add.1 @@ -3,11 +3,11 @@ .\" it under the terms of the MIT license. See LICENSE for details. .\" -.TH pvsecret-add 1 "2023-07-28" "s390-tools" "UV-Secret Manual" +.TH pvsecret-add 1 "2023-10-09" "s390-tools" "UV-Secret Manual" .nh .ad l .SH NAME -\fBpvsecret add\fP - Repeat an add-secret request (s390x only) +\fBpvsecret add\fP - Perform an add-secret request (s390x only) \fB .SH SYNOPSIS .nf @@ -18,7 +18,6 @@ pvsecret add .SH DESCRIPTION Perform an add-secret request using a previously generated add-secret request. Only available on s390x. - .SH OPTIONS .PP diff --git a/rust/pvsecret/man/pvsecret-create-association.1 b/rust/pvsecret/man/pvsecret-create-association.1 index 9657daf4..1d62bd94 100644 --- a/rust/pvsecret/man/pvsecret-create-association.1 +++ b/rust/pvsecret/man/pvsecret-create-association.1 @@ -3,11 +3,11 @@ .\" it under the terms of the MIT license. See LICENSE for details. .\" -.TH pvsecret-create-association 1 "2023-07-28" "s390-tools" "UV-Secret Manual" +.TH pvsecret-create-association 1 "2023-10-09" "s390-tools" "UV-Secret Manual" .nh .ad l .SH NAME -\fBpvsecret create association\fP - Use an association secret to connect an I/O device to a guest +\fBpvsecret create association\fP - Create an association secret \fB .SH SYNOPSIS .nf @@ -18,13 +18,12 @@ pvsecret create association [OPTIONS] .SH DESCRIPTION Use an association secret to connect a trusted I/O device to a guest. The `pvapconfig` tool provides more information about association secrets. - .SH OPTIONS .PP .RS 4 String to identify 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 mapped to `_`. .RE .RE diff --git a/rust/pvsecret/man/pvsecret-create-meta.1 b/rust/pvsecret/man/pvsecret-create-meta.1 index 07b12997..dc3519a5 100644 --- a/rust/pvsecret/man/pvsecret-create-meta.1 +++ b/rust/pvsecret/man/pvsecret-create-meta.1 @@ -3,11 +3,11 @@ .\" it under the terms of the MIT license. See LICENSE for details. .\" -.TH pvsecret-create-meta 1 "2023-07-28" "s390-tools" "UV-Secret Manual" +.TH pvsecret-create-meta 1 "2023-10-09" "s390-tools" "UV-Secret Manual" .nh .ad l .SH NAME -\fBpvsecret create meta\fP - Use a meta secret to carry flags to the ultravisor +\fBpvsecret create meta\fP - Create a meta secret \fB .SH SYNOPSIS .nf @@ -17,8 +17,7 @@ pvsecret create meta .fi .SH DESCRIPTION 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. - +actual secret value. Meta secrets do not appear in the list of secrets. .SH "SEE ALSO" .sp \fBpvsecret\fR(1) \fBpvsecret-create\fR(1) diff --git a/rust/pvsecret/man/pvsecret-create.1 b/rust/pvsecret/man/pvsecret-create.1 index 9f91051a..981c6f58 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 "2023-07-28" "s390-tools" "UV-Secret Manual" +.TH pvsecret-create 1 "2023-10-09" "s390-tools" "UV-Secret Manual" .nh .ad l .SH NAME @@ -22,10 +22,10 @@ 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 + .SH OPTIONS .PP \-k, \-\-host-key-document @@ -62,15 +62,15 @@ to use multiple CRLs. .PP \-\-offline .RS 4 -Make no attempt to download CRLs +Make no attempt to download CRLs. .RE .RE .PP \-\-root-ca .RS 4 -Use FILE as the root-CA certificate for the verification. If omitted, the -system-wide root CAs installed on the system are used. Use this only if you -trust the specified certificate. +Use FILE as the root-CA certificate for the verification. If omitted, the system +wide-root CAs installed on the system are used. Use this only if you trust the +specified certificate. .RE .RE .PP @@ -93,7 +93,7 @@ behavior. .PP \-o, \-\-output .RS 4 -Write the generated request to FILE +Write the generated request to FILE. .RE .RE .PP @@ -120,21 +120,21 @@ all requests. .PP \-\-cuid-hex .RS 4 -Use HEXSTRING as the Configuration Unique ID. Must be a hex 128-bit unsigned -big endian number string. Leading zeros must be provided. If specified, the -value must match with 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. +Use HEXSTRING as the Configuration Unique ID. Must be a hex 128-bit unsigned big +endian number string. Leading zeros must be provided. If specified, the value +must match with 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. .RE .RE .PP \-\-cuid .RS 4 Use the content of FILE as the Configuration Unique ID. The file must contain -exactly 128 bit of data, a hex string, 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. +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. .RE .RE .PP diff --git a/rust/pvsecret/man/pvsecret-list.1 b/rust/pvsecret/man/pvsecret-list.1 index 6f60a87d..17e9bb0a 100644 --- a/rust/pvsecret/man/pvsecret-list.1 +++ b/rust/pvsecret/man/pvsecret-list.1 @@ -3,7 +3,7 @@ .\" it under the terms of the MIT license. See LICENSE for details. .\" -.TH pvsecret-list 1 "2023-07-28" "s390-tools" "UV-Secret Manual" +.TH pvsecret-list 1 "2023-10-09" "s390-tools" "UV-Secret Manual" .nh .ad l .SH NAME @@ -22,22 +22,24 @@ currently running IBM Secure Execution guest. Only available on s390x. .PP .RS 4 -Store the result in FILE. Default value: '-' +Store the result in FILE. +[default: '-'] .RE .RE .PP \-\-format .RS 4 -Define the output format of the list. Default value: 'human' +Define the output format of the list. +[default: 'human'] Possible values: .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 diff --git a/rust/pvsecret/man/pvsecret-lock.1 b/rust/pvsecret/man/pvsecret-lock.1 index 125e7485..1b3b473a 100644 --- a/rust/pvsecret/man/pvsecret-lock.1 +++ b/rust/pvsecret/man/pvsecret-lock.1 @@ -3,7 +3,7 @@ .\" it under the terms of the MIT license. See LICENSE for details. .\" -.TH pvsecret-lock 1 "2023-07-28" "s390-tools" "UV-Secret Manual" +.TH pvsecret-lock 1 "2023-10-09" "s390-tools" "UV-Secret Manual" .nh .ad l .SH NAME @@ -18,9 +18,6 @@ pvsecret lock .SH DESCRIPTION Lock the secret store (s390x only). After this command executed successfully, all add-secret requests will fail. Only available on s390x. - -.SH OPTIONS - .SH "SEE ALSO" .sp \fBpvsecret\fR(1) diff --git a/rust/pvsecret/man/pvsecret-version.1 b/rust/pvsecret/man/pvsecret-version.1 deleted file mode 100644 index e1e170f5..00000000 --- a/rust/pvsecret/man/pvsecret-version.1 +++ /dev/null @@ -1,25 +0,0 @@ -.\" Copyright 2023 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-version 1 "2023-07-28" "s390-tools" "UV-Secret Manual" -.nh -.ad l -.SH NAME -\fBpvsecret version\fP- Print version information and exit -\fB -.SH SYNOPSIS -.nf -.fam C -pvsecret version -.fam C -.fi -.SH DESCRIPTION -Print version information and exit - -.SH OPTIONS - -.SH "SEE ALSO" -.sp -\fBpvsecret\fR(1) diff --git a/rust/pvsecret/man/pvsecret.1 b/rust/pvsecret/man/pvsecret.1 index 5e1c0483..32856408 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 "2023-07-28" "s390-tools" "UV-Secret Manual" +.TH pvsecret 1 "2023-10-09" "s390-tools" "UV-Secret Manual" .nh .ad l .SH NAME @@ -49,20 +49,16 @@ Print version information and exit. .SH EXAMPLES .PP -Create the add-secret request on a trusted system. The program generates three -files. \fFaddsecreq.bin\fP contains the add-secret request. \fFTEST.yaml\fP +Create the add-secret request on a trusted system. The program generates two +files. \fFaddsecreq.bin\fP contains the add-secret request. \fEXAMPLE.yaml\fP contains the non-confidential information about the generated secret. It -contains the name and ID of the secret. \fFTEST\fP contains the plaintext secret -that is encrypted in the request. It can be used to generate add-secret requests -for a different guest with the same secret. Destroy the secret when it is not -used anymore. +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 Successfully generated the request Successfully wrote association info to 'EXAMPLE.yaml' - Successfully wrote generated association secret to 'EXAMPLE' .fam T .fi On the SE-guest, \fIadd\fP the secret from request to the secret store. @@ -100,4 +96,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-version\fR(1) +\fBpvsecret-create\fR(1) \fBpvsecret-add\fR(1) \fBpvsecret-lock\fR(1) \fBpvsecret-list\fR(1) diff --git a/rust/pvsecret/src/cli.rs b/rust/pvsecret/src/cli.rs index d4d0ecdd..96f97b42 100644 --- a/rust/pvsecret/src/cli.rs +++ b/rust/pvsecret/src/cli.rs @@ -84,7 +84,7 @@ pub struct CreateSecretOpt { /// Use the content of FILE as the Configuration Unique ID. /// - /// The file must contain exactly 128 bit of data, a hex string, or a yaml with a `cuid` entry. + /// 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.