NAME

       pkcshsm_mk_change  - utility to manage and control the re-enciphering of secure keys for a
       concurrent HSM master key change for openCryptoki.

SYNOPSIS

       pkcshsm_mk_change command [OPTIONS]

       pkcshsm_mk_change --help|-h

DESCRIPTION

       Manages and controls the re-enciphering of secure keys for a  concurrent  HSM  master  key
       change  for  openCryptoki.  Secure  keys  are  encrypted by the HSM master key(s). The HSM
       master key(s) must be changed (rolled) from time to time, dependent on policies defined by
       the  HSM  security officer. Whenever a HSM master key is changed, all secure keys that are
       encrypted with that HSM master key must be re-enciphered with the new  to  be  set  master
       key.

       Changing  HSM  master keys needs to be coordinated between the HSM security officer and an
       openCryptoki administrator. The HSM security officer performs a master key change via  the
       TKE  (Trusted  Key  Entry),  while  the openCryptoki administrator performs administrative
       steps using the pkcshsm_mk_change tool to re-encipher all openCryptoki token  and  session
       key  objects, as well as currently active crypto operation states with the new master key.
       Applications using those keys can continue to run, the re-enciphering process takes  place
       transparently to them.

       A concurrent master key change works as follows:

         1. The  HSM  security  officer  loads  the  new  master  keys using the TKE into the NEW
            register of the set of APQNs logically belonging together.

         2. The HSM security officer notifies the openCryptoki administrator that new master keys
            have been loaded for all the APQNs.

         3. The  openCryptoki  administrator  uses the pkcshsm_mk_change to initiate a master key
            change for openCryptoki, specifying the set of APQNs (and master key types) that  are
            to  be changed. The pkcshsm_mk_change tool communicates with running applications and
            performs/controls re-encipherment of the key objects with the new master key.

         4. When the pkcshsm_mk_change tool has completed  its  re-encipherment  processing,  the
            openCryptoki  administrator  notifies  the  HSM security officer that openCryptoki is
            ready to set/activate the new master keys.

         5. The HSM security officer coordinates with other (non-openCryptoki)  applications  and
            once  all  users  of  the  APQNs are OK, he sets/activates the new master keys on the
            APQNs.

         6. The HSM security officer notifies the openCyptoki administrator when  for  all  APQNs
            the new master key have been set/activated.

         7. The openCryptoki administrator uses the pkcshsm_mk_change tool to finalize the master
            key change for openCryptoki. The tool  communicates  with  running  applications  and
            performs/controls  finalizing  the  re-encipherment  of  the key objects with the new
            master key.

         8. When the pkcshsm_mk_change tool has completed its finalizing processing,  the  master
            key change operation is complete.

       The  whole procedure can take an arbitrary amount of time. Especially the time between the
       moment when the new master key has been loaded on all APQNs, and the moment the new master
       keys  are  set/activated can even last several days, due to time required for coordination
       with other (non-openCryptoki) applications/users of the APQNs to prepare  for  the  master
       key change.

       The  time  to  perform  the  re-encipherment  and  finalization (steps 3 and 7) of all key
       objects as such depends on the amount of keys and openCryptoki  applications  using  them,
       but is usually relatively short, i.e. seconds up to a few minutes.

       The  system where openCryptoki runs may be restarted while a master key change is ongoing,
       provided that the  re-encipherment  and  finalization  steps  (steps  3  and  7)  are  not
       interrupted.

       An  ongoing  master key change operation can be canceled using the pkcshsm_mk_change tool,
       as long as for none of the APQNs the new master key has been set/activated, that is up  to
       step 5 from above.

