Creating a Dedicated Key Protect instance

Provisioning from the console

1. Log in to your IBM Cloud account.

2. Click Catalog to view the list of services available on IBM Cloud.

3. Search for "Key Protect" and click the Key Protect tile.

4. Select the Dedicated Plan.

5. Configure your instance:

   • Service name: Enter a unique name for your instance
   • Resource group: Select the resource group where you want to create the instance
   • Location: Choose the region where you want to deploy your instance
   • Crypto units: Select 2 or 3 crypto units (cannot be changed later)

   If you do not specify a number of crypto units, your instance is provisioned with two. You can also specify three crypto units using the drop-down list. The value cannot be changed later.

6. Click Create to provision your instance.

The provisioning process can take several minutes. After provisioning, you must initialize your instance using CLI before you can create keys. For more information, see Initializing your Dedicated instance.

Provisioning from the CLI

Before crypto units can be created and your instance initialized, your instance must be created. First, set a resource group to target by issuing:

ibmcloud target -c <resource_group>

If you do not know your resource group, you can find out which ones you have by issuing:

ibmcloud resource groups

After you have your resource group set, provision a Dedicated instance using the IBM Cloud CLI.

For a Dedicated instance with 2 crypto units (default):

ibmcloud resource service-instance-create <instance_name> kms dedicated <region>

For a Dedicated instance with 3 crypto units:

ibmcloud resource service-instance-create <instance_name> kms dedicated <region> -p '{"crypto_units": 3}'

Specifying a number of crypto units other than 2 or 3 returns an error. You cannot change the number of crypto units later.

Provisioning a Dedicated instance can take several minutes. You can check on the status of your instance by issuing:

ibmcloud resource service-instance <instance_name>

Where:

• <instance_name> is the name you gave your instance in the previous step.

The instance can have one of two states: active or in progress. An active instance has not yet been initialized; initialization requires completing the remaining steps in this topic. Until you initialize your instance, it cannot be used because your identities have not yet been configured with your crypto units to create the master key.

You might have to wait for a few minutes after provisioning before your crypto units are available. For more information, see Crypto unit states

Provisioning with Terraform

data "ibm_resource_group" "resource_group" {
   name = "<your_resource_group_name>"
  }
  resource "ibm_resource_instance" "key_protect_instance" {
  name              = "<your_instance_name>"
  resource_group_id = data.ibm_resource_group.resource_group.id
  service           = "kms"
  plan              = "dedicated"
  location          = "us-south"
  tags              = ["<tag1>"]
  parameters = {
    crypto_units = "3"
  }
}

Creating a root key in the console

1. From your IBM Cloud resource list, select your provisioned Dedicated instance of Key Protect.

2. Click Add to create a new key.

3. Select Create a key.

4. Specify the key details:

   Root key settings

   Setting	Description
   Type	Select Root key
   Key name	Enter a human-readable name (2-90 characters). Avoid personally identifiable information (PII).
   Key description	Optional. Add a description (2-240 characters) to help identify the key's purpose.
   Key ring	Optional. Select a key ring to organize your keys. If not specified, the key is placed in the default key ring.
   Rotation policy	Optional. Set an automatic rotation schedule for the key.

5. Click Add to confirm.

Keys created in the service are symmetric 256-bit keys, supported by the AES-GCM algorithm. For added security, keys are generated by FIPS 140-3 Level 4 HSMs (submitted for NIST certification) in your dedicated crypto units.

Creating a root key with CLI

1. Retrieve your authentication credentials.

2. Create a root key by running the following command:

   ibmcloud kp key create <key_name> -i <instance_ID>
   

   Replace the variables in the example request according to the following table:

   Variables for creating a root key with CLI

   Variable	Description
   key_name	A human-readable name for your key. The name must be 2–90 characters in length. Avoid entering personally identifiable information (PII) as part of the key name.
   instance_ID	The unique identifier (GUID) assigned to your Dedicated instance.

   A successful response returns the ID and name of your new root key.

3. Optional: Verify that the key was created by listing the keys in your instance.

   ibmcloud kp keys -i <instance_ID>
   

Keys created in the service are symmetric 256-bit keys, supported by the AES-GCM algorithm. For added security, keys are generated by FIPS 140-3 Level 4 HSMs (submitted for NIST certification) in your dedicated crypto units.

