Load and set a master key

After you load a function control vector, load and set the master key. You can use your master key to encrypt other keys.

After you load a function control vector, you can load and set a master key. The Coprocessor uses the master key to encrypt all operational keys. The master key is a special key-encrypting key stored in the clear (not encrypted) within the Coprocessor secure module. Your Coprocessor uses the master key to encrypt other keys so that you can store those keys outside of your Coprocessor. The master key is a 168-bit key formed from at least two 168-bit parts exclusive ORed together.

Note: Read the Code license and disclaimer information for important legal information.
Related concepts
Load a function control vector

Loading a master key

There are three registers for your master keys: New, Current®, and Old. The new master key register is used to hold a pending master key while it is being built. It is not used to encrypt any keys. The Current master key register holds the master key that is currently being used to encrypt newly generated/imported/re-enciphered keys. The old master key register holds the previous master key. It is used to recover keys after a master key change has occurred. When you load a master key, the Coprocessor places it into the New master key register. It remains there until you set the master key.

Choose one of these three ways to create and load a master key, based on your security needs:
  • Load the first key parts and the subsequent key parts separately to maintain split knowledge of the key as a whole. This is the least secure method, but you can increase security by giving each key part to a separate individual.
  • Use random key generation, which will remove any human knowledge of the key. This is the most secure method for loading a master key, but you will need to clone this randomly generated master key into a second Cryptographic Coprocessor in order to have a copy of it.
  • Use a pre-existing master key by cloning it from another Coprocessor.
Related information
IBM PCI Cryptographic Coprocessor documentation library

Setting a master key

Setting the master key causes the key in the Current master key register to move to the Old master key register. Then, the master key in the New master key register moves to the Current master key register.

Note: It is vital for retrieval of data encrypted by the master key that you have a backup copy of the master key at all times. For example write it on a piece of paper, and make sure that you store the backup copy with appropriate security precautions. Or, clone the master key to another Coprocessor.

The easiest and fastest way to load and set master keys is to use the Cryptographic Coprocessor configuration web-based utility found off of the System Tasks page at http://server-name:2001. The utility includes the Basic configuration wizard that is used when the Coprocessor is in an un-initialized state. If the Cryptographic Coprocessor already has been initialized, then click on Manage configuration and then click on Master keys to load and set master keys.

If you would prefer to write your own application to load and set master keys, you can do so by using the Master_Key_Process (CSNBMKP) API verb.

Related reference
Example: ILE C program for loading a master key into your Cryptographic Coprocessor
Example: ILE RPG program for loading a master key into your Cryptographic Coprocessor

Re-encrypting keys

When you set a master key, you should re-encrypt all keys that were encrypted under the former master key to avoid losing access to them. You must do this before you change and set the master key.

You can re-encrypt keys in key store by using the Cryptographic Coprocessor configuration web-based utility found off of the System Tasks page at http://server-name:2001. The Cryptographic Coprocessor must have already been initialized. Click on "Manage configuration" and then click on either "DES keys" to re-encrypt DES keys, or "PKA keys" to re-encrypt PKA keys.

If you have keys that are not in key store or if you would prefer to write your own application to re-encrypt keys, you can do so by using the Key_Token_Change (CSNBKTC) or PKA_Key_Token_Change (CSNDKTC) API verbs.

An example program is provided for your consideration.

Related reference
Example: ILE C program for re-encrypting keys for your Cryptographic Coprocessor