Hyper Protect Crypto Services Demo
Setting up Hyper Protect Crypto Services requires an understanding of the tools’ security features. However, with an understanding of a few key concepts, the actual setup process is straightforward. Broadly, the process is as follows:
- Provision the Crypto Units that power HPCS on IBM Cloud.
- Initialize those Crypto Units by creating a master key through the IBM Cloud Command Line Interface.
- Connect to your HPCS instance on the cloud to manage vaults, keystores, and keys.
Part 1: Provisioning the Crypto Service
You can find the offering page for Hyper Protect Crypto Services here: https://cloud.ibm.com/catalog/services/hyper-protect-crypto-services.
STEP 1—Choose your Plan Type
The first major choice to make when provisioning your Hyper Protect Crypto Services Instance is whether to include the Unified Key Orchestrator feature. This feature enables cross-cloud key management, so make sure to choose UKO for a multi-cloud setup! The setup process for both the standard plan and the UKO add-on are the same, but the use cases will vary. For this demo, we will use the UKO add-on to demonstrate the multi-cloud Vaults feature.
STEP 2—Choose your Region
The next major consideration is the host region and whether you wish to utilize cross-region failover units. As of April 2023, we host Crypto Services instances in Asia Pacific (Tokyo); Europe (Frankfurt, London, Madrid); North America (Dallas, Toronto, Washington DC); and South America (Sao Paulo). You can host groups of 2 or 3 crypto units in any one of these regions for high availability.
Currently, cross-region failover units are only enabled for the Dallas and Washington DC regions (one unit hosted in each region). If you want to utilize cross-region backups of your crypto units, you must host your service in these two regions.
STEP 3—Instance Details
Once you’ve made these two major considerations, finish the provisioning process by selecting a name, a resource group, and any tags, then selecting ‘Create.’
The service instance may take several minutes to provision. You can find your service instance in the Security tab on the IBM Cloud resource list. Once provisioning is complete and your service is active, you may move on to part 2.
Part 2: Initializing the Service Instance
Initializing the service instance entails creating and loading the master key you’ll use to interact into the service, as well as setting up some security features. There are several methods to initialize your service instance. The most secure method utilizes environments physical smart cards and a smart card reader. In this method, you store your master key onto the smart card and scan that card to grant access to the service.
Smart cards are our official recommendation for production, and you can find out more by consulting with an IBM Cloud expert. In this demo, we will follow another option—storing the master key on your own workstation card using key part files.
STEP 1—Connect to your Instance
Initializing the service instance requires installing the IBM Cloud CLI and Trusted Key Entry (TKE) plug-in and performing some basic setup. You can find full prerequisite instructions here: https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-initialize-hsm-prerequisite&interface=ui.
Once you’ve completed the prerequisite steps, you can view your provisioned crypto units with the command ibmcloud tke cryptounits
The SELECTED column indicates which crypto units your changes will apply to. Before you make any changes, make sure all crypto units are selected with ibmcloud tke cryptounit-add
STEP 2—Create a Signature Key
Now that all crypto units have been selected, it’s time to create a signature key, a unique identifier for your workstation to track which users are making changes to the crypto units. Run the following commands to create and select a signature key. NOTE: You must remember the password for this signature key—without your signature key, your HPCS instance could become inaccessible.
Once you’ve created your signature key, you can add yourself as an administrator to your instance with the following commands:
STEP 3—Set Authentication Thresholds
When you initialize a HPCS instance, the crypto units are in imprint mode, meaning that changes can be executed without signatures or admin approval. This mode of operation is not considered secure. In order to exit imprint mode, we must set a signature threshold, the number of administrators needed to sign off on a change to the crypto units before it is executed. There is also the concept of the revocation threshold, the number of signatures needed to remove an admin user. Setting the threshold to 1 allows individual admins to make changes on their own, while setting a threshold of 2+ enforces quorum authentication.
You can set the threshold with ibmcloud tke cryptounit-thrhld-set
STEP 4—Create the Master Key Parts
Now that administrators have been set up and the crypto units are running securely, it’s time to create the master key, the key used to secure the crypto units themselves. The following commands create master key parts, which will be combined later to form a complete master key. You must create at least 2 master key parts to activate a master key. These part files are stored in the file location specified during the prerequisite steps. Use the following commands to create your master key part files.
STEP 5—Load the Master Key Register
Now that you’ve created master key parts on your workstation, it’s time to combine them for the crypto units to use. You can use the following commands to load and commit a master key into the crypto unit’s master key register. For information on changing your master key, see rotating master keys: https://test.cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-rotate-master-key-cli-key-part
STEP 7—Activate the Master Key
All that’s left to do to initialize your HPCS instance is activate the master key. You can use the following command to activate the master key. Note that when the master key is activated, the master key register (or the new master key register) you loaded in the previous step is emptied, while another register (the current master key register) is filled.
Returning to the IBM Cloud Web UI, under the ‘Details’ page for your HPCS instance, you should now see a list of all your crypto units and the message ‘initialized,’ indicating this stage of setup is complete.
Part 3—Creating Vaults, Keystores, and Keys
Now that you’ve provisioned your instance on the cloud and initialized the crypto units to power it, it’s time to start creating and protecting cryptographic keys. Keys are protected by two layers of security, vaults and keystores. Keystores are the standard place to store cryptographic keys—these can be IBM Key Protect keystores within our cloud, or similar keystores from other cloud providers. Keys can be activated in multiple keystores for easy use across platforms. Vaults are unique to IBM Hyper Protect, and they act like access groups for controlling who can access your key library. They also sync any changes to a key across all keystores that key is activated in. A key can only be in one vault at a time.
STEP 1—Creating a Vault
Creating a vault inside HPCS is easy. Start by navigating to the ‘Vaults’ tab on the far left and select ‘Create a Vault’
Choose a name and optional description for your vault, then select ‘Create’ and you’re done!
STEP 2—Create or Connect to a Keystore
Now that we have a vault, it’s time to fill it with keys. First, keys must be activated within a keystore to be used. To connect a vault and a keystore, navigate to the ‘Target keystores’ tab on the far left and select ‘Add keystore,’ then select the vault you created in the previous step as the target.
If you have an existing keystore, either on IBM Cloud or another cloud provider, you can connect to it in this dialog. We will be creating a new keystore from this same dialog.
STEP 3—Create a Managed Key
Now we can create a key and safely store it within our vault/keystore. Like the previous steps, navigate to the ‘Managed keys’ tab and select ‘Create key.’ Choose the vault and keystore we created in the previous step, and then choose a name and algorithm for generating your key. You can also choose whether to hold the key in a pre-active state or activate it immediately.
Part 4: Using your Keys
You can add, create, and delete keys, keystores, and vaults within HPCS, but you will also want to use them to encrypt other data on the cloud. There are many different services that can utilize HPCS encryption (a full list can be found here: https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-integrate-services), but for this demo we will use a common cryptography use case: securing a database.
STEP 1—Grant Service Authorization
Different offerings on IBM Cloud must be given explicit access to the keys within HPCS. To give a resource access to HPCS keys, click Manage > Access (IAM) from the top right menu bar.
From the side navigation bar, select ‘Authorizations,’ then ‘Create.’ On the create page, you can select a source service that’s requesting authorization (in this case, IBM Cloud Databases for MongoDB) and a target service that’s providing authorization (HPCS). You can choose whether to select a specific resource or allow this authorization for all resources of this type. Once you’ve selected the proper resources, click ‘Authorize.’
STEP 2—Using the Key
Now that you’ve authorized use of your keys, you will see HPCS keys as an option whenever you create an instance of the Source service specified. For this demo, we can select the key we created earlier when initializing an IBM Cloud Database for MongoDB.
Appendix: Concepts
- Crypto Units: A Hardware Security Module (HSM) and associated software stack specifically designed for cryptography functions.
- Unified Key Orchestrator: An add-on to Hyper Protect Crypto Services that enables HPCS to manage keys across all cloud providers.
- Smart Card: A physical credit card-sized device with an embedded integrated circuit chip for controlling access to a digital resource.
- Signature Key: A key unique to your workstation, used to sign off on any changes you make to the service instance.
- Signature Threshold: the number of admin signature keys that must be attached to a command for a crypto unit for that command to be executed.
- Keystore: the standard method for housing cryptographic keys, on IBM Cloud and other cloud providers. One key can be activated within many keystores.
- Vault: a way of managing your keys/keystores through Identity and Access Management (IAM). A key can only be activated within one vault.
Join the IBM Z ScaleUp Program community page for updates! You can also see our latest news here.