Migrating master keys with the pkcsep11_migrate tool

There may be situations when the master key on (a domain of) a CEX*P adapter must be changed, for example, if company policies require periodic changes of all master keys. Simply changing the master keys using the TKE results in all secure keys stored in the EP11 token to become useless. Therefore all data encrypted by these keys are lost. To avoid this situation, you must accomplish a master key migration process, where activities on the TKE and on the Linux® system must be interlocked.

Per default, the EP11 token stores all token key objects in the Linux file system in the /var/lib/opencryptoki/ep11tok/TOK_OBJ directory. For information about using multiple EP11 token instances, see Adding EP11 tokens to openCryptoki.

All secret and private keys are secure keys, that means they are enciphered (wrapped) with the master key (MK) of the CEX*P adapter domain. Therefore, the master key is often also referred to as wrapping key. If master keys are changed in a domain of a CEX*P adapter, all key objects for secure keys in the EP11 token object repository become invalid. Therefore, all key objects for secure keys must be re-enciphered with the new MK. In order to re-encipher secure keys that are stored as EP11 key objects in the EP11 token object repository, openCryptoki provides the master key migration tool pkcsep11_migrate.

How to access the master key migration tool

The pkcsep11_migrate key migration utility is part of openCryptoki version 3.1, which includes the EP11 support.

Prerequisites for the master key migration process

The master key migration process for the EP11 token requires a TKE version 7.3 environment. How to set up this environment is described in Setting up the TKE environment.

To use the pkcsep11_migrate migration tool, the EP11 crypto stack including openCryptoki must be installed and configured. For information on how to set up this environment, refer to Building the EP11 crypto stack.

The master key migration process

Prerequisite for re-encipherment: The EP11 token may be configured to use more than one adapter/domain pair to perform its cryptographic operations. This is defined in the EP11 token configuration file. If the EP11 token is configured to use more than one adapter/domain pair, then all adapter/domain pairs must be configured to each have the same set of master keys. Therefore, if a master key on one of these adapter/domain pairs is changed, it must be changed on all those other adapter/domain pairs, too.

To migrate master keys on the set of adapter/domain pairs used by an EP11 token, you must perform the following steps:

On the TKE workstation (TKE), submit and commit the same new master key on all CEX*P adapter/domain combinations used by the EP11 token.
On Linux, stop all processes that are currently using openCryptoki with the EP11 token.
On Linux, back up the token object repository of the EP11 token. For example, you can use the following commands:
```
cd /var/lib/opencryptoki/ep11
tar -cvzf ~/ep11TOK_OBJ_backup.tgz TOK_OBJ 
```
On Linux, migrate the keys of the EP11 token object repository with the pkcsep11_migrate migration tool (see the invocation information provided at the end of these process steps). The pkcsep11_migrate tool must only be called once for one of the adapter/domain pairs that the EP11 token uses. If a failure occurs, restore the backed-up token repository and try this step again.
Attention: Do not continue with step 5 unless step 4 was successful. Otherwise you will lose your encrypted data.
On the TKE, activate the new master keys on all EP11 adapter/domain combinations that the EP11 token uses.
On Linux, restart the applications that used openCryptoki with the EP11 token.

In step 1 of the master key migration process, the new master key must be submitted and committed via the TKE interface. That means the new EP11 master key must be in the state Full Committed. The current MK is in the state Valid. Now both (current and new) EP11 master keys are available and accessible. The utility can now decrypt all relevant key objects within the token and re-encrypt all these key objects with the new master key.

Note: All the decrypt and encrypt operations are done inside the EP11 coprocessor card, that means that at no time clear key values are visible within memory.

Invocation:

pkcsep11_migrate -slot <number> -adapter <number>
-domain <number>

The following parameters are mandatory:

-slot: - slot number for the EP11 token
-adapter: - the card ID; can be retrieved form the card ID in the sysfs (to be retrieved from /sys/devices/ap/cardxx, or with lszcrypt.
-domain: - the decimal card domain number (to be retrieved from /sys/bus/ap/ap_domain or with lszcrypt -b)

All token objects representing secret or private keys that are found for the EP11 token, are re-encrypted.

Note: The adapter and domain numbers can be specified in decimal, octal (with suffix 0), or hexadecimal (with suffix 0x) notation. The lszcrypt utility displays these fields in hexadecimal values.

Usage: You are prompted for your user PIN.

Examples:


pkcsep11_migrate  -slot 2 -adapter 8 -domain 48
pkcsep11_migrate  -slot 0x2 -adapter 010 -domain 0x30

Both invocations migrate the master key for the cryptographic coprocessor 8 (octal 010) and domain 48 (hex 0x30) used by the EP11 token from slot 2.

Note: The program stops if the re-encryption of a token object fails. In this case, restore the back-up.

After this utility re-enciphered all key objects, the new master key must be activated. This activation must be done by using the TKE interface command Set, immediate. Finally, the new master key becomes the current master key and the previous master key must be deleted.

Note: This tool is embedded in the users sbin path and therefore callable from everywhere.

To prevent token object generation during re-encryption, openCryptoki with the EP11 token must not be running during re-encryption. It is recommended to make a back-up of the EP11 token object directory (/usr/local/var/lib/opencryptoki/ep11tok/TOK_OBJ).