vania-janet/multiturn-rag-retrieval-data huggingface dataset:
When you rotate a root key, the registered key is used to re-encrypted Schematics resources with a new key version. You can access the Schematics resources metadata such as details until the rotation completes.



 Key deletion or disable 

Key Deletion is a destructive action. When you disable or delete a root key that is used to encrypt your Schematics resources, you cannot access transactional data such as activity or job logs, resource list, variable store. However, you can access the metadata details. Furthermore any subsequent deployment or configuration operation through Schematics result in failure. Key deletion or disable events are sent to the IBM Log Analysis Activity Tracker.





 Key enable or restore 

When you can [enable or restore a root key](https://cloud.ibm.com/docs/schematics?topic=schematics-kms-integrationkey-mgt-ui), the Schematics resources transactional data that is inaccessible due to disabled or deleted root key is now accessible. You can also use Schematics resources for deployment or configuration operations. Key enable or restore events are sent to the IBM Log Analysis Activity Tracker.







 What technical information is stored in Schematics? 

The following technical data is encrypted and stored when you create and use a Schematics Workspace:



* Workspace details
* Workspace variables
* Terraform configuration files that your workspace points to
* Terraform state files
* Terraform log files
* User activity logs







 Where is my information stored? 

By default, all information that is stored in Schematics is encrypted in transit and at rest. To ensure resiliency and high availability, all data stored in the US and EU geographies is replicated across multiple locations in the same geography. When choosing a Schematics location to work with, verify that your data can be stored in these geographic locations.



Location information

 Geography/ location API endpoint Data stored Data replicated
$ curl -X POST "https://us-south.kms.cloud.ibm.com/api/v2/keys/$KEY_ID/actions/unsetKeyForDeletion" -H "authorization: Bearer $ACCESS_TOKEN" -H "bluemix-instance: $KP_INSTANCE_ID" -H "content-type: application/vnd.ibm.kms.key_action+json"





 JSON response 

{
"metadata": {
"collectionType": "application/vnd.ibm.kms.error+json",
"collectionTotal": 1
},
"resources": [
{
"errorMsg": "Conflict: Action could not be performed on key. Please see reasons for more details.",
"reasons":
{
"code": "NOT_DUAL_AUTH_ERR",
"message": "The key is not dual auth enabled and cannot be set for deletion",
"status": 409,
"moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
}
]
}
]
}







 Example 2 

This example attempts to authorize a deletion and remove an authorization using the CLI.

Note: the $KEY_ID was set in the previous example.

 this request fails because the key DOES NOT have a dual authorization policy
$ ibmcloud kp key schedule-delete $KEY_ID

