IBM Cloud Docs
Initializing service instances with smart cards and the Management Utilities

Initializing service instances with smart cards and the Management Utilities

Before you can use your Hyper Protect Crypto Services instance, you need to first initialize your service instance by loading the master key. Initialize your service instance by using smart cards and the Hyper Protect Crypto Services Management Utilities with the steps that are provided.

For an introduction to the approaches of service instance initialization and the related fundamental concepts, see Initializing service instances and Introducing service instance initialization approaches.

The Hyper Protect Crypto Services Management Utilities use smart cards to hold signature keysAn encryption key that is used by the crypto unit administrator to sign commands that are issued to the crypto unit. and master key parts. You need to complete the tasks in Setting up smart cards and the Management Utilities before you can complete the steps in this task.

You can also watch the following video to learn how to initialize Hyper Protect Crypto Services instances with smart cards and the Management Utilities:

It is your responsibility to secure assets used to initialize the Hyper Protect Crypto Services instance. For best practices, see the FAQ.

Before you begin

  1. Make sure that you set up the Management Utilities.

  2. Complete the prerequisite steps before you initialize your service instance.

  3. Plug the two smart card readers into the USB ports of your workstation.

  4. Start the Trusted Key Entry application by changing to the subdirectory where you install the Management Utilities applications and running the following command:

    ./tke
    

Loading the master key from the smart cards

Crypto units that are assigned to an IBM Cloud user start in a cleared state that is known as imprint modeAn operational mode in which crypto units are assigned to a user.. To load the master key from the smart cards, complete the following steps with the Trusted Key Entry application:

Step 1: Generate the signature keys and master key parts

If you have created signature keys and master key parts with the TKE CLI plug-in on your workstation, you can copy them to smart cards instead of generating new keys. To do so, on the Smart card tab, click Copy signature key file or Copy key part file and follow the instructions. During the process, you need to provide the password for the key file.

  1. To generate a signature key for an administrator, select the Smart card tab, and click Generate signature key.

    When prompted, insert an EP11 smart card in smart card reader 2. Enter a name for the administrator, and enter the personal identification number (PIN) for the smart card on the smart card reader PIN pad.

    An administrator signature key is generated and stored on the smart card. Each smart card can contain only one signature key. If you want to set up multiple administrators, repeat this step by using different EP11 smart cards.

  2. To generate the master key parts for service instance initialization, on the Smart card tab, click Generate key part.

    If prompted, insert an EP11 smart card in smart card reader 2 and enter the smart card PIN. Enter a description for the key part.

    A random master key part is generated and stored on the smart card.

    To create more master key parts, repeat this step.

    You need to generate at least two master key parts to load a master key. For added security, you can generate a maximum of three master key parts. To improve security, you can choose to generate signature keys and master key parts on separate smart cards and assign each smart card to a different person. For more information, see Smart card setup recommendations.

  3. (Optional) If you want to create a backup copy of an EP11 smart card, click Copy smart card on the Smart card tab and follow the prompts.

Step 2: Select the crypto units where the master key is to be loaded

Select the Crypto units tab. A list of crypto unitsA single unit that represents a hardware security module and the corresponding software stack that is dedicated to the hardware security module for cryptography. in the target resource group under the current user account is displayed. The SELECTED column shows what crypto units you're going to work with in later commands.

For more information about how to retrieve your service instance ID, see Retrieving your instance ID.

  • To select extra crypto units to work with, click Add crypto units and enter the CRYPTO UNIT NUM (crypto unit numbers) of the extra crypto units you want to work with. You can enter multiple crypto unit numbers, which are separated by a space.
  • To remove crypto units from the set you're going to work with, click Remove crypto units and enter the CRYPTO UNIT NUM of the crypto units you want to remove. You can enter multiple crypto unit numbers, which are separated by a space.

When the operations are done, true is displayed in the SELECTED column for each crypto unit that is to be affected by later commands. If more than one crypto unit is assigned to a service instance, all crypto units in the service instance must be configured the same.

If you enable cross-region high availability with failover crypto units, make sure that you add all the failover crypto units to the selected list for instance initialization.

If you don't initialize and configure failover crypto units the same as the operational crypto units, you are not able to use the failover crypto units for automatic data restoration when a regional disaster happens. For more information about cross-region disaster recovery, see High availability and disaster recovery.

Step 3: Add administrators to the selected crypto units

The command to load a master key must be signed by an administrator that is predefined to the crypto unit. This step predefines an administrator.

  1. Select the Administrators tab. This tab displays a list of administrators that are allowed to sign commands to the crypto unit.
  2. Click Add administrator.
  3. When prompted, insert the EP11 smart card that holds that administrator signature key in smart card reader 1, and enter the PIN on the smart card reader PIN pad.

