vania-janet/multiturn-rag-retrieval-data huggingface dataset:
* [Protecting data integrity through message digests](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-grep11-api-refgrep11-operation-digest-data)
* [Code examples](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-grep11-api-refcode-example)









 CLI reference 

[Hyper Protect Crypto Services CLI change log](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-cli-change-logcli-change-log)



* [IBM Cloud TKE CLI plug-in](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-cli-change-logtke-cli-change-log)
* [IBM Cloud Hyper Protect Crypto Services certificate manager CLI plug-in](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-cli-change-logcert-manager-cli-change-log)
* [IBM Cloud Hyper Protect Crypto Services Unified Key Orchestrator CLI plug-in](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-cli-change-loguko-cli-change-log)







 Terraform reference 

[Provisioning and initializing service instances with Terraform](https://registry.terraform.io/providers/IBM-Cloud/ibm/latest/docs/resources/hpcs)

[Managing keys with Terraform - Key management service](https://registry.terraform.io/providers/IBM-Cloud/ibm/latest/docs/resources/kms_key)

[Managing keys with Terraform - Unified Key Orchestrator](https://registry.terraform.io/providers/IBM-Cloud/ibm/latest/docs/resources/hpcs_managed_key)





 Regions and locations
Before you can use the Schnorr algorithm, make sure to enable this feature by following the instructions in [Enabling the Schnorr algorithm](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-enable-mechanismsenable-schnorr).





 31 January 2021 

Added: Support for a single-tenant KMIP adapter
: Hyper Protect Crypto Services now provides a single tenant KMIP adapter to manage the key distribution in the vSphere or vSAN environment. For more information, see [Configuring KMIP in Hyper Protect Crypto Services for key management and distribution](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-tutorial-kmip-vmware).





 31 December 2020 

Added: Managing the key create and import access policy
: After you set up your Hyper Protect Crypto Services instance, you can enable and update the key create and import access policy to control actions permissions for root keys and standard keys. For more information, see [Managing the key create and import access policy](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-manage-keyCreateImportAccess).

Added: Provisioning and managing service instances with the private-only network
: To achieve increased security, you can now limit the network access to your service instance to the private-only network. You can either [choose the allowed network when you provision the service instance](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-provision) or [update the network access policy after you set up the instance](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-managing-network-access-policies).

Before you [update the network access policy](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-managing-network-access-policies), you need to initialize the service instance first.
Site map 

Find what you are looking for in the compilation of topics that are available in this documentation set.



 Getting started 

[Getting started with IBM Cloud Hyper Protect Crypto Services](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-get-startedget-started)



* [Step 1: Initialize your service instance](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-get-startedinitialize-crypto-dashboard)
* [Step 2 (Standard Plan only): Manage your encryption keys with the key management service](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-get-startedmanage-data-key-dashboard)
* [Step 2 (Unified Key Orchestrator Plan only): Manage your encryption keys in a multicloud environment using Unified Key Orchestrator](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-get-startedmanage-uko-key-dashboard)
* [Step 3: Encrypt your data with cloud HSM](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-get-startedencrypt-data-hsm-dashboard)
* [Before you begin](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-get-startedget-started-prerequisites)
* [Step 1: Provision the service](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-get-startedprovision-service)
* [Step 2: Initialize your service instance](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-get-startedinitialize-crypto)
* [Identity and access management](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-shared-responsibilitiesiam-responsibilities)
* [Security and regulation compliance](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-shared-responsibilitiessecurity-compliance)
* [Disaster recovery](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-shared-responsibilitiesdisaster-recovery)







 High availability and disaster recovery 

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



* [Locations, tenancy, and availability](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-ha-dravailability)
* [In-region data redundancy and failover](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-ha-drdata-failover)
* [Cross-region disaster recovery](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-ha-drcross-region-disaster-recovery)







 Open-source licenses 

[Open-source licenses](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-open-source-licensesopen-source-licenses)



* [Hyper Protect Crypto Services notices and information](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-open-source-licensesnotice)
* [Hosting appliance notices and information](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-open-source-licenseshosting-appliance-notice)







 FAQs
(https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-faq-security-compliancefaq-hpcs-ibm-access)
* [How does IBM offer a unique and secure process for service initialization (key ceremony)?](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-faq-security-compliancefaq-hpcs-user-access)
* [What is a 140-2 FIPS Level 4 Certification and how can I validate it?](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-faq-security-compliancefaq-fips-level4-meaning)
* [What is the difference between FIPS 140-2 Level 1, 2, 3, and Level 4?](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-faq-security-compliancefaq-fips-levels)
* [How to understand the key hierarchy for Hyper Protect Crypto Services KYOK?](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-faq-security-compliancefaq-cryptographic-algorithms)

[How does EP11 differ from PKCS #11?](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-faq-security-compliancefaq-ep11-pkcs11)
* [What EP11 mechanisms are supported by the GREP11 functions?](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-faq-security-compliancefaq-EP11-mechanisms)
* [What compliance standards does Hyper Protect Crypto Services meet?](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-faq-security-compliancefaq-compliance-standards)
* [Can I monitor my service instance?]
* UI
* API







 Viewing associations between root keys and encrypted IBM Cloud resources 

You can view associations between root keys and other cloud resources, such as IBM Cloud Object Storage buckets, by using the IBM Cloud® Hyper Protect Crypto Services key management service API.

When you use a root key to protect at-rest data with envelope encryption, the cloud services that use the key can create a registration between the key and the resource that it protects. Registrations are associations between keys and cloud resources that help you get a full view of which encryption keys protect what data on IBM Cloud.



Table 1. Describes the benefits of key registration

 Benefit Description 

 Centralized view of protected resources As an administrator for your Hyper Protect Crypto Services instance, you want to quickly understand which cloud resources are protected by a root key. 
 Security and compliance As a security admin, you need a way to determine the risk that's involved with [destroying a root key](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-delete-keys). You want to examine which keys are actively protecting what data so that you can evaluate exposures based on your organization's security or compliance needs. 



Key registration is an extra feature that's available only if the cloud service enables it as part of the integration with Hyper Protect Crypto Services. To determine whether an [integrated service](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-integrate-services) supports key registration, see the service documentation for more information.



 Viewing protected resources with the console 

You can browse the registrations that are available between your Hyper Protect Crypto Services keys and cloud resources by using the Hyper Protect Crypto Services GUI.



 Viewing protected resources associated with your root key 



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. On the KMS keys page, use the Keys table to browse the keys in your service.
5.
Components and concepts - Unified Key Orchestrator Plan 

Before you can use IBM Cloud® Hyper Protect Crypto Services to manage encryption keys and protect data, learn the basic components and concepts of Hyper Protect Crypto Services.



 Key management service 

Learn concepts that are related to the Hyper Protect Crypto Services [key management feature](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-uko-overviewuko-key-management) to manage encryption keys. The list starts with the most fundamental concepts.



 Root keys 

Root keys, also known as customer root keys (CRKs), are primary resources in Hyper Protect Crypto Services. They are symmetric key-wrapping keys that are used as roots of trust for wrapping (encrypting) and unwrapping (decrypting) other data encryption keys (DEKs) that are stored in a data service. With Hyper Protect Crypto Services, you can create, store, and manage the lifecycle of root keys. Root keys that are created in Hyper Protect Crypto Services are symmetric 256-bit AES keys. Unlike a standard key, a root key can never leave the bounds of the Hyper Protect Crypto Services service. To learn more, see [Introduction to envelope encryption](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-uko-envelope-encryption) and [Manage your keys](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-get-startedmanage-keys).





 Standard keys 

Standard keys are another resources in Hyper Protect Crypto Services to directly encrypt and decrypt data. You can manage standard keys by following steps in [Manage your keys](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-get-startedmanage-keys).





 Data encryption keys 

Data encryption keys (DEKs) are cryptographic keys that you use for data encryption. They are provided by user-owned applications and are used to encrypt data stored in applications. Root keys that you manage in Hyper Protect Crypto Services serve as wrapping keys to protect DEKs.
"href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/templates?vault.id=5295ad47-2ce9-43c3-b9e7-e5a9482c362b&limit=20&offset=0"
},
"templates": [
{
"vault": {
"id": "5295ad47-2ce9-43c3-b9e7-e5a9482c362b",
"name": "Test Vault Name",
"href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/vaults/5295ad47-2ce9-43c3-b9e7-e5a9482c362b"
},
"id": "2014f3ba-87ea-4125-aa9f-95141ede04cf",
"version": 0,
"name": "AWS-KMS-TEMPLATE",
"key": {
"size": "256",
"algorithm": "aes",
"activation_date": "P5Y1M1W2D",
"expiration_date": "P1Y2M1W4D",
"state": "active"
},
"description": "AWS KMS key template description",
"created_at": "2022-03-09T11:00:53Z",
"updated_at": "2022-03-09T11:00:53Z",
"created_by": "IBMid-1308197YB4",
"updated_by": "IBMid-1308197YB4",
"keystores":
{
"group": "Production",
"type": "aws_kms"
}
Once you have an instance of Hyper Protect Crypto Services, you need to create a root key and note the CRN ([Cloud Resource Name](https://cloud.ibm.com/docs/account?topic=account-crn)) of that key. The CRN is sent in a header during bucket creation.

Before creating the bucket for use with Hyper Protect Crypto Services, review the [relevant guidance around availability and disaster recovery](https://cloud.ibm.com/docs/hs-crypto?hs-crypto-ha-dr).





 Create or add a key in Hyper Protect Crypto Services 

Navigate to your instance of Hyper Protect Crypto Services and [initialize the service instance](https://cloud.ibm.com/docs/services/hs-crypto?topic=hs-crypto-initialize-hsm). Once a [master key](https://cloud.ibm.com/docs/services/hs-crypto?topic=hs-crypto-initialize-hsmstep1-create-signature-keys) has been created, [generate or enter a root key](https://cloud.ibm.com/docs/services/hs-crypto?topic=hs-crypto-create-root-keys).





 Grant service authorization 

Authorize Hyper Protect Crypto Services for use with IBM COS:



1. Open your IBM Cloud dashboard.
2. From the menu bar, click Manage > Access (IAM).
3. In the side navigation, click Authorizations.
4. Click Create to create an authorization.
5. In the Source service menu, select Cloud Object Storage.
6. In the Source service instance menu, select the service instance to authorize.
7. In the Target service menu, select Hyper Protect Crypto Services.
8. In the Target service instance menu, select the service instance to authorize.
9. Enable the Reader role.
10. Click Authorize.







 Create a bucket
Configuring HashiCorp Vault 

You can configure HashiCorp Vault as a tool integration in your toolchain so that you can access and refer to securely stored secrets in a HashiCorp Vault server.

Before you configure the HashiCorp Vault tool integration for your toolchain, you need the authentication method and associated credentials with permission to access the HashiCorp Vault server that you want to connect to. For example, if the authentication_method is github, you must know your token credential. You also need to know the values for the server url, integration url, and secrets path. If the HashiCorp Vault server is bound to a specific port, include the port number in the server url. For example, https://192.168.0.100:8200.

The HashiCorp Vault tool integration supports only secrets references by name. If you want to use secrets references by CRN, you must use a [Secrets Manager tool integration](https://cloud.ibm.com/docs/ContinuousDelivery?topic=ContinuousDelivery-secretsmanager).

Configure HashiCorp Vault to securely manage secrets such as API keys and secrets that are part of your toolchain or delivery pipeline:



1. If you are configuring this tool integration as you are creating the toolchain, and a HashiCorp Vault tool integration exists within the template that you are configuring, click the HashiCorp Vault tab. Alternatively, in the More tools section, click HashiCorp Vault.
2. If you have a toolchain and are adding this tool integration to it, from the IBM Cloud console, click the menu icon ![hamburger icon](https://cloud.ibm.com/docs-content/v1/content/562806c0b18119f4d21cb66f5ae6d051634b4a16/ContinuousDelivery/images/icon_hamburger.svg) and select DevOps. On the Toolchains page, click the toolchain to open its Overview page.
* [30 April 2020](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-what-newhs-crypto-april2020)



* [Added: Hyper Protect Crypto Services adds support for EP11 private endpoints](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-what-newadded-private-endpoints-202004)
* [Added: Hyper Protect Crypto Services adds support for the Management Utilities](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-what-newadded-management-utilities-202004)
* [Updated: IBM Cloud service integration](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-what-newadded-service-integration-202004)



* [31 August 2019](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-what-newhs-crypto-August2019)



* [Added: Hyper Protect Crypto Services adds support for private endpoints](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-what-newadded-private-endpoints)
* [Added: Hyper Protect Crypto Services Cloud HSM now supports EP11 cryptographic operations over gRPC](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-what-newadded-EP11)
* [Added: Hyper Protect Crypto Services expands into the Frankfurt region](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-what-newadded-frankfurt-region)
* [Added: IBM Cloud service integration](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-what-newadded-service-integration)
Hyper Protect Crypto Services Integration 

The data that you store in IBM Cloud® Databases is encrypted by default by using randomly generated keys. If you need to control the encryption keys, you can Bring Your Own Key (BYOK) through [Hyper Protect Crypto Services](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-get-started), and use one of your own keys to encrypt your databases. Take note that Hyper Protect Crypto Services for IBM Cloud® Databases backups is not currently supported.

This document covers the integration of Hyper Protect Crypto Services (HPCS) with Cloud Databases, which includes Databases for DataStax,Databases for Elasticsearch, Databases for EnterpriseDB, Databases for etcd, Databases for MongoDB, Databases for PostgreSQL, Databases for Redis, IBM Cloud® Databases for MySQL, and Messages for RabbitMQ.

To get started, you need [Hyper Protect Crypto Services](https://cloud.ibm.com/catalog/services/hyper-protect-crypto-services) provisioned on your IBM Cloud account.



 Creating or adding a key in Hyper Protect Crypto Services 

Navigate to your instance of Hyper Protect Crypto Services and [generate or enter a key](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-get-started).





 Granting service authorization 

Authorize Hyper Protect Crypto Services for use with Cloud Databases deployments:



1. Open your IBM Cloud dashboard.
2. From the menu bar, click Manage > Access (IAM).
3. In the side navigation, click Authorizations.
4. Click Create.
5. In the Source service menu, select the service of the deployment. For example, Databases for PostgreSQL or Messages for RabbitMQ
6. In the Source service instance menu, select All instances.
7. In the Target service menu, select HPCS.
8. Select or retain the default value Account as the resource group for the Target Service
9.
* [Added: Using Terraform to initialize the Hyper Protect Crypto Services instance](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-what-newadd-terraform-automation)
* [Added: Using a signing service to manage signature keys for instance initialization](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-what-newadd-signing-service)



* [30 June 2021](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-what-newhs-crypto-june2021)



[Added: Authenticated PKCS #11 keystore](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-what-newadd-authenticated-pkcs11-keystore)
* [Added: Enabling cross-region recovery with failover crypto units](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-what-newadd-failover-crypto-units)
* [Added: Hyper Protect Crypto Services expands into the London region](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-what-newadd-london-region)



* [30 April 2021](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-what-newhs-crypto-april2021)



* [Added: Rotating your master key by using smart cards and the Management Utilities](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-what-newadd-master-key-rotation-smart-cards)
* [Updated: Restore key API and UI](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-what-newupdate-restore-key-api-ui)
Make sure that you're logged in to the correct region and resource group where the service instance locates with the following command:

ibmcloud target -r <region> -g <resource_group>

To find out the regions that Hyper Protect Crypto Services supports, see [Regions and locations](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-regions).





 What's next 

Depending on your business needs and security requirements, Hyper Protect Crypto Services provides you with three options to initialize your service instance. For detailed operation steps, see:



* [Initializing service instances by using recovery crypto units](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-initialize-hsm-recovery-crypto-unit)
* [Initializing service instances by using key part files](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-initialize-hsm)
* [Initializing service instances by using smart cards and the Management Utilities](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-initialize-hsm-management-utilities)
"href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/templates/2014f3ba-87ea-4125-aa9f-95141ede04cf"
},
{
"vault": {
"id": "5295ad47-2ce9-43c3-b9e7-e5a9482c362b",
"name": "Test Vault Name",
"href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/vaults/5295ad47-2ce9-43c3-b9e7-e5a9482c362b"
},
"id": "93777bca-baef-4070-b9b5-a2e6079df1b4",
"version": 0,
"name": "IBM-CLOUD-EXAMPLE-TEMPLATE",
"key": {
"size": "256",
"algorithm": "aes",
"activation_date": "P5Y1M1W2D",
"expiration_date": "P1Y2M1W4D",
"state": "active"
},
"description": "IBM CLOUD key template description",
"created_at": "2022-03-09T11:00:47Z",
"updated_at": "2022-03-09T11:00:47Z",
"created_by": "IBMid-1308197YB4",
"updated_by": "IBMid-1308197YB4",
"keystores":
{
"group": "Production",
"type": "ibm_cloud_kms"
}
],
The hashing algorithm that is used in the transient virtual server webhook is HMAC-SHA256, which is a keyed hashing algorithm. The key to use is the secret that was provided when the webhook was set up.
3. Encode the hashed canonical string to Base64.
4. Compare the resulting string to the signature in the 'Authorization' header.

Use a timing-attack safe string comparison function. If the strings don't match, don't accept the request.









 Anatomy of the reclaim-scheduled notification request payload 

The request that is sent from the transient virtual server webhook is like any HTTP request in that it has headers and a payload. The payload is a JSON formatted string in the following form.

Key names might not be listed as shown in the example.

{
'event': 'reclaim-scheduled',
'id': <string - that is the ID of the transient guest being reclaimed>,
'link': <string - link for an API call to return info about the guest being reaped>,
'serviceName': <string - name of the API service class>,
'time stamp': <integer - timestamp of when the reclaim was scheduled>
}





 Code examples for creating the HMAC signature 

Python:

 This assumes that the request headers are stored in a dictionary that are called headers and that the JSON
 content of the request was decoded into a dictionary called payload.

import base64
import hashlib
import hmac

secret = 'Your secret key'
canonical = 'POST' + headers['Content-Type'] + payload['id'] + payload['serviceName'] + payload['event'] 
+ payload['timestamp'] + headers['X-IBM-Nonce']
signature = base64.b64encode(hmac.new(secret, canonical, hashlib.sha256).hexdigest())
match_flag = hmac.compare_digest(headers['Authorization'], signature)

PHP: