NAME

       pvapconfig - automatic configure APQNs within an SE KVM guest.

SYNOPSIS

       pvapconfig [OPTIONS]

DESCRIPTION

       pvapconfig is a tool for automatically configuring the APQNs within an Secure Execution KVM guest with AP
       pass-through  support.  Based  on  a given AP configuration it tries to find matching APQNs and binds and
       associates them with the given secret(s).

       Here is a description of pvapconfig's process:

       1. Check AP bus: Support for AP bus needs to be available and the AP
          bus needs to support APSB. APSB is only available within an KVM SE guest with AP pass-through support.

       2. Check Ultravisor: UV support needs to be available and the UV needs
          to support the list secrets feature.

       3. Read in and validate the AP configuration file. By default if not
          overwritten by the --config  option  the  AP  configuration  is  read  from  /etc/pvapconfig.yaml  and
          syntactically  verified.  See  section  CONFIGFILE  for  details  about the syntax and semantic of the
          configuration file.

       4. Fetch the list of association secrets from the UV. Actually the
          index of the secret and the secret id for each entry is collected. The secret value is NOT fetched  as
          it is NOT accessible but only usable within the UV firmware.

       5. Gather all APQNs available within this KVM SE guest. Collect
          information about each APQN like online states, crypto card serial numbers and master key verification
          patterns (MKVP).

       6. Go through all AP config entries. For each AP config entry try to
          find  an  APQN  which is already configured (bound/associated) to satisfy this config entry. If such a
          match is found, the AP config entry is assumed to be fulfilled and marked as done.

       7. All remaining APQNs which do not already satisfy an AP config entry
          are now examined for their bind and association state and maybe reset to unbound state.

       8. Go through all AP config entries which are still not
          fulfilled. For each such AP config entry try to search for an APQN which would match to this entry and
          then prepare this APQN (bind, maybe associate). If successful, mark the AP config entry as done.

       9. Evaluation of the applied AP config entries. Applied means the AP
          config entry has been fulfilled either in step 6 or in step 8. With the strict  option  given  ALL  AP
          config  entries  need  to apply otherwise an error message is printed and pvapconfig returns with exit
          failure.  If the strict option is not given, it is enough to satisfy at least one AP config entry from
          the configuration and pvapconfig will return successfully.

OPTIONS

       -c, --config <configfile>
               Use <configfile> as the AP config file for pvapconfig. If pvapconfig is run without  this  option
               the default configuration file /etc/pvapconfig.yaml is used.

       -h, --help
               Print pvapconfig usage information and exit.

       -n, --dry-run
               Do not bind, unbind or associate APQNs but only process the configuration and the available APQNs
               and secrets and simulate the bind, unbind or associate action on the chosen APQN. Use it together
               with the verbose option to see which actions pvapconfig would do if unleashed.

       -s, --strict
               All  AP  config  entries  need to be satisfied to have pvapconfig terminate with success. Without
               this option one applied AP config entry is enough to meet the expectations.

       -v, --verbose
               Print out informational messages about what pvapconfig is actually doing.

       -V, --version
               Print version information and exit.

CONFIGFILE

       The pvapconfig yaml configuration file consists of a list of AP config entries. Each entry may hold  this
       information:

       - mode: AP queue mode information, required, either "EP11" or "Accel".

       - mkvp: AP queue Master Key Verification Pattern (MKVP), required for
         EP11, hex string optional prepented with 0x. The MKVP hex string value may hold either 16 bytes (32 hex
         characters)  or  32  bytes (64 hex characters) but only the leftmost 16 bytes hold MKVP information and
         thus the rest is ignored.

       - serialnr: Crypto Card Serial Number, string, optional for EP11,
         ignored for Accel. As this is a real ASCII string uppercase and lowercase character(s) count different.

       - mingen: Card Minimal Generation, string "CEX4", "CEX5", "CEX6",
         "CEX7" or "CEX8" for Accelerator, string "CEC8" for EP11, optional.  If  given  specifies  the  minimal
         accepted Crypto card generation.

       - secretid: Secret id, hex string with optional 0x prepented, required
         for EP11, ignored for Accel. Details see the following text.

       - name: ASCII string, optional, but see details below.

       - description: Description of this AP config entry, string, ignored,
           just for convenience for the reader or editor of the configuration.

       The  secret  id  uniquely  identifies  an  association  secret.  However, it is a clumsy hex string of 64
       characters which represent the readable sha256 value over the secret's name. So pvapconfig  can  use  the
       name instead and calculate the secret id from the name. So the rule is:

       - If name and secretid is given, the secretid needs to match to the
         sha256 hash over the given name for this AP config entry.

       - If only name is given then the secretid is calculated with a sha256
           hash over the given name.

       - If only the secretid is given, there is nothing more to do but
         verify that the value is a hex string with 64 characters.

LOCKING

       Pvapconfig  needs  to  have  a  consistent  view  of the AP resources during lifetime. There must not run
       multiple instances of pvapconfig or any manipulations of the AP resources in  parallel.  To  prevent  the
       execution  of  multiple  pvapconfig  instances  the lock file /run/lock/pvapconfig.lock is established. A
       second instance of pvapconfig will detect this lock file and terminated with an error message. If for any
       reason this file still exists as a leftover from a previous pvapconfig crash for example, it needs to get
       removed by hand. The lock file contains the process id of the pvapconfig process which created this file.

RETURN VALUE

       0 - Successful termination.
               At least one AP config entry has been applied or at least one APQN has  been  found  in  a  state
               matching  to  one  AP  config  entry.  If strict option is given, ALL AP config entries have been
               applied. An AP config entry is applied either by configuring the APQN accordingly or an APQN  has
               been found which already fulfills the constrains.

       1 - Failure.
               Either  some  kind  of  failure happened during processing the configuration or the configuration
               could not get applied successful. In all cases pvapconfig prints out a message to standard  error
               with  details  about  the failure. Also pvapconfig does NOT reset the APQNs to the state found at
               the startup when failing to apply the configuration.

NOTES

       For more information and details see the IBM documentation about Confidential Computing "Introducing  IBM
       Secure Execution for Linux" available at https://www.ibm.com/docs/.

SEE ALSO

       pvsecret(1), lszcrypt(8), chzcrypt(8)

s390-tools                                          DEC 2023                                       PVAPCONFIG(1)