Handling retrievable secrets of an IBM Secure Execution for Linux guest

Edit online

Use retrievable secrets for pervasive encryption and store them in the zkey key repository. The described features are only available to a Linux instance that is running in Secure Execution mode on systems starting with IBM z17.

Working with PVSECRET-AES keys in the repository

Retrievable secrets are created for an IBM® Secure Execution guest to protect confidential workload. They are represented as zkey key type PVSECRET-AES in the zkey key repository. Like with other zkey key types, you can list, validate, change, copy, rename, remove, import, and export keys of type PVSECRET-AES using the appropriate zkey subcommands (zkey list, zkey validate, and so on).

Retrievable secrets do not use a cryptographic coprocessor, thus no master key information is available. Also, no APQNs can be associated with retrievable secrets for the same reason.

You cannot generate a PVSECRET-AES key using the zkey generate command, nor can you create such a secret randomly or from a clear key. However, you can import keys of type PVSECRET-AES from an IBM SEL guest's ultravisor into the zkey key repository. Such PVSECRET-AES keys do not contain the key material, but only a reference (the ID) to the retrievable secret in the ultravisor.

Because keys of type PVSECRET-AES do not use a cryptographic coprocessor, no re-enciphering is necessary nor possible. Such keys cannot be managed with a key management system (KMS) plugin. They are always local keys, even if the key repository is bound to a KMS.

zkey pvsecret list: list keys in an IBM SEL guest

You can list retrievable secrets that are available in the ultravisor of an SEL guest. Such retrievable secrets of type AES and AES-XTS on the guest side can be imported as PVSECRET-AES key blobs into the zkey key repository.

Use this subcommand on an SEL guest that has been set up with the required retrievable secret or secrets of type AES or AES-XTS previously.

Note: The zkey pvsecret list command must be run as root user.

Figure 1. zkey pvsecret list

where

pvsecret list: by default, lists all retrievable secrets of type AES and AES-XTS that are available in the ultravisor of an . Without further options, this subcommand displays a list of secret IDs as 32-byte hex strings, and the type of the secret.
Note: As an alternative to the zkey pvsecret list command, you can also use the pvsecret list command as described in Introducing IBM Secure Execution for Linux®, SC34-7721.
In contrast to pvsecret list, the zkey pvsecret list command only displays retrievable secrets usable by the zkey utility. The pvsecret list displays all types of secrets, including association secrets, or secret types not usable by zkey.
--pvsecret-id <hex_ID>: filters the list by ID. The ID is a hexadecimal string that was calculated as a SHA-256 hash of the name when the secret was created.
If the add-secret request was created with the pvsecret create command together with the --use-name option, then the ID of the retrievable secret is not a SHA-256 hash of the name, but a printable version of the name. In this case, zkey pvsecret list does show the printable name instead of the hex ID. To always show the hex ID, use option --hex with the zkey pvsecret list command.
--pvsecret-name <name>: filters the list by name. The zkey pvsecret list command cannot display the name of the retrievable secret unless it was created using the --use-name option.
--pvsecret-type <type>: filters the list by the protected virtualization (PV) secret type. Parameter<type> can be one of AES-128, AES-192, AES-256, AES-XTS-128, or AES-XTS-256.
--all: lists all PV secret types, not only those that can be used with zkey.
--hex: always lists the ID of the secret as a hexadecimal string even if the ID contains a printable version of the name.

zkey pvsecret import: import retrievable secrets from an IBM SEL guest

You can import retrievable secrets of type AES and AES-XTS on the IBM SEL guest into the secure key repository as key blobs with the key type PVSECRET-AES. Such PVSECRET-AES keys do not contain the key material, but only a reference (the ID) to the retrievable secret in the ultravisor. These key blobs enable the use of dm-crypt-based disk encryption using the PAES cipher.

Note: The zkey pvsecret import command must be run as root user.

Figure 2. zkey pvsecret import

where:

pvsecret im or pvsecret import

imports retrievable secrets of type AES and AES-XTS into the zkey key repository. The command checks that a secret with the specified ID or name exists in the ultravisor.

Keys that have been imported from retrievable secrets have a key type of PVSECRET-AES. Such a key can be an AES key of size 128, 192, or 256 bits, or an AES-XTS key of size 256, or 512 bits.

--pvsecret-id <hex_ID>

imports retrievable secrets with this ID. The ID was calculated as a SHA-256 hash of the name when the secret was created.

