vania-janet/multiturn-rag-retrieval-data huggingface dataset:
The backup of the master key relies on the backup of the smart cards in that case.

For more information about the Hyper Protect Crypto Services components, see [Components and concepts](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-uko-understand-concepts).





 Hyper Protect Crypto Services workload isolation 

Hyper Protect Crypto Services is a single-tenant, regional service that supports complete tenant-based workload isolation with the following characteristics:



* Dedicated keystore in Hyper Protect Crypto Services is provided to ensure data isolation and security.
* You have exclusive control to your hardware security module (HSM) and your master key. Privileged users are locked out for protection against abusive use of system administrator credentials or root user credentials.
* [Secure Service Container (SSC)](https://www.ibm.com/marketplace/secure-service-container) provides the enterprise level of security and impregnability that enterprise customers expect from [IBM LinuxONE](https://www.ibm.com/it-infrastructure/linuxone) technology.



The following diagram illustrates how Hyper Protect Crypto Services workload of each tenant is isolated.

Zoom

![Hyper Protect Crypto Services workload isolation](https://cloud.ibm.com/docs-content/v1/content/217f108cc44e2ce15fb692d4b57b4c628464e908/hs-crypto//images/architecture-workload-isolation.svg)

Figure 2. Hyper Protect Crypto Services workload isolation





 Service dependencies 

Hyper Protect Crypto Services has dependencies on the following IBM Cloud services:



* [IBM Cloud® Identity and Access Management (IAM)](https://cloud.ibm.com/docs/account?topic=account-iamoverview)
* [IBM Cloud Databases for PostgreSQL](https://cloud.ibm.com/docs/databases-for-postgresql?topic=databases-for-postgresql-getting-started)
mkfs.ext4 /dev/mapper/cryptData
10. Mount the volume.



 mkdir /cryptData

 mount /dev/mapper/cryptData /cryptData

 df -H /cryptData



 Unmounting and closing the encrypted volume securely 

 umount /cryptData
 cryptsetup luksClose cryptData





 Remounting and mounting an existing LUKS encrypted partition 

 cryptsetup luksOpen /dev/mapper/3600a0980383034685624466470446564 cryptData
Enter the password previously provided.
 mount /dev/mapper/cryptData /cryptData
 df -H /cryptData
 lsblk
NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT
xvdb 202:16 0 2G 0 disk
└─xvdb1 202:17 0 2G 0 part [SWAP]
xvda 202:0 0 25G 0 disk
├─xvda1 202:1 0 256M 0 part /boot
└─xvda2 202:2 0 24.8G 0 part /
sda 8:0 0 20G 0 disk
└─3600a0980383034685624466470446564 (dm-0) 253:0 0 20G 0 mpath
└─cryptData (dm-1) 253:1 0 20G 0 crypt /cryptData
sdb 8:16 0 20G 0 disk
└─3600a0980383034685624466470446564 (dm-0) 253:0 0 20G 0 mpath
└─cryptData (dm-1) 253:1 0 20G 0 crypt /cryptData
Show more
The command returns the output similar to the following example:

{
"total_count": 3,
"limit": 20,
"offset": 0,
"first": {
"href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/keystores?limit=20"
},
"last": {
"href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/keystores?limit=20&offset=0"
},
"keystores": [
{
"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": "5312861e-5b9b-4f40-9264-997afc2cd034",
"name": "AWS KMS Keystore Name",
"description": "AWS KMS keystore",
"groups":
"Production-UK",
"Production-DE"
],
"type": "aws_kms",
"created_at": "2022-03-09T10:59:44Z",
"updated_at": "2022-03-09T10:59:44Z",
"created_by": "IBMid-1308197YB4",
"updated_by": "IBMid-1308197YB4",
Why can't I view or list keys? 

When you try to list keys by using the Hyper Protect Crypto Services key management service API, you're unable to view any keys in a service instance that you have access to.

  What’s happening 

You call GET api/v2/keys to list the keys that are available in your service instance. The system returns a response similar to the following JSON object:

{
"metadata": {
"collectionType": "application/vnd.ibm.kms.key+json",
"collectionTotal": 0
}
}

  Why it’s happening 

You do not have the correct authorization to view the requested range of keys.

  How to fix it 

Contact an administrator to check your permissions. If the service instance contains keys that you're unable to view, verify that you're assigned the applicable [level of access to keys](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-grant-access-keys) in the service instance.
Viewing root key versions 

View the versions that are associated with a root key by using IBM Cloud® Hyper Protect Crypto Services.

When you rotate a root key, Hyper Protect Crypto Services creates a new version of the key. As a security admin, you can audit the rotation history of a root key by viewing the key version history.

Key versions are available only for root keys. To learn more about how key rotation works in Hyper Protect Crypto Services, check out [Comparing your key rotation options](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-root-key-rotation-introcompare-key-rotation-options).



 Viewing root key versions with the key management service API 

For a high-level view, you can list the versions that are associated with a root key by making a GET call to the following endpoint.

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



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 root key that you want to inspect.

The ID value is used to access detailed information about the key. You can find the ID for a key in your service instance by [retrieving a list of your keys](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-view-keys), or by accessing the IBM Cloud console.
3. Get a list of versions that are associated with the root key by running the following cURL command.
2. The new master key value is copied to the new master key registers of the crypto units that are assigned to the service instance and other recovery crypto units for the service instance. All the new master key registers now are in Full uncommitted state.
3. The new master key is committed, and all the new master key registers state are changed to Full committed.
4. Key storage is reencrypted. Encryption keys that are managed in the service instance are decrypted using the current master key in the current master key registers and reencrypted using the new master key in the new master key registers.
5. The new master key is loaded to the current master key registers of the operational and recovery crypto units for the service instance in Valid state, and the new master key registers are cleared and back to Empty state.



For detailed instructions on how to rotate master keys by using recovery crypto units, see [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 key part files 

Master keys that are created from key part files can be rotated by using TKE CLI plug-in. When master keys are rotated, master key parts are stored in files on the local workstation.

Similar to using the Management Utilities, you need to first create the 2 or 3 key parts that you are going to use. To be able to rotate the master key, the current master key registers must be in Valid state with the same verification pattern and the new master key registers must be Empty.

You can rotate the master key using TKE CLI plug-in regardless of whether your service instance has recovery crypto units assigned to it or not.

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



1. Load the new master key register by using the cryptounit-mk-load command. The state of the new master key register is changed from Empty to Full uncommitted.
2. Commit the new master key value by using the cryptounit-mk-commit command.
"last": {
"href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/managed_key/5295ad47-2ce9-43c3-b9e7-e5a9482c362b/associated_resources?limit=20&offset=0"
},
"previous": {
"href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/managed_keys?offset=80"
},
"next": {
"href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/managed_keys?offset=120"
},
"associated_resources": [
{
"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"
},
"managed_key": {
"id": "93777bca-baef-4070-b9b5-a2e6079df1b4",
"name": "My Managed Key",
"href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/managed_keys/5295ad47-2ce9-43c3-b9e7-e5a9482c362b"
},
"referenced_keystore": {
Encrypted Key
Ch7hcsT1EOfSdghjOHKAemBZuzDoqJoH ...<redacted>... F4p/mkGT/EQJS5o=

 capture the encrypted key material
$ ENCRYPTED_KEY=Ch7hcsT1EOfSdghjOHKAemBZuzDoqJoH ...<redacted>... F4p/mkGT/EQJS5o=

 encrypt the nonce
$ ibmcloud kp import-token nonce-encrypt -k $KEY_MATERIAL -n $NONCE

Encrypted Nonce IV
nrrCczvYXvc6T7J2G+EOLjHZO1cpPyu/nhsIlA== N6oLJnUqaKF3v5Sd

 capture the encrypted nonce and the initialization vector (IV)
$ ENCRYPTED_NONCE=nrrCczvYXvc6T7J2G+EOLjHZO1cpPyu/nhsIlA==
$ IV=N6oLJnUqaKF3v5Sd

 restore the deleted key
$ ibmcloud kp key restore $KEY_ID -k $ENCRYPTED_KEY -n $ENCRYPTED_NONCE -v $IV --output json

{
"id": "c42c6f2c-8b67-4016-b2c3-99fba9490f5d",
"name": "my-imported-root-key",
"type": "application/vnd.ibm.kms.key+json",
"extractable": false,
"state": 1,
Buckets created prior to February 26th, 2020 are not registered with the Key Protect 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 Key Protect, 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 Key Protect 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).
11-May 19:30:36 -0500 BKUP-I-04128 job completed at 11-May-2022 19:30:36 -0500
11-May 19:30:36 -0500 BKUP-I-04129 elapsed time 00:00:10 ...
Show more

You can use the following syntax to show only backup data size.

for i in $(ls -d /); do echo "backup history of $i"; find $i -name ".XLOG" ! -name "Agent" -print -exec /opt/BUAgent/xlogcat {} ; | grep -A 1 "deltized bytes processed"; done

backup history of AgtUpgd.backup/
backup history of Languages/
backup history of test/
13-May 19:30:31 -0500 BKUP-I-00013 deltized bytes processed: 0 (0 bytes)
13-May 19:30:31 -0500 BKUP-I-00014 compressed bytes processed: 0 (0 bytes)
11-May 19:30:36 -0500 BKUP-I-00013 deltized bytes processed: 0 (0 bytes)
11-May 19:30:36 -0500 BKUP-I-00014 compressed bytes processed: 0 (0 bytes)
10-May 19:30:15 -0500 BKUP-I-00013 deltized bytes processed: 0 (0 bytes)
10-May 19:30:15 -0500 BKUP-I-00014 compressed bytes processed: 0 (0 bytes)





 I'd like to free up space in my vault, how can I remove a specific safeset? 

Customers cannot delete the backup safesets. If you want to remove a specific safeset, create a [support case](https://cloud.ibm.com/unifiedsupport/supportcenter) so that the IBM Cloud Backup Admins can erase it on the backend.

When a Backup deletion request is submitted to the vaults, the data is automatically deleted from the associated vaults. Because backup deletion requests are submitted and processed by the vaults immediately, backup deletion requests cannot be canceled.
* UI
* API







 Viewing details about a root key or a standard key 

You can retrieve the general characteristics of a single encryption key by using IBM Cloud® Hyper Protect Crypto Services.

Retrieving a root key or a standard key requires a Writer or Manager access policy, but you might need a way to view only the details about a root key or a standard key, such as the transition history or configuration, without retrieving the key itself. If you have Reader access permissions, you can use the Hyper Protect Crypto Services key management API to retrieve only metadata about a root key or a standard key.



 Viewing key details with the IBM Cloud console 

You can view details about a specific key with the IBM Cloud console by completing the following steps:



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 Hyper Protect Crypto Services.
4. On the KMS keys page, use the Keys table to browse the keys in your service.
5. 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 a specific key.
6. From the options menu, click View key details to view the details of the key.







 Viewing key details with the key management service API 

To view detailed information about a specific root key or a standard 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>/metadata



1.
"updated_at": "2022-03-09T11:00:53Z",
"created_by": "IBMid-1308197YB4",
"updated_by": "IBMid-1308197YB4",
"keystores":
{
"group": "Production",
"type": "aws_kms"
}
],
"href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/templates/2014f3ba-87ea-4125-aa9f-95141ede04cf"
},
{
"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": "93777bca-baef-4070-b9b5-a2e6079df1b4",
"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-09T11:00:47Z",
You cannot use the CLI or web console to review actual key content after it is uploaded. However, you can use the [REST API](https://cloud.ibm.com/apidocs/key-protectretrieve-a-key-by-id) directly to review existing custom key content by issuing the following command:

curl -X GET "https://us-south.kms.cloud.ibm.com/api/v2/keys/<key id>" 
-H "accept: application/vnd.ibm.collection+json" 
-H "authorization: <Bearer token>" 
-H "bluemix-instance: <kp instance id>" 
| jq -r '.resources[].payload' | base64 --decode

Replace us-south in the REST API URL with the appropriate region. The <key id> is the one you obtained in step 7. The required <Bearer token> can be retrieved with ibmcloud iam oauth-tokens. For more information, see to the [Key Protect CLI documentation](https://cloud.ibm.com/docs/key-protect?topic=key-protect-set-up-cli).



 Managing access to custom secrets 

Use IAM access policies to manage access to your keys. You can do so for an entire service instance or for an individual key. Refer to the [documentation](https://cloud.ibm.com/docs/services/key-protect?topic=key-protect-grant-access-keys) for further details.
--uko-vault=eb66ebbd-7230-4cde-89bf-17282cda5faa 
--id=f779c44d-b90e-4917-b8b0-28d4591fefda 
--output json
* Output

The command returns the output similar to the following example:

{
"total_count": 3,
"limit": 20,
"offset": 0,
"first": {
"href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/managed_keys?vault.id=5295ad47-2ce9-43c3-b9e7-e5a9482c362b&limit=20&offset=0"
},
"last": {
"href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/managed_keys?vault.id=5295ad47-2ce9-43c3-b9e7-e5a9482c362b&limit=20&offset=0"
},
"managed_keys": [
{
"id": "8cacc6c9-a4ac-43b7-88c0-cf94765f4bf9",
"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"
},
"template": {
Recovery crypto units can also be used as backup crypto units that save a copy of the master key value used by the operational crypto units. If the master key is lost or destroyed, you can [recover the master key from a recovery crypto unit](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-recover-master-key-recovery-crypto-unit) by using signed TKE administrative commands.

If smart cards are used to load the master key, the recovery crypto units are not applicable and can be ignored. The backup of the master key relies on the backup of the smart cards in that case.
* Failover crypto unit

Failover crypto units back up the operational crypto units and keystores in another region, and are initialized to provide quick failover in case of disaster. Failover crypto units [charge extra fees](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-faq-pricing) and this option is now available only in regions of us-south and us-east, which means if you create your instance in either of the two regions, the failover crypto units are located in the other region. For more information about using failover crypto units in a regional disaster, 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).







 Administrators 

Administrators can be added to the target crypto units for issuing commands to the crypto units. You can add up to eight administrators to one crypto unit to increase security. Each administrator owns one private [signature key](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-understand-conceptssignature-key-concept) for identity authentication.





 Signature keys 

An administrator must sign any commands that are issued to the crypto unit with a signature key. The signature keys that are created in Hyper Protect Crypto Services are P521 Elliptic Curve (EC) keys.
* 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. For example, if the value is "6144", and there are three database members, then the deployment gets 6 GB of RAM total, giving 2 GB of RAM per member. If omitted, the default value is used for the database type is used.
* members_disk_allocation_mb - Total amount of disk to be shared between the database members within the database. For example, if the value is "30720", and there are three members, then the deployment gets 30 GB of disk total, giving 10 GB of disk per member. If omitted, the default value for the database type is used.
* members_cpu_allocation_count - Enables and allocates the number of specified dedicated cores to your deployment. For example, to use two dedicated cores per member, use "members_cpu_allocation_count":"2". If omitted, the default value "Shared CPU" uses compute resources on shared hosts.
* service-endpoints - The [Service Endpoints](https://cloud.ibm.com/docs/cloud-databases?topic=cloud-databases-service-endpoints) supported on your deployment, public or private. A MongoDB deployment cannot have both public and private endpoints simultaneously. This parameter cannot be changed after provisioning.
"type": "application/vnd.ibm.kms.key+json",
"aliases":
"alias-1",
"alias-2"
],
"name": "test-root-key",
"description": "...",
"state": 5,
"expirationDate": "2020-03-15T20:41:27Z",
"crn": "crn:v1:bluemix:public:hs-crypto:us-south:a/f047b55a3362ac06afad8a3f2f5586ea:30372f20-d9f1-40b3-b486-a709e1932c9c:key:2291e4ae-a14c-4af9-88f0-27c0cb2739e2",
"deleted": true,
"algorithmType": "AES",
"createdBy": "...",
"deletedBy": "...",
"creationDate": "2020-03-10T20:41:27Z",
"deletionDate": "2020-03-16T21:46:53Z",
"lastUpdateDate": "2020-03-16T20:41:27Z",
"extractable": false
}
]
}

For a detailed description of the available parameters, see the Hyper Protect Crypto Services [key management service API reference doc](https://cloud.ibm.com/apidocs/hs-crypto).









 What's next 



* To restore a previously deleted key, check out [Restoring keys](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-restore-keys).
* To create another root key, check out [Creating root keys](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-create-root-keys).
When you create volume, snapshot, file share, or custom image with customer-managed encryption, your root key is automatically registered in the KMS instance. You can view the registration to verify whether the key was rotated. The following procedure shows how to verify key rotation for a Block Storage for VPC volume, but steps are similar for other resources.



1. From the [IBM Cloud console)](https://cloud.ibm.com/login), go to menu icon ![menu icon](https://cloud.ibm.com/docs-content/v1/content/icons/icon_hamburger.svg) > VPC Infrastructure > Storage > Block storage volumes. The list shows all volumes and the Encryption column displays either "Provider Managed" or the name of the KMS that is used for custoner-managed encryption.
2. Click the name of a volume to see its details.
3. In the Encryption Instance field, click the link of the KMS instance. The KMS instance overview page is displayed.

If you created your KMS instance by using a private endpoint, these instances and associated root keys do not appear in the UI. Use the Key Protect or Hyper Protect Crypto Services CLI or API to verify key rotation instead.
4. Click KMS Keys (Hyper Protect Crypto Services) or Key (Key Protect). The list of all keys in the instance is displayed. The Last updated column shows the date when the key was created or rotated.
5. Click the Actions menu in the row of the key that you want to know more about. Select View key details. A side panel opens and information about the key is displayed. 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