Creating a root key with Terraform

You can create a root key using Terraform.

Terraform cannot be used to initialize Dedicated instances. You must initialize your instance using the CLI before using Terraform to manage keys.

1. Configure Terraform to use your Dedicated instance by setting the IBMCLOUD_KP_API_ENDPOINT environment variable:

   export IBMCLOUD_KP_API_ENDPOINT=https://<region>.kms.cloud.ibm.com
   

2. Add the following to your main.tf file:

   resource "ibm_kms_key" "root_key" {
     instance_id  = "<dedicated_instance_guid>"
     key_name     = "my-root-key"
     standard_key = false
     force_delete = true
   }
   
   output "root_key_id" {
     value       = ibm_kms_key.root_key.key_id
     description = "The ID of the root key"
   }
   

3. Apply the configuration:

   terraform apply
   

For more advanced configurations:

resource "ibm_kms_key" "root_key_advanced" {
  instance_id = "<dedicated_instance_guid>"
  key_name    = "my-root-key-advanced"
  standard_key = false
  
  # Optional: Add to a specific key ring
  key_ring_id = ibm_kms_key_rings.ring.key_ring_id
  
  # Optional: Set rotation policy
  rotation {
    interval_month = 3
  }
  
  # Optional: Set dual authorization policy
  dual_auth_delete {
    enabled = true
  }
}

# Create a key ring first
resource "ibm_kms_key_rings" "ring" {
  instance_id = "<dedicated_instance_guid>"
  key_ring_id = "my-key-ring"
}

For more information, see Creating root keys and Setting up Terraform.

Importing a key in the console

1. From your Dedicated instance dashboard, click Add.

2. Select Import your own key.

3. Specify the key details:

   Import key settings

   Setting	Description
   Key type	Select Root key or Standard key
   Key name	Enter a human-readable name for your key
   Key material	The base64-encoded key material (16, 24, or 32 bytes)
   Key description	Optional. Add a description for the key
   Key ring	Optional. Select a key ring to organize your keys

4. Click Add to confirm.

Importing a key with CLI

1. Retrieve your authentication credentials.

2. Prepare your key material. Your key material must be a base64-encoded value that is 16, 24, or 32 bytes (128, 192, or 256 bits) in length. To generate a random 32-byte key material, run:

   KEY_MATERIAL=$(openssl rand -base64 32)
   

3. Import the key by running the following command:

   ibmcloud kp key create <key_name> -i <instance_ID> -k $KEY_MATERIAL
   

   Replace the variables in the example request according to the following table:

   Variables for importing a key with CLI

   Variable	Description
   key_name	A human-readable name for your key. The name must be 2–90 characters in length. Avoid entering personally identifiable information (PII) as part of the key name.
   instance_ID	The unique identifier (GUID) assigned to your Dedicated instance.
   KEY_MATERIAL	The base64-encoded key material to import. You can also pass the value directly using the -k flag.

   A successful response returns the ID and name of your imported key.

4. Optional: Verify that the key was imported by listing the keys in your instance.

   ibmcloud kp keys -i <instance_ID>
   

For enhanced security, use an import token to encrypt your key material before importing. An import token ensures that your key material is protected in transit.

1. Create an import token:

   ibmcloud kp import-token create -i <instance_ID> -e 300 -m 10
   

   Where -e sets the expiration time in seconds and -m sets the maximum number of retrievals.

2. Extract the nonce and public key from the import token:

   NONCE=$(ibmcloud kp import-token show -i <instance_ID> | jq -r '.["nonce"]')
   PUBLIC_KEY=$(ibmcloud kp import-token show -i <instance_ID> | jq -r '.["payload"]')
   

3. Encrypt the key material and nonce using the public key:

   ibmcloud kp import-token key-encrypt -k $KEY_MATERIAL -p $PUBLIC_KEY
   ibmcloud kp import-token nonce-encrypt -k $KEY_MATERIAL -n $NONCE
   

4. Import the root key using the encrypted values:

   ibmcloud kp key create <key_name> -i <instance_ID> -k $ENCRYPTED_KEY -n $ENCRYPTED_NONCE -v $IV
   

For more information about import tokens, see Using import tokens.

