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)