vania-janet/multiturn-rag-retrieval-data huggingface dataset:
Performing cryptographic operations by accessing the cloud HSM 

Hyper Protect Crypto Services provides a set of cryptographic functions that are executed in the cloud HSM. You can perform cryptographic operations such as key generation, data encryption, and signature verification. To do so, access the cloud HSM with either the PKCS #11 API or the Enterprise PKCS #11 over gRPC (GREP11) API.



 Accessing the cloud HSM with the PKCS 11 API 

[Public-Key Cryptography Standards (PKCS) #11](http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/os/pkcs11-base-v2.40-os.html) is an industry standard that defines a platform-independent API, called Cryptoki, for devices such as HSMs that hold cryptographic information and perform cryptographic operations. With Hyper Protect Crypto Services, you can use the standard PKCS #11 API to access the cloud HSM with the PKCS #11 library. The library connects your applications to the cloud HSM to perform cryptographic operations.

With the support of the PKCS #11 API, you don't need to change your existing applications that use the PKCS #11 standard. The PKCS #11 library accepts the PKCS #11 API requests from your applications and remotely accesses the cloud HSM to execute the corresponding cryptographic functions. For more information about the PKCS #11 API, see

[Introducing PKCS #11](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-uko-pkcs11-intro).





 Accessing the cloud HSM with the GREP11 API 

In addition to the PKCS #11 API, you can also use the Enterprise PKCS #11 over gRPC (GREP11) API to access the Hyper Protect Crypto Services cloud HSM.
: You can now create Hyper Protect Crypto Services instances in the London (eu-gb) region where the infrastructure is based on IBM Cloud Virtual Private Cloud (VPC). For more information, see [Regions and locations](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-regions).





 30 April 2021 

Added: Rotating your master key by using smart cards and the Management Utilities
: Besides rotating your master key [using key part files](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-rotate-master-key-cli-key-part) and [using recovery crypto units](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-rotate-master-key-cli-recovery-crypto-unit), you can now also rotate the master key if you are using smart cards and the Management Utilities.

For detailed instructions, see [Rotating master keys by using smart cards and the Management Utilities](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-rotate-master-key-smart-cards). For more information about how master key rotation works, see [Rotating master keys by using key part files](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-master-key-rotation-introhow-master-key-rotation-works-use-key-parts).

Updated: Restore key API and UI
: Now you can restore keys that were deleted within 30 days without providing any key materials. All root keys and standard keys, whether generated by Hyper Protect Crypto Services or imported by you, can be restored. For more information, see [Restoring keys](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-restore-keys).





 31 March 2021 

Added: Grouping keys by using key rings
: You can now group the keys in your Hyper Protect Crypto Services instance by creating a key ring. In this case, you can manage keys and control access at the key ring level.
For more information about gRPC, see [the gRPC documentation](https://grpc.io/docs/guides/index.html).





 Enterprise PKCS 11 over gRPC 

IBM Cloud® Hyper Protect Crypto Services provides a set of the Enterprise PKCS #11 (EP11) over [gRPC](https://grpc.io) API calls (also referred to as GREP11), with which all the Crypto functions are executed in a cloud HSM. EP11 over gRPC is a stateless interface for cryptographic operations on cloud. For more information about the GREP11 API, see [Introducing EP11 over gRPC](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-uko-grep11-intro) and [GREP11 API reference](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-grep11-api-ref).







 Unified Key Orchestrator 

This section covers concepts that are related to [Unified Key Orchestrator](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-introduce-uko).



 Unified Key Orchestrator 

Unified Key Orchestrator is a public cloud control plane for multicloud and hybrid cloud key orchestration. As part of the IBM Cloud® Hyper Protect Crypto Services, it provides key lifecycle management according to NIST recommendations and secure transfer of keys to internal keystores and external keystores.





 Vault 

A vault is a single repository that controls a user's or an access group's access to keys and keystores through Identity and Access Management (IAM). A managed key or internal keystore can be created only in a vault. When you connect to an external keystore, you need to assign it to a vault. To use a managed key for encryption and decryption, you need to install it in one or more keystores within the same vault. The vault keeps all installations of a managed key in sync.





 Managed key 

A managed key is a key that is created in and assigned to a vault.
Security <br><br> * [Hyper Protect Crypto Services](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-ha-dr)<br><br><br> <br><br> * [Hyper Protect Crypto Services](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-ha-dr)<br><br><br> <br><br> * [App ID](https://cloud.ibm.com/docs/appid?topic=appid-ha-dr)<br><br><br> 
 Logging and monitoring <br><br> * [Activity Tracker Event Routing](https://cloud.ibm.com/docs/activity-tracker?topic=activity-tracker-ha-dr)<br> * [Security and Compliance Center](https://cloud.ibm.com/docs/security-compliance?topic=security-compliance-ha-dr)<br> * [Flow Logs for VPC](https://cloud.ibm.com/vpc?topic=vpc-ha-dr-vpc)<br><br><br> <br><br> * [Activity Tracker Event Routing](https://cloud.ibm.com/docs/activity-tracker?topic=activity-tracker-ha-dr)<br> * [Security and Compliance Center](https://cloud.ibm.com/docs/security-compliance?topic=security-compliance-ha-dr)<br><br><br> 
 Integration <br><br> * [Event Streams](https://cloud.ibm.com/docs/EventStreams?topic=EventStreams-sla)<br><br><br>
[FAQs: Pricing](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-faq-pricingfaq-pricing)



* [How am I charged for my use of Hyper Protect Crypto Services standard plan?](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-faq-pricingfaq-how-charge-hpcs)
* [How am I charged for my use of Hyper Protect Crypto Services with Unified Key Orchestrator?](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-faq-pricingfaq-how-charge-hpcs-uko)
* [Is there a free trial for Hyper Protect Crypto Services?](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-faq-pricingfaq-free-trial)



[FAQs: Provisioning and operations](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-faq-provisioning-operationsfaq-provisioning-operations)



* [Are there any prerequisites for using Hyper Protect Crypto Services?](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-faq-provisioning-operationsfaq-hpcs-prerequisites)
* [How to initialize Hyper Protect Crypto Services service instances?](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-faq-provisioning-operationsfaq-how-to-initialize)
* [Can I initialize my service instance through the TKE CLI plug-in by using a proxy?](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-faq-provisioning-operationsfaq-tke-proxy)
* [Are there any recommendations on how to set up smart cards?]
Hyper Protect Crypto Services supports the Keep Your Own Key (KYOK) feature. You can configure the master key to take the full control of the cloud HSM, so that you have full control and authority over encryption keys that you can bring, control, and manage. No one except you have access to your encryption keys.





 PKCS 11 

Public-Key Cryptography Standards (PKCS) #11 API defines a platform-independent API to cryptographic tokens, such as HSM and smart cards. Existing applications that use PKCS #11 can benefit from enhanced security by using secure key cryptography and stateless interface, which makes the cryptographic operations much more efficient. For more information, see

[PKCS #11 API](http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/os/pkcs11-base-v2.40-os.html).





 Cryptoki 

The Cryptographic Token Interface defined in the PKCS #11 standard. Cryptoki follows a simple object based approach, addressing the goals of technology independence and resource sharing.





 PKCS 11 library 

A PKCS #11 library that implements the Cryptoki API functions that are specified in the PKCS #11 standard. With the PKCS #11 library, your applications can use the PKCS #11 API to access the Hyper Protect Crypto Services cloud HSM to perform cryptographic operations. To learn more about how to set up the library, see

[Performing cryptographic operations with the PKCS #11 API](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-set-up-pkcs-api).





 Cryptoki token 

The logical view of a cryptographic device that is defined by Cryptoki. For more information, see
Mech: &pb.Mechanism{Mechanism: ep11.CKM_SHA256},
Data: digestData,
}

DigestSingleResponse, err := cryptoClient.DigestSingle(context.Background(), DigestSingleRequest)
* JavaScript code snippet

client.DigestSingle({
Mech: {
Mechanism: ep11.CKM_SHA256
},
Data: Buffer.from(digestData)
}, (err, response) => {
callback(err, response);
});









 Code examples 

GREP11 API supports programming languages with [gRPC libraries](https://www.grpc.io/docs/). Two sample GitHub repositories are provided for you to test the GREP11 API:



* [The sample GitHub repository for Golang](https://github.com/IBM-Cloud/hpcs-grep11-go)
* [The sample GitHub repository for JavaScript](https://github.com/IBM-Cloud/hpcs-grep11-js)
The region abbreviation, such as us-south or eu-de, that represents the geographic area where your Hyper Protect Crypto Services service instance resides. 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 want to create a rotation policy for. 
 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 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. 
 rotation_interval Required. An integer value that determines the key rotation interval time in months. The minimum is 1 and the maximum is 12. 



A successful PUT api/v2/keys/{id}/policies response returns policy details that are associated with your key. The following JSON object shows an example response for a root key that has an existing rotation policy.

{
"metadata": {
"collectionTotal": 1,
"collectionType": "application/vnd.ibm.kms.policy+json"
},
"resources": [
{
"id": "a1769941-9805-4593-b6e6-290e42dd1cb5",
"rotation": {
"interval_month": 1
},
Go to your instance of Hyper Protect Crypto Services and [create a root key](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-create-root-keys) or [import an existing root key](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-import-root-keys).







 Step 2. Grant service authorization 

Authorize Hyper Protect Crypto Services for use with Hyper Protect DBaaS for MongoDB service instances:



1. Go to the IBM Cloud console.
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 Hyper Protect DBaaS for MongoDB.
6. In the Source service instance menu, select All service instances.
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.



If you want to remove an authorization, see [Removing access](https://cloud.ibm.com/docs/account?topic=account-assign-access-resourcesremoving-access-console).





 Step 3. Create a Hyper Protect DBaaS for MongoDB instance with the Hyper Protect Crypto Services Key 

When you [create a Hyper Protect DBaaS for MongoDB service instance](https://cloud.ibm.com/docs/hyper-protect-dbaas-for-mongodb?topic=hyper-protect-dbaas-for-mongodb-gettingstartedcreating-a-database-cluster-introduction), select your Hyper Protect Crypto Services instance and root key.

The new Hyper Protect DBaaS for MongoDB service instance uses your Hyper Protect Crypto Services root key to protect your data encryption key.
You manage the lifecycle of your keys and benefit as your keys are secured by FIPS140-2 Level 3 certified cloud-based hardware security modules (HSMs) that protects from information theft.

Hyper Protect Crypto Services is a single-tenant, dedicated HSM that is controlled by you. The service is built on FIPS 140-2 Level 4-certified hardware, the highest offered by any cloud provider in the industry. To get started, you need to provision a Key Protect instance or a Hyper Protect Crypto Services instance on your IBM Cloud account.





 Creating or adding a key in the key management service 



1. To add a key in Key Protect, go to your instance of Key Protect and generate or enter a key.
2. To add a key in Hyper Protect Crypto Services, navigate to your instance ofHyper Protect Crypto Services(HPCS) and generate a key.





 Regions offered 

The chart that follows, shows which keys can be used in which region.



Table 1. Regions - IBM

 watsonx.data Regions (IBM) Key Protect Region Available HPCS Region Available 

 Dallas (US-South) US-South US-South 
 Washington (US-East) US-South US-East 





Table 1. Regions - AWS

 watsonx.data Regions (AWS) Key Protect Region Available HPCS Region Available 

 N. Virginia (US-East-1) US-South US-East 
 Oregon (US-West-2) US-South US-South 
 Frankfurt (EU-Central-1) EU-DE N/A 









 Granting service authorization 

Authorize Key Protect for use with watsonx.data deployments:



1. Open your IBM Cloud dashboard.
2. From the menu bar, select Manage > Access (IAM).
3. In the side navigation, select Authorizations. Click Create.
4. In the Source service menu, select the service of the deployment. For example, watsonx.data.
5. In the Source service instance menu, select All service instances.
6. In the Target service menu, select Key Protect or Hyper Protect Crypto Services.
7.
<br><br> * hs-crypto.managed-keys.preactivation-activate<br> * hs-crypto.managed-keys.preactivation-destroy<br> * hs-crypto.managed-keys.active-deactivate<br> * hs-crypto.managed-keys.active-install<br> * hs-crypto.managed-keys.active-uninstall<br> * hs-crypto.managed-keys.deactivated-install<br> * hs-crypto.managed-keys.deactivated-reactivate<br> * hs-crypto.managed-keys.deactivated-uninstall<br> * hs-crypto.managed-keys.read<br> * hs-crypto.managed-keys.list<br> * hs-crypto.managed-keys.write<br> * hs-crypto.managed-keys.distribute<br> * hs-crypto.managed-keys.write-dates<br> * hs-crypto.managed-keys.write-tags<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.vaults.read<br> * hs-crypto.vaults.list<br><br><br> 
 My reader Performs read-only actions for auditing purposes. <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.key-templates.read<br> * hs-crypto.key-templates.list<br> * hs-crypto.vaults.read<br> * hs-crypto.vaults.list<br><br><br> 



8. Click Create after you select the appropriate actions for your custom role.







 Step 2: Assign IAM roles to users
* [Rotating root keys with the API](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-rotate-keysrotate-root-key-api)
* [What's next](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-rotate-keysrotate-key-next)



[Viewing root key versions](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-view-key-versionsview-key-versions)



* [Viewing root key versions with the key management service API](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-view-key-versionsview-key-versions-api)



[Disabling root keys](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-disable-keysdisable-keys)



* [Disabling and enabling root keys with the console](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-disable-keysdisable-enable-ui)
* [Disabling and enabling root keys with the API](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-disable-keysdisable-enable-api)



[About deleting and purging keys](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-delete-purge-keysdelete-purge-keys)



* [Considerations before you delete and purge a key](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-delete-purge-keysdelete-purge-keys-considerations)
* [What's next](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-delete-purge-keysdelete-purge-keys-next)
Data: msgHash[:],
}

// Sign the data
SignResponse, err := cryptoClient.Sign(context.Background(), SignRequest)
* JavaScript code snippet

client.Sign({
State: state,
Data: dataToSign
}, (err, data={}) => {
cb(err, data.Signature);
});







 SignUpdate 

The SignUpdate function continues a multiple-part signature operation. Before you call this function, make sure to run SignInit first.

Enterprise PKCS #11 over gRPC

Enterprise PKCS #11

PKCS #11





 Description Binds to EP11 m_SignUpdate, which is an implementation of PKCS #11 C_SignUpdate. 
 Parameters message SignUpdateRequest { bytes State = 1; bytes Data = 2; } message SignUpdateResponse { bytes State = 1; } 
 Return values Wraps EP11 error into message Grep11Error. 



Code snippets



* Golang code snippet

// Use SignUpdate if you would like to breakup
// the sign operation into multiple suboperations
SignUpdateRequest1 := &pb.SignUpdateRequest {
State: SignInitResponse.State,
Data: msgHash[:16],
}

SignUpdateResponse, err := cryptoClient.SignUpdate(context.Background(), SignUpdateRequest1)

SignUpdateRequest2 := &pb.SignUpdateRequest {
State: SignUpdateResponse.State,
Data: msgHash[16:],
}

SignUpdateResponse, err := cryptoClient.SignUpdate(context.Background(), SignUpdateRequest2)
* JavaScript code snippet

client.SignUpdate({
State: state,
Data: digest
}, (err, response) => {
Optional: Enter a succinct and helpful description that helps the users who are assigning access know what level of access this role assignment gives a user. This description also shows in the console when you assign access to the service.
6. From the list of services, select Hyper Protect Crypto Services.
7. Select Add to add actions for the role. The following table lists the actions that correspond to the EP11 keystore or key operations with the console:



Table 1. Actions corresponding to the EP11 keystore or key operations with the console

 Operations Actions 

 View EP11 keystores. <br><br> * hs-crypto.keystore.listkeystoresbyids<br><br><br> 
 Create EP11 keystores. <br><br> * hs-crypto.keystore.listkeystoresbyids<br> * hs-crypto.keystore.createkeystore<br><br><br> 
 Delete EP11 keystores. <br><br> * hs-crypto.keystore.listkeystoresbyids<br> * hs-crypto.keystore.deletekeystore<br><br><br> 
 View EP11 keys. <br><br> * hs-crypto.keystore.listkeystoresbyids<br> * hs-crypto.keystore.listkeysbyids<br><br><br> 
 Create EP11 keys. <br><br> * hs-crypto.keystore.listkeystoresbyids<br> * hs-crypto.keystore.listkeysbyids<br> * hs-crypto.crypto.generatekey<br> * hs-crypto.crypto.generatekeypair<br> * hs-crypto.keystore.storenewkey<br><br><br> 
 View EP11 keys.
"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"
}
],
"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",
<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.key-templates.read<br> * hs-crypto.key-templates.list<br> * hs-crypto.vaults.read<br> * hs-crypto.vaults.list<br><br><br> 



8. Click Create after you select the appropriate actions for your custom role.







 Step 2: Assign IAM roles to users 

Before users can access Unified Key Orchestrator vaults, keystores, or keys, you need to grant users the appropriate IAM roles by completing the following steps:



1. From the menu bar, click Manage > Access (IAM), and select Users to browse the existing users in your account.
2. Select the user, and click the Actions icon ![Actions icon](https://cloud.ibm.com/docs-content/v1/content/217f108cc44e2ce15fb692d4b57b4c628464e908/icons/action-menu-icon.svg) to open a list of options for that user.

Click Invite users to add a user to your account if the user is not in the table. For more information, see [Inviting users to an account](https://cloud.ibm.com/docs/account?topic=account-iamuserinv).
3. From the options menu, click Assign access.
4. Click Access policy.
5. Under Service, select Hyper Protect Crypto Services and click Next.
6. Under Resources, select resources that you want to assign access to and click Next.



* If you want to assign the user access to all the Hyper Protect Crypto Services instances under your account, select All resources.
* If you want to assign the user access to part of the Hyper Protect Crypto Services resources under you account, select Specific resources and add the corresponding conditions based on your needs.
* [Key management service](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-uko-understand-conceptsuko-key-management-concepts)
* [Cloud hardware security module](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-uko-understand-conceptsuko-cloud-hsm-concepts)
* [Unified Key Orchestrator](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-uko-understand-conceptsuko-unified-key-orchestrator-concepts)





 About service instance initialization - Unified Key Orchestrator Plan 

[Initializing your service instance - Unified Key Orchestrator Plan](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-uko-introduce-serviceuko-introduce-service)



* [Understanding administrators and signature keys](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-uko-introduce-serviceuko-understand-crypto-unit-admin)
* [Understanding imprint mode and signature thresholds](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-uko-introduce-serviceuko-understand-imprint-mode)
* [Understanding the master key](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-uko-introduce-serviceuko-understand-key-ceremony)
* [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)