Getting started with IBM Cloud Hyper Protect Crypto Services

IBM Cloud® Hyper Protect Crypto Services (Hyper Protect Crypto Services for short) is a dedicated key management service and hardware security module (HSM) based on IBM Cloud. With this service, you can take the ownership of the cloud HSM to fully manage your encryption keys and to perform cryptographic operations. Hyper Protect Crypto Services is also the only service in the cloud industry that is built on FIPS 140-2 Level 4-certified hardware. The Unified Key Orchestrator function provides the only cloud native single-point-of-control of encryption keys across hybrid multicloud environments of your enterprise.

This tutorial shows you the high-level steps on how to set up your service instance by loading your master keys, create and manage encryption keys with the UI, and perform cryptographic operations with the PKCS #11 API or with the GREP11 API.

Step 1: Initialize your service instance
Step 2 (Standard Plan only): Create keys
Step 2 (Unified Key Orchestrator Plan only): Manage your encryption keys
Step 3: Encrypt your data with cloud HSM

Before you begin

In order to use Hyper Protect Crypto Services, make sure that you meet the following prerequisites:

You have a Pay-As-You-Go or Subscription IBM Cloud account.

You can use promo code HPCRYPTO30 to get two crypto units at no charge for 30 days.
You have provisioned a service instance with either of the following plans:
- A standard plan with the Keep Your Own Key capability
- An extended plan with both Keep Your Own Key and Unified Key Orchestrator

Step 1: Initialize your service instance

Depending on where your service instance locates and your security requirements, Hyper Protect Crypto Services provides you with the following three options to initialize your service instance:

Option 1: Initializing service instances using smart cards and the Management Utilities

This option gives you the highest security, which enables you to store and manage master key parts by using smart cards.
Option 2: Initializing service instances using recovery crypto units

You can choose this option if you create your service instance in regions where the recovery crypto units are enabled. With this option, the master key is randomly generated within a recovery crypto unit and then automatically exported to other crypto units. You can manage the master key and complete the instance initialization with minimal effort.
Option 3: Initializing service instances using key part files

You can also initialize your service instance using master key parts that are stored in files on your local workstation. You can use this approach regardless of whether or not your service instance includes recovery crypto units.

Step 2 (Standard Plan only): Create keys

With the Standard Plan, you can create root keys or standard keys for data encryption. Complete the following steps to create your first cryptographic key. To complete these steps, make sure that you are the IBM Cloud account owner or are assigned the writer role. For details, see Assigning access to Hyper Protect Crypto Services in the UI.

From the UI, click KMS keys > Add key.
Select Create a key.
Specify Root key or Standard key as the key type and enter a unique name for your key. Ensure that the key name doesn't contain personally identifiable information (PII), such as your name or location.
Click Add key to confirm.

The created key is a symmetric 256-bit key, supported by the AES-CBC algorithm. You can inspect the general characteristics of your keys in the Key management service keys table. You can also bring your own keys by importing the base64-encoded key materials.

Step 2 (Unified Key Orchestrator Plan only): Manage your encryption keys

Follow these steps to manage your encryption keys if you are using Hyper Protect Crypto Services with Unified Key Orchestrator. To complete these steps, make sure that you are the IBM Cloud account owner or are assigned the Vault administrator role. For details, see Assigning access to Hyper Protect Crypto Services in the UI.

1. Create vaults

A vault is a single repository that controls a user's or an access group's access to managed keys and keystores through Cloud Identity and Access Management (IAM).

Complete the following steps to create your first vault:

From your service instance UI, click Vaults from the navigation to view all the available vaults.
Click Create vault.
Enter a name in Vault name. The vault name can be of 1 to 100 characters. Optionally, you can add an extended description to your vault in the Description section.
Click Create vault to confirm.

2. Create keystores

