pvsecret - Create requests, add and list secrets, and lock the store of secrets

pvsecret syntax

Where:

create <options>: On a trusted Linux instance, creates an add-secret request, see pvsecret create for details.
add <options>: On a KVM guest running in secure execution mode, adds the secret to the store of secrets, see pvsecret add for details.
lock: On a KVM guest running in secure execution mode, locks the store of secrets, see pvsecret lock for details.
list: On a KVM guest running in secure execution mode, lists the secrets in the store of secrets, see pvsecret list for details.
retrieve: On a KVM guest running in secure execution mode, retrieves a secret from the ultravisor secret store.
-h or --help: Optional: The short form, -h, displays short information about command usage. Specify after the main command for general help and after a sub-command for help specific to that command. The long form, --help gives more information.
-v or --verbose: Optional: displays verbose messages.
-q or --quiet: Optional: provides less output.
--version: Optional: displays version information.

pvsecret create

Where:

association <name>: creates an add-secret request that contains an association secret with the name <name>.
meta: creates an add-secret request that contains 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.
retrievable: creates an add-secret request that contains a retrievable secret. A retrievable secret is stored in the guest storage of the ultravisor. A KVM guest running in secure execution mode can retrieve the secret at runtime and use it.
update-cck: creates an add-secret request that updates the CCK.
-k or --host-key-document <host_key_doc>: specifies the host key document.
--no-verify: Creates the request without verifying the host key document.
Warning: Working with an unverified host key document makes your KVM guest vulnerable to man-in-the-middle attacks.
-C <certificate> or --cert <certificate>: specifies the certificate that is 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 certificate and the intermediate CA certificate (signed by the root CA).
Ignored when --no-verify is specified.
--crl <revoked_certificates>: Optional: specifies a list of revoked certificates.
--offline: Optional: does not download certificate-revocation lists. Every certificate requires a list of revoked certificates. If you specify --offline, specify one --crl for every -C.
--root-ca=<trusted_CA_certificate>: Optional: specifies a trusted root CA to use instead of one of the root CAs that are installed on the system.
--hdr <header_file>: specifies the header of the KVM guest.
-f or --force: forces the generation of add-secret requests on IBM Secure Execution guests.
-o <output_file> or --output <output_file>: specifies the file that contains the generated add-secret request.

--extension-secret <ext_file>: uses the contents of the input file as 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. If no extension secret is specified with either the --extension-secret option or the --cck option, a string consisting of 32 zeroes is used. 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. Mutually exclusive with --cck.

--cck <cck_file>: specifies the customer-communication key (CCK) to derive the extension secret. Mutually exclusive with --extension-secret.

--cuid-hex <hex_string>: specifies the hex string to use as the Configuration Unique ID.
--cuid <cuid_file>: uses the content of <file> as the Configuration Unique ID
--flags <flag>: specifies flags for the add-secret request. Possible flag value: disable-dump. This flag disables host-initiated dumping for the target guest instance.
--user-sign-key <file>: uses the content of the specified file as the user-signing key. Adds a signature calculated from the key in the file to the add-secret request. The file must be in DER or PEM format and contain a private key. Supported key types are RSA 2048-bit, RSA 3072-bit, and EC (secp521r1). The firmware ignores the signature content, but the request tag protects the signature. During signature calculation, the signature field is filled with zeros. The request tag also secures the signature. For more details, see the man page for pvsecret verify. Optional. No signature is added by default.

pvsecret create association

The secret in the add-secret request can be a random secret (default), or provided as input with the --input-secret option. For more information about association secrets, see pvapconfig - Implement an AP queue configuration.

where

<name>: A string that identifies the new secret. Strings are hashed with SHA-256 to form the ID that is used by the ultravisor. The ID is saved in <name>.yaml with white-spaces mapped to underscores ( _ ).
--stdout: prints the hashed name to stdout. The hashed name is not written to <name>.yaml
--input-secret <file>: specifies the file from which to read the plaintext secret. A random secret is used if no input file is specified.
--output-secret <file>: saves the random association secret as plain text in <file>.
Important: Use this option when a random association secret is generated. The value of the random secret is required to create add-secret requests for an updated version of the guest image. In that case, use the --input-secret option to create updated add-secret requests for the updated secure execution boot image.
The saved random association secret can also be used to generate add-secret requests for a different guest with the same secret. Store the resulting file securely and destroy the secret when it is no longer used.

pvsecret create 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.

where:

--flags <flag>: specifies flags for the add-secret request. Possible flag value: disable-dump. This flag disables host-initiated dumping for the target guest instance.

pvsecret create retrievable

Create an add-secret request that contains a retrievable secret. A retrievable secret is a ultravisor-managed secret associated with an SEL guest image. It is securely retrievable only by the attested guest instance for which it was provisioned.

where

-k or --host-key-document <host_key_doc>

specifies the host key document.

--hdr <header_file>

