Migrate to a new CCA master key - pkcscca utility

If you need to migrate a CCA key to a new wrapping CCA master key (MK), use the pkcscca tool.

Before you begin

Prerequisite for using the key migration function is that you have installed openCryptoki version 3.4 or higher.

About this task

There may be situations when CCA master keys must be changed. With openCryptoki, you can choose between a concurrent master key change described in Managing a concurrent master key change - pkcshsm_mk_change utility or an offline master key change where you need to stop all openCryptoki applications that access the CCA token. Use the tool described in this topic to perform this offline scenario.

All CCA secret and private keys are enciphered (wrapped) with a master key (MK). After a CCA master key is changed, the keys wrapped with an old master key need to be re-enciphered with the new master key. Only keys which are marked as CKA_EXTRACTABLE=TRUE can be migrated. However, by default all keys are marked as CKA_EXTRACTABLE. So only those keys where the user explicitly chooses to mark them as non extractable, for example, by setting CKA_EXTRACTABLE=FALSE cannot be migrated.

Use the pkcscca tool to migrate wrapped CCA keys.

After a new master key is loaded and set, perform the following steps:

Procedure

Stop all processes that are currently using openCryptoki with the CCA token.
1. Stop all applications that use openCryptoki.
2. Find out whether the pkcsslotd daemon is running by issuing one (or both to cross-check) of the following commands:
```
$ systemctl status pkcsslotd    /* for Linux distributions providing systemd */
$ ps awx | grep pkcsslotd
```
  If the daemon is running, the command output shows a process for pkcsslotd.
3. If applicable, stop the daemon by issuing a command of this form:
```
$ systemctl stop pkcsslotd.service /* for Linux distributions providing systemd */
```
Back up the token object repository of the CCA token. For example, you can use the following commands:
```
cd /var/lib/opencryptoki/cca/
      tar -cvzf ~/cca/TOK_OBJ_backup.tgz TOK_OBJ
```
Migrate the keys of the CCA token object repository with the pkcscca migration tool.
```
pkcscca -m keys -s <slotid> -k <aes|apka|asym|sym>
```
Specify the following parameters:

-s

slot number for the CCA token

-k

master key type to be migrated: aes, apka, asym, or sym

-m keys

re-encipers private keys only with a new CCA master key.

All the specified token objects representing extractable keys that are found for the CCA token are re-encrypted and ready for use. Keys with an attribute CKA_EXTRACTABLE=FALSE are not eligible for migration. The keys that failed to migrate are displayed to the user.
Example:
```
$ pkcscca -m keys -s 2 -k sym
```
migrates all private keys wrapped with symmetric master keys found in the CCA plug-in for openCryptoki in PKCS slot 2.
Re-start the previously stopped openCryptoki processes.
Start or restart pkcsslotd if it was stopped in step 1.

Results

All specified keys, for example, all private and secret keys (for asymmetric and symmetric cryptography) are now re-encrypted with the new CCA master key and are ready for use in CCA verbs.