vania-janet/multiturn-rag-retrieval-data huggingface dataset:
The cloud-object-storage.bucket-key-state.update actions are triggered by events taking place in Hyper Protect Crypto Services, and require that the bucket is registered with the Hyper Protect Crypto Services service. This registration happens automatically when a bucket is created with a Hyper Protect Crypto Services root key.

Buckets created prior to February 26th, 2020 are not registered with the Hyper Protect Crypto Services service and will not receive notifications of encryption key lifecycle events at this time. These buckets can be identified by performing [a bucket listing operation](https://cloud.ibm.com/docs/cloud-object-storage?topic=cloud-object-storage-compatibility-api-bucket-operationscompatibility-api-list-buckets) and looking at the dates for bucket creation. To ensure that these buckets have the latest key state from Hyper Protect Crypto Services, it is recommended that [some data operation is performed](https://cloud.ibm.com/docs/cloud-object-storage?topic=cloud-object-storage-object-operationsobject-operations-head), such as a PUT, GET, or HEAD on an object in each affected bucket. It is recommended that an object operation is done twice, at least an hour apart, to ensure that the key state is properly in synchronization with the Hyper Protect Crypto Services state.

For more information on Activity Tracker events for object storage, [see the reference topic](https://cloud.ibm.com/docs/cloud-object-storage?topic=cloud-object-storage-at-events).
"href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/managed_keys/5295ad47-2ce9-43c3-b9e7-e5a9482c362b"
},
"key_id_in_keystore": "93777bca-baef-4070-b9b5-a2e6079df1b4",
"type": "com_ibm_cloud_kms_registration",
"com_ibm_cloud_kms_registration": {
"prevents_key_deletion": false,
"service_name": "cloud-object-storage",
"service_instance_name": "Cloud Object Storage-7s",
"crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/db995d8d9cc715cd99f13b0671d978b6:57da8e3a-a86d-4e01-b840-f22d36e6f23f:bucket:keyprotecttest",
"description": "some description"
}
}
]
}







 hpcs uko keystore-status 

Retrieve the status of a target internal or external keystore.

ibmcloud hpcs uko keystore-status --id ID --uko-vault UKO-VAULT



* Command options

--id (string)
: Required. The UUID of the keystore. You can use the ibmcloud hpcs uko keystores command to retrieve the UUID.

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

ibmcloud hpcs uko keystore-status
* Hyper Protect Crypto Services - it can be used when the original back is encrypted by using the Hyper Protect Crypto Services service.





Tags are automatically copied over from the parent backup.
6. Click Save.
7. The Summary updates automatically with the selections that you made. For example, the plan might be "Every Monday at -5:53 UTC (12:30 AM CDT) starting on 26 March 2022." The Plan status toggle is enabled by default.
8. Click Create to save the new plan. The list of plans is updated in the policy details page. If you want to make any changes, click the pencil icon for that plan. If you want to delete the plan, click the delete icon.







 Estimating your expected usage and costs 

Use the cost estimator to see what your backups might cost based on the rate of expected change in your Block Storage for VPC volumes.



