Ubuntu Manpage: pkcshsm_mk_change - utility to manage and control the re-enciphering of secure keys for a concurrent HSM

Provided by: opencryptoki_3.24.0+git20250128.0462717+dfsg-0ubuntu1_amd64

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. Important: CCA does not support the concept of APQNs when
running on AIX, Linux on x64, and Linux on Power; whenever an APQN is being used as input, the user must
specify the value 0.0.

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.

NAME

SYNOPSIS

DESCRIPTION

COMMANDS

OPTIONS

SEE ALSO