vania-janet/multiturn-rag-retrieval-data huggingface dataset:
* UI
* API







 Deleting managed keys 

You can delete your managed keys in Unified Key Orchestrator with the IBM Cloud® console, or programmatically with the Unified Key Orchestrator API.

When you delete a managed key, the key is to be detached from all target keystores, and all key materials and the metadata are destroyed permanently.



 Deleting managed keys with the IBM Cloud console 

To delete a key in Active state, you need to first deactivate the key, and then destroy the key and remove it from the vault.

To delete a key in Pre-active or Deactivated state, you only need to destroy the key, and then remove it from the vault.

For more information about key states and transitions, see [Monitoring the lifecycle of encryption keys in Unified Key Orchestrator](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-uko-key-states).

Follow these steps to complete the process:



1. [Log in to the Hyper Protect Crypto Services instance](https://cloud.ibm.com/login).
2. Click Managed keys from the navigation to view all the available keys.
3. If the managed key that you want to delete is in Active state, click the Actions icon ![Actions icon](https://cloud.ibm.com/docs-content/v1/content/217f108cc44e2ce15fb692d4b57b4c628464e908/icons/action-menu-icon.svg) and choose Deactivated to deactivate the key first.

When you change the Active key to Deactivated state, the key is detached from all the target keystores, and not accessible to all associated resources and their data. Make sure that you open the confirmation tile to check all the associated resources before you continue. However, you can still reactivate the key so that it is accessible to the resources again.
4. To destroy a Pre-active or Deactivated key, click the Actions icon !
Because a key ring cannot be deleted as long as it contains keys in any state (including the destroyed state keys are moved to after they are deleted but before they are automatically purged 90 days after deletion), if you want to delete a key ring, you might need to transfer keys to a different ring first.

After transferring a key to a different key ring, it may take up to a maximum of ten minutes for the change to take effect.



 Transferring a key to a different key ring with the UI 

If you do not see all of the options you expect to see, it might be because you do not have the permission to execute a particular action. Make sure your roles and permissions are sufficient to perform the action. For more information on roles, check out [Managing user access](https://cloud.ibm.com/docs/key-protect?topic=key-protect-manage-access).

You must have the service "Manager" role of both the key being transferred and the target key ring to transfer a key.

From the Keys panel:



1. Find the key you want to transfer. Note that it can be helpful to specify the key ring where the key is currently located by selecting the ring in the Key ring ID drop down list. You can also click on Key rings in the left navigation, find the appropriate key ring, and click View associated keys inside the setting drop-down list. This will show you all of the keys associated with that key ring.
2. Click on the ⋯ button, and select Edit key ring from the drop-down list.
3. In the drop-down list, select the key ring you want to move the key to. Then click Save.







 Transferring a key to a different key ring with the API 

Transfer a key to a different key ring by making a PATCH call to the following endpoint.

https://<region>.kms.cloud.ibm.com/api/v2/keys/<keyID_or_alias>



1. [Retrieve your authentication credentials to work with keys in the service](https://cloud.ibm.com/docs/key-protect?topic=key-protect-set-up-api).
Choose from a list of options for managing your key, such as [rotating the key](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-rotate-keysrotate-root-key-gui) or [deleting the key](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-delete-keysdelete-keys-gui).







 Step 8: Clean up 



1. Gather the identifier for the encryption key that you imported in the previous step.

ROOT_KEY_ID=$(jq -r '.resources[].id' createRootKeyResponse.json)
2. Remove the encryption key from your Hyper Protect Crypto Services service instance.



Use the API

curl -X DELETE $HPCS_API_URL/api/v2/keys/$ROOT_KEY_ID -H "Accept: application/vnd.ibm.collection+json" -H "Authorization: $ACCESS_TOKEN" -H "Bluemix-Instance: $INSTANCE_ID" | jq .
Use the IBM Key Protect CLI

ibmcloud kp key delete {ROOT_KEY_ID}



3. Remove all the local files associated with this tutorial.

rm kms-encrypt-nonce .json .bin .pem
4. Delete the test directory that you created for this tutorial.

cd .. && rm -r hs-crypto-test
5. Optional: Remove your Hyper Protect Crypto Services service instance.

ibmcloud resource service-instance-delete import-keys-demo

If you created more test keys in your service instance, be sure to [remove all encryption keys from your service instance](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-delete-keysdelete-keys) before you deprovision the instance.







 Next steps
For more information about deleting and purging keys, check out [About deleting and purging keys](https://cloud.ibm.com/docs/key-protect?topic=key-protect-delete-purge-keys).

The following table lists which APIs you can use to retrieve data related to a deleted key.



Table 4. Lists the API that users can use to view details about a key and its registrations.

 API Description 

 [Get key](https://cloud.ibm.com/docs/key-protect?topic=key-protect-retrieve-key) Retrieve key details 
 [Get key metadata](https://cloud.ibm.com/docs/key-protect?topic=key-protect-retrieve-key-metadata) Retrieve key metadata 
 [Get registrations](https://cloud.ibm.com/docs/key-protect?topic=key-protect-view-protected-resources) Retrieve a list of registrations associated with the key 







 Removing an existing authorization 

If you need to cancel an authorization for a key before the seven-day authorization period expires, you can remove the existing authorization by making a POST call to the following endpoint.

https://<region>.kms.cloud.ibm.com/api/v2/keys/<keyID_or_alias>/actions/unsetKeyForDeletion



1. [Retrieve your authentication credentials to work with keys in the service](https://cloud.ibm.com/docs/key-protect?topic=key-protect-set-up-api).

To remove an authorization to delete a key, you must be assigned a Manager or Writer access policy for the instance or key. To learn how IAM roles map to Key Protect service actions, check out [Service access roles](https://cloud.ibm.com/docs/key-protect?topic=key-protect-manage-accessmanage-access-roles).
2. Copy the ID of the key that you want to unset or deauthorize for deletion.
3. Remove an existing authorization to delete the key.
About deleting and purging keys 

You can use IBM® Key Protect for IBM Cloud® to delete an encryption key and its key material if you are a manager for your Key Protect instance.

Before you can delete an instance, you must delete every key in that instance. However, if you close your account, any existing instances and keys are automatically hard deleted. Check out [Account cancelation and data deletion](https://cloud.ibm.com/docs/key-protect?topic=key-protect-security-and-complianceaccount-cancelation) for more information.

In the event that a key is no longer needed or should be removed, Key Protect allows you to delete and ultimately purge keys, an action that shreds the key material and makes any of the data encrypted with it inaccessible.

Deleting a key moves it into a Destroyed state, a "soft" deletion in which the key can still be seen and restored for 30 days. After 90 days, the key will be automatically purged, or "hard deleted", and its associated data will be permanently shredded and removed from the Key Protect service. If it is desirable that a key be purged sooner than 90 days, it is also possible to hard delete a key four hours after it has been moved into the Destroyed state.

After a key has been deleted, any data that is encrypted by the key becomes inaccessible, though this can be reversed if the key is restored within the 30-day time frame. After 30 days, key metadata, registrations, and policies are available for up to 90 days, at which point the key becomes eligible to be purged. Note that once a key is no longer restorable and has been purged, its associated data can no longer be accessed. As a result, [destroying resources](https://cloud.ibm.com/docs/key-protect?topic=key-protect-security-and-compliancedata-deletion) is not recommended for production environments unless absolutely necessary.

The following table lists the time frames in which you can view, restore, and purge a key after it has been deleted.



Table 1. Lists how users can interact with keys during certain time intervals after a key has been deleted
Note that you will not be able to delete the key if it is protecting a registered IBM Cloud resource that's non-erasable due to a [retention policy](https://cloud.ibm.com/docs/cloud-object-storage?topic=cloud-object-storage-immutableimmutable-terminology-policy).



After you delete a key, the key transitions to the Destroyed state. Any data encrypted by keys in this state is no longer accessible. Metadata that is associated with the key, such as the key's deletion date, is kept in the Key Protect database. Destroyed keys can be recovered after up to 30 days or their expiration date, whichever is sooner. After 30 days, keys can no longer be recovered, and become eligible to be purged after 90 days, a process that shreds the key material and makes its metadata inaccessible.

If a user [has the KeyPurge attribute](https://cloud.ibm.com/docs/key-protect?topic=key-protect-grant-access-keysgrant-access-keys-specific-functions), they can purge a key after four hours. Check out [Purging keys in the console](https://cloud.ibm.com/docs/key-protect?topic=key-protect-delete-keysdelete-keys-gui-purge) for more information.





 Purging keys in the console 

If it is important to your use case to purge a key sooner than 90 days (the soonest a key can be purged after a normal deletion), the key can be purged after four hours if a user [has the KeyPurge role](https://cloud.ibm.com/docs/key-protect?topic=key-protect-grant-access-keysgrant-access-keys-specific-functions).

Because a purged key has its key material permanently shredded and metadata inaccessible, a purged key cannot be restored. It is therefore even more important to ensure that the key has no vital associated resources.

To purge a key:



1.
If it is desirable that a key be purged sooner than 90 days, it is also possible to hard delete a key four hours after it has been moved into the Destroyed state.

After a key has been deleted, any data that is encrypted by the key becomes inaccessible, though this can be reversed if the key is restored within the 30-day time frame. After 30 days, key metadata, registrations, and policies are available for up to 90 days, at which point the key becomes eligible to be purged. Note that once a key is no longer restorable and has been purged, its associated data can no longer be accessed. As a result, [destroying resources](https://cloud.ibm.com/docs/key-protect?topic=key-protect-security-and-compliancedata-deletion) is not recommended for production environments unless absolutely necessary.





 What happens if I try to delete a key that's actively encrypting data? 

For your protection, Key Protect prevents the deletion of a key that's actively encrypting data in the cloud. If you try to delete a key that's registered with a cloud resource, the action won't succeed.

If needed, you can [force deletion on a key](https://cloud.ibm.com/docs/key-protect?topic=key-protect-delete-keysdelete-keys-force-delete) by using the Key Protect APIs. [Review which resources are encrypted by the key](https://cloud.ibm.com/docs/key-protect?topic=key-protect-view-protected-resources) and verify with the owner of the resources to ensure you no longer require access to that data.

If you can't delete a key because a retention policy exists on the associated resource, contact the account owner to remove the retention policy on that resource.





 What happens when I disable a key? 

When you disable a key, the key transitions to the Suspended state. Keys in this state are no longer available for encrypt or decrypt operations, and any data that's associated with the key becomes inaccessible.

Disabling a key is a reversible action.
[Log in to the IBM Cloud console](https://cloud.ibm.com/login/).
2. Go to Menu > Resource List to view a list of your resources.
3. From your IBM Cloud resource list, select your provisioned instance of Key Protect.
4. On the application details page, use the Keys table to browse the keys in your service.
5. Click the ⋯ icon to open a list of options for the key that you want to delete.
6. From the options menu, click Schedule key deletion and review the key's associated resources.
7. Click the Next button, enter the key name, and click Schedule deletion.
8. Contact another user to complete the deletion of the key.



The other user must have Manager access policy for the instance or key in order to authorize the key for deletion.





 Purging a key that holds dual authorization in the console 

Four hours after the other user with a Manager access policy has authorized the key for deletion, it can be purged by one of the users as long as they hold [the KeyPurge attribute](https://cloud.ibm.com/docs/key-protect?topic=key-protect-grant-access-keysgrant-access-keys-specific-functions).

This can be done by clicking the ⋯ icon to open a list of options for the key that you want to purge and then clicking Purge. If you cannot delete the key, make sure it has been at least four hours since the key was authorized for deleting by another user and that you hold the KeyPurge attribute.





 Authorize deletion for a key with the API 

[After you enable dual authorization for an instance or key](https://cloud.ibm.com/docs/key-protect?topic=key-protect-manage-dual-auth), you can provide the first authorization to delete a key by making a POST call to the following endpoint.

https://<region>.kms.cloud.ibm.com/api/v2/keys/<keyID_or_alias>/actions/setKeyForDeletion



1.
Enabling key: '264fadc3-7667-4b25-916e-5825fe70de0b', in instance: '390086ac-76fa-4094-8cf3-c0829bd69526'...
OK

 show key details - a state of "1" is "active"
$ ibmcloud kp key show 264fadc3-7667-4b25-916e-5825fe70de0b --output json

{
"id": "264fadc3-7667-4b25-916e-5825fe70de0b",
"name": "my-root-key",
"type": "application/vnd.ibm.kms.key+json",
"algorithmType": "AES",
"createdBy": "user id ...<redacted>...",
"creationDate": "2020-06-09T21:21:55Z",
"lastUpdateDate": "2020-06-09T21:31:44Z",
"keyVersion": {
"id": "264fadc3-7667-4b25-916e-5825fe70de0b",
"creationDate": "2020-06-09T21:21:55Z"
},
"extractable": false,
"state": 1,
"crn": "crn:v1:bluemix:public:kms:us-south:a/ea998d3389c3473aa0987652b46fb146:390086ac-76fa-4094-8cf3-c0829bd69526:key:264fadc3-7667-4b25-916e-5825fe70de0b"
}





 Required parameters 



* KEY_ID_OR_ALIAS

The v4 UUID or alias of the key that you want to delete.
Hyper Protect Crypto Services blocks the deletion of a key that's protecting a cloud resource, such as a IBM Cloud Object Storage bucket. You can force-delete a key and the contents by making a DELETE call to the following endpoint.

https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>?force=true

When you delete a key with registrations that are associated, you shred the key's contents and associated data. Any data that is encrypted by the key becomes inaccessible.

This action can't succeed if the key is protecting a resource that's non-erasable due to a retention policy. You can verify whether a key is associated with a non-erasable resource by [checking the registration details](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-view-protected-resources) for the key. Then, you must contact an account owner to remove the retention policy on each resource that is associated with the key before you can delete the key.



1. [Retrieve your authentication credentials to work with keys in the service](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-set-up-kms-api).
2. Retrieve the ID of the key that you want to force delete.

You can retrieve the ID for a specified key by making a GET /v2/keys/request, or by viewing your keys in the IBM Cloud console.
3. Run the following cURL command to force-delete the key and the contents.

curl -X DELETE "https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>?force=true" -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>' -H "x-kms-key-ring: <key_ring_ID>" -H 'prefer: <return_preference>'
If the key has been deleted within the last 30 days, it can be restored. If it has been more then 30 days, you will not be able to restore the key. If you attempt to restore a key that is no longer eligible to be restored, you will receive an error when trying to restore the key.







 Restoring a deleted key with the console 

If you prefer to restore your key by using a graphical interface, you can use the IBM Cloud console.

[After you import your existing keys into the service](https://cloud.ibm.com/docs/key-protect?topic=key-protect-create-root-keys) and [delete](https://cloud.ibm.com/docs/key-protect?topic=key-protect-delete-keys) a key, complete the following steps to restore the key:



1. [Log in to the IBM Cloud console](https://cloud.ibm.com/login/).
2. Go to Menu > Resource List to view a list of your resources.
3. From your IBM Cloud resource list, select your provisioned instance of Key Protect.
4. Click Keys to open the keys panel and find the key in the destroyed state you want to restore. One way to achieve this is to click the Key states drop-down list and select the Destroyed state. This will limit the results to only keys that have been deleted.
5. Click the ⋯ icon to open a list of options for the key that you want to restore. Note that if the key has just been moved to a Destroyed state you must wait 30 seconds before attempting to restore it.
6. Click the Restore Key button to open the restore side panel.
7. Click Restore Key button.
8. Confirm the key was restored in the updated Keys table.







 Restoring a deleted key with the API 

Restore a previously imported key by making a POST call to the following endpoint:

https://<region>.kms.cloud.ibm.com/api/v2/keys/<keyID_or_alias>/restore



1.
Force deletion on a key won't succeed if the key is protecting a registered IBM Cloud resource that's non-erasable due to a [retention policy](https://cloud.ibm.com/docs/cloud-object-storage?topic=cloud-object-storage-immutableimmutable-terminology-policy), which is a Write Once Read Many (WORM) policy set on the your IBM Cloud resource. You can verify whether a key is associated with a non-erasable resource by checking the 'preventKeyDeletion" field in the [registration details](https://cloud.ibm.com/docs/key-protect?topic=key-protect-view-protected-resources) for the key. Then, you must contact an account owner to remove the retention policy on each registered IBM Cloud resource that is associated with the key before you can delete the key.



1. [Retrieve your authentication credentials to work with keys in the service](https://cloud.ibm.com/docs/key-protect?topic=key-protect-set-up-api).
2. Retrieve the ID of the key that you want to force delete.

You can retrieve the ID for a specified key by making a GET /v2/keys/ request, or by viewing your keys in the Key Protect dashboard.
3. Run the following curl command to force delete the key and its contents.

$ curl -X DELETE "https://<region>.kms.cloud.ibm.com/api/v2/keys/<keyID_or_alias>?force=true" -H "authorization: Bearer <IAM_token>" -H "bluemix-instance: <instance_ID>" -H "prefer: <return_preference>"

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





Table 2. Describes the variables that are needed to delete keys with the Key Protect API.

 Variable Description 

 region Required. The region abbreviation, such as us-south or eu-gb, that represents the geographic area where your Key Protect instance resides.
"lastUpdateDate": "2020-06-22T21:29:10Z",
"updatedBy": "user id ...<redacted>...",
"dualAuthDelete": {
"enabled": true
}
}
]

 cancel a previously scheduled key delete
$ ibmcloud kp key cancel-delete $KEY_ID

Cancelling key for deletion...
OK





 Required parameters 

KEY_ID
: The ID of the key that you want to delete. To retrieve a list of your available keys, run the [kp keys](#kp-keys) command.







 kp key create 

[Create a root key](https://cloud.ibm.com/docs/key-protect?topic=key-protect-create-root-keys) in the Key Protect instance that you specify or [import your own key](https://cloud.ibm.com/docs/key-protect?topic=key-protect-import-root-keys)

Root keys must be 16, 24, or 32 bytes long; corresponding to 128, 192, or 256 bits.

ibmcloud kp key create KEY_NAME
-i, --instance-id INSTANCE_ID
[-k, --key-material KEY_MATERIAL]
[-n, --encrypted-nonce NONCE]
[-o, --output OUTPUT]
[-s, --standard-key]
[-v, --iv IV]



 Examples 

These are examples of kp key create.



 Example 1 

Create a root key.

 create a root key
$ ibmcloud kp key create my-root-key

Creating key: 'my-root-key', in instance: '390086ac-76fa-4094-8cf3-c0829bd69526'...
OK
Key ID Key Name
24203f96-b134-440e-981a-a24f2d432256 my-root-key
To force the deletion of a root key in Hyper Protect Crypto Services, use the API. Hyper Protect Crypto Services requires that you delete all resources before you delete a root key that is protecting those resources. If you can't delete the key, see [troubleshooting key management service](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-troubleshoot-unable-to-delete-keys).

Block Storage for VPC volumes, snapshots, and custom images with a deleted root key appear in the list of resources with an unusable status. File Storage for VPC shares show a suspended status. The API reason code is encryption_key_deleted.

Deletion of the root key results in the following conditions.



* All instances with an unusable boot volume do not restart.
* You can't attach unusable data volumes to an instance.
* You can't restore a volume from a snapshot.
* You can't access a file share.
* You can't provision instances from unusable images.
* Billing continues for unusable resources until you delete them.



Before you force delete a root key, it's best to review all resources that are associated with that root key. Consider [temporarily disabling the key](https://cloud.ibm.com/docs/vpc?topic=vpc-vpc-encryption-managing&interface=uibyok-disable-root-keys) instead of deleting it to suspend the use of that root key. Root keys can be restored within 30 days, but only if they are imported root keys, not KMS generated.

For more information about deleting root keys, see the following topics.



* [Key Protect - Deleting keys](https://cloud.ibm.com/docs/key-protect?topic=key-protect-delete-keys)
* [Hyper Protect Crypto Services - Deleting keys](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-delete-keys)