1. After you [create your backup policy and plan](https://cloud.ibm.com/docs/vpc?topic=vpc-create-backup-policy-and-planbackup-policy-create-ui), on the side panel of Backup summary, click Add to estimate.
2. On the Estimate side panel, enter your expected usage to the initial costs. The backup policy is without charge. You pay for the amount of backup storage that is used. Provide the following estimates:



* Number of volumes you want to associate with the backup policy.
* Average amount of data per volume (in GBs). For example, you might associate two volumes with a policy. The first volume has 4 GB of data and the second 20 GB. An average of the two would be 12 GB.
* Number of backups per volume per month. You can take a maximum of 750 backup snapshots per volume.
* Percent of incremental change after the initial backup. For example, 15 percent increase in size for each subsequent backup.



3. When you're finished, click Calculate cost.



The cost estimate summary shows how the costs are calculated and breaks down the storage cost, providing a monthly estimate.
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 key that you want to restore.

You can retrieve the ID for a specified key by making a [list keys API request](https://cloud.ibm.com/apidocs/hs-cryptogetkeys), or by viewing your keys in the IBM Cloud console.
4. Run the following curl command to restore the key and regain access to the associated data. You must wait 30 seconds after deleting a key before you are able to restore it.

You cannot restore a key that has an expiration date that is current or in the past.

curl -X POST "https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>/restore" -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>' -H 'x-kms-key-ring: <key_ring_ID>'

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



Table 1. Describes the variables needed to restore keys with the Hyper Protect Crypto Services API

 Variable Description 

 region Required. The region abbreviation, such as us-south or eu-de, that represents the geographic area where your Hyper Protect Crypto Services service instance resides. For more information, see [Regional service endpoints](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-regionsservice-endpoints). 
 port Required. The port number of the API endpoint. 
 key_ID Required. The unique identifier for the key that you want to restore. 
 IAM_token Required. Your IBM Cloud access token. Include the full contents of the IAM token, including the Bearer value, in the cURL request.
* Hyper Protect Crypto Services - it can be used when the original back is encrypted by using the Hyper Protect Crypto Services service.





Tags are automatically copied over from the parent backup.
6. Click Save.
7. The Summary updates automatically with the selections that you made. For example, the plan might be "Every Monday at -5:53 UTC (12:30 AM CDT) starting on 26 March 2022." The Plan status toggle is enabled by default.
8. Click Create to save the new plan. The list of plans is updated in the policy details page. If you want to make any changes, click the pencil icon for that plan. If you want to delete the plan, click the delete icon.







 Estimating your expected usage and costs 

Use the cost estimator to see what your backups might cost based on the rate of expected change in your Block Storage for VPC volumes.



1. After you [create your backup policy and plan](https://cloud.ibm.com/docs/vpc?topic=vpc-create-backup-policy-and-plan&interface=terraformbackup-policy-create-ui), on the side panel of Backup summary, click Add to estimate.
2. On the Estimate side panel, enter your expected usage to the initial costs. The backup policy is without charge. You pay for the amount of backup storage that is used. Provide the following estimates:



* Number of volumes you want to associate with the backup policy.
* Average amount of data per volume (in GBs). For example, you might associate two volumes with a policy. The first volume has 4 GB of data and the second 20 GB. An average of the two would be 12 GB.
* Number of backups per volume per month. You can take a maximum of 750 backup snapshots per volume.
* Percent of incremental change after the initial backup. For example, 15 percent increase in size for each subsequent backup.



3. When you're finished, click Calculate cost.
When the reencryption is done, the value in the new master key registers is moved to the current master key registers and the new master key registers are cleared.
* If the first message is present but the second message is not, reencryption of key storage has started. To recover, run the ibmcloud tke cryptounit-mk-rotate command. This command restarts the process with a request to reencrypt key storage and does not replace the master key value in the new master key registers.

Do not rerun the ibmcloud tke auto-mk-rotate command. If you do, the contents of key storage becomes unusable.
* If both messages are present, the reencryption of key storage is complete. The only remaining step is to promote the values in the new master key registers to the current master key registers. Run the ibmcloud tke cryptounit-mks command. If all the new master key registers are in the Valid state with the same verification pattern and all the current master key registers are in the Valid state with a different same verification pattern, run the ibmcloud tke cryptounit-mk-setimm command to finish the master key rotation.

If for some crypto units the new master key value has already been moved to the current master key register, clear those crypto units by using the ibmcloud tke cryptounit-rm command. Then, run the ibmcloud tke cryptounit-mk-setimm command to finish the master key rotation.

In both cases, it is safe to continue past the warning on the ibmcloud tke cryptounit-mk-setimm command. Key storage has been prepared to accept the new master key value.
* IBM Cloud KMS keys: Displays the rewrapping progress of KMS keys that are stored in the internal KMS keystores.



If the only rewrapped keys are System internal keys, you can view the progress in the form of a percentage indicator under Crypto units. If multiple types of keys that need to be rewrapped, you can view the latest key-rewrapping progress by clicking the refresh button next to Crypto units or reloading the web page.
3. Key rewrapping is complete

After the key rewrapping process is complete, a notification is displayed in the IBM Cloud console. Then, you can continue to commit and activate the new master key using the approach that you choose.
4. Master key rotation is complete

After the master key rotation process is complete, a notification is displayed in the IBM Cloud console. Under Overview from the navigation, you can also find the timestamp of the key updates under Crypto units.







 What's next 

For more detailed instructions on options to rotate master keys, see:



* [Rotating master keys by using smart cards and the Management Utilities](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-rotate-master-key-smart-cards).
* [Rotating master keys by using recovery crypto units](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-rotate-master-key-cli-recovery-crypto-unit).
* [Rotating master keys by using workstation files](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-rotate-master-key-cli-key-part).
* Hyper Protect Crypto Services - it can be used when the original back is encrypted by using the Hyper Protect Crypto Services service.





Tags are automatically copied over from the parent backup.
6. Click Save.
7. The Summary updates automatically with the selections that you made. For example, the plan might be "Every Monday at -5:53 UTC (12:30 AM CDT) starting on 26 March 2022." The Plan status toggle is enabled by default.
8. Click Create to save the new plan. The list of plans is updated in the policy details page. If you want to make any changes, click the pencil icon for that plan. If you want to delete the plan, click the delete icon.







 Estimating your expected usage and costs 

Use the cost estimator to see what your backups might cost based on the rate of expected change in your Block Storage for VPC volumes.



1. After you [create your backup policy and plan](https://cloud.ibm.com/docs/vpc?topic=vpc-create-backup-policy-and-plan&interface=clibackup-policy-create-ui), on the side panel of Backup summary, click Add to estimate.
2. On the Estimate side panel, enter your expected usage to the initial costs. The backup policy is without charge. You pay for the amount of backup storage that is used. Provide the following estimates:



* Number of volumes you want to associate with the backup policy.
* Average amount of data per volume (in GBs). For example, you might associate two volumes with a policy. The first volume has 4 GB of data and the second 20 GB. An average of the two would be 12 GB.
* Number of backups per volume per month. You can take a maximum of 750 backup snapshots per volume.
* Percent of incremental change after the initial backup. For example, 15 percent increase in size for each subsequent backup.



3. When you're finished, click Calculate cost.
encryption_key = "crn:v1:staging:public:kms:us-south:a/df0564dd126042ebb03e0224728ce939:4957299d-0ba0-487f-a1a0-c724a729b8b4:key:0cb88b98-9261-4d07-8329-8f594b6641b5"
}

For more information about the arguments and attributes, see [ibm_is_snapshot](https://registry.terraform.io/providers/IBM-Cloud/ibm/latest/docs/resources/is_snapshot).





 Next steps 

After you create a snapshot, you can view more details about it or restore a volume from the snapshot.



* [View](https://cloud.ibm.com/docs/vpc?topic=vpc-snapshots-vpc-view) all the snapshots that you created, or details about a single snapshot.
* [Restore a volume](https://cloud.ibm.com/docs/vpc?topic=vpc-snapshots-vpc-restore) from a snapshot.
Do not delete a key that is actively protecting data in your production environments.

Within 30 days after you delete a key, you can restore the key to reverse the deletion. For more information, see [Restoring keys](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-restore-keys).

Note that even if the key is not restored, your data remains in those services in the encrypted form. Metadata that is associated with a key, such as the key's transition history and name, is kept in the Hyper Protect Crypto Services database.

To help you determine what data is protected by a key, you can use the key management service API to [view associations between a key and your cloud resources](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-view-protected-resources).







 Compliance readiness 

Hyper Protect Crypto Services helps meet controls for global, industry, and regional compliance standards. The hardware security module (HSM) meets Common Criteria EAL 4 and is FIPS 140-Level 4 certified. The service is GDPR, HIPAA, and ISO certified.

For a complete listing of IBM Cloud compliance certifications, see [Compliance on the IBM Cloud](https://www.ibm.com/cloud/compliance).



 Common Criteria EAL4 certified 

The Hardware Security Module (HSM) used by Hyper Protect Crypto Services is the IBM PCIe Cryptographic Coprocessor Version 3 (PCIeCC3) or Version 4 (PCIeCC4). PCIeCC3 is also referred to as the IBM 4768 crypto card or the Crypto Express 6S (CEX6S). PCIeCC4 is also referred to as the IBM 4769 crypto card or the Crypto Express 7S (CEX7S). Both CEX6S and CEX7S are Common Criteria EAL4 certified to meet the security requirements defined by the Common Criteria for Information Technology Security Evaluation.

Common Criteria is an international standard (ISO/IEC 15408) to assess the security of computer security products.
* When you rotate your master key by using key part files, an invalid set of crypto units is selected.
* One or more crypto units are in imprint mode.
* Signature thresholds on the crypto units are not set the same.
* A common set of administrators is not selected and installed in all crypto units large enough to meet the signature threshold value.
* The current master key registers are not all in the Valid state with the same verification pattern.
* When you rotate your master key using key part files, the new master key registers are not all in the Valid state with the same verification pattern.



Operational workloads cannot be run until master key rotation has completed.

 How to fix it 

If an error occurs when you run the ibmcloud tke auto-mk-rotate command to rotate master keys, check whether the error is an expired authentication token or failed pre-check. If it is not, check whether the following messages are displayed:



* The following message indicates that all new master key registers have been set with a randomly generated new master key value:

> Delaying 30 seconds to allow server to discover new master key values
* The following message indicates that the reencryption of key storage is completed:

> KMS CRK rewrap successful, waiting on cryptounit-mk-setimm



Depending on the presence of the described messages, perform one of the following tasks:



* If neither message is present, you can recover from the error by running the ibmcloud tke auto-mk-rotate command again. Rerunning this command loads a new random master key value in the new master key registers and overwrites the previous value. This command then continues by reencrypting key storage. When the reencryption is done, the value in the new master key registers is moved to the current master key registers and the new master key registers are cleared.
* If the first message is present but the second message is not, reencryption of key storage has started. To recover, run the ibmcloud tke cryptounit-mk-rotate command. This command restarts the process with a request to reencrypt key storage and does not replace the master key value in the new master key registers.
Not seeing the full list of keys that are stored in your service instance? Verify with your administrator that you are assigned the correct role for the applicable service instance or individual key. For more information about roles, see [Roles and permissions](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-manage-accessroles).

You can also search for a specific key by using the search bar, or filter keys based on your needs by clicking the Filter icon ![Filter icon](https://cloud.ibm.com/docs-content/v1/content/217f108cc44e2ce15fb692d4b57b4c628464e908/icons/filter.svg) in the Keys table.







 Viewing root keys or standard keys with the key management service API 

You can retrieve the contents of your keys by using the Hyper Protect Crypto Services key management service API.



 Retrieving a list of your root keys or standard keys 

For a high-level view, you can browse your root keys or standard keys that are managed in your provisioned instance of Hyper Protect Crypto Services by making a GET call to the following endpoint.

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



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. View general characteristics about your keys by running the following cURL command.

curl -X GET "https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys" -H 'accept: application/vnd.ibm.collection+json' -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>' -H 'x-kms-key-ring: <key_ring_ID>' -H 'correlation-id: <correlation_ID>'
The new master key is now in Valid state in the current master key register. Check out [Master key rotation](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-master-key-rotation-intro) for information on how the key states change.



You have successfully rotated the current master key with the new master key. Your encryption keys are now well protected by the new master key.

If an error occurs during master key rotation, see [Why can't I rotate master keys using smart cards](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-troubleshoot-master-key-rotation-key-smart-cards).





 What's next 



* To find out more about programmatically managing your keys, check out the Hyper Protect Crypto Services [key management service API reference doc](https://cloud.ibm.com/apidocs/hs-crypto) or the [Unified Key Orchestrator API reference doc](https://cloud.ibm.com/apidocs/uko).
* To find out more about encrypting your data by using the cloud HSM function of Hyper Protect Crypto Services, check out the

[PKCS #11 API reference](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-pkcs11-api-ref) and [GREP11 API reference doc](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-grep11-api-ref).
Select the key that you want to restore and click the Actions icon ![Actions icon](https://cloud.ibm.com/docs-content/v1/content/217f108cc44e2ce15fb692d4b57b4c628464e908/icons/action-menu-icon.svg) to open a list of options for the key.
6. From the options menu, click Restore key.
7. Click Restore key to confirm the action.







 Restoring a deleted key with the API 

Restore a key by making a POST call to the following endpoint.

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



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).

To restore a key, you must be assigned a Manager access policy 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 key that you want to restore.

You can retrieve the ID for a specified key by making a [list keys API request](https://cloud.ibm.com/apidocs/hs-cryptogetkeys), or by viewing your keys in the IBM Cloud console.
4.
-H 'authorization: Bearer <IAM_token>' 
-H 'bluemix-instance: <instance_ID>'
-H 'accept: application/vnd.ibm.kms.key+json'

Review the lastRotateDate and keyVersion values in the response entity-body to inspect the date and time that your key was last rotated.

You can also list the versions that are available for the key by using the Hyper Protect Crypto Services API. To learn more, see [Viewing key versions](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-view-key-versions).









 What's next 



* After you rotate a root key, new cryptographic key material becomes available for protecting the data encryption keys (DEKs) that are associated with the root key. Learn how to reencrypt or rewrap your DEKS without exposing the keys in their plain text form, see [Rewrapping keys](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-rewrap-keys).
* To learn how envelope encryption helps you control the security of at-rest data in the cloud, see [Protecting data with envelope encryption](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-envelope-encryption).
* To find out more about programmatically managing your keys, [check out the Hyper Protect Crypto Services key management service API reference doc](https://cloud.ibm.com/apidocs/hs-crypto).