vania-janet/multiturn-rag-retrieval-data huggingface dataset:
The region abbreviation, such as us-south or eu-gb, that represents the geographic area where your Key Protect instance resides. For more information, see [Regional service endpoints](https://cloud.ibm.com/docs/key-protect?topic=key-protect-regionsservice-endpoints). 
 keyID_or_alias Required. The unique identifier or alias for the key that you want to inspect. 
 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/key-protect?topic=key-protect-retrieve-access-token). 
 instance_ID Required. The unique identifier that is assigned to your Key Protect service instance. For more information, see [Retrieving an instance ID](https://cloud.ibm.com/docs/key-protect?topic=key-protect-retrieve-instance-ID). 
 key_ring_ID Optional. The unique identifier of the key ring that the key is a part of. The header itself is optional, but if unspecified, Key Protect will search for the key in every key ring associated with the specified instance. It is recommended to specify the key ring ID for a more optimized request. Note: The key ring ID of keys that are created without an x-kms-key-ring header is: default. For more information, see [Grouping keys](https://cloud.ibm.com/docs/key-protect?topic=key-protect-grouping-keys). 
 correlation_ID Optional.The unique identifier that is used to track and correlate transactions. 



A successful GET api/v2/keys/<key_ID_or_alias>/metadata response returns details about your key. The following JSON object shows an example returned value for a standard key.

{
"metadata": {
"collectionType": "application/vnd.ibm.kms.key+json",
* UI
* CLI
* API







 Deleting a custom resolver 

You can delete a custom resolver in IBM Cloud® DNS Services by using the UI, CLI, or API.



 Deleting a custom resolver using the UI 

You can delete your custom resolver with the UI in two ways.

To delete a custom resolver from the custom resolver list view:



1. Click the overflow icon next to the custom resolver you want to delete.
2. Select Delete.
3. Click Delete in the confirmation dialog that appears.



To delete a custom resolver from the custom resolver details view:



1. Select the custom resolver you want to delete to open the details page.
2. Click Delete resolver.
3. Click Delete in the confirmation dialog that appears.







 Deleting a custom resolver using the CLI 

To delete a custom resolver using the CLI, run the following command:

ibmcloud dns custom-resolver-delete RESOLVER_ID [-i, --instance INSTANCE] [-f, --force]

Where:



* RESOLVER_ID is the ID of custom resolver.
* -i, --instance is the instance name or ID. If this is not set, the context instance specified by dns instance-target INSTANCE is used instead.
* --output specifies output format. Currently, JSON is the only supported format.
* -f, --force deletes the custom resolver without prompting for confirmation.







 Deleting a custom resolver using the API 

To delete a custom resolver using the API, follow these steps:



1. Set up your API environment with the correct variables.
2. Store the following values in variables to be used in the API command:



* instance_id, which is the unique identifier of a service instance.
* resolver_id, which is the unique identifier of a custom resolver.
* X-Correlation-ID, which is a string that uniquely identifies a request.



3.
Describes the variables that are needed to update a key's key ring with the Key Protect API.

 Variable Description 

 region Required. The region abbreviation, such as us-south or eu-gb, that represents the geographic area where yourKey Protect instance resides. <br> <br>For more information, see [Regional service endpoints](https://cloud.ibm.com/docs/key-protect?topic=key-protect-regionsservice-endpoints). 
 keyID_or_alias Required. The unique identifier or alias for the key that you would like to update. 
 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). 
 original_key_ring_ID Optional. The unique identifier of the key ring that the key is currently a part of. If unspecified, Key Protect will search for the key in every key ring associated with the specified instance. It is therefore recommended to specify the key ring ID for a more optimized request. Note: The key ring ID of keys that are created without an x-kms-key-ring header is: default. 
 correlation_ID Optional.The unique identifier that is used to track and correlate transactions. 
 new_key_ring_ID Required. The unique identifier for the target key ring that you would like to move the key to. 



A successful PATCH api/v2/keys/keyID_or_alias request returns the key's metadata, including the id of the key ring that the key is a part of.

{
metrics-router.target.list This event is generated when an administrator lists all targets defined under a region. 
 metrics-router.target.read This event is generated when an administrator retrieves a target and its details by specifying the ID of the target. 
 metrics-router.target.update This event is generated when an administrator updates a target details by specifying the ID of the target. 
 metrics-router.target.delete This event is generated when an administrator deletes a target by specifying the ID of the target. 







 Routes 

The following table lists the auditing events that are generated when you manage routes:



Table 2. Events for managing routes

 Action Description 

 metrics-router.route.create This event is generated when an administrator creates a route with rules that define how to route metrics data to targets. 
 metrics-router.route.list This event is generated when an administrator lists routes. 
 metrics-router.route.read This event is generated when an administrator retrieves a route and its details by specifying the ID of the route. 
 metrics-router.route.update This event is generated when an administrator replaces a route details by specifying the ID of the route. You can also get this event when you validate a target by checking the credentials to the destination target. 
 metrics-router.route.delete This event is generated when an administrator deletes a route by specifying the ID of the route. 







 Settings 

The following table lists the auditing events that are generated when you manage settings:



Table 3. Events for managing settings

 Action Description 

 metrics-router.setting.update This event is generated when an administrator configures the IBM Cloud Metrics Routing settings for an account. 
 metrics-router.setting.get This event is generated when an administrator gets information about the IBM Cloud Metrics Routing settings for an account.
You can find the ID for a key in your Key Protect instance by [retrieving a list of your keys](https://cloud.ibm.com/docs/key-protect?topic=key-protect-view-keys), or by accessing the Key Protect dashboard.
3. Copy the ciphertext value that was returned during the initial wrap request.
4. Run the following curl command to decrypt and authenticate the key material.

$ curl -X POST "https://<region>.kms.cloud.ibm.com/api/v2/keys/<keyID_or_alias>/actions/unwrap" -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" -H "x-kms-key-ring: <key_ring_ID>" -H "correlation-id: <correlation_ID>" -d '{
"ciphertext": "<encrypted_data_key>",
"aad": [
"<additional_data>",
"<additional_data>"
]
}'



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



Table 1. Describes the variables that are needed to unwrap keys in Key Protect.

 Variable Description 

 region Required. 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). 
 keyID_or_alias Required. The unique identifier or alias for the root key that you used for the initial wrap request. 
 IAM_token Required. Your IBM Cloud access token.
$ ibmcloud kp key versions af61298c-d75d-42a8-aa76-e04178cf4685 -i 99980ccc-d482-4cd0-bb41-deb4f7f1eb92 -t

Retrieving key Versions...
FAILED
KEY_ACTION_INVALID_STATE_ERR
Key is not in a valid state
Correlation-ID:a494bf49-be82-426f-88d8-17b58cc8634d

With CLI version 0.8.0 and higher, the command succeeds when adding the -a flag, as in the following example:

 Attempt to show version count
$ ibmcloud kp key versions af61298c-d75d-42a8-aa76-e04178cf4685 -i 99980ccc-d482-4cd0-bb41-deb4f7f1eb92 -t -a

Retrieving key Versions...
OK
TotalCount: 2
Key Version ID Creation Date
14dfde20-a751-4c3e-b6b0-e8d00a17d8d1 2023-06-22T15:16:09Z
af61298c-d75d-42a8-aa76-e04178cf4685 2023-06-22T15:10:28Z

Note that if the -a flag is not given, the KEY_ACTION_INVALID_STATE_ERR is still returned for a key in a state other than active.







 Required parameters 



* KEY_ID_OR_ALIAS

The v4 UUID or alias of the root key that you used for the initial wrap request.
* -i, --instance-ID

The IBM Cloud instance ID that identifies your Key Protect instance.

You can set an environment variable instead of specifying -i with the following command: $ export KP_INSTANCE_ID=<INSTANCE_ID>.







 Optional parameters 



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

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



Table 1. Describes the variables needed to view details about a key with the API

 Variable Description 

 region Required. The region abbreviation, such as us-south or eu-de, that represents the geographic area where your Hyper Protect Crypto Services instance resides. For more information, see [Regional service endpoints](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-regionsservice-endpoints). 
 key_ID_or_alias Required. The identifier or alias for the key that you want to inspect. 
 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. For more information, see [Retrieving an instance ID](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-retrieve-instance-ID). 
 key_ring_ID Optional. The unique identifier of the key ring that the key belongs to. If unspecified, Hyper Protect Crypto Services will search for the key in every key ring that is associated with the specified instance.
For more information, see [Regional service endpoints](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-regionsservice-endpoints). 
 port Required. The port number of the API endpoint. 
 key_ID Required. The unique identifier for the root key that you used for the initial wrap request. 
 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 yourHyper Protect Crypto Services service instance. For more information, see [Retrieving an instance ID](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-retrieve-instance-ID). 
 key_ring_ID Optional. The unique identifier of the key ring that the key belongs to. If unspecified, Hyper Protect Crypto Services searches for the key in every key ring that is associated with the specified instance. It is suggested to specify the key ring ID for a more optimized request.<br><br>Note: The key ring ID of keys that are created without an x-kms-key-ring header is: default. For more information, see [Managing key rings](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-managing-key-rings). 
 correlation_ID Optional. The unique identifier that is used to track and correlate transactions. 
 encrypted_data_key The ciphertext value that was returned during a wrap operation. 



The original key material is returned in the response entity-body. The response body also contains the ID of the key version that was used to unwrap the supplied ciphertext. The following JSON object shows a sample returned value.

{
$ KEY_ID=$(ibmcloud kp key create my-root-key --output json | jq -r '.["id"]')

$ echo $KEY_ID

63d044d9-b38b-4803-85ef-ed9a1e5087c2

 disable the root key
$ ibmcloud kp key disable $KEY_ID

Disabling key: '63d044d9-b38b-4803-85ef-ed9a1e5087c2', in instance: '390086ac-76fa-4094-8cf3-c0829bd69526'...
OK

 create a random, base64-encoded, 32-byte data encryption key (DEK)
$ PLAINTEXT=$(openssl rand -base64 32)

$ echo $PLAINTEXT

BNxtU9B4kXOZA45Cnyz3wOh4J77TakTXI1n2rj0ZiMc=

 wrap the plaintext key with the root key, creating a DEK (this is the ciphertext)
 this should fail (the root key is disables)
$ ibmcloud kp key wrap $KEY_ID -p $PLAINTEXT --output json

FAILED
kp.Error:
correlation_id='c2edbdad-7e62-4690-8fcc-10515ade9913',
msg='Conflict: Action could not be performed on key. Please see "reasons" for more details.',
reasons='[KEY_ACTION_INVALID_STATE_ERR: Key is not in a valid state -
FOR_MORE_INFO_REFER: https://cloud.ibm.com/apidocs/key-protect]'





 Example 3 

Create a root key with an alias, use that alias to identify the key to be disabled, verify the key state (suspended), then enable the root key and verify the new key state (active).

 create a root key
Why does encryption fail with an invalid KMS endpoint? 

Virtual Private Cloud

Classic infrastructure

 What’s happening 

When you provision Portworx and set up encryption, you receive an error similar to the following:

kp.Error: correlation_id='673bb68a-be17-4720-9ae1-85baf109924e', msg='Unauthorized: The user does not have access to the specified resource'"

 Why it’s happening 

The endpoint that you entered in your Kubernetes secret is incorrect. If the KMS endpoint is entered incorrectly, Portworx can't access the KMS provider that you configured.

For more information about enabling encryption on your Portworx volumes, see [Setting up encryption](https://cloud.ibm.com/docs/openshift?topic=openshift-storage_portworx_encryption).

 How to fix it 

Edit your Kubernetes secret to include the correct endpoint for your KMS provider.



1. Retrieve the correct endpoint for your KMS provider.



* IBM Key Protect: [Retrieve the region](https://cloud.ibm.com/docs/key-protect?topic=key-protect-regionsregions) where you created your service instance. Make sure that you note your API endpoint in the correct format. Example: https://us-south.kms.cloud.ibm.com.
* Hyper Protect Crypto Services: [Retrieve the Key Management public endpoint URL](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-regionsservice-endpoints). Make sure that you note your endpoint in the correct format. Example: https://api.us-south.hs-crypto.cloud.ibm.com:<port>. For more information, see the [Hyper Protect Crypto Services API documentation](https://cloud.ibm.com/apidocs/hs-cryptogetinstance).



2. Encode the endpoint to base64.
$ 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>" -H "x-kms-key-ring: <key_ring_ID>" -H "correlation-id: <correlation_ID>"

Replace the variables in the example request according to the information in Table 1. For more information about optional parameters available when viewing collections of keys, including the ability to search your keys, see the [API documentation regarding the List keys method](https://cloud.ibm.com/apidocs/key-protectgetkeys).





Table 1. Describes the variables that are needed to view keys with the Key Protect API.

 Variable Description 

 region Required. The region abbreviation, such as us-south or eu-gb, that represents the geographic area where your Key Protect instance resides. For more information, see [Regional service endpoints](https://cloud.ibm.com/docs/key-protect?topic=key-protect-regionsservice-endpoints). 
 keyID_or_alias Required. The unique identifier or alias for the key that you want to inspect. 
 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/key-protect?topic=key-protect-retrieve-access-token). 
 instance_ID Required. The unique identifier that is assigned to your Key Protect service instance. For more information, see [Retrieving an instance ID](https://cloud.ibm.com/docs/key-protect?topic=key-protect-retrieve-instance-ID). 
 key_ring_ID Optional. The unique identifier of the target key ring.
-H 'bluemix-instance: <instance_ID>'



* Replace <port> with the port number of your API endpoint. You can get the <port> in your provisioned service instance dashboard through Overview > Key management endpoint URL. Or, you can dynamically [retrieve the API endpoint URL](https://cloud.ibm.com/apidocs/hs-cryptogetinstance).

Note that the port range of a Hyper Protect Crypto Services instance is between 8000 - 19999.

The returned value includes:

{
"instance_id": "<instance_ID>",
"kms": {
"public": "api.<region>.hs-crypto.cloud.ibm.com:<port>",
"private":"api.private.<region>.hs-crypto.cloud.ibm.com:<port>"
},
"ep11": {
"public": "ep11.<region>.hs-crypto.cloud.ibm.com:<port>",
"private":"ep11.private.<region>.hs-crypto.cloud.ibm.com:<port>"
}
}

For the key management service, use the <region> and <port> in the kms section.
* Replace <access_token> and <instance_ID> with your retrieved service and authentication credentials.



Want to track your API requests in case something goes wrong? When you include the -v flag as part of cURL request, you get a correlation-id value in the response headers. You can use this value to correlate and track the request for debugging purposes.





 What's next 

You're all set to start managing your encryption keys and data. To find out more about programmatically managing your keys, [check out the key management service API reference doc](https://cloud.ibm.com/apidocs/hs-crypto).
https://<region>.kms.cloud.ibm.com/api/v2/keys/<keyID_or_alias>/actions/rewrap



1. [Retrieve your service and authentication credentials to work with keys in the service](https://cloud.ibm.com/docs/key-protect?topic=key-protect-set-up-api).
2. Copy the ID of the rotated root key that you used to perform the initial wrap request.

You can retrieve the ID for a key by making a GET api/v2/keys request, or by viewing your keys in the Key Protect GUI.
3. Copy the ciphertext value that was returned during the latest wrap request.
4. Rewrap the key with the latest root key material by running the following curl command.

$ curl -X POST "https://<region>.kms.cloud.ibm.com/api/v2/keys/<keyID_or_alias>/actions/rewrap" -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" -H "x-kms-key-ring: <key_ring_ID>" -H "correlation-id: <correlation_ID>" -d '{
"ciphertext": "<encrypted_data_key>",
"aad": [
"<additional_data>",
"<additional_data>"
]
}'

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





Table 1. Describes the variables that are needed to rewrap keys in Key Protect.

 Variable Description 

 region Required. The region abbreviation, such as us-south or eu-gb, that represents the geographic area where your Key Protect instance resides.
[Retrieve your authentication credentials to work with keys in the service](https://cloud.ibm.com/docs/key-protect?topic=key-protect-set-up-api).

To create a key alias, you must be assigned a Manager or Writer service access role. To learn how IAM roles map to Key Protect service actions, check out [Service access roles](https://cloud.ibm.com/docs/key-protect?topic=key-protect-manage-accessmanage-access-roles).
2. Create a key alias by running the following curl command.

$ curl -X POST "https://<region>.kms.cloud.ibm.com/api/v2/keys/<keyID_or_alias>/aliases/<key_alias>" -H "authorization: Bearer <IAM_token>" -H "bluemix-instance: <instance_ID>" -H "content-type: application/vnd.ibm.kms.key+json" -H "correlation-id: <correlation_ID>"



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



Table 1. Describes the variables that are needed to create a key alias with the Key Protect API

 Variable Description 

 region Required. The region abbreviation, such as us-southor eu-gb, that represents the geographic area where your Key Protect instance resides. <br>For more information, see [Regional service endpoints](https://cloud.ibm.com/docs/key-protect?topic=key-protect-regionsservice-endpoints). 
 keyID_or_alias Required. The identifier or alias for the key that you would like to associate with an alias. To retrieve a key ID, see the [list keys API](https://cloud.ibm.com/docs/key-protect?topic=key-protect-view-keysretrieve-keys-api). 
 key_alias Required. A unique, human-readable name for easy identification of your key.
-H 'accept: application/vnd.ibm.collection+json' 
-H 'authorization: Bearer <IAM_token>' 
-H 'bluemix-instance: <instance_ID>' 
-H 'correlation-id: <correlation_ID>' 







 Importing standard keys with the CLI 

Complete the following steps to import standard keys that use the Key Protect CLI, which is integrated in Hyper Protect Crypto Services:



1. [Set up the Key Protect CLI](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-set-up-cli).
2. Import a standard key with the following command:

ibmcloud kp key create

You can find extra parameters for this command in the [Key Protect CLI reference](https://cloud.ibm.com/docs/key-protect?topic=key-protect-cli-plugin-key-protect-cli-referencekp-key-create).







 Base64 encoding your key material 

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



 Using OpenSSL to encode existing key material 



1. Download and install [OpenSSL](https://github.com/openssl/opensslfor-production-use).
2. Base64 encode your key material string by running the following command:

$ openssl base64 -in <infile> -out <outfile>

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



Table 3. Describes the variables needed to base64 encode your key material

 Variable Description 

 infile The name of the file where your key material string resides. 
 outfile The name of the file where your base64-encoded key material is created when the command is run. 



If you want to output the base64 material in the command line directly rather than a file, run the command openssl enc -base64 <<< '<key_material_string>', where key_material_string is the key material input for your imported key.