Scheduling key for deletion...
FAILED
kp.Error:
correlation_id='3d941968-c599-43b3-b681-306422079412',
msg='Conflict:
Action could not be performed on key.
Please see reasons for more details.',
reasons='[NOT_DUAL_AUTH_ERR:
The key is not dual auth enabled and cannot be set for deletion -
The region abbreviation, such as us-south or eu-gb, that represents the geographic area where your Key Protect instance resides. <br> <br>For more information, see [Regional service endpoints](https://cloud.ibm.com/docs/key-protect?topic=key-protect-regionsservice-endpoints). 
 key_ring_id Required. The unique identifier for the key ring that you would like to delete. 
 IAM_token Required. Your IBM Cloud access token. Include the full contents of the IAM token, including the Bearer value, in the curl request. <br> <br>For more information, see [Retrieving an access token](https://cloud.ibm.com/docs/key-protect?topic=key-protect-retrieve-access-token). 
 instance_ID Required. The unique identifier that is assigned to your Key Protect service instance. <br> <br>For more information, see [Retrieving an instance ID](https://cloud.ibm.com/docs/key-protect?topic=key-protect-retrieve-instance-ID). 



A successful request returns an HTTP 204 No Content response, which indicates that the key ring was successfully deleted.
If you are required to retain any data related to a purged key (key metadata, registrations, policies, etc) for an extended period of time, it is recommended to perform the necessary API or CLI calls to retrieve and store that data in your own storage device.







 05 February 2021 

Key Protect supports new UI actions
: If you have Manager access permissions, you can filter for keys in the Destroyed state and restore an imported root key via the ⋯ icon on the Keys table. You can use the restore key side panel to complete the process for restoring the key. For more information, see [Restoring a deleted key with the console](https://cloud.ibm.com/docs/key-protect?topic=key-protect-restore-keysrestore-ui).





 05 February 2021 

Key Protect supports private networks
: You can now connect to Key Protect from your virtual private cloud (VPC) via a virtual private endpoint (VPE). VPEs are bound to a [VPE gateway](https://cloud.ibm.com/docs/vpc?topic=vpc-about-vpe) and serve as an intermediary that enables your workload to interact with Key Protect.



* To get started, [provision a Virtual Private Cloud](https://cloud.ibm.com/docs/vpc?topic=vpc-getting-started) and create a [VPE gateway](https://cloud.ibm.com/docs/vpc?topic=vpc-ordering-endpoint-gateway). For more information, see [Using private endpoints](https://cloud.ibm.com/docs/key-protect?topic=key-protect-private-endpoints).









 January 2021 



 27 January 2021 

Key Protect supports key rings
: You can now use the Key Protect REST API to manage access to a specific set of keys that are bundle a collection called a key ring. You can manage and restrict access to key rings to via IAM policies. To find out more, see [Grouping keys](https://cloud.ibm.com/docs/key-protect?topic=key-protect-grouping-keys).





 06 January 2021
To learn how IAM roles map to Hyper Protect Crypto Services actions, check out [Service access roles](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-manage-accessservice-access-roles).
2. Copy the ID of the key that you want to set or authorize for deletion.
3. Provide the first authorization to delete the key.

curl -X POST 
'https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>/actions/setKeyForDeletion' 
-H 'accept: application/vnd.ibm.kms.key_action+json' 
-H 'authorization: Bearer <IAM_token>' 
-H 'bluemix-instance: <instance_ID>' 
-H 'content-type: application/vnd.ibm.kms.key_action+json'

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



Table 1. Describes the variables needed to set a key for deletion

 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 instance resides. For more information, see [Regional service endpoints](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-regionsservice-endpoints). 
 key_ID Required. The unique identifier for the root key that you want to delete. 
 IAM_token Required. Your IBM Cloud access token. Include the full contents of the IAM token, including the Bearer value, in the cURL request. For more information, see [Retrieving an access token](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-retrieve-access-token). 
 instance_ID Required. The unique identifier that is assigned to your Hyper Protect Crypto Services instance.
Monitoring the lifecycle of encryption keys in Unified Key Orchestrator 

IBM Cloud® Hyper Protect Crypto Services follows the security guidelines by [NIST SP 800-57 for key states](https://www.nist.gov/publications/recommendation-key-management-part-1-general-0).



 Key states and transitions 

Managed keys in Unified Key Orchestrator transition through several states that indicate how long the keys are in existence and whether data is protected.

The following diagram shows how a managed key passes through states between the generation and the destruction.

Zoom

![Key states and transitions](https://cloud.ibm.com/docs-content/v1/content/217f108cc44e2ce15fb692d4b57b4c628464e908/hs-crypto//images/uko-key-states.svg)

Figure 1. Key states and transitions

The following table shows the details of each key state.



Table 1. Key states and transitions

 State Integer mapping Description 

 Pre-active 0 A Pre-active key is not yet activated in target keystores and is therefore not available for use by applications. New keys are initially created in the Pre-active state. 
 Active 1 An Active key is activated in target keystores and is available for use by applications. If the key is used to protect associated resources, the key will be accessible to its associated resources and can be used for data protection. You can set a key to the Active state when you create the key, or manually activate a Pre-active key later. 
 Deactivated 3 A Deactivated key is no longer allowed for operations that generate new cryptographic data, such as encryption or signing, but can still be used for operations on existing data to do decryption or signature verification. When you deactivate a key, the key is detached from all the target keystores, and not accessible to all associated resources and their data. However, you can still reactivate the key so that it is accessible to the resources again. 
 Destroyed 5 A Destroyed key is a key record for which the actual key material has been permanently erased.
* As a Writer, you can create, modify, rotate, and use keys. Writers cannot delete or disable keys.
* As a Manager, you can perform all actions that a Reader, ReaderPlus and Writer can perform, including the ability to delete keys and set policies for keys. Managers cannot purge keys.
* As a VMware KMIP Manager, you can configure KMIP for VMware with Hyper Protect Crypto Services to enable encryption with your own root keys.
* As a KMS Key Purge role, you can purge a deleted key to permanently remove a key from your instance.
* As a Certificate Manager role, you can manage administrator signature keys and client certificates for the second layer of authentication in GREP11 or PKCS #11 API connections.



The following table shows how service access roles map to Hyper Protect Crypto Services permissions. IAM roles are the default roles provided. Custom roles can be defined by the user.



* Trusted Key Entry (TKE) uses either smart cards or software CLI plug-in with IAM authentication. Commands that deals with managing keys locally on the smart card or CLI are not included. Those commands do not interact with the HSM domain.
* The key management service API is used for envelope encryption and deals with root keys that are used by IBM Cloud services for encrypting data-at-rest.
* HSM APIs (the PKCS #11 API and the GREP11 API) are used for application-level encryption.
* Key Management Interoperability Protocol (KMIP) adapter is used to configure the KMIP for VMware service with Hyper Protect Crypto Services to enable vSphere encryption or vSAN encryption by using your own root keys.
* Certificate Manager Server receives and processes requests for setting up certificate administrator signature keys and client certificates to enable the second layer of authentication in GREP11 or PKCS #11 API connections.



Trusted Key Entry commands

Key management

HSM APIs



Table 3. Lists service access roles as they apply to Hyper Protect Crypto Services TKE commands

 Action Reader ReaderPlus Writer Manager Crypto unit administrator
Authorization to the Configuration API is enforced by using a service key.

A service key is a unique code that is passed in an API request to identify the calling application or user. The service key is specific to an auditing instance. For more information on how to generate a service key, see [Managing service keys](https://cloud.ibm.com/docs/activity-tracker?topic=activity-tracker-service_keys).

Use of the Configuration REST API is done by adding a valid service key to the HTTP Authorization request header. You must pass the service key as a header parameter (-H) of your requests.

For example, in a cURL request, you must set the content-type header as follows:

-H 'servicekey: <SERVICE_KEY>'





 Body parameters 

The following fields are body parameters that you can set in API request:



 name (string) 

Specifies the name of the view.

The following table indicates when the name parameter is required:



Table 2. Required status per method

 Action Request Field required 

 Create a view and attach an alert to a view. POST ![Check mark icon](https://cloud.ibm.com/docs-content/v1/content/6f3c07c34058f637b1c86044ca4f9b24214330a7/activity-tracker/images/checkmark-icon.svg) 
 Modify an existing view and the alerts that are attached to the view. PUT ![Check mark icon](https://cloud.ibm.com/docs-content/v1/content/6f3c07c34058f637b1c86044ca4f9b24214330a7/activity-tracker/images/checkmark-icon.svg) 
 Get all configured views and alerts GET 
 Delete a view and its associated alerts. DELETE 







 query (string) 

Specifies the search query that is applied to the view.

Check the query in the UI to validate that the data that is displayed through the view matches the data entry that you plan to monitor through that view.
A successful request returns an HTTP 204 No Content response, which indicates that your service instance is now enabled for dual authorization. Keys that you create or import to the service now require two authorizations before they can be deleted. For more information, see [Deleting keys](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-delete-keys).

This new policy does not affect existing keys in your instance. If you need to enable dual authorization for an existing key, see [Creating a dual authorization policy for a key](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-set-dual-auth-key-policycreate-dual-auth-key-policy-api).
3. Optional: Verify that the dual authorization policy was created by browsing the policies that are available for your Hyper Protect Crypto Services instance.

curl -X GET 
'https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/instance/policies?policy=dualAuthDelete' 
  -H 'authorization: Bearer <IAM_token>' 
  -H 'bluemix-instance: <instance_ID>' 
  -H 'accept: application/vnd.ibm.kms.policy+json'







 Disabling dual authorization for your service instance with the console 

As an instance manager, if you prefer to disable a dual authorization policy on your instance by using a graphical interface, you can use the IBM Cloud console.

After creating a service instance, complete the following steps to create a dual authorization policy:



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. In the UI of the selected service instance, select the Instance policies tab in the side menu.
5.
$ ENCRYPTED_KEY=C+/puHn1v5p7aohitM4r6N4ohiVkCecP ...<redacted>... eWmJRuvsSxDg/OY=

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

Encrypted Nonce IV
TxrgdayWnM5OB3JoYuQR97oulxvREptk8TzciQ== 7BiIpcbGxXBzuXZP

 capture the encrypted nonce and the initialization vector (IV)
$ ENCRYPTED_NONCE=TxrgdayWnM5OB3JoYuQR97oulxvREptk8TzciQ==
$ 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
For more information, see [Monitoring the lifecycle of encryption keys in Unified Key Orchestrator](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-uko-key-states).<br><br>If your key state is different from the key state in its target keystores, an Out of sync flag is displayed beside the state. There can be multiple reasons why the key state is out of sync. For example, you have deactivated the key in this target keystore before, or you activate the key through the CLI and the console doesn't reflect the state timely. When you hover over this flag, you can see the specific reason. You can sync keys by selecting Show details on the Actions ![Actions icon](https://cloud.ibm.com/docs-content/v1/content/217f108cc44e2ce15fb692d4b57b4c628464e908/icons/action-menu-icon.svg) menu and clicking Sync keys. 
 Activation date The date when the key gets activated, or the date on which you plan to activate the key. 
 Expiration date The date when the key gets deactivated, or the date on which you plan to deactivate the key. 
 Last updated The date and time when the key was last updated. This field gets updated when the key is created, edited, or any part of the key metadata is modified. 
 Last rotated The date and time when the key was last rotated. If the key was not rotated before, it shows Never. 
 Creation date Set a date range of when the key was created. 
 Keystores The target keystores where the key is activated. 
 Algorithm The encryption algorithm to encrypt data for the key. 
 Length The number of bits that represents the encryption strength of the key. 
 Keystore type The type of keystore where the key is stored. 



You can search for a specific key by using the search bar, or filter keys based on your needs by clicking the Filter icon !
* The responseData.eventAckData.eventAckTimeStamp field includes the date and time that the event was acknowledged.







 Completed action of an enabled key 

The following fields include extra information:



* The responseData.eventAckData.eventId field includes the unique identifier that is associated with the event.
* The responseData.eventAckData.eventType field includes the type of lifecycle action that is associated with the event.
* The responseData.eventAckData.keyState field includes the integer that correlates to the state of the key associated with the event.
* The responseData.eventAckData.eventAckTimeStamp field includes the date and time that the event was acknowledged.







 Completed action of a disabled key 

The following fields include extra information:



* The responseData.eventAckData.eventId field includes the unique identifier that is associated with the event.
* The responseData.eventAckData.eventType field includes the type of lifecycle action that is associated with the event.
* The responseData.eventAckData.keyState field includes the integer that correlates to the state of the key associated with the event.
* The responseData.eventAckData.eventAckTimeStamp field includes the date and time that the event was acknowledged.











 Analyzing failed events 



 Unable to delete a key 

If the delete key event has a reason.reasonCode of 409, the key could not be deleted because it is possibly protecting one or more cloud resources that have a retention policy. Make a GET request to /keys/{id}/registrations to learn which resources this key is associated with. A registration with "preventKeyDeletion": true indicates that the associated resource has a retention policy. To enable deletion, contact an account owner to remove the retention policy on each resource that is associated with this key.

A delete key event could also receive a reason.reasonCode of 409 due to a dual auth deletion policy on the key. Make a GET request to /api/v2/keys/{id}/policies to see if there is a dual authorization policy associated with your key.
<br> <br>For more information, see [Retrieving an instance ID](https://cloud.ibm.com/docs/key-protect?topic=key-protect-retrieve-instance-ID). 
 return_preference Optional. A header that alters server behavior for POST and DELETE operations. <br> <br>When you set the return_preference variable to return=minimal, the service returns a successful deletion response. When you set the variable to return=representation, the service returns both the key material and the key metadata. 



If the return_preference variable is set to return=representation, the details of the DELETE request are returned in the response entity-body.

After you delete a key, it transitions to the Deactivated key state. After 24 hours, if a key is not reinstated, the key transitions to the Destroyed state. Deleted keys can be recovered after up to 30 days or their expiration date, whichever is sooner. After this the key contents are permanently shredded and its metadata is no longer accessible.

The following JSON object shows an example returned value.

{
"metadata": {
"collectionType": "application/vnd.ibm.kms.key+json",
"collectionTotal": 1
},
"resources": [
{
"id": "2291e4ae-a14c-4af9-88f0-27c0cb2739e2",
"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",
Deleted keys can be [restored within 30 days](https://cloud.ibm.com/docs/key-protect?topic=key-protect-delete-purge-keys) of being deleted, but if 30 days have passed, you can use stored key material to create a functionally identical key (it will be able to unwrap data encryption keys created by the deleted root key, for example). You will need to update your application to use the unique key ID given for this functionally identical key and to change the endpoint (if the new key is created in a different region).

Because any key that uses the same material during key creation is functionally equivalent, you are encouraged to keep your backed up key material secure.

Similarly, you can also securely backup your root keys by using the key material to create a duplicate key in a Key Protect region that is different from the original key.

Every time a root key is rotated, new key material is added to the key, which creates a new version of the key. As a result, your equivalent keys (duplicate keys created using the same key material) should be kept up to date with the new material.





 Using key aliases with duplicate keys 

Because keys created with the same material are functionally identical (that is, both can be used to wrap and unwrap the same data), users have the option of creating these keys in different regions and using them as backups in the event a data center is temporarily unavailable. While these duplicates will have different key IDs, they can be given the same [key alias](https://cloud.ibm.com/docs/key-protect?topic=key-protect-create-key-alias). This alias can serve to organize functionally identical keys together, making it easier to update an application to point to these backup keys.





 Using key rings 

[Key rings](https://cloud.ibm.com/docs/key-protect?topic=key-protect-grouping-keys) are a way to create a group of keys for a target group of users that require the same IAM access permissions. This allows an account admin to easily tailor the keys they own to the users who manage them and is therefore less error prone than manually updating the permissions of each key and user.