vania-janet/multiturn-rag-retrieval-data huggingface dataset:
After you set a rotation policy for a root key, the clock starts immediately based on the initial creation date for the key. If you choose at any time to manually rotate this key, the rotation period resets based on that rotation. 
 [Manual key rotation](https://cloud.ibm.com/docs/key-protect?topic=key-protect-rotate-keys) Up to one rotation per hour Key Protect allows no more than one rotation per hour for each key. 



It is possible to learn the last date a key was rotated by using the lastRotateDate field available in APIs such as [getkey](https://cloud.ibm.com/apidocs/key-protectgetkey), [getkeymetadata](https://cloud.ibm.com/apidocs/key-protectgetkeymetadata), and [getkeys](https://cloud.ibm.com/apidocs/key-protectgetkeys).







 How key rotation works 

During a root key rotation, the key remains in an active state. However, older versions are deactivated and can be considered "retired". This latest version of the root key will then be used for all future actions. While unwraps can still be done with WDEKs which were generated with an older version of the root key, wraps and re-wraps use the latest version of the root key. Note that a previous key version can only be used to unwrap and access data encrypted using that particular key version or lower. An old version of a root key cannot be used to create a new DEK or to wrap the DEK and create a WDEK. For more information, check out [Managing retired key versions](https://cloud.ibm.com/docs/key-protect?topic=key-protect-key-rotationkey-rotation-managing).

For more information about how key rotation works, check out [Understanding the key rotation process](https://cloud.ibm.com/docs/key-protect?topic=key-protect-key-rotationunderstand-key-rotation-process).

To enable key rotation options for your IBM Cloud data service, the data service must be integrated with Key Protect.
create a root key using an import token, provide an encrypted key, nonce, and initialization vector (IV)
$ KEY_ID=$(ibmcloud kp key create my-imported-root-key -k $ENCRYPTED_KEY -n $ENCRYPTED_NONCE -v $IV --output json | jq -r '.["id"]')

$ echo $KEY_ID

fa0a7d81-a947-4bac-883d-952f6288f0a9

 delete the root key
$ ibmcloud kp key delete $KEY_ID

Deleting key: 'fa0a7d81-a947-4bac-883d-952f6288f0a9', from instance: 'a192d603-0b8d-452f-aac3-f9e1f95e7411'...
OK
Deleted Key
fa0a7d81-a947-4bac-883d-952f6288f0a9
Show more

Step 2 - trigger the error by creating an import token, which is required to restore the key, and restore the key, then restore the key

 NOTE: the "kp key restore" requires an import token to complete the process,
 if you follow this example, the import token created above may still exist and
 the example works; otherwise, if the import token has expired then you need to
 create a new import token prior to restoring the key

 create an import token that expires in 15 minutes (900 seconds) and allows 10 retrievals
$ ibmcloud kp import-token create -e 900 -m 10

Created Expires Max Retrievals Remaining Retrievals
2020-08-18 19:12:35 +0000 UTC 2020-08-18 19:27:35 +0000 UTC 10 10

 extract the nonce that was created by the "kp import-token create" command
$ NONCE=$(ibmcloud kp import-token show | jq -r '.
"id": "264fadc3-7667-4b25-916e-5825fe70de0b",
"name": "my-root-key",
"type": "application/vnd.ibm.kms.key+json",
"algorithmType": "AES",
"createdBy": "user id ...<redacted>...",
"creationDate": "2020-06-09T21:21:55Z",
"lastUpdateDate": "2020-06-09T21:21:55Z",
"keyVersion": {
"id": "264fadc3-7667-4b25-916e-5825fe70de0b",
"creationDate": "2020-06-09T21:21:55Z"
},
"extractable": false,
"state": 1,
"crn": "crn:v1:bluemix:public:kms:us-south:a/ea998d3389c3473aa0987652b46fb146:390086ac-76fa-4094-8cf3-c0829bd69526:key:264fadc3-7667-4b25-916e-5825fe70de0b"
}

 disable the root key
$ ibmcloud kp key disable 264fadc3-7667-4b25-916e-5825fe70de0b

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

 show key details - a state of "2" is "suspended"
"creationDate": "2020-06-09T21:21:55Z",
"lastUpdateDate": "2020-06-09T21:31:44Z",
"keyVersion": {
"id": "264fadc3-7667-4b25-916e-5825fe70de0b",
"creationDate": "2020-06-09T21:21:55Z"
},
"extractable": false,
"state": 1,
"crn": "crn:v1:bluemix:public:kms:us-south:a/ea998d3389c3473aa0987652b46fb146:390086ac-76fa-4094-8cf3-c0829bd69526:key:264fadc3-7667-4b25-916e-5825fe70de0b"
}





 Required parameters 

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







 kp key policies 

Retrieve details about a key policy, such as the key's automatic rotation interval.

ibmcloud kp key policies KEY_ID
-i, --instance-id INSTANCE_ID
[-d, --dual-auth]
[-o, --output OUTPUT]
[-r, --rotation]



 Example 

This example lists the policies for a root key.

Key policies are [dual authorization delete](https://cloud.ibm.com/docs/key-protect?topic=key-protect-cli-reference-five-twokp-key-policy-update-dual) and [rotation](https://cloud.ibm.com/docs/key-protect?topic=key-protect-cli-reference-five-twokp-key-policy-update-rotation).

 create a root key
This means that if service in us-south, jp-tok, or eu-de is disrupted, requests to Key Protect in those regions are routed to the region where the data has already been replicated. Note that the standby infrastructure in the region with failover support is completely separate from the Key Protect service available in that region, and that failover only goes in one direction. Your data in us-east, for example, is not currently replicated to us-south.

Because your requests are routed automatically, you can continue to call your original endpoint. Initially, read-only operations are all that will be available. However, if there is reason to believe the disruption will last for an extended period, write operations will be enabled as soon as possible. Otherwise, read-only operations are all that will be available for up to six hours before write operations will be enabled.

Key Protect will be adding cross-regional high availability to selected regions in different geographical locations.

As you plan your encryption strategy with IBM Cloud, remember that provisioning Key Protect in a region that is nearest to you is more likely to result in faster, more reliable connections when you interact with the Key Protect APIs. Furthermore, regulatory requirements might influence which region or regions to use. Note that Key Protect does not restrict using keys across regions and geographical locations. For example, a user might use keys from us-south to encrypt storage in Frankfurt. Choose the region that is best for your use case overall.





 Application-level high availability 

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.
Expiration date (Optional) Set the date and time when the key gets expired. After the expiration date, the key moves into the Deactivated state. For more information about key state, see [Monitoring the lifecycle of encryption keys](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-key-states). 
 Description (Optional) Add an extended description for your key. It can be two to 240 characters in length. 



6. When you finish filling out the key's details, click Create key to confirm.



Keys that are created in the service are symmetric 256-bit keys, supported by the AES-CBC algorithm. For added security, keys are generated by FIPS 140-2 Level 4 certified

hardware security modules (HSMs)that are located in secure IBM Cloud data centers.





 Creating root keys with the API 

Create a root key by making a POST 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. Call the [Hyper Protect Crypto Services key management service API](https://cloud.ibm.com/apidocs/hs-crypto) with the following curl command.

curl -X POST "https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys" -H "authorization: Bearer <IAM_token>" -H "bluemix-instance: <instance_ID>" -H "content-type: application/vnd.ibm.kms.key+json" -H "x-kms-key-ring: <key_ring_ID>" -H "correlation-id: <correlation_ID>" -d '{
"metadata": {
5f2cc155-fe16-492c-845c-4d1f0688c7ba my-root-key 2020-05-10 18:04:01 +0000 UTC Key does not expire

Grabbing info for key id: c36e9f3a-feaf-4033-8603-687784dc7e51...
OK
Key ID Key Name Description Creation Date Expiration Date
c36e9f3a-feaf-4033-8603-687784dc7e51 my-root-key 2020-05-10 17:56:37 +0000 UTC Key does not expire





 Example 5 

Create 20 keys and show them in groups of 5 using the kp keys -n -s options.

 create 20 test keys
$ for I in {1..20}; do
KEY_ID=$(ibmcloud kp key create my-test-key-$I --output json | jq -r '.["id"]')
KEY_NAME=$(ibmcloud kp key show $KEY_ID --output json | jq -r '.["name"]')
echo $KEY_ID $KEY_NAME
done

b70f62a1-4d52-4526-91a9-ce47bf14c2a5 my-test-key-1
215f592c-3e42-47b6-867c-3cc1cce8a8fd my-test-key-2
df530c55-39c0-44e8-b7db-397593f70d90 my-test-key-3
768c9ceb-368b-46f7-9b1d-be211e036fe1 my-test-key-4
f141be88-5a34-4290-8513-4f01d934e75a my-test-key-5
<br> <br>When you set the return_preference variable to return=minimal, the service returns only the key metadata, such as the key name and ID value, in the response entity-body. When you set the variable to return=representation, the service returns both the key material and the key metadata. 
 key_name Required. A unique, human-readable name for easy identification of your key. To protect your privacy, do not store your personal data as metadata for your key. 
 alias_list Optional. One or more unique, human-readable aliases assigned to your key. <br> <br>Important: To protect your privacy, do not store your personal data as metadata for your key. <br> <br>Each alias must be alphanumeric, case sensitive, and cannot contain spaces or special characters other than - or _. The alias cannot be a UUID and must not be a Key Protect reserved name: allowed_ip, key, keys, metadata, policy, policies. registration, registrations, ring, rings, rotate, wrap, unwrap, rewrap, version, versions. 
 key_description Optional. An extended description of your key. To protect your privacy, do not store your personal data as metadata for your key. 
 expiration_date Optional. The date and time that the key expires in the system, in RFC 3339 format (YYYY-MM-DD HH:MM:SS.SS, for example 2019-10-12T07:20:50.52Z). The key will transition to the deactivated state within one hour past the key's expiration date. If the expirationDate attribute is omitted, the key does not expire. 
 key_material Required. The base64-encoded key material, an existing key-wrapping key, that you want to store and manage in the service. For more information, check out [Base64 encoding your key material](https://cloud.ibm.com/docs/key-protect?topic=key-protect-import-root-keyshow-to-encode-root-key-material).
This example is based on the restore key command and it uses the [CLI](https://cloud.ibm.com/docs/key-protect?topic=key-protect-key-protect-cli-reference) because the output is easier to follow than the [API](https://cloud.ibm.com/apidocs/key-protect).

Step 1 - setup the problem by creating a root key using an import token and then delete the key

 create an import token that expires in 15 minutes (900 seconds) and allows 10 retrievals
$ ibmcloud kp import-token create -e 900 -m 10

Created Expires Max Retrievals Remaining Retrievals
2020-08-18 19:05:51 +0000 UTC 2020-08-18 19:20:51 +0000 UTC 10 10

 create a random, base64-encoded, 32-byte key material
$ KEY_MATERIAL=$(openssl rand -base64 32)

$ echo $KEY_MATERIAL

DL4Avc1yL7DhclfV9Uksvzy8VkYIKWZA9InYQv/iiro=

 extract the nonce that was created by the "kp import-token create" command
$ NONCE=$(ibmcloud kp import-token show | jq -r '.["nonce"]')

$ echo $NONCE

6SB0nQ8ROUCPUiyF

 extract the public key that was created by the "kp import-token create" command
$ PUBLIC_KEY=$(ibmcloud kp import-token show | jq -r '.["payload"]')

$ echo $PUBLIC_KEY

LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0t ...<redacted>... QyBLRVktLS0tLQo=

 encrypt the key material using the public key
$ ibmcloud kp import-token key-encrypt -k $KEY_MATERIAL -p $PUBLIC_KEY

Encrypted Key
* The responseData.keyState field includes the integer that correlates to the state of the key.







 Expire Key 

The following field includes extra information:



* The requestData.keyType field includes the type of key that was created.
* The responseData.keyId field includes the unique identifier associated with the key.
* The requestData.expirationDate field includes the date that the key expired on.
* The responseData.initialValue.keyState field includes the integer that correlates to the previous state of the key.
* The responseData.newValue.keyState field includes the integer that correlates to the current state of the key.







 Wrap or unwrap key 

The following field includes extra information:



* The responseData.keyVersionId field includes the unique identifier of the current key version used to wrap input ciphertext on wrap requests.
* The responseData.expirationDate includes the date that the key will expire on.







 Rewrap key 

The following field includes extra information:



* The responseData.keyVersionId field includes the unique identifier of the current key version used to wrap input ciphertext on wrap requests.
* The responseData.rewrappedKeyVersionId field includes the unique identifier of the new key version used to wrap input ciphertext on wrap requests.







 Restore key 

The following field includes extra information:



* The responseData.keyVersionId field includes the unique identifier of the current key version used to wrap input ciphertext on wrap requests.







 Rotate key 

Rotate key doesn't have any additional fields outside of those from the [Common Fields](https://cloud.ibm.com/docs/key-protect?topic=key-protect-at-eventsat-events-common-fields) section





 Patch key 

The following fields include extra information:



* The requestData.initialValue.keyRingId field includes the ID of the key ring that the key previously was a part of.
* The requestData.newValue.keyRingId field includes the ID of the key ring that the key is currently a part of.







 Purge key
(https://cloud.ibm.com/docs-content/v1/content/0bc8db34a3d90b2a5103c9c71b08a96de9525bbc/key-protect/images/key-rotation.svg)

Figure 1. Contextual view of key rotation.

With each rotation request, Key Protect creates a new root key version by associating new key material with your key.

Zoom

![The diagram shows a micro view the key stack.](https://cloud.ibm.com/docs-content/v1/content/0bc8db34a3d90b2a5103c9c71b08a96de9525bbc/key-protect/images/root-key-stack.svg)

Figure 2. Micro view of a key stack.

Keys do not rotate at precisely the same time of the day the key was created. That is, if a key was originally created at 8 a.m., it will not necessarily be rotated at 8 a.m. on the day the rotation is scheduled. Instead, the rotation can happen at any point during a 24-hour window.







 What's next 



* For more information about how to use Key Protect to set an automatic rotation policy for an individual root key, see [Setting a rotation policy](https://cloud.ibm.com/docs/key-protect?topic=key-protect-set-rotation-policy).
* For more information about manually rotating root keys, check out [Manually rotating keys](https://cloud.ibm.com/docs/key-protect?topic=key-protect-rotate-keys).
* For more information about viewing the key versions that are available for a root key, check out [Viewing key versions](https://cloud.ibm.com/docs/key-protect?topic=key-protect-view-key-versions).
$ IV=7BiIpcbGxXBzuXZP

 create a root key using an import token, provide an encrypted key, nonce, and initialization vector (IV)
$ KEY_ID=$(ibmcloud kp key create my-imported-root-key -k $ENCRYPTED_KEY -n $ENCRYPTED_NONCE -v $IV --output json | jq -r '.["id"]')

$ echo $KEY_ID

c42c6f2c-8b67-4016-b2c3-99fba9490f5d

 list keys - verify the key was created
$ ibmcloud kp keys

Retrieving keys...
OK
Key ID Key Name
c42c6f2c-8b67-4016-b2c3-99fba9490f5d my-imported-root-key

 delete the root key
$ ibmcloud kp key delete $KEY_ID

Deleting key: c42c6f2c-8b67-4016-b2c3-99fba9490f5d, from instance: a192d603-0b8d-452f-aac3-f9e1f95e7411...
OK
Deleted Key
c42c6f2c-8b67-4016-b2c3-99fba9490f5d

 list keys - verify the key was deleted
$ ibmcloud kp keys

Retrieving keys...
OK
Key ID Key Name

Step 2 - create an import token, which is required to restore the key, and restore the key

 NOTE: "kp key restore" requires an import token to complete the process,
 if you follow this example, the previously created import token may still
 exist and the example works; otherwise, if the import token has expired then
 you need to create a new import token prior to restoring the key

 create an import token that expires in 5 minutes and allows 10 retrievals
Note that the metadata for imported keys, such as the key ID, do not change when the key is rotated, just as with a key generated with Key Protect.
* Rotating keys manually
As a security admin, you might want to have more control over the frequency of rotation for your root keys. If you don't want to set an automatic rotation policy for a key, you can manually create a new key to replace an existing key, and then update your applications so that they reference the new key.

To simplify this process, you can use Key Protect to rotate the root key at any time. In this scenario, Key Protect creates and replaces the key on your behalf with each rotation request. The metadata and key ID of the key will not change. For more information about to manually rotate a key, check out [Manually rotating keys](https://cloud.ibm.com/docs/key-protect?topic=key-protect-rotate-keys).



Manually rotating a root key does not disturb any rotation policy that might currently exist for the key. As a result, a good option is to set a regular rotation policy and then manually update keys more often as needed.



 How often should keys be rotated? 

After you generate a root key in Key Protect, you decide how often it is rotated. The best practice is to rotate your keys regularly.



Table 2. Rotation frequency options for rotating keys in Key Protect

 Rotation type Frequency Description 

 [Policy-based key rotation](https://cloud.ibm.com/docs/key-protect?topic=key-protect-set-rotation-policy) Intervals of 30 days (in other words, every 30 days, or 60 days, or 90 days, etc) Choose a rotation interval between one and 12 months for your root key based on your security needs. After you set a rotation policy for a root key, the clock starts immediately based on the initial creation date for the key. If you choose at any time to manually rotate this key, the rotation period resets based on that rotation. 
 [Manual key rotation](https://cloud.ibm.com/docs/key-protect?topic=key-protect-rotate-keys) Up to one rotation per hour Key Protect allows no more than one rotation per hour for each key.
c42c6f2c-8b67-4016-b2c3-99fba9490f5d

 list keys - verify the key was created
$ ibmcloud kp keys

Retrieving keys...
OK
Key ID Key Name
c42c6f2c-8b67-4016-b2c3-99fba9490f5d my-imported-root-key

 delete the root key
$ ibmcloud kp key delete $KEY_ID

Deleting key: c42c6f2c-8b67-4016-b2c3-99fba9490f5d, from instance: a192d603-0b8d-452f-aac3-f9e1f95e7411...
OK
Deleted Key
c42c6f2c-8b67-4016-b2c3-99fba9490f5d

 list keys - verify the key was deleted
$ ibmcloud kp keys

Retrieving keys...
OK
Key ID Key Name

Step 2 - create an import token, which is required to restore the key, and restore the key

 NOTE: "kp key restore" requires an import token to complete the process,
 if you follow this example, the previously created import token may still
 exist and the example works; otherwise, if the import token has expired then
 you need to create a new import token prior to restoring the key

 create an import token that expires in 5 minutes and allows 10 retrievals
$ ibmcloud kp import-token create -e 300 -m 10

Created Expires Max Retrievals Remaining Retrievals
2020-06-18 12:30:54 +0000 UTC 2020-06-18 12:35:54 +0000 UTC 10 10

 extract the nonce that was created by the "kp import-token create" command
$ NONCE=$(ibmcloud kp import-token show | jq -r '.["nonce"]')

$ echo $NONCE
If the expirationDate attribute is omitted, the key does not expire. 
 key_material Required. The base64-encoded key material, an existing key-wrapping key, that you want to store and manage in the service. For more information, check out [Base64 encoding your key material](https://cloud.ibm.com/docs/key-protect?topic=key-protect-import-root-keyshow-to-encode-root-key-material). <br> <br>Ensure that the key material meets the following requirements: <br>A standard key can be up to 7,500 bytes in size. The key must be base64-encoded. 
 key_type A boolean value that determines whether the key material can leave the service. <br> <br>When you set the extractable attribute to false, the service designates the key as a root key that you can use for wrap or unwrap operations. 



To protect the confidentiality of your personal data, avoid entering personally identifiable information (PII), such as your name or location, when you add keys to the service.

A successful POST api/v2/keys response returns the ID value for your key, along with other metadata. The ID is a unique identifier that is assigned to your key and is used for subsequent calls to the Key Protect API.

Optional: Verify that the key was added by running the following call to browse the keys in your Key Protect instance.

$ curl -X GET "https://<region>.kms.cloud.ibm.com/api/v2/keys" -H "accept: application/vnd.ibm.collection+json" -H "authorization: Bearer <IAM_token>" -H "bluemix-instance: <instance_ID>"





 Base64-encoding your key material 

When importing an existing root key, it is required to include the encrypted key material that you want to store and manage in the service.



 Using OpenSSL to encrypt existing key material 

Use this process to encrypt the contents of a key material in a file.



1.
"lastUpdateDate": "2020-06-19T16:07:50Z",
"keyVersion": {
"id": "d887bfe8-5166-4dad-af32-7e3055ca1873",
"creationDate": "2020-06-19T16:07:50Z"
},
"extractable": false,
"state": 1,
"crn": "crn:v1:bluemix:public:kms:us-south:a/ea998d3389c3473aa0987652b46fb146:a192d603-0b8d-452f-aac3-f9e1f95e7411:key:d887bfe8-5166-4dad-af32-7e3055ca1873"
}

 enable the dual authorization policy
$ ibmcloud kp key policy-update dual-auth-delete $KEY_ID --enable --output json

{
"createdBy": "user id ...<redacted>...",
"creationDate": "2020-06-19T16:08:59Z",
"crn": "crn:v1:bluemix:public:kms:us-south:a/ea998d3389c3473aa0987652b46fb146:a192d603-0b8d-452f-aac3-f9e1f95e7411:policy:0aab763d-b650-43a2-86ad-bdfe2c35c94c",
"lastUpdateDate": "2020-06-19T16:08:59Z",
"updatedBy": "user id ...<redacted>...",
"dualAuthDelete": {
"enabled": true
}
}

 list the policies