vania-janet/multiturn-rag-retrieval-data huggingface dataset:
examplePolicyId = res.result.id;
console.log(JSON.stringify(res.result, null, 2));
})
.catch(err => {
console.warn(err)
});





 Assigning access to Hyper Protect Crypto Services by using Terraform 

The following example is for assigning the Writer role for your service instance:

Use <hs-crypto> for the service name.

resource "ibm_iam_user_policy" "policy" {
ibm_id = "test@example.com"
roles = ["Writer"]

resources {
service = "hs-crypto"
}
}

For more information, see [ibm_iam_user_policy](https://registry.terraform.io/providers/IBM-Cloud/ibm/latest/docs/resources/iam_user_policy).





 Managing access to multiple instances 

If you have multiple Hyper Protect Crypto Services instances in different accounts, you might need to leverage IBM Cloud enterprises to manage accounts and user access.



1. Create the enterprise hierarchy

With IBM Cloud enterprises, you can centrally manage multiple accounts and resources. You can create an enterprise hierarchy as needed by nesting account groups or accounts within the enterprise account. The access management to the enterprise and the child accounts is isolated to provide greater security. To learn how to create an enterprise and add accounts to an enterprise, see [Getting started with an enterprise](https://cloud.ibm.com/docs/account?topic=account-enterprise-tutorial) and [Best practices for setting up an enterprise](https://cloud.ibm.com/docs/account?topic=account-enterprise-best-practices).
2. Organize account resources in resource groups

Hyper Protect Crypto Services instances are associated with child accounts of the enterprise. Within each account, you can organize service instances in resource groups so that you can assign different access policies to each resource group to enable independent access control.
For a tutorial on how to offload the SSL workload to a load balancer such as NGINX while managing keys by using Hyper Protect Crypto Services, see [Using IBM Cloud Hyper Protect Crypto Services to offload NGINX TLS](https://developer.ibm.com/components/ibmz/tutorials/use-hyper-protect-crypto-services-to-offload-nginx-tls/).

Zoom

![Protecting data in transit with TLS/SSL offloading](https://cloud.ibm.com/docs-content/v1/content/217f108cc44e2ce15fb692d4b57b4c628464e908/hs-crypto//images/ssl-offloading.svg)

Figure 6. Protecting data in transit with TLS/SSL offloading







 Using Hyper Protect Crypto Services as Enterprise PKCS 11 HSMs 

Hyper Protect Crypto Services provides the

[Enterprise PKCS #11 (EP11) API](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-grep11-api-ref). Cloud application can use this function through [gRPC](https://grpc.io).

Enterprise PKCS #11 supports stateless cryptography use cases and allows for scaling and redundancy in an enterprise environment. For some use cases around asset protection, the keys can be managed outside the cryptographic service, while all sensitive operations are executed within the HSM boundary. You can use Enterprise PKCS #11 when state handling is an issue, especially for enterprise applications that benefit from the stateless character of Enterprise PKCS #11.

You as a cloud developer can use standard interfaces from your applications for cryptographic operations with data integrity and confidentiality. Hyper Protect Crypto Services supports secure connectivity from cloud application to cloud HSM, and allows for enterprise control of Cloud HSM for application keys.

As IBM is starting to provide a new set of capabilities to support your workloads to move to the cloud, you can benefit from the cryptographic capabilities of Hyper Protect Crypto Services for both your new and existing workloads.
Provisioning and initializing the Hyper Protect Crypto Services service 

Before you deploy this deployable architecture, you need an instance of the Hyper Protect Crypto Services service.



1. You can provision Hyper Protect Crypto Services in one of two ways:



* By using the [IBM Cloud Hyper Protect Crypto Services](https://github.com/terraform-ibm-modules/terraform-ibm-hpcs) Terraform module.
* By creating and initializing an instance directly.



1. (Optional) [Create a resource group](https://cloud.ibm.com/docs/account?topic=account-rgs&interface=ui) for your instance.
2. On the Hyper Protect Crypto Services [details page](https://cloud.ibm.com/catalog/services/hyper-protect-crypto-services), select a plan.
3. Complete the required details and click Create.





2. Initialize Hyper Protect Crypto Services:



* If you used the IBM Cloud Hyper Protect Crypto Services module, follow the steps in the module [readme file](https://github.com/terraform-ibm-modules/terraform-ibm-hpcscreate-hyper-protect-crypto-services-instance).
* If you created the instance directly, follow the steps in [Getting started with IBM Cloud Hyper Protect Crypto Services](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-get-started).



For proof-of-technology environments, use the auto-init flag. For more information, see [Initializing service instances using recovery crypto units](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-initialize-hsm-recovery-crypto-unit).
3. When you configure your deployable architecture, specify the resource group in the hs_crypto_resource_group input value and the instance name in the hs_crypto_instance_name value. If you don't provide those values, the default Key Protect encryption is used.
hs-crypto.keystore.listkeystoresbyids View EP11 keystores. 
 hs-crypto.keystore.storenewkey Store an EP11 key. 
 hs-crypto.keystore.updatekey Update an EP11 key. 







 EP11 crypto events 

The following table lists the EP11 crypto actions that generate an event:



Table 11. EP11 crypto actions

 Action Description 

 hs-crypto.ep11.use Cryptographic operation 









 Viewing events 

Events that are generated by an instance of Hyper Protect Crypto Services are automatically forwarded to the IBM Cloud Activity Tracker service instance that is available in the same location.

IBM Cloud Activity Tracker can have only one instance per location. To view events, you must access the web UI of the IBM Cloud Activity Tracker service in the same location where your service instance is available. For more information, see [Launching the web UI through the IBM Cloud UI](https://cloud.ibm.com/docs/activity-tracker?topic=activity-tracker-launchlaunch_cloud_ui).



Table 12. Activity Tracker regions

 Deployment Region Activity Tracker Region 

 au-syd au-syd 
 br-sao br-sao 
 ca-tor ca-tor 
 eu-de eu-de 
 eu-gb eu-gb 
 jp-tok jp-tok 
 us-east us-east 
 us-south us-south 







 Analyzing successful events 

Most successful requests have unique requestData and responseData associated with each related event. The following sections describe the data of each Hyper Protect Crypto Services service action event.

Fields are not guaranteed to appear unless the request is successful.



 Common fields 

Some common fields are available for Hyper Protect Crypto Services to use outside of the CADF event model to provide more insight into your data.



Table 13. Common fields in Activity Tracker events for Hyper Protect Crypto Services service actions

 Field Description 

 requestData.requestURI The URI of the API request that was made. 
 requestData.instanceID The unique identifier of your Hyper Protect Crypto Services service instance. 
 correlationId The unique identifier of the API request that generated the event.
If you want to encrypt the OSD volumes (cluster wide encryption) used by the ODF system pods, select Enable cluster encryption.
13. If you want to enable encryption for the application volumes (app storage), select Enable volume encryption.



1. In the Instance name field, enter a unique name for your Hyper Protect Crypto Services or Key Protect instance.
2. In the Instance type field, enter the type of encryption instance.
3. In the Instance ID field, enter your Hyper Protect Crypto Services or Key Protect instance ID. For example: d11a1a43-aa0a-40a3-aaa9-5aaa63147aaa.
4. In the Secret name field, enter the name of the secret that you created using your Hyper Protect Crypto Services or Key Protect credentials. For example: ibm-hpcs-secret.
5. In the Base URL field, enter the public endpoint of your Hyper Protect Crypto Services or Key Protect instance. For example: https://api.eu-gb.hs-crypto.cloud.ibm.com:8389.
6. In the Token URL field, enter https://iam.cloud.ibm.com/identity/token.



14. After you enter the parameters that you want to use, click Install
15. Wait a few minutes for the add-on deployment to complete. When the deployment is complete, the add-on status is Normal - Addon Ready.
16. Verify your installation. [Access your Red Hat OpenShift cluster](https://cloud.ibm.com/docs/openshift?topic=openshift-access_cluster).
17. Run the following command to verify the ODF pods are running.

oc get pods -n openshift-storage



Next steps
: [Deploy an app that uses ODF](https://cloud.ibm.com/docs/openshift?topic=openshift-odf-deploy-app).





 Installing the add-on from the CLI
FAQs: High availability and disaster recovery 

Read to get answers for high-availability and disaster-recovery related questions about IBM Cloud® Hyper Protect Crypto Services.



 How do I set up a high availability configuration? 

It is suggested that you provision at least two crypto units for high availability. In this way, there is always at least one extra crypto unit operating in a crypto unit failure. Hyper Protect Crypto Services is built to provide high availability by default.

For more information, see [High availability and disaster recovery](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-ha-dr).





 Can I back up my service instance manually? 

You need to back up only your master key parts and signature keys for service initialization. Your data in Hyper Protect Crypto Services is backed up automatically by IBM Cloud daily.





 What happens if my service instance fails? 

IBM Cloud has automatic in-region failover plan in place. Currently, your data is backed up daily by the service and you don't need to do anything to enable it. For [cross-region data restores](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-ha-dr), you need to open an IBM support ticket so that IBM can restore the service instance for you.





 How can I restore the content from backups? 

For cross-region data restores of Standard Plan instances, you can restore your data by using failover crypto units or open an IBM support ticket so that IBM can restore the service instance for you. For more information, see [Restoring your data from another region](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-restore-data).

For the plan with Unified Key Orchestrator, currently you can only open an IBM support ticket so that IBM can restore the service instance.





 What happens if I delete my service instances? 

If you delete your service instance, your keys that are managed are not accessible.





 Can I back up the keys before I delete a service instance? 

Backing up the keys manually is not supported.
[PKCS #11 API](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-pkcs11-api-ref), and [GREP11 API](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-grep11-api-ref).

Public

Private



Table 1. Lists public endpoints for interacting with Hyper Protect Crypto Services APIs over IBM Cloud's public network

 Region Public key management service endpoints Public Unified Key Orchestrator service endpoints Public GREP11 service endpoints 

 Dallas api.us-south.hs-crypto.cloud.ibm.com uko.us-south.hs-crypto.cloud.ibm.com ep11.us-south.hs-crypto.cloud.ibm.com 
 Frankfurt api.eu-de.hs-crypto.cloud.ibm.com uko.eu-de.hs-crypto.cloud.ibm.com ep11.eu-de.hs-crypto.cloud.ibm.com 
 London api.eu-gb.hs-crypto.cloud.ibm.com uko.eu-gb.hs-crypto.cloud.ibm.com ep11.eu-gb.hs-crypto.cloud.ibm.com 
 Sydney api.au-syd.hs-crypto.cloud.ibm.com uko.au-syd.hs-crypto.cloud.ibm.com ep11.au-syd.hs-crypto.cloud.ibm.com 
 Tokyo api.jp-tok.hs-crypto.cloud.ibm.com uko.jp-tok.hs-crypto.cloud.ibm.com ep11.jp-tok.hs-crypto.cloud.ibm.com 
 Washington DC api.us-east.hs-crypto.cloud.ibm.com uko.us-east.hs-crypto.cloud.ibm.com ep11.us-east.hs-crypto.cloud.ibm.com
[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?](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-faq-ukofaq-uko-functions)
* [Is Unified Key Orchestrator a separate offering?](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-faq-ukofaq-uko-offering)
* [How is Hyper Protect Crypto Services with Unified Key Orchestrator different from the Hyper Protect Crypto Services Standard Plan?](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-faq-ukofaq-uko-hpcs)
* [What type of HSM is used for Hyper Protect Crypto Services with Unified Key Orchestrator?](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-faq-ukofaq-uko-fips)
* [Which cloud vendors or providers are supported by Hyper Protect Crypto Services with Unified Key Orchestrator as connected external keystores?](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-faq-ukofaq-uko-vendor-cloud)
* [How is Unified Key Orchestrator different from EKMF Web?](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-faq-ukofaq-uko-ekmf)
* [Step 4: Delete your service instance](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-delete-instancedelete-instance-step)







 Restoring your data from another region 

[Restoring your data from another region](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-restore-datarestore-data)



* [Restoring your data by using failover crypto units](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-restore-datarestore-data-failover-crypto-units)
* [Restoring your data by opening an IBM support ticket](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-restore-datarestore-data-open-support-ticket)
* [What's next](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-restore-datarestore-data-next)







 Enhancing security - Standard Plan only 

[Managing user access](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-manage-accessmanage-access)



* [Roles and permissions](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-manage-accessroles)
* [Managing access to multiple instances](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-manage-accessmanage-multiple-instances)
* [What's next](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-manage-accessmanage-access-next)



[Granting access to keys](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-grant-access-keysgrant-access-keys)
Service architecture - Standard Plan 

Review the service architecture, workload isolation characteristics, and service dependencies for IBM Cloud® Hyper Protect Crypto Services.



 Hyper Protect Crypto Services architecture 

The following architecture diagram shows how you interact with Hyper Protect Crypto Services components to protect your sensitive data and keys.

Zoom

![Service instance components](https://cloud.ibm.com/docs-content/v1/content/217f108cc44e2ce15fb692d4b57b4c628464e908/hs-crypto//images/hs-crypto-components-new.svg)

Figure 1. Interaction with Hyper Protect Crypto Services components

The following list explains each component in detail.

Key management service API
: The API that you use to interact with the key management service (KMS) module to manage root keys and standard keys.

PKCS #11 API
: The industry standard API to perform cryptographic operations. Hyper Protect Crypto Services implements API functions with the PKCS #11 library that interacts with the Enterprise PKCS #11 (EP11) module in the cloud HSM.

GREP11 API
: The abbreviation of Enterprise PKCS #11 over gRPC API. It is a stateless interface for cryptographic operations, which also leverages the EP11 module in the cloud HSM.

Management Utilities
: The Management Utilities are composed of the Smart Card Utility Program and the Trusted Key Entry (TKE) application, which provide GUI for you to initialize service instances. With signature keys and master key parts that are stored on smart cards, the Management Utilities provide an approach to initializing service instances with the highest level of security.

TKE CLI plug-in
: A CLI plug-in working with IBM Cloud CLI for you to initialize service instances. Depending on whether recovery crypto units are assigned to your instance, the plug-in provides two ways for instance initialization: by using recovery crypto units and by using key part files.

Operational crypto unit
: Each service instance is composed of multiple operational crypto units. The operational crypto units are located in different availability zones of the same region for high availability.
* [What's next](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-uko-introduce-serviceuko-introduce-instance-initialization-next)



[Introducing service instance initialization approaches - Unified Key Orchestrator Plan](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-uko-initialize-instance-modeuko-initialize-instance-mode)



* [Initializing service instances by using smart cards and the Management Utilities](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-uko-initialize-instance-modeuko-instance-initialization-management-utilities)
* [Initializing service instances by using recovery crypto units](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-uko-initialize-instance-modeuko-instance-initialization-recovery-crypto-unit)
* [Initializing service instances by using key part files](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-uko-initialize-instance-modeuko-instance-initialization-key-files)
* [What's next](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-uko-initialize-instance-modeuko-initialize-instance-mode-next)







 About Unified Key Orchestrator 

[Introducing Unified Key Orchestrator](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-introduce-ukointroduce-uko)



* [Use case example](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-introduce-ukouko-use-case-example)
* [Components](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-introduce-ukoComponents)
When you make an API call to the service, structure your API request according to how you initially provisioned your instance of Hyper Protect Crypto Services.

To build your request, pair a [regional service endpoint](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-regions) with the appropriate authentication credentials. For example, if you created a service instance for the us-south region, use the following endpoint and API headers to browse keys in your service:

curl --location --request GET 'https://uko.<region>.hs-crypto.cloud.ibm.com:<port>/api/v4/managed_keys' 
--header 'Authorization: Bearer <access_token>' 
--header 'Content-Type: application/json' 
--header 'Accept: application/json' 
--header 'UKO-Vault: <vault_id>'



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

Note that the port range of a Hyper Protect Crypto Services instance is between 8000 - 19999.
* Replace <access_token> with your retrieved service and authentication credentials.
* Replace <vault_id> with the ID of the vault that your keys are assigned to.



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 [Unified Key Orchestrator API reference doc](https://cloud.ibm.com/apidocs/uko).
"DOCKER_REPO": "secureimages/secure-bitcoin-wallet",
"DOCKER_USER": "iamapikey",
"DOCKER_PASSWORD": "<your api key>",
"DOCKER_RO_USER": "iamapikey",
"DOCKER_RO_PASSWORD": "<your api key>",
"DOCKER_CONTENT_TRUST_BASE": "False",
"DOCKER_CONTENT_TRUST_BASE_SERVER": "",
"DOCKER_BASE_SERVER": "docker.io",
"DOCKER_PUSH_SERVER": "us.icr.io",
"DOCKER_CONTENT_TRUST_PUSH_SERVER": "https://us.icr.io",
"ENV_WHITELIST": ["ZHSM", "APIKEY", "INSTANCE_ID", "IAM_ENDPOINT"],
"ARG": {
"NO_GRPC_BUILD": "1",
"ACCESS_TOKEN": ""
}
}
Show more

This file defines the configuration for your Secure Build Server instance, which you create in the next steps.

Notes:



* The property HOSTNAME of the SBS server which will be used while generating certificates and communicating with the secure build server.
* The property GITHUB_KEY_FILE specifies the key file (on your workstation) that contains the SSH key for your GitHub account.
* The property DOCKER_REPO identifies the namespace (which you created in step 1) and the container image name to be used. Specify a value that is not used or allocated in your container registry.
* Specify the value of the API key that is created in step 1 for both properties DOCKER_PASSWORD and DOCKER_RO_PASSWORD.
* Specify the value of your personal access token for the property ACCESS_TOKEN. The build process uses a personal access token for github.com to avoid a build failure due to its access rate limit.
Rewrapping data encryption keys with root keys 

Reencrypt your data encryption keys by using the IBM Cloud® Hyper Protect Crypto Services key management service API.

When you [rotate a root key in Hyper Protect Crypto Services](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-root-key-rotation-intro), new cryptographic key material becomes available for protecting the data encryption keys (DEKs) that are associated with the root key. With the rewrap API, you can reencrypt or rewrap your DEKS without exposing the keys in their plain text form.

To learn how envelope encryption helps you control the security of at-rest data in the cloud, see [Protecting data with envelope encryption](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-envelope-encryption).



 Rewrapping keys by using the API 

You can reencrypt a specified data encryption key (DEK) with a root key that you manage in Hyper Protect Crypto Services, without exposing the DEK in the plain text form.

Rewrapping keys works by combining unwrap and wrap calls to the service. For example, you can emulate a rewrap operation by first calling the unwrap API to access a DEK, and then calling the wrap API to reencrypt the DEK by using the newest root key material.

[After you rotate a root key in the service](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-rotate-keys), rewrap a data encryption key that is associated with the root key by making a POST call to the following endpoint.

https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>/actions/rewrap



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.