Performing key management operations with the CLI - Standard Plan only

IBM Cloud® Hyper Protect Crypto Services Standard Plan is integrated with IBM Key Protect command-line interface (CLI) plug-in, so that you can use the IBM Key Protect CLI plug-in to create, import, and manage encryption root keysA symmetric wrapping key that is used for encrypting and decrypting other keys that are stored in a data service. and standard keys.

Currently, performing key management operations with the CLI is only supported with the Standard Plan. You can still perform key management operations for the Hyper Protect Crypto Services with Unified Key Orchestrator through the UI or API.

Before you use the Key Protect CLI through a Hyper Protect Crypto Services instance (service instance for short), you need to perform the following steps:

1. Install the IBM Key Protect CLI plug-in.

2. Set the KP_PRIVATE_ADDR environment variable on your workstation:

   • On the Linux operating system or macOS, run the following command:

     export KP_PRIVATE_ADDR=<URL>
     

     In this command, the URL is the Key management endpoint URL. You can get the endpoint from your provisioned service instance dashboard through Overview > Connect > Key management endpoint URL. Or, you can dynamically retrieve the API endpoint URL with an API call. For example,

     export KP_PRIVATE_ADDR="https://api.us-south.hs-crypto.cloud.ibm.com:<port>"
     

     To find out the regions that Hyper Protect Crypto Services supports, see Regions and locations.

   • On the Windows operating system, in Control Panel, type environment variable in the search box to locate the Environment Variables window. Create a KP_PRIVATE_ADDR environment variable and set the value to the endpoint that is displayed on the Manage tab of your provisioned UI. For example, https://api.us-south.hs-crypto.cloud.ibm.com:<port>.

   You can also retrieve the endpoint URL through the API. For details, check out the Hyper Protect Crypto Services key management service API reference doc.

   Depending on whether you are using public or private endpoint, choose the corresponding endpoint URL to set the value of the KP_PRIVATE_ADDR environment variable.

3. Set the KP_INSTANCE_ID environment variable on your workstation:

   • On the Linux operating system or macOS, run the following command:

     export KP_INSTANCE_ID=<instance_ID>
     

     In this command, the instance_ID is displayed on the Manage tab of your provisioned UI. instance_ID is in a Universally Unique Identifier (UUID) format.

   • On Windows, in Control Panel, type environment variable in the search box to locate the Environment Variables window. Create a KP_INSTANCE_ID environment variable and set the value to the instance ID value that is displayed on the Manage tab of your provisioned Hyper Protect Crypto Services dashboard.

   Alternatively, you can use the -i <instance_ID> option on the ibmcloud kp command to set the instance ID.

4. Run the specific command to perform key management operations. For the full list of commands, check out the key management CLI reference.

5. Upgrade the Key Protect CLI plug-in to the newest version to enable new features.

6. (Optional) If you don't need the plug-in any more, you can uninstall the Key Protect CLI plug-in.