vania-janet/multiturn-rag-retrieval-data huggingface dataset:
[Actions icon](https://cloud.ibm.com/docs-content/v1/content/217f108cc44e2ce15fb692d4b57b4c628464e908/icons/action-menu-icon.svg) menu and then click Sync keys.
* You can create external keys with no restrictions.
* You can create vaults only after the master key rotation process is complete.







 How the IBM Cloud console reflects master key rotation 

The following flow shows how master key rotation progress is displayed in the IBM Cloud console:



1. Master key rotation process starts

After you start the master key rotation process by using one of the approaches introduced in [Master key rotation introduction](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-uko-master-key-rotation-intro&interface=ui), you can go back to the IBM Cloud console to view the progress.
2. Key rewrapping starts

After the new master key register is loaded, all managed keys are to be rewrapped by the new master key. If the key-rewrapping progress is failed or the master key rotation is manuallly cancelled, a corresponding notification is displayed in the IBM Cloud console. Under Overview from the navigation, you can view the key progress indicators under Crypto units during the key rewrapping process. Three types of keys progress indicators are displayed:



* System internal keys: Displays the rewrapping progress of any system internal keys that are not accessible by the user, such as the key-encryption keys.
* 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
Check out master key rotation [for the standard plan](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-master-key-rotation-intro) or [for the Unified Key Orchestrator plan](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-uko-master-key-rotation-intro) for more information about how the key states change.



Your encryption keys are now protected by the new master key.

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





 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).
If you need to adjust resources or use a Key Protect key, add the optional parameters key_protect_key, members_disk_allocation_mb, members_memory_allocation_mb, and/or members_cpu_allocation_count, and their values to the body of the request.







 Verifying PITR 

To verify the correct recovery time, check the database logs. Checking the database logs requires the [Logging Integration](https://cloud.ibm.com/docs/databases-for-postgresql?topic=cloud-databases-logging) to be set up on your deployment.

When you perform a recovery, your data is restored from the most recent incremental backup. Any outstanding transactions from the WAL log are used to restore your database up to the time you recovered to. After the recovery is finished, and the transactions are run, the logs display a message. You can check that your logs have the message,

LOG: last completed transaction was at log time 2019-09-03 19:40:48.997696+00

There are two scenarios where recovery does not show up in the logs.



1. Your deployment has a recent full backup and there is no activity after the backup was taken that needs to be replayed.
2. If you entered a time to recover to that is after the current time or is past latest available point-in-time recovery point.



In both cases the recovery is usually still successful, but there won't be an entry in the logs to check the exact time that the database was restored to.
[Retrieving a root key or a standard key](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-retrieve-keyretrieve-key)



* [Retrieving a key with the key management service API](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-retrieve-keyget-key-api)



[Wrapping data encryption keys with root keys](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-wrap-keyswrap-keys)



* [Wrapping keys by using the API](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-wrap-keyswrap-keys-api)



[Unwrapping data encryption keys with root keys](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-unwrap-keysunwrap-keys)



* [Unwrapping keys by using the API](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-unwrap-keysunwrap-key-api)
* [Decoding your key material](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-unwrap-keyshow-to-decode-key-material)



[Rewrapping data encryption keys with root keys](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-rewrap-keysrewrap-keys)



* [Rewrapping keys by using the API](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-rewrap-keysrewrap-key-api)



[Rotating root keys based on the rotation policy](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-set-rotation-policyset-rotation-policy)
"created_by": "IBMid-1308197YB4",
"updated_by": "IBMid-1308197YB4",
"referenced_keystores": [],
"instances": [
{
"id": "ea7b6b27-d71b-4fe9-bbfe-309c7ca713a6",
"label_in_keystore": "IBM CLOUD KEY",
"type": "secret_key",
"keystore": {
"group": "Production",
"type": "ibm_cloud_kms"
}
}
],
"href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/managed_keys/3dab42dc-6941-4841-8d27-4dabcc5aa09e"
}







 hpcs uko managed-key-update 

Update attributes of a managed key. You can only modify the key's state separately from other changes. Changing a key's state affects its availability for cryptographic operations in keystores.