The public signature key and administrator name are read from the smart card and installed in the crypto unit. When the operation is done, the administrator's name is displayed in the ADMIN NAME field of the selected crypto units.

For security and compliance reasons, the administrator name of the crypto unit might be shown up in logs for auditing purposes.

Repeat this step if you want to add multiple administrators. The number of administrators that are added must be equal to or greater than the larger of the following values:

  • The signature threshold value. The signature threshold controls how many signatures are needed to run most administrative commands.
  • The revocation signature threshold value that you intend to set in Step 4. The revocation signature threshold controls how many signatures are needed to remove an administrator.

Do not remove the administrator signature keys from your smart cards. Otherwise, you are not able to perform TKE actions that need to be signed, such as zeroizing crypto units and rotating master keys.

If you want to remove the administrator in a later phase, click Remove Administrator.

Step 4: Set the signature thresholds to exit imprint mode in the selected crypto units

When crypto units in service instances are assigned to a user, they begin in a cleared state that is called imprint mode. In imprint mode, most operations on the crypto unit are disabled. To load the master key in a crypto unit, first exit imprint mode by setting the signature thresholds to a value greater than zero.

  1. To set the signature thresholds, select the Signature thresholds tab and click Change signature thresholds.
  2. When prompted, enter the new signature threshold value and the new revocation signature threshold value.  The values must be numbers between one and eight and do not need to be the same. The signature threshold controls how many signatures are needed to run most administrative commands. The revocation signature threshold controls how many signatures are needed to remove an administrator after you leave imprint mode. Some commands need only one signature, regardless of how the signature threshold is set.
  3. If prompted, insert an EP11 smart card with an administrator signature key that is defined to the selected crypto units in smart card reader 1. And then, enter the smart card PIN on the smart card reader PIN pad. Repeat this operation if prompted for more EP11 smart cards with signature keys. When the crypto unit exits imprint mode, the number of signatures that are needed for this command is the new signature threshold value.

After the signature threshold values are set, the new values are displayed on the Signature thresholds page. Setting the signature thresholds to a value greater than one enables quorum authentication from multiple administrators for sensitive operations.

When an EP11 smart card with a valid administrator signature key is inserted in smart card reader 1 and the PIN is entered, the smart card can be used to sign multiple commands. In Step 5, if the reader contains an EP11 smart card with a valid signature key and the PIN is entered, you're not prompted to insert an EP11 smart card with a signature key in smart card reader 1.

Step 5: Load the master key

For more information about the state transition of the master key register, see Understanding how master key is loaded.

Load the new master key register

  1. Select the Master keys tab and click Load.
  2. If prompted, insert an EP11 smart card with an administrator signature key that is defined to the selected crypto units in smart card reader 1. And then, enter the smart card PIN on the smart card reader PIN pad.
  3. When prompted, enter the number of master key parts to be loaded. Only 2 or 3 master key parts are accepted.
  4. When prompted, insert the EP11 smart card that contains the first master key part in smart card reader 2 and enter the smart card PIN on the smart card reader PIN pad.
  5. Select the master key part to be loaded from the list of master key parts on the smart card.
  6. Repeat substep 4 and 5 for each master key part to be loaded.
  7. If prompted, in smart card reader 1, insert the EP11 smart card with an administrator signature key that is defined to the selected crypto units, and enter the smart card PIN on the smart card reader PIN pad.

After all master key parts are loaded, the new master key register is in Full uncommitted state.

Commit the new master key register

Make sure that you complete this step immediately after the previous step to move the new master key register to the Full committed state. Otherwise, you will not be able to initialize your service instance or perform cryptographic operations with GREP11 API or PKCS #11 API.

  1. Click Commit to move the master key to the Full committed state.
  2. If prompted, in smart card reader 1, insert an EP11 smart card with an administrator signature key that is defined to the selected crypto units and enter the smart card PIN on the smart card reader PIN pad. Repeat this operation if prompted for more EP11 smart cards with signature keys.

After the process is complete, the new master key register is in Full committed state.

Activate the master key

Perform this step only when you are setting up a service instance for the first time and the key storage is empty. This command changes the value in the current master key register. If this command is run when key storage contains keys, and those keys are encrypted by using a master key value that is different from the value that is placed in the current master key register by this command, the keys in key storage become unusable.

  1. Click Set immediate to move the value of the new master key register to the current master key register and clear the new master key register.
  2. Click Yes if you are ready to move the master key to the current master key register. This action can't be reversed.
  3. If prompted, insert an EP11 smart card with an administrator signature key that is defined to the selected crypto units in smart card reader 1. And then, enter the smart card PIN on the smart card reader PIN pad.

The crypto units in the current master key register is now in Valid status, which indicates that your master key is loaded to your service instance.

If you want to clear your current master key in a later phase, click Clear current.

What's next