Migrating master keys - pkcsep11_migrate utility

Edit online

There may be situations when the master key on (a domain of) a Crypto Express EP11 coprocessor (CEX*P) 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.

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 EP11 token. Use the tool described in this topic to perform this offline scenario.

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 versions 3.1 or later, which include 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 topic Setting up the TKE environment of Exploiting Enterprise PKCS #11 using openCryptoki.

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, read Exploiting Enterprise PKCS #11 using openCryptoki.

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 cryptographic coprocessor, 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 prefix 0), or hexadecimal (with prefix 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 installed 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 (/var/lib/opencryptoki/ep11tok/TOK_OBJ).