Importing a key with Terraform

You can import a key using Terraform.

resource "ibm_kms_key" "imported_root_key" {
  instance_id  = "<dedicated_instance_guid>"
  key_name     = "my-imported-root-key"
  standard_key = false
  payload      = "<base64_encoded_key_material>"
  force_delete = true
}

output "imported_key_id" {
  value       = ibm_kms_key.imported_root_key.key_id
  description = "The ID of the imported root key"
}

For enhanced security, you can use an import token to encrypt your key material before importing. For more information, see Using import tokens and Importing root keys.

Wrapping a data encryption key with CLI

Use the kp key wrap command to generate a new data encryption key (DEK) and protect it with a root key. Key Protect performs the wrap operation in your dedicated HSM partitions.

You cannot wrap a standard key. Only root keys can be used for wrapping.

1. Retrieve your authentication credentials.

2. Retrieve the ID of the root key you want to use for wrapping:

   ibmcloud kp keys -i <instance_ID>
   

3. Wrap a new DEK with the root key. If you omit the -p flag, Key Protect generates a new DEK and returns it as ciphertext:

   ibmcloud kp key wrap <root_key_ID> -i <instance_ID>
   

   To wrap an existing base64-encoded DEK, supply it using the -p flag:

   PLAINTEXT=$(openssl rand -base64 32)
   ibmcloud kp key wrap <root_key_ID> -i <instance_ID> -p $PLAINTEXT
   

   Replace the variables in the example request according to the following table:

   Variables for wrapping a DEK with CLI

   Variable	Description
   root_key_ID	The ID or alias of the root key to use for wrapping.
   instance_ID	The unique identifier (GUID) assigned to your Dedicated instance.
   PLAINTEXT	Optional. A base64-encoded DEK to wrap. If omitted, a new DEK is generated.

   A successful response returns the ciphertext. Store the ciphertext alongside your encrypted data — it is required to retrieve the original DEK later.

   Do not save the plaintext DEK to persistent storage. Store only the ciphertext and use kp key unwrap to retrieve the DEK when needed.

Unwrapping a data encryption key with CLI

Use the kp key unwrap command to decrypt a previously wrapped DEK and recover the original plaintext key.

1. Unwrap the ciphertext using the same root key that was used for wrapping:

   ibmcloud kp key unwrap <root_key_ID> <ciphertext> -i <instance_ID>
   

   Replace the variables in the example request according to the following table:

   Variables for unwrapping a DEK with CLI

   Variable	Description
   root_key_ID	The ID or alias of the root key that was used for the original wrap operation.
   ciphertext	The encrypted DEK returned by the wrap operation.
   instance_ID	The unique identifier (GUID) assigned to your Dedicated instance.

   A successful response returns the plaintext DEK in base64-encoded format.

2. Optional: To add extra protection, supply additional authentication data (AAD) during both wrap and unwrap. The same AAD values must be provided in the same order:

   ibmcloud kp key wrap <root_key_ID> -i <instance_ID> -a "my-app,production"
   ibmcloud kp key unwrap <root_key_ID> <ciphertext> -i <instance_ID> -a "my-app,production"
   

   If you supply AAD on wrap, save it to a secure location. You must provide the same AAD in the same order on every subsequent unwrap request.

Using envelope encryption with Terraform

While Terraform does not directly support wrap/unwrap operations, you can use the Key Protect API within your application code to perform envelope encryption with keys created by Terraform.

# Create a root key for envelope encryption
resource "ibm_kms_key" "envelope_root_key" {
  instance_id  = "<dedicated_instance_guid>"
  key_name     = "envelope-encryption-key"
  standard_key = false
  force_delete = true
}

# Output the key ID for use in your application
output "envelope_key_id" {
  value       = ibm_kms_key.envelope_root_key.key_id
  description = "Root key ID for envelope encryption operations"
  sensitive   = true
}

# Output the instance ID for API calls
output "kp_instance_id" {
  value       = "<dedicated_instance_guid>"
  description = "Dedicated Key Protect instance ID for API calls"
}

Your application can then use these outputs to perform wrap and unwrap operations via the Key Protect API or SDKs.

For more information about envelope encryption, see Protecting data with envelope encryption, Wrapping keys, and Unwrapping keys.