pvapconfig - Implement an AP queue configuration

Edit online

Use the pvapconfig command on a KVM guest that is running in IBM® Secure Execution mode to implement AP queue device configurations that are defined in a YAML file.

Prerequisites

The pvapconfig command requires privileges for the following tasks:

Read and write sysfs entries.
Open /dev/uv and run ioctl calls on this device.

Locking

To prevent multiple instances of pvapconfig, the command creates a lock file, /var/lock/pvapconfig.lock. A second instance of pvapconfig detects this lock file and terminates with an error message.

If for any reason this file still exists as a leftover from a previous pvapconfig crash, for example, you must remove it. The lock file contains the process ID of the pvapconfig process that created it.

pvapconfig syntax

where:

-c or --config <config_file>: The default file /etc/pvapconfig.yaml is used if no -c option is given.
-n or --dry-run: processes the configuration, the available AP queues, and secrets. Then simulates the bind, unbind or associate action on the chosen AP queues. Use this option together with the verbose option to see which actions pvapconfig would perform if ran without -n.
-s or --strict: requires all AP-queue configuration entries to be valid for pvapconfig to terminate successfully. Without this option, one valid AP configuration entry is enough for pvapconfig to terminate successfully.
-v or --verbose: prints detailed information about the processing.
-V or --version: prints version information and exits.

pvapconfig configuration file

You can use a configuration file to automate which association secrets shall be used with which APQN configuration.

Create a .yaml file with entries that describe your AP queue configuration.

The configuration file contains AP queue configurations in a YAML format. Each configuration must contain the mode specification and the parameters for that mode:

AP queue mode, either EP11 or Accel

Required.

Specify EP11 for an AP queue based on a Crypto Express adapter in Enterprise PKCS #11 coprocessor mode.
Specify Accel for an AP queue based on a Crypto Express adapter in accelerator mode.

For EP11:

mkvp: Required. The master key verification pattern (MKVP) of the AP queue as a hex string optionally prefixed with 0x. The hex string value can hold either 16 bytes (32 hex numbers) or 32 bytes (64 hex numbers) but only the leftmost 16 bytes hold MKVP information. The rest is ignored.
secretid: Required. Find the 32-byte ID of the secret in the .yaml file that you generated with the pvsecret create command. The secret ID is a hex string optionally prefixed with 0x. This is an SHA-256 hash of the string that was specified with the association subcommand when the add-secret request was created.
serialnr: Optional. The serial number of the Crypto Express adapter as a case-sensitive ASCII string.
mingen: Optional. The only valid value is CEX8.

For Accel:

mingen: Optional. The only valid value is CEX8.

mkvp, serialnr, secretid

Ignored for Accel mode.

Common optional parameters

name: A name of your choice as an ASCII string. Must fit on one line. This is the string that was specified with the association subcommand when the add-secret request was created. If both a secretid and a name is given, the command checks that secretid = sha256(name).
description: A one-line description as an ASCII string.

Example configuration files

The following file defines an AP queue based on a Crypto Express adapter in Enterprise PKCS #11 coprocessor mode with a secret ID created by the pvsecret create command, a verification pattern, and serial number provided by the HSM domain administrator:

# A configuration file for an EP11
- mode: EP11
  mkvp: 0xdb3c3b3c3f097dd55ec7eb0e7fdbcb93
  serialnr: 93AADFK719460083
  secretid: 0x546869732069732061207665727920736563726574207365637265742069642e

The following file defines one accelerator.

# A configuration file for an accelerator
- name: my Accelerator
  mode: Accel
  mingen: CEX8

The following file defines a pair of virtual adapters in Enterprise PKCS #11 coprocessor mode with the same HSM master key and the same secret ID, but on different Crypto Express adapters.

# A configuration file for a backup pair
- name: my EP11 APQN 1
  mode: EP11
  mkvp: 0xdb3c3b3c3f097dd55ec7eb0e7fdbcb93
  serialnr: 93AADFK719460083
  secretid: 0x546869732069732061207665727920736563726574207365637265742069642e
- name: my EP11 APQN 2
  mode: EP11
  mkvp: 0xdb3c3b3c3f097dd55ec7eb0e7fdbcb93
  serialnr: 93AADHZU42082261
  secretid: 0x546869732069732061207665727920736563726574207365637265742069642e