If the add-secret request was created with the pvsecret create command together with the --use-name option, then the ID of the retrievable secret is not a SHA-256 hash of the secret name, but a printable version of the secret name. In this case, the secret name specified using the --pvsecret-name option is compared to the printable version of the secret name, and if it matches, the secret is selected for importing.

--pvsecret-name <name>

imports retrievable secrets with the specified name. The zkey pvsecret list command cannot display the name of the secret unless the retrievable secret was created using the --use-name option.

--name <key_name> or -N <key_name>

specifies a name for the imported key in the zkey key repository. If the name of the retrievable secret is specified with --pvsecret-name, then the -N option can be omitted. The imported key then receives the same name as the name of the secret in the zkey key repository.

-t <volume-type> or --volume-type <volume-type>

Optional. Specifies the volume type of the associated volumes used with dm-crypt. Possible values are PLAIN or LUKS2 (not case-sensitive). If omitted, LUKS2 is used. This option is only available if zkey has been compiled with LUKS2 support enabled. If LUKS2 support is not enabled, the default volume type is PLAIN.

-d <description> or --description <description>

Optional. Describes the retrievable secret.

-l <volumes> or --volumes <volumes>

Optional. You can associate volumes with a key. Each volume association specifies the name of the block device (for example /dev/mapper/disk1) and the device mapper name separated by a colon. Separate multiple volume associations with a comma, for example:

-l /dev/mapper/disk1:enc-disk1,/dev/mapper/disk2:enc-disk2

-t <volume-type> or --volume-type <volume-type>

--gen-dummy-passphrase

For LUKS2 volumes only. Generate a random 16-byte passphrase and associate it with a retrievable secret key. Because the AES key’s security derives from the ultravisor protection, and not from the passphrase, the dummy passphrase is non-critical and may be stored insecurely. Since the AES key ensures security, the passphrase can be stored insecurely in the secure key repository. This option is only allowed for keys contained in the secure key repository that are associated with a LUKS2 volume.

--set-dummy-passphrase

For LUKS2 volumes only. Read a dummy passphrase from the specified file and associates it with a retrievable secret key used to encrypt LUKS2 volumes. Because the AES key’s security derives from the ultravisor protection, and not from the passphrase, the dummy passphrase is non-critical and may be stored insecurely. If, nevertheless, for a certain usage the passphrase is of relevance for security, then do not use this option.

This option is only allowed for keys contained in the secure key repository that are associated with a LUKS2 volume.

Note: You cannot associate APQNs with a key that was imported from a retrievable secret. Such keys are of type PVSECRET-AES.

You can encrypt a volume using dm-crypt with a key of type PVSECRET-AES. Ensure that you associate the desired volumes with the key. Then use the same procedure as with other key types, see Encrypting a disk with PVSECRET-AES keys and Creating a volume for pervasive encryption.

Encrypting a disk with PVSECRET-AES keys

Like with other zkey key types, you can encrypt a disk using dm-crypt with a key of type PVSECRET-AES. The procedure is exactly the same as with other key types.

Make sure you associate the desired volume(s) with the key. You can then generate the cryptsetup commands to format a LUKS2 disk as follows:

 zkey cryptsetup [--volumes <volumes>] [--run]

This produces an output like the following (assuming an AES-XTS secret is used):

cryptsetup luksFormat --type luks2 --master-key-file ’/etc/zkey/repository/<key-name>.skey’ \ 
           --key-size 352 --cipher paes-xts-plain64 --pbkdf argon2i --pbkdf-memory 32 \ 
           --pbkdf-force-iterations 4 /dev/<device> 

zkey-cryptsetup setvp /dev/<device>

The --key-size 352 option specifies the size of the key blob in bits. Once the disk has been formatted, you can open it using:

cryptsetup luksOpen /dev/<device> <dm-name>

Optionally, you can let zkey generate that command using:

zkey cryptsetup --open [--volumes <volumes>] [--run]

To use an unattended opening of such a volume during boot, you must setup a crypttab entry for this volume. To avoid a passphrase prompt during boot, associate a dummy passphrase with they key. The LUKS2 passphrase is of less or no relevance for the security of the volume(s), when a retrievable secret is used to encrypt the volume(s), and can therefore be stored insecurely inside the key repository. Use a command similar to the following to generate a random dummy passphrase for the key:

zkey change --name <key-name> --gen-dummy-passphrase

You can let zkey generate a crypttab entry with the following command:

zkey crypttab [--volumes <volumes>]

This produces an output like the following (assuming a dummy passphrase has been set):

<dm-name> /dev/<device> /etc/zkey/repository/<key-name>.pass luks