KMS integration for BYOK or KYOK

IBM Cloud® Schematics integrates to fully manage enterprise-grade key management to manage the lifecycle of your encryption keys that are used in your IBM Cloud resources, services, and applications.

Launching key management

By default the data that you store in Schematics workspaces using the Enterprise plan is encrypted by using randomly generated keys. If you need to control the encryption keys, you can use the IBM Key Protect to create, import, and manage encryption root keys and standard keys. Then, you can associate those keys with your Schematics resource deployment to encrypt your resources.

You can use your encryption keys from key management services (KMS), IBM Key Protect(BYOK), and IBM Cloud Hyper Protect Crypto Services (KYOK) to encrypt and secure data stored in Schematics. For more information about how to protect sensitive data in Schematics, see protecting your sensitive data in Schematics.

Prerequisites

The key management system lists the instance that are created from your specific location and region. Following prerequisites are followed to perform the KMS activity.

You should have your KYOK, or BYOK. To create the IBM Key Protect keys, see create BYOK. To create an IBM Cloud Hyper Protect Crypto Services keys, see create KYOK.
You need to add root key to your KYOK, or BYOK instance.
You need to configure service to service authorization to integrate BYOK, and KYOK in Schematics service. Follow these steps to grant service to service authorization Key Protect access to Schematics service.
- In the IBM Cloud console, click Manage > Access (IAM), and select Authorizations > Create.
- Select a Source Service as Schematics.
- Select Target Service as Key Protect or Hyper Protect Crypto Services. Select the instance you want to provide authorization.
- Select the Role as Reader.
- Click Authorize.
  
  For more information, see IAM authorization to create by using CLI, and API.

KMS setting is a one time settings. You need to open the support ticket to update KMS settings.

Enabling IBM Key Protect through UI

Follow these steps to launch key management system and encrypt your keys with Schematics.

Log in to IBM Cloud console.
Click the Menu icon > Platform Automation > Schematics > Extensions.
Click Connect > Key Management from the drop down.
Select Service as Key Protect, or Hyper Protect Crypto Services.
Select an Choose existing instance instance. If your instance not created, select an Create a new instance to create IBM Key Protect, or IBM Cloud Hyper Protect Crypto Services. For more information, see Create a key protect instance.

You can view your instance in the service list, when the prerequisites are met. Or you can see a message No Keys found.
Select your Service and Root key that is configured for BYOK or KYOK.
Click Update to complete the integration of your keys with your Schematics resource deployment.
Click Launch icon to view your enabled keys in the Resource list.

Enabling IBM Key Protect through CLI

Follow the steps to integrate root keys with Schematics to encrypt the data through command-line.

Download and install command-line.
List all the KMS instance in your IBM Cloud account to find your Key Protect or Hyper Protect Crypto Services instances.
```
ibmcloud schematics kms instance ls --location LOCATION_NAME --scheme ENCRYPTION_SCHEME
```

Integrate the root key with Schematics to encrypt your data in the specified location.

ibmcloud schematics kms enable --location LOCATION_NAME --scheme ENCRYPTION_SCHEME --group RESOURCE_GROUP --primary_name PRIMARY_KMS_NAME --primary_crn PRIMARY_KEY_CRN --primary_endpoint PRIMARY_KMSPRIVATEENDPOINT --secondary_name SECONDARY_KMS_NAME --secondary_crn SECONDARY_KEY_CRN --secondary_endpoint SECONDARY_KMSPRIVATEENDPOINT

Get current root key information.
```
ibmcloud schematics kms info --location LOCATION_NAME
```
For more information about enabling the BYOK or KYOK commands, see Enable BYOK or KYOK commands.