vania-janet/multiturn-rag-retrieval-data huggingface dataset:
Cryptographic operations: GREP11 API 

IBM Cloud® Hyper Protect Crypto Services provides a set of cryptography functions that are executed in a

Hardware Security Module (HSM)in the cloud. You can perform cryptographic operations by remotely accessing these functions with the Enterprise PKCS #11 (EP11) over gRPC API calls (also referred to as GREP11).

For more information about how the GREP11 functions are related to PKCS #11 and EP11, see [GREP11 introduction](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-introduce-cloud-hsmaccess-cloud-hsm-pkcs11).

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



 Accessing the API 

A GREP11 API endpoint, a service ID API key, an IAM endpoint are needed for initialization before you perform any GREP11 API function calls. For more information, see [Generating a GREP11 API request](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-set-up-grep11-apiform-grep11-api-request).





 Error handling 

GREP11 relies on the gRPC specification for [error handling](https://grpc.io/docs/guides/error/). When an error occurs, gRPC clients receive a [message Status protocol buffer](https://github.com/grpc/grpc/blob/master/src/proto/grpc/status/status.proto).

message Status {
int32 code = 1;
string message = 2;
repeated google.protobuf.Any details = 3;
}

In the error message,



* code includes the status code, which needs to be an enumerated-type (enum) value of the google.rpc.Code field.
* message includes a developer-facing error message in English. Any user-facing error message needs to be localized and sent in the google.rpc.Status.details field, or localized by the user.
region Required. The region abbreviation, such as us-south or eu-de, that represents the geographic area where your Hyper Protect Crypto Services instance resides. For more information, see [Regional service endpoints](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-regionsservice-endpoints). 
 port Required. The port number of the API endpoint. 
 url_encoded_CRN_query Filters for resources that are associated with a specified [Cloud Resource Name (CRN)](https://cloud.ibm.com/docs/account?topic=account-crn) by using URL encoded wildcard characters (). The parameter needs to contain all CRN segments and must be URL encoded. To view examples, see [CRN query examples](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-view-protected-resourcescrn-query-examples). 
 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). 







 CRN query examples 

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.
* [Added: Hyper Protect Crypto Services expands into the Toronto region](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-what-newadd-toronto-region)



* [22 March 2022](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-what-newhs-crypto-march2022)



* [General availability: Using Unified Key Orchestrator to manage and orchestrate keys in a multicloud environment](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-what-newadd-uko%7D)



* [28 February 2022](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-what-newhs-crypto-28feb2022)



* [Limited availability: Using Unified Key Orchestrator to manage and orchestrate keys in a multicloud environment](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-what-newadd-uko%7D)



* [23 February 2022](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-what-newhs-crypto-23feb2022)



* [Added: Using IBM Cloud Monitoring to measure Hyper Protect Crypto Services metrics](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-what-newadd-monitoring-metrics)



* [15 February 2022](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-what-newhs-crypto-15feb2022)



* [Added: Hyper Protect Crypto Services expands into the São-Paulo region](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-what-newadd-sao-region)
[HashiCorp Vault](https://cloud.ibm.com/docs-content/v1/content/5eb88a2575e30e316dbb83829c7f4c8b1ddbc67c/devsecops/images/devsecops_hashicorp1_orig.png)

Figure 10. HashiCorp Vault



* Name: A name for this tool integration. This name is displayed in the toolchain.
* Server URL: The server URL for your HashiCorp Vault Instance. (For example, https://192.168.0.100:8200)
* Integration URL: The URL that you want to navigate to when you click the HashiCorp Vault Integration tile.
* Secrets Path: The mount path where your secrets are stored in your HashiCorp Vault Instance.
* Authentication Method: The Authentication method for your HashiCorp Vault Instance.
* Role ID: Your team's [AppRole Role ID](https://www.hashicorp.com/blog/authenticating-applications-with-vault-approle).
* Secret ID: Your team's [Secret ID](https://www.hashicorp.com/blog/authenticating-applications-with-vault-approle).



You can use the AppRole authentication method to read secret values.





 Evidence Storage 

All raw compliance evidence that belongs to the application is collected in this repository. Use this repository option for evaluation purposes only.

The default behavior of the toolchain is to Use existing evidence locker. The Repository URL field can be set to the Evidence Repository URL that was created/used for CI Toolchain. If you want to create an Evidence Locker for the toolchain, choose Create new evidence locker repository, which creates a new repository as an IBM-hosted Git Repos and Issue Tracking Repository.
Storage class encryption is available only for versions 4.10.0 and later of OpenShift Data Foundation.



1. Create an [Hyper Protect Crypto Services](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-provision&interface=ui) or [Key Protect](https://cloud.ibm.com/docs/key-protect?topic=key-protect-provision) service instance.
2. Create root key



* [Hyper Protect Crypto Services](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-create-root-keys&interface=ui).
* [Key Protect](https://cloud.ibm.com/docs/key-protect?topic=key-protect-create-root-keys&interface=ui).



3. After creating your instance and root key, make a note of your Hyper Protect Crypto Services or Key Protect instance name, instance ID, root key ID, and public endpoint.
4. Create a [service ID](https://cloud.ibm.com/docs/account?topic=account-serviceids), [API key](https://cloud.ibm.com/docs/account?topic=account-serviceidapikeys), and [access policy](https://cloud.ibm.com/docs/account?topic=account-assign-access-resources) that allows access to either Hyper Protect Crypto Services and Red Hat OpenShift on IBM Cloud or Key Protect and Red Hat OpenShift on IBM Cloud. Make a note of the API that you create.



[Access your Red Hat OpenShift cluster](https://cloud.ibm.com/docs/openshift?topic=openshift-access_cluster).



1. List your namespaces to determine whether you have an openshift-storage namespace. If you don't have an openshift-storage namespace, create it.

oc get namespaces | grep openshift-storage



1. Create an openshift-storage namespace in your cluster.
For more information about the detailed steps, see [Encrypting routes with keys stored in Hyper Protect Crypto Services](https://cloud.ibm.com/docs/openshift?topic=openshift-hpcs-router).







 Getting started to manage your regulated workloads with Hyper Protect Crypto Services 

To manage your regulated workloads with Hyper Protect Crypto Services, see the [Getting started tutorial](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-get-started).





 Reference 

For more information about setting up your environment in IBM Cloud to manage your regulated workloads, see the following topics:



* [Encrypt consumer data at rest and in transit](https://cloud.ibm.com/docs/allowlist/framework-financial-services?topic=framework-financial-services-best-practicesbest-practices-encryption).
* [VMware encryption](https://cloud.ibm.com/docs/vmwaresolutions?topic=vmwaresolutions-vrw-encryptionvrw-encryption-keys).
* [VMware use case 2](https://cloud.ibm.com/docs/vmwaresolutions?topic=vmwaresolutions-vrw-use-case-2).
* [VMware architecture overview](https://cloud.ibm.com/docs/vmwaresolutions?topic=vmwaresolutions-vrw-archi-overview).
Hyper Protect Crypto Services (HPCS) is a dedicated key management service and hardware security module (HSM). HPCS integrates with Key Protect to generate and encrypt keys. The Keep Your Own Key (KYOK) function is also enabled by HPCS.







 Notes 

For more information about HPCS, see [Getting started with IBM Cloud Hyper Protect Crypto Services](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-get-started).







 kp import-token show 

[Retrieve the import token](https://cloud.ibm.com/docs/key-protect?topic=key-protect-create-import-tokensretrieve-import-token-api) that is associated with your Key Protect instance.

The import token contains a public encryption key and a nonce. Provide the retrieved public key and nonce as arguments for ibmcloud kp import-token nonce-encrypt and ibmcloud kp import-token key-encrypt.

ibmcloud kp import-token show
-i, --instance-id INSTANCE_ID



 Example 

This example creates an import token and shows the results.

 create an import token that expires in 5 minutes and allows 10 retrievals
$ ibmcloud kp import-token create -e 300 -m 10

 show the created token
$ ibmcloud kp import-token show

{
"nonce": "8rf2ldP/zWm1Tjrb",
"payload":
"LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0t ...<redacted>... QyBLRVktLS0tLQo="
}

 extract the nonce that was created by the "kp import-token create" command
$ ibmcloud kp import-token show | jq -r '.["nonce"]'

8rf2ldP/zWm1Tjrb

 extract the public key that was created by the "kp import-token create" command
"crn": "crn:v1:bluemix:public:hs-crypto:us-south:a/f047b55a3362ac06afad8a3f2f5586ea:346d9f67-4bb2-481e-a3e1-3c2c646aa886:key:644cba65-e240-471f-8b84-14115447d2ae",
"extractable": false,
"imported": true
}
]
}



* The id value is a unique identifier that is assigned to your key and is used for subsequent calls to the key management service API.
* The state value set to 1 indicates that your key is now in the [Active key state](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-key-states).
* The crn value provides the full scoped path to the key that specifies where the resource resides within IBM Cloud.
* Finally, the extractable and imported values describe this resource as a root key that you imported to the service. 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. Otherwise, when you set the extractable attribute to false, the service designates the key as a root key.



4. Optional: Navigate to the Hyper Protect Crypto Services dashboard to view and manage your key.

You can browse the general characteristics of your keys from the application details page. Choose from a list of options for managing your key, such as [rotating the key](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-rotate-keysrotate-root-key-gui) or [deleting the key](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-delete-keysdelete-keys-gui).







 Step 8: Clean up 



1. Gather the identifier for the encryption key that you imported in the previous step.
* [Retrieving supported crypto algorithms](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-grep11-api-refgrep11-operation-retrieve-mechanisms)
* [Generating and deriving keys](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-grep11-api-refgrep11-operation-generate-keys)
* [Protecting keys](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-grep11-api-refgrep11-operation-manage-keys)
* [Retrieving and modifying attributes for keys](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-grep11-api-refgrep11-operation-attribute-value)
* [Generating random data](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-grep11-api-refgrep11-operation-generate-random-data)
* [Encrypting and decrypting data](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-grep11-api-refgrep11-operation-encrypt-decrypt-data)
* [Signing and verifying data](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-grep11-api-refgrep11-operation-sign-verify-data)
* [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
* [15 February 2022](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-what-newhs-crypto-15feb2022)



* [Added: Hyper Protect Crypto Services expands into the São-Paulo region](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-what-newadd-sao-region)



* [21 January 2022](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-what-newhs-crypto-jan2022)



* [Updated: Hyper Protect Crypto Services key management functions](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-what-newupdate-kms-api-v282)



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



* [Added: Exclusive control on the execution of cryptographic operations](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-what-newadd-cert-manager)
* [Added: Hyper Protect Crypto Services expands into the Tokyo region](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-what-newadd-tokyo-region)
* [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)
The service is built on FIPS 140-2 Level 4-certified hardware, the highest security level that is offered in the industry. The HSM is also certified to meet the Common Criteria Part 3 conformant EAL 4.









 What's next 



* To get an overall tutorial about using Hyper Protect Crypto Services, check out [Getting started with IBM Cloud Hyper Protect Crypto Services](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-get-started).
* To find out more about programmatically managing your keys, check out the [Hyper Protect Crypto Services key management service API reference doc](https://cloud.ibm.com/apidocs/hs-crypto).
* To find out more about the PKCS #11 API, see

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

[PKCS #11 API reference](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-pkcs11-api-ref).
* To find out more about the GREP11 API, see [Introducing EP11 over gRPC](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-grep11-intro) and [GREP11 API reference](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-grep11-api-ref).
* For more information about the compliance certificates that Hyper Protect Crypto Services receives, see [Security and compliance](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-security-and-compliance).
* To find more about available IBM Cloud services for integration, see [Integrating IBM Cloud services with Hyper Protect Crypto Services](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-integrate-services).
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). 
 key_ring_ID Optional. The unique identifier of the target key ring that you want to assign the key to. If unspecified, the header is automatically set to default and the key will belong to the default key ring in the specified Hyper Protect Crypto Services instance.<br><br>For more information, see [Managing key rings](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-managing-key-rings). 
 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.<br><br>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_name 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. 
 alias_list Optional. One or more unique, human-readable aliases assigned to your key.<br><br>Important: To protect your privacy, do not store your personal data as metadata for your key.<br><br>Each alias must be alphanumeric, case-sensitive, and cannot contain spaces or special characters other than dashes (-) or underscores (_). The alias cannot be a version 4 UUID and must not be a Hyper Protect Crypto Services reserved name: allowed_ip, key, keys, metadata, policy, policies, registration, registrations, ring, rings, rotate, wrap, unwrap, rewrap, version, versions. Alias size can be 2 - 90 characters (inclusive).
The unique identifier that is assigned to your Hyper Protect Crypto Services instance. For more information, see [Retrieving an instance ID](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-retrieve-instance-ID). 



A successful request returns a 200 OK response with dual authorization policy details for your key. The following JSON object shows an example response.

{
"metadata": {
"collectionType": "application/vnd.ibm.kms.policy+json",
"collectionTotal": 1
},
"resources": [
{
"id": "2291e4ae-a14c-4af9-88f0-27c0cb2739e2",
"crn": "crn:v1:bluemix:public:hs-crypto:us-south:a/f047b55a3362ac06afad8a3f2f5586ea:30372f20-d9f1-40b3-b486-a709e1932c9c:key:2291e4ae-a14c-4af9-88f0-27c0cb2739e2",
"dualAuthDelete": {
"enabled": true
},
"createdBy": "...",
"creationDate": "2020-03-10T20:41:27Z",
"updatedBy": "...",
"lastUpdateDate": "2020-03-16T20:41:27Z"
}
]
}

The key now requires an authorization from two users before it can be deleted.

For more information, see [Deleting keys using dual authorization](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-delete-dual-auth-keys).
Only a hash of the data in the collection is added to the channel ledger and is stored on the peers of other channel members and the ordering service. This allows organizations to verify private data if they want to make the transaction details public. To learn more, visit the [Private Data](https://hyperledger-fabric.readthedocs.io/en/release-2.2/private-data/private-data.htmlprivate-data) concept article in the Fabric documentation.

Zoom

![Private data](https://cloud.ibm.com/docs-content/v1/content/c5288bed34c3820e3a5251d820ee91adcd2591a3/blockchain/images/data_res_private_data.svg)

Figure 3. Org C and Org D use a private data collection to keep data from being distributed on channel X and from leaving Germany. Hashes of data in the collection are stored on ledger X.

In Figure 3, Org C and Org D have created a private data collection, the OrgC-OrgD collection, that allows the organizations to transact without having to share data with Org A, Org B, or the ordering service. The key-value state data inside this collection is only stored on the peers of Org C and Org D and does not leave Germany. However, a hash of the data within the collection is stored on ledger X and shared with the broader channel. This means that a hash of the data in the OrgC-OrgD collection is stored on the peers and the ordering service in the United States.

When considering private data, it is important to understand the difference between hashed data and encrypted data. Encryption uses a two-way function to transform data into a form that hides its original value, but can be converted back to the original state. As an example, when data is sent over a network that is secured using TLS, the data is encrypted using a TLS certificate. It is then sent over the network as crypto text, and then decrypted by the recipient. The encrypted text contains all the original data, and can be decrypted using a private key.
Managing regulated workloads with Hyper Protect Crypto Services 

Because IBM Cloud® Hyper Protect Crypto Services is built on FIPS 140-2 Level 4-certified hardware, it provides the same cryptographic technology that financial institutions rely on. By encrypting your workloads with Hyper Protect Crypto Services, it meets the security requirements of regulatory industries, such as the financial industry.

To help prevent unauthorized access to sensitive data, Hyper Protect Crypto Services provides the Keep Your Own Key capability for you to retain exclusive access to your encryption keys. Unauthorized parties, including IBM Cloud admins, have no access to your encryption keys at any time. In cases where your application encrypts data with those keys, no other parties have access to your data.

To mitigate risk of stolen private keys, cloud users store the private key of the Transport Layer Security (TLS) certificates that are used for network encryption in the Hardware Security Module (HSM). This approach aligns with Keep Your Own Key that is provided by Hyper Protect Crypto Services. Private keys never leave the HSM, helping prevent unauthorized access to keys.



 Encrypting your regulated workloads with Hyper Protect Crypto Services 

With Hyper Protect Crypto Services, you have two options to encrypt your workloads:



* Using the key management service With the key management service provided, you can benefit from envelope encryption to protect your keys. Envelope encryption is the practice of encrypting data with a data encryption key (DEK) and then wrapping the DEK with a root key that you can fully manage. The root keys in Hyper Protect Crypto Services instance are also wrapped and protected by the master key that is protected in the hardware security module (HSM) of the Hyper Protect Crypto Services instance. By leveraging the key management service, your regulated workloads are protected with the envelope encryption mechanism.

For more information about the key management service, see [Bringing your encryption keys to the cloud](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-importing-keys) and [Protecting your data with envelope encryption](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-envelope-encryption).