vania-janet/multiturn-rag-retrieval-data huggingface dataset:
Retrieving a root key or a standard key 

You can retrieve a root key or standard key by using IBM Cloud® Hyper Protect Crypto Services.

If you have a Writer or Manager access policy, you can retrieve the contents of a standard key, such as the key material and policy details.

Root keysstay within the bounds of a hardware security module. The key material for a root key cannot be retrieved.



 Retrieving a key with the key management service API 

To view detailed information about a specific key, you can make a GET call to the following endpoint.

https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID_or_alias>



1. [Retrieve your service and 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 standard key that you would like to access or manage.

The ID value is used to access detailed information about the standard key, such as the key material itself. You can retrieve the ID for a specified key by making a GET /v2/keys request, or by accessing the IBM Cloud console.
3. Run the following cURL command to get details about your key and the key material.

curl -X GET "https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID_or_alias>" -H 'accept: application/vnd.ibm.kms.key+json' -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>' -H "x-kms-key-ring: <key_ring_ID>" -H 'correlation-id: <correlation_ID>'

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



Table 4. Describes the variables needed to view a specified key with the API

 Variable Description 

 region Required.
You can also [use the Unified Key Orchestrator API](https://cloud.ibm.com/apidocs/ukoget-vault) to retrieve a list of your vaults, along with the metadata of the vaults.





 Step 2. Grant access to vaults from the IBM Cloud UI 

To assign access to a vault for a user from the UI, complete the following steps:



1. From the menu bar, click Manage > Access (IAM), and select Users to browse the existing users in your account.
2. Select the user from the table, and click the Actions icon ![Actions icon](https://cloud.ibm.com/docs-content/v1/content/217f108cc44e2ce15fb692d4b57b4c628464e908/icons/action-menu-icon.svg), and then select Assign access.
3. Click Access policy.
4. Under Service, select Hyper Protect Crypto Services and click Next.
5. Under Resources, select Specific resources.
6. Select Service Instance ID and enter the [instance ID that is retreived](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-retrieve-instance-ID).
7. Click Add a condition, select the Vault ID attribute to enter the vault ID that is retrieved in [Step 1](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-grant-access-vaultsaccess-vault-retrieve-ID), and click Next
8. Under Roles and actions, choose a combination of [platform and service access roles](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-manage-accessroles) to assign access for the user and click Next.
9. (Optional) Under Conditions (optional), click Review to check the access policy.
10. After confirmation, click Add > Assign.
If bucket creation fails with a 400 Bad Request error with the message The Key CRN could not be found, ensure that the CRN is correct and that the service to service authorization policy exists.

In the Buckets listing, the bucket now has a View link under Attributes, indicating that the bucket has a Hyper Protect Crypto Services key enabled. To view the key details (along with other object metadata), click View.

Note that the Etag value returned for objects encrypted using Hyper Protect Crypto Services will be the actual MD5 hash of the original decrypted object.

It is also possible to use [the REST API](https://cloud.ibm.com/docs/cloud-object-storage?topic=cloud-object-storage-compatibility-api-bucket-operationscompatibility-api-key-protect) or SDKs ([Go](https://cloud.ibm.com/docs/cloud-object-storage?topic=cloud-object-storage-using-gogo-examples-kp), [Java](https://cloud.ibm.com/docs/cloud-object-storage?topic=cloud-object-storage-javajava-examples-kp), [Node.js](https://cloud.ibm.com/docs/cloud-object-storage?topic=cloud-object-storage-nodenode-examples-kp), or [Python](https://cloud.ibm.com/docs/cloud-object-storage?topic=cloud-object-storage-pythonpython-examples-kp)).



 Creating Cross Region buckets 

Creating COS Cross Region bucket with a root key from a Hyper Protect Crypto Services instance requires that instance to be [configured with failover configuration](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-enable-add-failover).

You can confirm that failover is properly configured for the selected Hyper Protect Crypto Services instance correctly using either the IBM Cloud console or CLI.

From IBM Cloud console, navigate to a Hyper Protect Crypto Services instance and click on Overview. A "Failover" section will indicate the status of crypto units in the corresponding failover regions.
You can see the key name, key ID, CRN, creation date, version date, last updated date, last rotated date, and so on.



After you [rotate the key](https://cloud.ibm.com/docs/vpc?topic=vpc-vpc-key-rotation), the version ID field and key version date are updated. The rotated key retains its original name and ID in the list of KMS instances.





 User actions that impact root key states and resource status 

Root keys move to various states as a result of the actions that you take, and different root key states impact resources differently. The following table describes what happens to a resource when you disable, enable, delete, and restore a root key.

Disable root key

Enable root key

Delete root key



Table 1. Disable root key

 Resource type Resource status Result 

 Root key state = suspended<br><br>[1] 
 All -- The key can't be used to encrypt new resources or unwrap (decrypt) passphrases that are protecting existing resources until you enable the key. For more information, see [Disabling root keys](https://cloud.ibm.com/docs/vpc?topic=vpc-vpc-encryption-managing&interface=uibyok-disable-root-keys). 
 Custom image unusable Images cannot be used for creating boot volumes during instance provisioning. 
 Boot volume available Boot volumes remain encrypted with the suspended key. If you stop the instance that uses that boot volume, it can't restart. 
 Data volume available Data volumes remain encrypted, attached, and available until you stop the instance. Stand-alone data volumes that are encrypted by the suspended key can't be attached to an instance. 
 Snapshot unusable Snapshot cannot be used to restore a volume. 
 File shares stable Data on the file share is accessible but you can't create a file Share with that key. 
 Instance available Instance workloads continue to run with an available status in the CLI and API, and with a running status in the UI. If you stop instances, they can't restart.
"resources": [
{
"type": "application/vnd.ibm.kms.key+json",
"id": "02fd6835-6001-4482-a892-13bd2085f75d",
"name": "test-standard-key",
"state": 1,
"extractable": true,
"crn": "crn:v1:bluemix:public:hs-crypto:us-south:a/f047b55a3362ac06afad8a3f2f5586ea:12e8c9c2-a162-472d-b7d6-8b9a86b815a6:key:02fd6835-6001-4482-a892-13bd2085f75d",
"imported": false,
"creationDate": "2020-03-12T03:50:12Z",
"createdBy": "...",
"algorithmType": "AES",
"algorithmMetadata": {
"bitLength": "256",
"mode": "CBC_PAD"
},
"algorithmBitSize": 256,
"algorithmMode": "CBC_PAD",
"lastUpdateDate": "2020-03-12T03:50:12Z",
"dualAuthDelete": {
"enabled": false
},
"deleted": false
}
]
}

Need to retrieve the payload value for a standard key? To learn more, see [Retrieving a root key or a standard key](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-retrieve-key).

For a detailed description of the response parameters, see the Hyper Protect Crypto Services key management [REST API reference doc](https://cloud.ibm.com/apidocs/hs-crypto).
If you import a root key into Key Protect, you are encouraged to maintain a secure backup of the key material so that you can restore the root key if it is accidentally deleted and the [30-day grace period to restore a deleted key](https://cloud.ibm.com/docs/key-protect?topic=key-protect-delete-purge-keys) has elapsed. In other words, within 30 days, Key Protect allows customers to restore a deleted key without having to use a backup.

Because two keys created using the same key material are effectively identical (both can unwrap any data encryption keys (DEKs) created by either root key), it is possible to securely backup your root keys by creating a duplicate key for every imported root key within your instance. Each duplicate key should be created in a Key Protect region that is different from the original key, which means that the key_id and service instance ID of the keys will be different. Your application will therefore be able to use either key as long as it knows the relevant IDs and endpoints of both keys.

Note that every time a root key is rotated, new key material is added to the key, which creates a new version of the key. Therefore, make sure to use this updated key material when rotating your duplicated keys.

Applications that communicate over networks are subject to transient faults. You should design your application to interact with Key Protect by using modern resiliency techniques, for example an exponential backoff that retries requests with exponentially increasing delays between each request.



 Example algorithm 

There are many approaches to implementing retries with exponential backoff logic. Your approach will depend on your specific use case and the network conditions surrounding your application. The following is an example implementation of incremental retry delay.

const maxRetries = 3
attempt := 1
delay := time.Second * 1
var ok bool
for !ok && attempt <= maxRetries {
ok = makeRequest()
if !ok {
time.Sleep(delay)
delay = delay * 2
attempt += 1
}
}
[Refresh your access token](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-retrieve-access-token) and check whether you have [appropriate permissions](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-manage-access) to perform the corresponding actions.

If the event has a reason.reasonCode of 500, check out the value of reason.reasonForFailure to identify the reasons of failure and the corresponding actions that you need to take.







 Event severity 

The severity for all Activity Tracker events with Hyper Protect Crypto Services is based on the type of request that was made, then status code. For example, you might request to create a key with an invalid key and are not authenticated in the service instance. The unauthentication takes precedence and the event is evaluated as a 401 bad request call with a severity of critical.

The severity level for all TKE events is critical due to the sensitivity of the actions.

The following table lists the actions that are associated with each severity level:



Table 20. Severity level for Hyper Protect Crypto Services service actions

 Severity Actions
List of Additional Parameters 



* backup_id- A CRN of a backup resource to restore from. The backup must be created by a database deployment with the same service ID. The backup is loaded after provisioning and the new deployment starts up that uses that data. A backup CRN is in the format crn:v1:<...>:backup:<uuid>. If omitted, the database is provisioned empty.
* version - The version of the database to be provisioned. If omitted, the database is created with the most recent major and minor version.
* disk_encryption_key_crn - The CRN of a KMS key (for example, [Hyper Protect Crypto Services](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-get-started) or [Key Protect](https://cloud.ibm.com/docs/key-protect?topic=key-protect-about)), which is then used for disk encryption. A KMS key CRN is in the format crn:v1:<...>:key:<id>.
* backup_encryption_key_crn - The CRN of a KMS key (for example, [Hyper Protect Crypto Services](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-get-started) or [Key Protect](https://cloud.ibm.com/docs/key-protect?topic=key-protect-about)), which is then used for backup encryption. A KMS key CRN is in the format crn:v1:<...>:key:<id>.

To use a key for your backups, you must first [enable the service-to-service delegation](https://cloud.ibm.com/docs/cloud-databases?topic=cloud-databases-key-protectbyok-for-backups).
* members_memory_allocation_mb - Total amount of memory to be shared between the database members within the database.
[checkmark icon](https://cloud.ibm.com/docs-content/v1/content/217f108cc44e2ce15fb692d4b57b4c628464e908/icons/checkmark-icon.svg) 







 Monitoring for lifecycle changes 

After you add a managed key to the service, use the IBM Cloud UI or the Unified Key Orchestrator API to view your key's transition history and configuration.

For audit purposes, you can also monitor the activity trail for a managed key by integrating Hyper Protect Crypto Services with the [IBM Cloud Activity Tracker](https://cloud.ibm.com/docs/activity-tracker?topic=activity-tracker-getting-started). After both services are provisioned and running, activity events are generated and automatically collected in a IBM Cloud Activity Tracker log when you perform actions on keys in Hyper Protect Crypto Services.





 What's next 



* To find out instructions on creating a managed key, check out [Creating managed keys](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-create-managed-keys).
* To find out instructions on editing a managed key, check out [Editing key details](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-edit-kms-keys).
* To find out more about managing your key list, check out [Viewing a list of keys](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-view-key-list) or [Filtering and searching keys](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-search-key-list).
* To find out instructions on deleting a managed key, check out [Deleting managed keys](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-delete-managed-keys).
When you disable a root key, the key moves to the [Suspended state](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-key-states), and it can no longer be used to encrypt data.

For an integrated cloud service that supports revoking access to a disabled root key, the service can take up to 4 hours to revoke access to the associated data of the root key. After access to the associated data is revoked, a corresponding disable event is displayed in the Activity Tracker web UI.

You can disable a root key that's in the Active key state by making a POST call to the following endpoint.

https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>/actions/disable



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-apiretrieve-kms-credentials).

To disable a root key, you must be assigned a Manager service access role for the instance or key. To learn how IAM roles map to Hyper Protect Crypto Services service actions, check out [Service access roles](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-manage-accessservice-access-roles).
2. Retrieve the key management service API endpoint URL.

You can get the API endpoint from your provisioned service instance dashboard through Overview > Connect > Key management endpoint URL. Or, you can dynamically [retrieve the API endpoint URL](https://cloud.ibm.com/apidocs/hs-cryptogetinstance) with an API call. Select the public or private key manage endpoint URL based on your needs.
3. Retrieve the ID of the root key that you want to disable.
$ ibmcloud kp key show $KEY_ID --output json

{
"id": "5b976173-7804-4f82-acfa-bb98098bc528",
"name": "my-root-key",
"type": "application/vnd.ibm.kms.key+json",
"algorithmType": "AES",
"createdBy": "user id ...<redacted>...",
"creationDate": "2020-06-10T18:09:27Z",
"lastUpdateDate": "2020-06-10T18:13:31Z",
"lastRotateDate": "2020-06-10T18:13:31Z",
"keyVersion": {
"id": "4330715a-918b-4718-b5ca-9475a214067e",
"creationDate": "2020-06-10T18:13:31Z"
},
"extractable": false,
"state": 1,
"crn": "crn:v1:bluemix:public:kms:us-south:a/ea998d3389c3473aa0987652b46fb146:390086ac-76fa-4094-8cf3-c0829bd69526:key:5b976173-7804-4f82-acfa-bb98098bc528"
}

 unwrap the ciphertext, reveal the original DEK (plaintext),
 and see the new ciphertext (the plaintext wrapped with the rotated root key)
$ ibmcloud kp key unwrap $KEY_ID $CIPHERTEXT --output json

{
"Plaintext": "UPJ4YDwbQMjQG/aqlHsPhHV1CBkpIXngLHFS5+i4UZ4=",
You can view the bucket location in the IBM Cloud console with these steps:



1. From the IBM Cloud console, select Storage to view your resource list.
2. Next, select the service instance with your bucket from within the Storage category. This takes you to the Object Storage Console.
3. Choose the bucket for which you want to see location and endpoints.
4. Select Configuration from the navigation menu to view the page with Location and Endpoints data.



Or you can list bucket information with a GET request that includes the “extended” parameter as shown in [Getting an extended listing](https://cloud.ibm.com/docs/cloud-object-storage/basics?topic=cloud-object-storage-compatibility-api-bucket-operationscompatibility-api-list-buckets-extended).





 How do I encrypt my data? 



1. Go to the IBM Cloud Object Storage documentation for [managing encryption](https://cloud.ibm.com/docs/cloud-object-storage?topic=cloud-object-storage-encryption) to research the encryption topic.
2. Choose between [IBM® Key Protect for IBM Cloud®](https://cloud.ibm.com/docs/key-protect?topic=key-protect-about) and [Hyper Protect Crypto Services](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-overview) for your encryption needs.
3. Remember that customer-provided keys are enforced on objects.
4. Use [IBM Key Protect](https://cloud.ibm.com/docs/key-protect?topic=key-protect-about) or [Hyper Protect Crypto Services](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-overview) to create, add, and manage keys, which you can then associate with your instance of IBM Cloud Object Storage.
5. Grant service authorization



1. Open your IBM Cloud dashboard.
2. From the menu bar, click Manage > Access.
3. In the side navigation, click Authorizations.
You can use the ibmcloud hpcs uko managed-keys command to retrieve the key UUID.

--uko-vault (string)
: Required. The UUID of the vault where the update is to take place. You can use the ibmcloud hpcs uko vaults command to retrieve the vault UUID.

--if-match (string)
: Required. The precondition of the update, which is the value of the ETag from the header on a GET request. You can use the ibmcloud hpcs uko managed-key command to retrieve the ETag.
* Example

ibmcloud hpcs uko managed-key-sync 
--id=b28bf13d-f49d-4b00-8b8d-457d38ad1e15 
--uko-vault=eb66ebbd-7230-4cde-89bf-17282cda5faa 
--if-match=2022-05-27T10:14:13Z 
--output json
* Output

The command returns the output similar to the following example:

{
"status_in_keystores": [
{
"keystore": {
"id": "b28bf13d-f49d-4b00-8b8d-457d38ad1e15",
"name": "AWS KMS Keystore Name",
"type": "aws_kms",
"href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/keystores/b28bf13d-f49d-4b00-8b8d-457d38ad1e15"
},
"status": "not_present"
}
]
}







 hpcs uko key-templates 

List all key templates in the instance.

If the --all-pages option is not set, the command only retrieves a single page of the collection.
"algorithm": "aes",
"activation_date": "P5Y1M1W2D",
"expiration_date": "P1Y2M1W4D",
"state": "active"
},
"description": "IBM CLOUD key template description",
"created_at": "2022-03-09T11:00:47Z",
"updated_at": "2022-03-09T11:00:47Z",
"created_by": "IBMid-1308197YB4",
"updated_by": "IBMid-1308197YB4",
"keystores":
{
"group": "Production",
"type": "ibm_cloud_kms"
}
],
"href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/templates/93777bca-baef-4070-b9b5-a2e6079df1b4"
},
{
"vault": {
"id": "5295ad47-2ce9-43c3-b9e7-e5a9482c362b",
"name": "Test Vault Name",
"href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/vaults/5295ad47-2ce9-43c3-b9e7-e5a9482c362b"
},
"id": "4411f1ae-62cc-484e-9910-65d2e8f258bb",
"version": 0,
"name": "AZURE-EXAMPLE-TEMPLATE",
"key": {
"size": "2048",
"algorithm": "rsa",
* [Added: Synchronizing protected resources associated with root keys](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-what-newadd-sync-resources)
* [Added: Using Virtual Private Endpoints for VPC](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-what-newadd-vpe-for-vpc)
* [Updated: The cryptography algorithm that is used to generate signature keys](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-what-newupdate-signature-key-algorithm)



* [28 February 2021](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-what-newhs-crypto-february2021)



[Added: Key verification by using the PKCS #11 API](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-what-newadd-key-verification)
* [Added: Support for the Schnorr algorithm](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-what-newadd-schnorr)



* [31 January 2021](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-what-newhs-crypto-january2021)



* [Added: Support for a single-tenant KMIP adapter](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-what-newadd-support-kmip-adapter)



* [31 December 2020](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-what-newhs-crypto-december2020)
A vault appears in the list if it is assigned to the user, or if the user added it in the computer’s Vault Settings.
* In the Log File Options list, select the level of detail for job logging. For more information, see [Log file options](https://cloud.ibm.com/docs/Backup?topic=Backup-configureMSSQLBackupSQLDBLogfile).
* For new backup jobs, the encryption method is AES 256 bit. Existing jobs can have other encryption methods. For more information, see [Encryption settings](https://cloud.ibm.com/docs/Backup?topic=Backup-configureMSSQLBackupSQLDBEncrypt).
* In the Password and Confirm Password boxes, enter an encryption password. You can also enter a password hint in the Password Hint box.



8. In the Select Databases for Backup box, select the database that you want to back up.



* To add specific databases to the backup job, select the checkbox for each database, and then click Include. The included databases appear in the Backup Set box.
* To back up all databases in the selected SQL Server instance, select the checkbox for the instance, and then click Include. The included instances appear in the Backup Set box.



When the job runs, newly added databases in the selected instance are automatically backed up.



* To back up databases with names that match a filter when the job runs, select the checkbox for the SQL Server instance, and then click Include. An inclusion record with an asterisk () appears in the Backup Set box. In the Database Filter box, enter the names of databases to include. Separate multiple names with commas, and use asterisks () and question marks (?) as wildcard characters. Filters are applied when the backup job runs. New databases that match the specified filters are automatically backed up when the job runs.



For example, to back up databases with names that end with “Management” or include the word “database” followed by a single character, enter the following filter: management, database?.
9.