Editing managed key details

Editing managed key details with the UI

To edit the details of a managed key by using the UI, complete the following steps:

1. Log in to the Hyper Protect Crypto Services instance.

2. Click Managed keys from the navigation to view all the available keys.

3. Click the Actions icon on the key that you want to edit, and choose Show details.

4. Under Key properties, click Edit on each card to update the key properties.

   1. You can update the general properties and lifecycle properties. Or, you can also view the key material properties, including algorithm, length, and key check value. The following are a few properties that you can edit. Note that you can edit one property card at a time. To edit another property card, save your changes first.

   Because the key is already created, you cannot make changes to key material properties that are marked with a Lock icon.

   Table 1. Key properties

   Property	Description
   Key name	A unique, human-readable name for easy identification of your key. When you change the name of a managed key, the key is to be renamed in all keystores where it is activated. Important: You cannot edit the key name after the managed key is created with key naming schemes. Depending on the keystore type, name your key with the following rules: IBM Cloud KMS: 2–50 characters in length. The characters can be letters (case-sensitive), digits (0–9), or spaces. IBM Key Protect: 2–50 characters in length. The characters can be letters (case-sensitive), digits (0–9), or spaces. AWS Key Management Service: 1–250 characters in length. The characters can be letters (case-sensitive), digits (0–9), or symbols (/_-). However, do not start the name with AWS/. Azure Key Vault: 1–127 characters in length. The characters can be letters (case-sensitive), digits (0–9), or hyphens (-). Google Cloud KMS: 1–63 characters in length. The characters can be letters (case-sensitive), digits (0–9), or symbols (_-).
   Description	(Optional) An extended description for your key, with up to 200 characters in length.
   State	Key states include Pre-active, Active, Deactivated, and Destroyed. A pending flag is displayed beside the state after you move a key from Deactivated to Destroyed state, the key will be pending on destruction for a time period defined by the default destruction policies of the external cloud providers. For Azure Key Vault and Google Cloud KMS keystore, the pending destruction time period can also be customized on the external cloud provider side. You cannot cancel pending destruction using the Unified Key Orchestrator UI or API. However, you might still do so through the third-party keystores that the keys are created in. For more information, see Monitoring the lifecycle of encryption keys in Unified Key Orchestrator.
   Activation date	Plan a date to activate the key. It is for planning purpose only.
   Expiration date	Plan a date to deactivate the key. It is for planning purpose only.

   2. In the Keystores card, click Edit to add or remove the keystores where the key is activated. You can use a key only for encryption and decryption after it is activated in at least one keystore. If the key is created with a key template, an Unaligned flag can be displayed if you update the keystore distribution list, which means the key is no longer in sync with the key template.

      • Add keystores

        If you want to distribute and activate the key in more keystores, click Edit and check the corresponding keystore cards. The Active key state is synced across all keystores.

      • Remove keystores

        If you want to unlink and deactivate the key in some keystores, click Edit and clear the checkbox in the corresponding keystore cards. After the removal, the key material remains unless you destroy the key. The key state in the removed keystores becomes Deactivated and cannot be synced with the managed key state in the future. However, you can reactivate the key by distributing the key to these keystores again so that the key state is synced again.

        A managed key is synced across multiple keystores that the key is to be distributed to. You can fully remove a key from a keystore only after the key is destroyed. However, you can deactivate the key or remove the keystores at any time.

      • Sync keys

        If the key state in some keystores is different from the managed key state, you receive a Key out of sync warning message. An Out of sync flag is also displayed in the corresponding keystore card. There can be multiple reasons why the key state is out of sync. For example, there is an issue in relinking the key in the keystore,the key is failed to be destroyed in some of the distributed keystores, or the key is modified in the target keystore outside of Unified Key Orchestrator. You can sync the key state by clicking Sync key. For more information, see Syncing keys in keystores with managed keys manually.

        During master key rotation, you can activate IBM Cloud KMS key in internal keystores. However, it will be shown as Out of sync. You can sync the key after the master key rotation is complete.

      • Create keystores

        Distributing and activating a key in multiple keystores enables redundancy. If you want to distribute the key in a new keystore, click Add keystore. For more instructions, see Creating internal keystores or Connecting to external keystores.

      • Realign with templates

        For a key that is created with a key template, after you edit the keystore distribution list, an Unaligned flag can be displayed on the key details card for keys. If you want to keep these changes, ignore the flag. Otherwise, realign your key with the key template again by selecting Actions > Realign with template. For more information, see Realigning keys with key templates.

      If you connect to an external keystore of type Azure Key Vault, you can distribute HSM-protected keys only to the Azure Key Vault (Premium).

5. Under Advanced properties, click Edit to update or add new key tags to the key. Key tags are used as identifications of a key.

6. When you finish making changes, click Save to save the changes.

You can search for a specific key by using the search bar, or filter keys based on your needs by clicking the Filter icon in the Managed keys table. For more information, see Filtering and searching keys.

Editing key details with the API

To edit key details through the API, follow these steps:

1. Retrieve your service and authentication credentials to work with keys in the service.

2. Update the details of a managed key by making a PATCH call to the following endpoint.

   https://uko.<region>.hs-crypto.cloud.ibm.com:<port>/api/v4/managed_keys/<id>
   

   Replace <id> with the ID of your managed key.

   For detailed instructions and code examples about using the API method, check out the Hyper Protect Crypto Services Unified Key Orchestrator API reference doc.

Editing keystores for keys with the API

To editing keystores for keys by using API, complete the following steps:

1. Retrieve your service and authentication credentials to work with keys in the service.

2. Add a keystore to or remove a keystore from a keystore group by making a PATCH call to the following endpoint. The keystore group must match the key template that is associated with the managed key.

   https://uko.<region>.hs-crypto.cloud.ibm.com:<port>/api/v4/keystores/<id>
   

   Replace <id> with the ID of your keystore.

3. Update the managed key to match the latest version of the associated key template by making a POST call to the following endpoint.

   https://uko.<region>.hs-crypto.cloud.ibm.com:<port>/api/v4/managed_keys/<id>/update_from_template
   

   Replace <id> with the ID of your managed key.

   For detailed instructions and code examples about using the API method, check out how to Update an internal keystore or a keystore connection and Update a managed key to match the key template in the Hyper Protect Crypto Services Unified Key Orchestrator API reference doc.