A keystore is a repository that stores the cryptographic keys. You can create an internal keystore within the service instance or connect to an external keystore in another service instance or even in another cloud provider, such as Microsoft Azure Key Vault, Amazon Web Services (AWS) Key Management Service (KMS), and Google Cloud KMS.

Complete the following steps to create your first internal keystore:

From your service instance UI, click Keystores from the navigation to view all the available keystores.
Click Add keystore.
Under Vault, select the vault that you create, and click Next. If you want to assign the keystore to a new vault, click Create vault.
Under Keystore type, select IBM Cloud KMS and click Next.
Under Keystore properties, enter a name in Keystore name. The keystore name can be of 1 to 100 characters. And then, click Next.
Under Summary, you can view the summary of the keystore that you create, including the keystore type, the assigned vault, and general properties.
After you confirm the keystore details, click Create keystore to create the keystore.

3. Create key templates

key template specifies the properties of the managed keys to be created, such as the naming convention, key algorithm, and key length.

Complete the following steps to create your first key template:

From your service instance UI, click Key templates from the navigation.
Click Create key template.
Under Vault, select the vault that you've just created and then click Next.
Under Keystores, select IBM Cloud KMS as the keystore type, select the keystore you've just created, and then click Next.
Under Key template properties, specify the following details of the key template. Click Next to continue.
Under Summary, view the summary of your key template, and then click Create key template to complete the key template creation.

4. Create managed keys

You can use a managed key for encryption or decryption only after it is created and activated in at least one keystore. Complete the following steps to create your first IBM Cloud KMS key and activate the key in the keystore that you create:

From your service instance UI, click Managed keys from the navigation to view all the available keys.
Click Create key.
Under Vault, select the vault that you've just created and then click Next.
Under Key template, select Create from a key template and then select the key template that you've just created and click Next.
Under Key properties, specify details of the key. Click Next to continue when you are done. Note that Pre-active keys are not to be installed in keystores until you manually activate them. Active keys are to be automatically installed in the keystores. For more information about the key properties, see Creating managed keys with a key template in the IBM Cloud UI.
Under Summary, view the summary of your key, and then click Create key to create the key.

Step 3: Encrypt your data with cloud HSM

You can remotely access Hyper Protect Crypto Services cloud HSM to perform cryptographic operations with the PKCS #11 API or with the GREP11 API. To complete these steps, make sure that you are the IBM Cloud account owner or are assigned the writer role. For details, see Assigning access to Hyper Protect Crypto Services in the UI.

Performing cryptographic operations with the PKCS #11 API

To perform cryptographic operations with the PKCS #11 API, complete the following steps:

Set up PKCS #11 Service IDs, roles, and actions. For more information, see Setting up PKCS #11 API user types.
Download, install, and configure the PKCS #11 client library. For more information about configuring the PKCS #11 client library, see Performing cryptographic operations with the PKCS #11 API.

Performing cryptographic operations with the GREP11 API

To perform cryptographic operations with the GREP11 API, you need to make sure your applications are developed with programming languages that are supported by gRPC.

The following procedure uses Golang code as an example to test GREP11 functions.

Install Golang by following the instruction.
Clone the sample GitHub repository for Golang into a local directory of your choice. Go modules are used for this repository, so you don't need to place the cloned repository in your GOPATH. Refer to the repository's README file for more information about the GREP11 Go code examples.
Update the following code snippet in the examples/server_test.go file.
```
var (
    Address        = "<instance_ID>.ep11.us-east.hs-crypto.appdomain.cloud"
    APIKey         = "<ibm_cloud_apikey>"
)
```
In the code example,
- Replace <instance_ID> with the value of your GREP11 API endpoint. To find the service endpoint URL, from your provisioned service instance UI, click Overview > Connect > Enterprise PKCS #11 endpoint URL.
- Replace <ibm_cloud_apikey> with the service ID API key that you created.
From the <your_repository_path>/hpcs-grep11-go/examples directory, execute the examples by running the go test -v -run Example command.