ibmcloud hpcs uko managed-key-update --id ID --uko-vault UKO-VAULT --if-match IF-MATCH [--label LABEL] [--activation-date ACTIVATION-DATE] [--expiration-date EXPIRATION-DATE] [--tags TAGS] [--description DESCRIPTION]



* Command options

--id (string)
: Required. The UUID of the key. 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.
A successful disable request returns an HTTP 204 No Content response, which indicates that the root key was disabled for encrypt and decrypt operations.
5. Optional: Verify that the root key was disabled by retrieving details about the key.

curl -X GET 
https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_id>/metadata 
-H 'authorization: Bearer <IAM_token>' 
-H 'bluemix-instance: <instance_ID>' 
-H 'accept: application/vnd.ibm.kms.key+json'

Review the state field in the response body to verify that the key moved to the Suspended key state. The following JSON output shows the metadata details for a disabled root key.

The integer mapping for the Suspended key state is 2. Key States are based on NIST SP 800-57.

{
"metadata": {
"collectionType": "application/vnd.ibm.kms.key+json",
"collectionTotal": 1
},
"resources": [
{
"type": "application/vnd.ibm.kms.key+json",
"id": "02fd6835-6001-4482-a892-13bd2085f75d",
"name": "...",
"description": "...",
"tags":
"..."
],
"state": 2,
"extractable": false,
The Universally Unique Identifier (UUID) of the vault that your manage key is assigned to. 
 ETag Required. The precondition of the update, which is the value of ETag from the header on a GET request. 



For detailed instructions and code examples about using the API method, check out the [Hyper Protect Crypto Services Unified Key Orchestrator API reference doc](https://cloud.ibm.com/apidocs/ukorotate-managed-key).

A successful rotation request returns an HTTP 204 No Content response, which indicates that your managed key is replaced by the new key material.







 What's next 



* To confirm whether the key rotation is successfully proceeded, you can [view managed key versions](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-uko-view-key-versions).
* After you rotate a managed key, new cryptographic key material becomes available for encryption. To learn how to rewrap data by using the latest key material, see [Rewrapping data after rotating a managed key](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-managed-key-rotation-introrewrap-data-after-managed-key-rotation).
* To find out more about programmatically managing your keys, check out the [Hyper Protect Crypto Services Unified Key Orchestrator API reference doc](https://cloud.ibm.com/apidocs/uko).
"crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/db995d8d9cc715cd99f13b0671d978b6:57da8e3a-a86d-4e01-b840-f22d36e6f23f:bucket:keyprotecttest",
"description": "some description"
}
}
]
}







 hpcs uko managed-key-ds 

Return the keystore distribution status for a managed key.

ibmcloud hpcs uko managed-key-ds --id ID --uko-vault UKO-VAULT



* Command options

--id (string)
: Required. The UUID of the key. 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.
* Example

ibmcloud hpcs uko managed-key-ds 
--id=21a7498e-2ae4-47ee-85ac-a19bf64e92fa 
--uko-vault=eb66ebbd-7230-4cde-89bf-17282cda5faa 
--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",
If you need to adjust resources or use a Key Protect key, add any of the optional parameters key_protect_key, members_disk_allocation_mb, members_memory_allocation_mb, and members_cpu_allocation_count, and their preferred values to the body of the request.







 Backups and Restoration 



