Cloning master keys

Master key cloning is a method for securely copying a master key from one Cryptographic Coprocessor to another without exposing the value of the master key. If you are using multiple coprocessors with TLS on your system running the IBM i operating system, use the Cryptographic Coprocessor configuration Web-based utility to clone master keys.

This is performed by a process of splitting the master key into n shares, where n is a number from 1 to 15. m shares are required to rebuild the master key in another Coprocessor, where m is a number from 1 to 15 and less than or equal to n.

The term "cloning" is used to differentiate the process from "copying" because no one share, or any combination of fewer than m shares, provide sufficient information needed to rebuild the master key.

The Coprocessor containing the master key to be cloned is referred to as either the master-key-share source node or the Sender. The Sender must generate a retained RSA key pair. This private key must also have been marked as suitable for use with cloning when it was generated. The key is known as either the Coprocessor Share Signing key or the Sender key. The Coprocessor that will receive the master key is referred to as either the master-key-share target node or the Receiver. The Receiver must also generate a retained RSA key pair and must also have been marked as suitable for use with cloning. This key is known as either the Coprocessor Share Receiving key or simply the Receiver key.

Both the Sender and Receiver public keys must be digitally signed or certified by a retained private key in a Coprocessor, referred to as the public key certifying node or the Certifier. This retained private key is the Certifier key. It is also referred to as the Share Administration key. The associated public key must be registered in both the Sender and the Receiver before shares can be generated and received. A Cryptographic Coprocessor can take on the role of Certifier only, or can it be both Certifier and Sender, or it can be both Certifier and Receiver.

As each share is generated it is signed by the Coprocessor using the Sender private key and encrypted by a newly generated triple DES key. The triple DES key is then wrapped or encrypted by the Receiver public key.

As each share is received, the signature on the share is verified using the Sender public key, the triple DES key is unwrapped or decrypted using the Receiver private key, and the share decrypted using the triple DES key. When m number of shares have been received, the cloned master key will be complete within the new master key register of the Receiver.

The easiest and fastest way to clone master keys is to use the Cryptographic Coprocessor configuration web-based utility. The utility includes the Master key cloning advisor. To start the master key cloning advisor, follow these steps:

  1. Click on Manage configuration on the Cryptographic Coprocessor configuration page.
  2. Click on Master keys.
  3. Select a device.
  4. Enter a valid Coprocessor profile and password.
  5. Click on the Clone button.

If you would prefer to write your own application to clone master keys, you can do so by using the following API verbs:

  • Cryptographic_Facility_Control (CSUACFC)
  • PKA_Key_Token_Build (CSNDPKB) (may not be needed depending upon how you write your application)
  • PKA_Key_Generate (CSNDPKG)
  • PKA_Public_Key_Register (CSNDPKR)
  • One_Way_Hash (CSNBOWH)
  • Digital_Signature_Generate (CSNDDSG)
  • Master_Key_Distribution (CSUAMKD)

Example programs

Nine pairs of example programs are provided for your consideration. Each pair contains a program written in ILE C and a program written in ILE RPG. Both perform the same function.

Note: Read the Code license and disclaimer information for important legal information.