COMMANDS

   Initiate a master key change for openCryptoki
       pkcshsm_mk_change  reencipher  [--apqns|-a APQNS] [--ep11-wkvp|-e WKVP] [--cca-sym-mkvp|-s
       MKVP]  [--cca-asym-mkvp|-S  MKVP]  [--cca-aes-mkvp|-A  MKVP]   [--cca-apka-mkvp|-p   MKVP]
       [--verbose|-v LEVEL]

       Use  the  reencipher  command  to initiate a master key change operation for the specified
       APQNs and master key types and re-encipher all  session  and  token  key  objects  of  the
       affected tokens. For each master key type that is changed, the verification pattern of the
       new, to be set master key must be specified.

       A CryptoExpress adapter in CCA coprocessor mode has 4 different master  keys:  SYM,  ASYM,
       AES, and APKA. The CCA token of openCryptoki only uses SYM, AES, and APKA. Each master key
       type can be change individually, or together with others. You  can  use  the  TKE  or  the
       panel.exe  tool  to  query  the  master  key  verification patterns: 'panel.exe --mk-query
       --mktype=<type> --mkregister=NEW'.  For master key types SYM and ASYM, use the hex  string
       under  [RND],  for types AES and APKA use the hex string under [VER]. For AES and APKA you
       can   also   find   the   master   key    verification    patterns    in    sysfs:    'cat
       /sys/bus/ap/devices/<card>.<domain>/mkvps'.

       A  CryptoExpress adapter in EP11 coprocessor mode has only one master key, called the EP11
       wrapping key (WK). You can use the TKE or the ep11info tool to query the current  wrapping
       key  verification  pattern (WKVP) of an EP11 APQN: 'ep11info -m <adapter> -d <domain> -D'.
       You can also find the wrapping key verification pattern for  EP11  APQNs  in  sysfs:  'cat
       /sys/bus/ap/devices/<card>.<domain>/mkvps'.

       the  pkcshsm_mk_change  reencipher command will query all available slots and determine if
       the token in the slot is affected by the master key change, based on the list of APQNs and
       master key types. For each affected slot, it prompts for the USER pin.

       On successful completion, the id of the master key change operation is displayed.  This id
       must later be specified when finalizing or canceling the operation using the  finalize  or
       cancel command.

   Finalize a master key change for openCryptoki
       pkcshsm_mk_change finalize [--id|-i OPERATION-ID] [--verbose|-v LEVEL]

       Use the finalize command to finalize a master key change operation when the new master key
       has been activated on the APQNs. The id of the master key  change  operation  to  finalize
       must be specified.

   Cancel a master key change for openCryptoki
       pkcshsm_mk_change cancel [--id|-i OPERATION-ID] [--verbose|-v LEVEL]

       Use  the  cancel  command to finalize a master key change operation.  The id of the master
       key change operation to cancel must be specified.  A master key change operation can  only
       be canceled as long as for none of the APQNs the new master key have been set/activated.

   List master key change operations
       pkcshsm_mk_change list [--id|-i OPERATION-ID] [--verbose|-v LEVEL]

       Use  the  list  command  to  list  currently  active  master  key change operations. If no
       operation ID  is  specified,  all  currently  active  master  key  change  operations  are
       displayed, otherwise only the specified one is displayed.

OPTIONS

       -a, --apqns APQNS
              Specifies  a  comma  separated list of APQNs for which a master key change is to be
              performed. Each APQN must be specified in the form  card.domain,  where  both  card
              and  domain  are  in  hex, as displayed by the lszcrypt command. Multiple APQNs are
              separated by a comma.  This options is only valid with the reencipher command.

       -e, --ep11-wkvp WKVP
              Specifies the EP11 wrapping key verification pattern (WKVP) of the new, to  be  set
              EP11  wrapping  key  as a 16 bytes hex string.  This options is only valid with the
              reencipher command.  You can use the TKE or the ep11info tool to query the  current
              wrapping key verification pattern (WKVP) of an EP11 APQN: 'ep11info -m <adapter> -d
              <domain> -D'.  You can also find the wrapping key  verification  pattern  for  EP11
              APQNs in sysfs: 'cat /sys/bus/ap/devices/<card>.<domain>/mkvps'.

       -s, --cca-sym-mkvp MKVP
              Specifies  the CCA master key verification pattern (MKVP) of the new, to be set CCA
              SYM master key as a 8 bytes hex string.   This  options  is  only  valid  with  the
              reencipher  command.  You can use the TKE or the panel.exe tool to query the master
              key verification patterns: 'panel.exe  --mk-query  --mktype=SYM  --mkregister=NEW'.
              Use the hex string under [RND].

       -S, --cca-asym-mkvp MKVP
              Specifies  the CCA master key verification pattern (MKVP) of the new, to be set CCA
              ASYM master key as a 8 bytes hex string.  This  options  is  only  valid  with  the
              reencipher  command.  You can use the TKE or the panel.exe tool to query the master
              key verification patterns: 'panel.exe --mk-query  --mktype=ASYM  --mkregister=NEW'.
              Use the hex string under [RND].

       -A, --cca-aes-mkvp MKVP
              Specifies  the CCA master key verification pattern (MKVP) of the new, to be set CCA
              AES master key as a 8 bytes hex string.   This  options  is  only  valid  with  the
              reencipher  command.  You can use the TKE or the panel.exe tool to query the master
              key verification patterns: 'panel.exe  --mk-query  --mktype=AES  --mkregister=NEW'.
              Use  the hex string under [VER].  You can also find the AES master key verification
              patterns in sysfs: 'cat /sys/bus/ap/devices/<card>.<domain>/mkvps'.

       -p, --cca-apka-mkvp MKVP
              Specifies the CCA master key verification pattern (MKVP) of the new, to be set  CCA
              APKA  master  key  as  a  8  bytes hex string.  This options is only valid with the
              reencipher command.  You can use the TKE or the panel.exe tool to query the  master
              key  verification  patterns: 'panel.exe --mk-query --mktype=APKA --mkregister=NEW'.
              Use the hex string under [VER].  You can also find the APKA master key verification
              patterns in sysfs: 'cat /sys/bus/ap/devices/<card>.<domain>/mkvps'.

       -i, --id OPERATION-ID
              Specifies  the  id  of the master key change operation for the finalize, cancel, or
              list command. On successful completion of the reencipher command,  the  id  of  the
              master key change operation is displayed.

       -v, --verbose LEVEL
              Specifies  the  verbose level (optional): none (default), error, warn, info, devel,
              or debug.

       -h, --help
              Displays help text and exits.

SEE ALSO

       opencryptoki(7)