* IBM Cloud Databases are not responsible for restoration, timeliness, or validity of said backups.
* Actions that you take as a user can compromise the integrity of backups, such as under-allocating memory and disk. Users can monitor that backups are successful by using the API, and periodically restore a backup to ensure validity and integrity. Users can retrieve the most recent-scheduled backup details from the [Cloud Databases CLI plug-in](https://cloud.ibm.com/docs/cloud-databases?topic=cloud-databases-dashboard-backupsbackups-in-the-cli) and the [Cloud Databases API](https://cloud.ibm.com/docs/cloud-databases?topic=cloud-databases-dashboard-backupsrestoring-a-backup-through-the-api).
* As a managed service, Cloud Databases monitors the state of your backups and can attempt to remediate when possible. If you encounter issues from which you cannot recover, contact support for more help.







 Backup Locations 

Backup location differs per database region. Ensure that the backup region location matches your data location requirements.



Table 1. Database and Backup Regions

 Database Region Backup Region 

 Dallas US Cross Regional Object Storage 
 Washington D.C. US Cross Regional Object Storage 
 London EU Cross Regional Object Storage 
 Frankfurt EU Cross Regional Object Storage 
 Tokyo AP Cross Regional Object Storage 
 Osaka AP Cross Regional Object Storage 
 Sydney AP Cross Regional Object Storage 
 Toronto Montreal Object Storage 
 Chennai Chennai Object Storage 
 Sao Paolo Sao Paolo Object Storage 



For more details about Cloud Databases Object Storage locations, review the location's [documentation](https://cloud.ibm.com/docs/cloud-object-storage?topic=cloud-object-storage-endpointsendpoints-geo).





 Point-in-Time Recovery
For more information, see [Disaster recovery](https://cloud.ibm.com/docs/overview?topic=overview-zero-downtimedisaster-recovery).





 Cross-region disaster recovery 

IBM also performs cross-region backup for your key resources. Your data is automatically backed up in another supported region daily. Depending on where you create your instance and your requirements for recovery time, you can restore your data in case of a regional disaster with the following options:



* If you create your instance in Dallas (us-south) or Washington DC (us-east) and you enable failover crypto units, the failover crypto units back up the operational crypto units and keystores in another region. When a regional disaster occurs, your data is restored automatically with the failover crypto units to reduce the downtime and data loss. For more information about how to use failover crypto units to restore data, see [Restoring your data by using failover crypto units](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-restore-datarestore-data-failover-crypto-units).
* If you don't enable failover crypto units, you can use the default daily backup to restore your data. In this case, you need to open a support ticket so that IBM can create a new service instance in another supported region to restore your data from the backup. Then, you need to manually load your master key to the new instance again to make it work. In this process, you're the only person who owns the master key. IBM administrators or any third-party users can't access your data or keys in the backup or the restored service instance. For more information about the recovery process, see [Restoring your data by opening an IBM support ticket](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-restore-datarestore-data-open-support-ticket).
* Not all crypto units in a single service instance are selected. Or, crypto units in more than one service instance are 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 by 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 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:

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



* If this message is not present, you can recover from the error by clicking the Rotate button again.
* If the message is present, the reencryption of key storage is complete. The only remaining step in the command is to promote the values in the new master key registers to the current master key registers.

Check the state of the new and current master key registers. If all the new master key registers are in the Full Committed state with the same verification pattern and all the current master key registers are in the Valid state with a different same verification pattern, click the Set immediate button to finish the master key rotation.

If for some crypto units the new master key value is moved to the current master key register, clear those crypto units by clicking the Remove crypto units button on the Crypto units tab. Then, click the Set immediate button on the Master keys tab to finish the master key rotation.

In both cases, it is safe to continue past the warning when you click the Set immediate button. Key storage is prepared to accept the new master key value.
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.

ibmcloud hpcs uko key-templates [--vault-id VAULT-ID] [--key-algorithm KEY-ALGORITHM] [--sort SORT] [--limit LIMIT] [--offset OFFSET]



* Command options

--vault-id (string)
: Optional. The UUID of the vault. The length must be 36 characters. The value must match the regular expression /^[-0-9a-z]+$/.

--key-algorithm (string)
: Optional. The algorithm of the returned key templates. Values that can be set are aes, rsa, hmac, and ec.

--sort ([]string)
: Optional. The sorting order. The default value is ["-updated_at"]. The list items must match the regular expression /^-?[a-z0-9_.\[\],-]+$/.

--limit (int64)
: Optional. The number of key templates to retrieve. The value must be between 1 and 1000.
1. [Log in to the IBM Cloud console](https://cloud.ibm.com/).
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 Hyper Protect Crypto Services.
4. On the KMS keys page, use the Keys table to browse the keys in your service.
5. To view the protected resources of a specific root key, 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, and select View associated resources to browse all resources protected by the key.



Table 2. Describes the table of viewing associated resources

 Column Description 

 Resource name The name of the cloud resource, such as a Cloud Object Storage bucket, that is associated with the key. 
 Service name The name of the IBM Cloud service instance that the resource resides in. 
 Retention policy Whether the cloud resource has a retention policy. If the value is True, a retention policy is enabled for the cloud resource, and the key that is associated with the cloud resource can't be deleted. If the value is False, the retention policy isn't enabled. 



6. To view details of each resource, expand the resource details by clicking the caret (^) icon under the Resource name column.

The following table describes the registration details.



Table 3. Describes the properties that are associated with a resource

 Field Description 

 Created The date and time that the resource was first associated with the key. 
 Last updated The date and time that the registration was updated. 
 Description The description of the registration. 
 Key version ID The version of the root key that's protecting the cloud resource. 
 Key version date The date and time that the root key version was updated.
--key='{"size": "256", "algorithm": "aes", "activation_date": "P5Y1M1W2D", "expiration_date": "P1Y2M1W4D", "state": "active"}' 
--keystores='[{"group": "Production", "type": "ibm_cloud_kms"}]' 
--description="IBM CLOUD key template description" 
--output json
* Output

The command returns the output similar to the following example:

ETag
2022-05-20T15:13:37Z
{
"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": "ada4293c-07ed-4903-b3ee-419bd1a05fde",
"version": 0,
"name": "IBM-CLOUD-EXAMPLE-TEMPLATE",
"key": {
"size": "256",
"algorithm": "aes",
"activation_date": "P5Y1M1W2D",
"expiration_date": "P1Y2M1W4D",
"state": "active"
},
"description": "IBM CLOUD key template description",
"created_at": "2022-03-09T15:40:52Z",
"updated_at": "2022-03-09T15:40:52Z",
--keystore-body='{"type": "aws_kms", "vault": {"id": "75d0f626-44b0-4076-80cd-8cb9e485fe73"}, "name": "AWS KMS Keystore", "description": "AWS KMS Keystore", "groups": ["Production", "Production-DE"], "aws_access_key_id": "HSNGYJMKHGFFF", "aws_secret_access_key": "JHGSY766YUG67GFV", "aws_region": "eu_central_1"}' 
--output json
* Output

The command returns the output similar to the following example:

ETag
2022-05-20T14:52:18Z
{
"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": "f6a5ccc1-7fc3-435e-9637-482e470ba8e8",
"name": "IBM Keystore Name",
"description": "The description of the created keystore.",
"groups": [
"IBM Keystore Name"
],
"type": "ibm_cloud_kms",
"created_at": "2022-03-09T11:00:11Z",
"updated_at": "2022-03-09T11:00:11Z",
Encryption keys in key storage are decrypted by using the value in the current master key register and then reencrypted by using the value in the new master key register. The rewrapping takes place inside the hardware security module (HSM), so it's secure.
2. The new master key is activated and loaded to the current master key register in Valid state, and the new master key register is cleared and back to Empty state.





For detailed instructions, 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 

If your service instance has recovery crypto units assigned to it, apart from using workstation files, you can also rotate the master keys using the ibmcloud tke auto-mk-rotate command. With this command, a random new master key value is generated in one of the recovery crypto units for the service instance and securely moved to the other crypto units in the service instance.

You don't need to prepare a new master key before the master key rotation. Before you can rotate the master key with the IBM TKE CLI plug-in, all the current master key registers in both [operational crypto units](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-initialize-instance-modeunderstand-operational-crypto-unit) and [recovery crypto units](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-initialize-instance-modeunderstand-recovery-crypto-unit) need to be in Valid state with the current master key loaded and all the new master key registers needs to be empty.

Comparing to the option where you load a new master key value from your local workstation files, the main difference in this mode is that a new master key value is first randomly generated within a recovery crypto unit and then exported to other crypto units.

The following flow shows how master key rotation works in this mode:



1.
--uko-vault=5295ad47-2ce9-43c3-b9e7-e5a9482c362b 
--if-match=2022-05-11T14:58:26Z 
--keystore-body='{"description": "Updated description", "keystore_type": "aws_kms"}' 
--output json
* Output

The command returns the output similar to the following example:

ETag
2022-05-20T14:59:03Z
{
"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": "f6a5ccc1-7fc3-435e-9637-482e470ba8e8",
"name": "IBM Keystore Name",
"description": "The description of the created keystore.",
"groups": [
"IBM Keystore Name"
],
"type": "ibm_cloud_kms",
"created_at": "2022-03-09T11:00:11Z",
"updated_at": "2022-03-09T11:00:11Z",
"created_by": "IBMid-1308197YB4",
"updated_by": "IBMid-1308197YB4",