vania-janet/multiturn-rag-retrieval-data huggingface dataset:
Use URL encoded CRN queries that contain all CRN segments. To learn more about CRN segments and format, see [Cloud Resource Names](https://cloud.ibm.com/docs/account?topic=account-crn).

When an integrated service calls the Hyper Protect Crypto Services key management service API, Hyper Protect Crypto Services replaces the given CRN query (up to the service-instance segment) with the CRN of the calling service. This means that the services that use Hyper Protect Crypto Services to associate keys with resources on your behalf can only view or query for CRNs that match the first eight segments of their service CRN.



* To search for the existence of a CRN segment, use a colon followed by an asterisk ().

crn:v1:bluemix:public:databases-for-redis:us-south:a/274074dce64e9c423ffc238516c755e1:29caf0e7-120f-4da8-9551-3abf57ebcfc7::

This query returns Databases for Redis registrations that are associated with all resource types and names for deployment ID 29caf0e7-120f-4da8-9551-3abf57ebcfc7.
* To search for a CRN segment that is prefixed by <string>, use a colon followed by <string> on the last segment of the CRN query.

crn:v1:bluemix:public:cloud-object-storage:global:a/e1bb63d6a20dc57c87501ac4c4c99dcb::bucket:prod

This query returns all Cloud Object Storage bucket registrations within account e1bb63d6a20dc57c87501ac4c4c99dcb that are prefixed by prod.
<br><br> * hs-crypto.managed-keys.read<br> * hs-crypto.managed-keys.list<br> * hs-crypto.target-keystores.read<br> * hs-crypto.target-keystores.list<br> * hs-crypto.target-keystores.write<br> * hs-crypto.target-keystores.delete<br> * hs-crypto.key-templates.read<br> * hs-crypto.key-templates.list<br> * hs-crypto.vaults.read<br> * hs-crypto.vaults.list<br> * hs-crypto.uko.initiate-paid-upgrade<br> * hs-crypto.uko.add-paid-keystore<br><br><br> 
 My key administrator Manages special permissions for administrative tasks, such as destructive actions. <br><br> * hs-crypto.managed-keys.deactivated-destroy<br> * hs-crypto.managed-keys.destroyed-remove<br> * hs-crypto.managed-keys.read<br> * hs-crypto.managed-keys.list<br> * hs-crypto.managed-keys.delete<br> * hs-crypto.target-keystores.read<br> * hs-crypto.target-keystores.list<br> * hs-crypto.key-templates.read<br> * hs-crypto.key-templates.list<br> * hs-crypto.key-templates.write<br> * hs-crypto.key-templates.delete<br> * hs-crypto.vaults.read<br> * hs-crypto.vaults.list<br><br><br> 
 My key custodian - creator Manages and creates keys. For a complete key lifecycle, both Creator and Deployer roles are needed. To implement separation of duties, assign Creator and Deployer role to different people.
Setting up Terraform for Hyper Protect Crypto Services with Unified Key Orchestrator 

Terraform on IBM Cloud® enables predictable and consistent provisioning of IBM Cloud services so that you can rapidly build complex, multitiered cloud environments following Infrastructure as Code (IaC) principles. Similar to using the IBM Cloud CLI or API and SDKs, you can automate the provisioning, update, and deletion of your Hyper Protect Crypto Services instances by using HashiCorp Configuration Language (HCL).

This topic only covers how to set up Terraform for Hyper Protect Crypto Services with Unified Key Orchestrator.

Looking for a managed Terraform on IBM Cloud solution? Try out [IBM Cloud® Schematics](https://cloud.ibm.com/docs/schematics?topic=schematics-getting-started). With Schematics, you can use the Terraform scripting language that you are familiar with, but you don't have to worry about setting up and maintaining the Terraform command line and the IBM Cloud Provider plug-in. Schematics also provides pre-defined Terraform templates that you can easily install from the IBM Cloud catalog.

Before you begin, make sure that you have the [required access](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-uko-manage-access) to create and work with Hyper Protect Crypto Services resources.



 Example: Provisioning and initializing service instances by using Terraform 

Complete the following steps to create and initialize a Hyper Protect Crypto Services instance by using Terraform:



1. Install the Terraform CLI and configure the IBM Cloud Provider plug-in for Terraform by following the [Terraform on IBM Cloud getting started tutorial](https://cloud.ibm.com/docs/ibm-cloud-provider-for-terraform?topic=ibm-cloud-provider-for-terraform-getting-started).

The plug-in abstracts the IBM Cloud APIs that are used to provision, update, or delete Hyper Protect Crypto Services service instances and resources. The preferred Terraform versions are 0.13.x, 0.14.x, and 0.15.x.
* UI
* API







 Disabling root keys 

You can use IBM Cloud® Hyper Protect Crypto Services to disable or enable a root key and temporarily revoke access to the key's associated data on the cloud.

As an admin, you might need to temporarily disable a root key if you suspect a possible security exposure, compromise, or breach with your data. When you disable a root key, you suspend the encrypt and decrypt operations. After you confirm that a security risk is no longer active, you can restore access to your data by enabling the disabled root key.

If you are using a cloud service that is integrated with Hyper Protect Crypto Services, your data might not be accessible after you disable a root key. To determine whether an [integrated service](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-integrate-services) supports revoking access to data by disabling a Hyper Protect Crypto Services root key, see the service documentation.

When you disable a root key, the key moves to the [Suspended state](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-key-states), and it can no longer be used to cryptographically protect data.

When you enable a root key that was previously disabled, the key moves from the Suspended to the Active key state. This action restores the key's encrypt and decrypt operations.

You must wait 30 seconds after you disable a root key before you are able to enable it again.

For an integrated Cloud Service that supports revoking access to a disabled root key, the service can take up to 4 hours to revoke or restore access to the associated data of the root key. After access to the associated data is revoked or restored, a corresponding enable event is displayed in the Activity Tracker web UI.



 Disabling and enabling root keys with the console 

If you prefer to enable or disable your root keys by using a graphical interface, you can use the IBM Cloud console.



 Disabling a root key
* UI
* API







 Creating vaults 

You can use Hyper Protect Crypto Services to create a group of keys and keystores for a target group of users that require the same Cloud Identity and Access Management (IAM) access permissions in a vault. You can create vaults in Unified Key Orchestrator with the IBM Cloud® console, or programmatically with the Unified Key Orchestrator API.

As a Vault Administrator, you can bundle the keys and keystores in your Hyper Protect Crypto Services instance into groups called vault. A vault is a collection of keys, internal keystores, and external keystores that require the same IAM access permissions. For example, if you have a group of team members who need a particular type of access to a specific group of keys and keystores, you can create a vault and assign the appropriate IAM access policy to the target user group. The users that are assigned access to the vault can create and manage the resources that exist within the vault.

Vaults are also useful in cases where it is important for one business unit to have access to a set of keys and keystores that another business unit cannot have. An account administrator can create vaults for each business unit and [assign the appropriate level of access](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-grant-access-vaults) to the appropriate users. In the case where the account administrator wants to delegate platform management of a specific vault to someone else, they can assign a user a [Vault Administrator role](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-uko-manage-accessuko-service-access-roles). The sub-administrator is then able to manage the vault and grant access to the appropriate users.

Before you create a vault for your Hyper Protect Crypto Services instance, keep in mind of the following considerations:



* Vaults can hold KMS keys and keystores, but not EP11 keys and keystores.

Vaults can contain both KMS keys and keystores. There is no limit on how many keys can exist within a vault. Vaults don't apply to Enterprise PKCS #11 (EP11) keys and keystores.
(https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-faq-provisioning-operationsfaq-hpcs-service-integration)



[FAQs: Hyper Protect Crypto Services Standard Plan](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-faq-performance-capacityfaq-performance-capacity)



* [How many keys can be stored in a Hyper Protect Crypto Services service instance?](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-faq-performance-capacityfaq-keys-number)
* [How many key rings can be created for a Hyper Protect Crypto Services service instance?](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-faq-performance-capacityfaq-keyrings-number)
* [Can I add or remove crypto units after I provision a service instance?](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-faq-performance-capacityfaq-add-remove-crypto-unit)
* [Is there a Service Level Agreement (SLA) specifically for Hyper Protect Crypto Services?](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-faq-performance-capacityfaq-hpcs-sla)



[FAQs: Hyper Protect Crypto Services with Unified Key Orchestrator](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-faq-ukofaq-uko)



* [What is the difference between key management, key orchestration, and key governance?](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-faq-ukofaq-uko-differences)
* [Does Hyper Protect Crypto Services with Unified Key Orchestrator provide key management, governance, and orchestration at the same time?]
For more information, see [Retrieving an access token](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-retrieve-access-token). 
 instance_ID The unique identifier that is assigned to your Hyper 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). 
 correlation_ID The unique identifier that is used to track and correlate transactions. 
 return_preference Optional: A header that alters server behavior for POST and DELETE operations. 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_alias A unique, human-readable name for easy identification of your key. <br> <br>Important: To protect your privacy, do not store your personal data as metadata for your key. 
 key_description Optional: An extended description of your key. <br> <br>Important: To protect your privacy, do not store your personal data as metadata for your key. 
 YYYY-MM-DD<br><br>HH:MM:SS.SS Optional: The date and time that the key expires in the system, in RFC 3339 format. If the expirationDate attribute is omitted, the key does not expire. 
 key_material The base64 encoded key material, such as a symmetric key, that you want to manage in the service. For more information, see [Base64 encoding your key material](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-import-standard-keysencode-key-material-standard-key). <br> <br>Ensure that the key material meets the following requirements: <br> <br>* The key can be up to 7,500 bytes. <br>* The key must be base64-encoded.
* EncryptSingle() is an IBM EP11 extension to the standard PKCS #11 specification, and is used to perform a single call to encrypt single-part data without the need to run the EncryptInit() and Encrypt() sub-operations.



The following diagram shows the three calling sequence flows of GREP11 functions to perform encryption. The flows can also apply to other operations such as decrypt, digest, sign, and verify. For more information about the GREP11 API, see [GREP11 API reference](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-grep11-api-ref).

Zoom

![GREP11 functions calling flow for encryption](https://cloud.ibm.com/docs-content/v1/content/217f108cc44e2ce15fb692d4b57b4c628464e908/hs-crypto//images/grep11-encryption-flow.svg)

Figure 1. Three calling flows of GREP11 functions for encryption

The GREP11 API can process up to 500 requests/second for a single crypto unit.



 Post-quantum cryptography support 

With the GREP11 API, you can also perform [post-quantum cryptographic](https://en.wikipedia.org/wiki/Post-quantum_cryptography) operations. Traditional cryptography relies on complicated mathematical problems that are difficult for classical computers to solve. However, with the computing capabilities, quantum computers can solve these problems. Post-quantum cryptography is considered to be resistant to cryptanalytic attacks from quantum computers. It usually uses asymmetric algorithms and has multiple approaches.

The GREP11 API provides the [Dilithium algorithm](https://pq-crystals.org/dilithium/) for post-quantum cryptography. It is a lattice-based digital signature scheme and can be used for signature generation and verification.
hs-crypto.secrets.readmetadata hs-crypto.secrets-metadata.read 







 Supported events 



 Key events 

The following table lists the key actions that generate an event:



Table 2. Lifecycle key actions

 Action Description 

 hs-crypto.secrets.create Create a key. 
 hs-crypto.secrets-alias.create Create a key alias. 
 hs-crypto.secrets.default Invalid key request event. 
 hs-crypto.secrets.delete Delete a key. 
 hs-crypto.secrets-alias.delete Delete a key alias. 
 hs-crypto.secrets.disable Disable operations for a key. 
 hs-crypto.secrets.enable Enable operations for a key. 
 hs-crypto.secrets-event.ack Acknowledge a lifecycle action on a key. 
 hs-crypto.secrets.expire Expire a key. 
 hs-crypto.secrets.head Retrieve key total. 
 hs-crypto.secrets.list List keys. 
 hs-crypto.secrets-key-versions.list List all the versions of a key. 
 hs-crypto.secrets.wrap Wrap a key. 
 hs-crypto.secrets.patch Patch a key. 
 hs-crypto.secrets.purge Purge a key. 
 hs-crypto.secrets.read Retrieve all key information. 
 hs-crypto.secrets-metadata.read Retrieve key metadata (excluding key payload, if applicable). 
 hs-crypto.secrets.restore Restore a key. 
 hs-crypto.secrets.rewrap Rewrap a key. 
 hs-crypto.secrets.rotate Rotate a key. 
 hs-crypto.secrets.setkeyfordeletion Authorize deletion for a key with Dual Authorization policy. 
 hs-crypto.secrets.unsetkeyfordeletion Cancel deletion for a key with Dual Authorization policy. 
 hs-crypto.secrets.unwrap Unwrap a key. 









 Key Ring events 

The following table lists the key ring actions that generate an event:



Table 3. Key ring actions

 Action Description 

 hs-crypto.key-rings.create Create a key ring.
: You can now create Hyper Protect Crypto Services resources in the Frankfurt region. For more information, see [Regions and locations](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-regions).

Added: IBM Cloud service integration
: Hyper Protect Crypto Services can now be integrated with the following IBM Cloud services:



* IBM Cloud Object Storage
* IBM Cloud Block Storage for Classic for Virtual Private Cloud
* IBM Cloud Virtual Servers for Virtual Private Cloud
* Key Management Interoperability Protocol (KMIP) for VMware® on IBM Cloud



For more information, see [Integrating services](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-integrate-services).





 30 June 2019 

Added: Hyper Protect Crypto Services expands into Sydney region
: You can now create Hyper Protect Crypto Services resources in the Sydney region. For more information, see [Regions and locations](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-regions).





 31 March 2019 

Hyper Protect Crypto Services is generally available
: As of 29 March 2019, provisioning new Hyper Protect Crypto Services Beta instances will no longer be possible. Existing instances will have support until the End of Beta Support Date (30 April 2019).

For more information about the Hyper Protect Crypto Services offering, see the [IBM Cloud Hyper Protect Crypto Services home page](https://www.ibm.com/cloud/hyper-protect-crypto).

High availability and disaster recovery
: IBM Cloud Hyper Protect Crypto Services, which now supports three availability zones in a selected region, is a highly available service with automatic features that help keep your applications secure and operational.

You can create Hyper Protect Crypto Services resources in the supported [IBM Cloud regions](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-regions), which represent the geographic area where your Hyper Protect Crypto Services requests are handled and processed.
Data encryption at rest 

Protecting data against unauthorized disclosure, modification or destruction throughout the data lifecycle is of paramount importance in the IBM Cloud for Financial Services. Cryptographic controls must be in place in all regions and availability zones to protect the confidentiality and integrity of data. Data at rest is to always be encrypted using your keys.



 Data encryption at rest in IBM Cloud 

Within IBM Cloud, you must use [Hyper Protect Crypto Services](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-overview) to manage encryption keys. Hyper Protect Crypto Services is a dedicated key management service and hardware security module (HSM). Hyper Protect Crypto Services is the only service in the cloud industry that is built on FIPS 140-2 Level 4-certified hardware.

With Hyper Protect Crypto Services you can take ownership of the cloud HSM to fully manage your encryption keys and to perform cryptographic operations by using [Keep Your Own Key (KYOK)](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-understand-conceptskyok-concept). This means you have full control and authority over encryption keys. No one except you (not even IBM) has access to your encryption keys.

You must ensure that:



* Keys are created for a single purpose, and dedicated encryption keys are unique per consumer.
* Keys have a lifecycle that is defined and are rotated periodically based on IBM Cloud Framework for Financial Services controls.
* Recovery functions, if used, can be accessed only by authorized personnel.





 Setting up Hyper Protect Crypto Services 



* Provision and configure an instance of Hyper Protect Crypto Services. See [Getting started with Hyper Protect Crypto Services](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-get-started) for specific instructions.



For the highest level of security, you should use smart cards when initializing Hyper Protect Crypto Services.
For more information, see [Base64 encoding your key material](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-import-standard-keysencode-key-material-standard-key). <br> <br>Ensure that the key material meets the following requirements: <br> <br>* The key can be up to 7,500 bytes. <br>* 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 true, the service designates the key as a standard key that you can store in your apps or services. 



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. For more examples of PII, see section 2.2 of the [NIST Special Publication 800-122](https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-122.pdf).

A successful POST /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 Hyper Protect Crypto Services key management service API.
3. Optional: Verify that the key was added by running the following call to get the keys in your Hyper Protect Crypto Services service instance.

curl -X GET 
https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys 
-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.
* CLI
* API







 Creating import tokens 

You can enable the secure import of root key material to the cloud by first creating an import token for your IBM Cloud® Hyper Protect Crypto Services service instance.

Import tokens are used to encrypt and securely bring root key material into Hyper Protect Crypto Services based on the policies that you specify. To learn more about importing your keys securely to the cloud, see [Bringing your encryption keys to the cloud](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-importing-keys).



 Creating an import token with the API 

Create an import token that's associated with your Hyper Protect Crypto Services service instance by making a POST call to the following endpoint.

https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/import_token



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. Set a policy for your import token by calling the [key management service API](https://cloud.ibm.com/apidocs/hs-crypto).

curl -X POST 
https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/import_token 
-H 'authorization: Bearer <IAM_token>' 
-H 'bluemix-instance: <instance_ID>' 
-H 'content-type: application/json' 
-d '{
"expiration": <expiration_time>, 
"maxAllowedRetrievals": <use_count> 
}'

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



Table 1. Describes the variables needed to create an import token with the API

 Variable Description 

 region Required.