specifies the header of the KVM guest.

-o <output_file> or --output <output_file>

specifies the file that contains the created request.

--no-verify

Creates the request without verifying the host key document.

Warning: Working with an unverified host key document makes your KVM guest vulnerable to man-in-the-middle attacks.

-C <certificate> or --cert <certificate>

specifies the certificate that is 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 certificate and the intermediate CA certificate (signed by the root CA).

Ignored when --no-verify is specified.

--secret <secret_file>

uses the contents of <secret_file> as the retrievable secret. The file can contain up to 8190 bytes for the plaintext secret. For the symmetric keys (AES, AES\-XTS, HMAC) the file must contain a byte pattern for the key with the key-size as file size. For the EC private keys, the file must be either in PEM or DER format and contain an BEC PRIVATE KEY with one of the following curves: secp256r1, secp384r1, secp521r1, ed25519, or ed448.

--type <secret_type>

specifies the type of the retrievable secret. Valid types are:

plain defines a plaintext secret. Can be any file up to 8190 bytes long..
aes defines an AES key. Must be a plain byte file 128, 192, or 256 bit long.
aes-xts defines an AES-XTS key. Must be a plain byte file 256, or 512 bit long.
hmac-sha defines a HMAC-SHA key. Must be a plain byte file 512, or 1024 bit long. Special care is required when creating HMAC-SHA keys, see the man page for details.
ec defines an elliptic curve private key. Must be a PEM or DER file.

<name>

identifies the retrievable secret. The SHA-256 hash of the name is used as the secret ID and is saved in a YAML file with the naming convention <name>.yaml. Any white spaces are mapped to dashes (-).

--stdout

prints the hashed name to standard output. The hashed name is not written to a yaml file.

Example: On the guest where you want to create a retrievable secret with a name of MyRetrSecret stored in a YAML file called MyRetrSecret.yaml, issue:

# pvsecret create retr --secret MyRetrSecret.txt --type plain MyRetrSecret

pvsecret create update-cck

You can update the CCK if the owner has allowed this by using pvimg --enable-cck-update when the image was built.

where

--secret <secret_file>: uses the contents of <secret_file> as the updated secret.

Example: On the guest where you want to update the CCK and your updated secret is stored in a file called MyUpdatedSecret.txt, issue:

# pvsecret create update-cck --secret MyUpdatedSecret.txt

Draft comment: maria1@de.ibm.com
Is the example correct?

pvsecret add

where:

<request_file>: contains the request with the secret to be added to the store. The secret can be a dummy secret.

pvsecret list

where:

--format <format>

defines the output format of the list. Valid values for <format> are:

human: Human-readable format (default).
yaml: YAML format.
bin: Binary format, as given by the ultravisor.

<output file>

Optional: writes the output to a file. Default is standard out.

Examples:

To list the store of secrets, issue:

# pvsecret list
Total number of secrets: 2

0 Association:
 a63a6f8b796ec96304ae6b0c635986a3b5fac19b9ce7eac55978453e2f222fd5
1 Association:
 546869732069732061207665727920736563726574207365637265742069642e

The output shows that there are two secrets of type association with indexes 0 and 1.

To list the secrets in YAML format, use the yaml option:
```
# pvsecret list --format yaml
```

pvsecret lock

Locks the store of secrets so that no more secrets can be added.

Example: On the guest for which you want to lock the store of secrets and prevent any further secrets from being added, issue:

# pvsecret lock

pvsecret retrieve

A retrievable secret is stored in the KVM guest storage of the ultravisor. You can retrieve the secret by specifying its ID. A KVM guest running in secure execution mode can retrieve the secret at runtime and use it. All retrievable secrets are retrieved as protected-key objects and are only usable inside the current, running guest instance.

where

<ID>

specifies the secret to be retrieved.

The input type depends on --inform. If yaml (default) is specified, the input type must be a YAML file created by the pvsecret create retrievable command. If hex is specified, it must be a hex 32-byte unsigned big endian number string. Leading zeros are required.

If multiple secrets in the secret store have the same ID, the command might retrieve any of them. Use the --inform idx option to ensure that a specific secret is retrieved.

-o or --output <filepath>

specifies the output path for the retrieved secret. Default is the current directory.

--inform <type>

specifies the input file type of the secret ID. Valid file types are:

yaml specifies a yaml file. This is the default.
hex specifies a hex string.
name uses a name-string. The command hashes the string if it does not find a secret with that name.
idx uses the secret index (base 10) instead of the secret ID.

--outform <output_format>

specifies the output format of the retrieved secret. Valid formats are:

pem writes the secret in privacy enhanced mail (PEM) format. This is the default.
bin writes the secret in binary format.

Example: On the guest for which you want to retrieve a secret with an ID of MySecret stored in a yaml file called MySecret.yaml, and write the retrieved secret to mysecret.pem, issue:

# pvsecret retrieve MySecret.yaml -o mysecret.pem