vania-janet/multiturn-rag-retrieval-data huggingface dataset:
A key object stores a cryptographic key. Each characteristic of the object is defined in an attribute. For more information, see

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





 Mechanism 

A process for implementing a cryptographic operation.





 Enterprise PKCS 11 

Enterprise PKCS #11 (EP11) is designed for customers that are seeking support for open standards and enhanced security. The EP11 library provides a stateless interface, which is similar to the industry-standard PKCS #11 API. The HSM that crypto units run on supports EP11 library, so users can call EP11 API through [gRPC](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-understand-conceptsgrpc-concept) for their own key management and data encryption. For more information, see

[Enterprise PKCS #11 (EP11) Library structure document](https://www.ibm.com/security/cryptocards/pciecc4/library).





 gRPC 

gRPC is a modern open source high performance remote procedure call (RPC) framework that can connect services in and across data centers for load balancing, tracing, health checking, and authentication. Applications access Hyper Protect Crypto Services EP11 library by calling the EP11 API remotely through gRPC. 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.
Follow the [instructions](https://cloud.ibm.com/hs-crypto?topic=hs-crypto-manage-ep11-keystores-uicreate-ep11-keystore-ui) to create a private EP11 keystore and note the keystore ID for subsequent steps.







 Step 2: Set up the Hyper Protect Crypto Services PKCS 11 library 



 1. Run the Db2 Community Edition container 



1. Use the following command to run the Db2 Community Edition container:

docker run -itd --name mydb --privileged=true -p 50000:50000 -e LICENSE=accept -e DB2INST1_PASSWORD=password -e DBNAME=testdb ibmcom/db2
2. Run the following command from a command line on your host system:

docker exec -it --user root --workdir / mydb bash



This shell is to be used to run the commands as root for the subsequent steps.





 2. Create the Hyper Protect Crypto Services PKCS 11 configuration file 

Now, create a configuration file for the Hyper Protect Crypto Services PKCS #11 feature. The configuration file is named grep11client.yaml.

Adapt the following file template and name the file grep11client.yaml:



* Replace <instance_id> with the ID of your Hyper Protect Crypto Services instance
* Replace <EP11_endpoint_URL> and <EP11_endpoint_port_number> with the respective parameters of the EP11 endpoint address of your Hyper Protect Crypto Services instance
* Replace <private_keystore_id> with the ID of the private keystore you created previously
* Replace <anonymous_user_api_key> with the respective API key of the anonymous user



iamcredentialtemplate: &defaultiamcredential
enabled: true
endpoint: "https://iam.cloud.ibm.com"
 The Universally Unique IDentifier (UUID) of your Hyper Protect Crypto Services instance.
instance: "<instance_id>"

tokens:
0:
grep11connection:
Configuring KMIP for key management and distribution in Hyper Protect Crypto Services Standard Plan 

Key Management Interoperability Protocol (KMIP) is a communication protocol for the storage and maintenance of key, certificate, and secret objects. The standard is governed by the Organization for the Advancement of Structured Information Standards (OASIS). Hyper Protect Crypto Services provides a dedicated single-tenant KMIP adapter so that VMware vCenter server instances can use Hyper Protect Crypto Services as the Key Management Service (KMS) for VMware vSphere encryption and vSAN encryption.

This tutorial is based on the Standard Plan instance setup only.

The following diagram illustrates the overall workflow of how the KMIP adapter that is provided in the Hyper Protect Crypto Services instance works with a VMWare customer environment.

Zoom

![KMIP workflow with VMWare customer environment](https://cloud.ibm.com/docs-content/v1/content/217f108cc44e2ce15fb692d4b57b4c628464e908/hs-crypto/images/kmip-vmware-workflow.svg)

Figure 1. KMIP workflow with VMWare customer environment

The overall workflow includes the following steps:



1. Create a Hyper Protect Crypto Services Standard Plan instance and your root key.
2. Configure the VMWare Solution Service KMIP for VMWare with the Hyper Protect Crypto Services service instance. The KMIP for VMware service manages the lifecycle of the KMIP adapter and KMIP client certificates.
3. Connect your VMware vCenter server to KMIP and enable vSphere encryption or vSAN encryption.





 Objectives 

This tutorial shows how you can configure KMIP with VMWare solution in IBM Cloud.





 Before you begin 

To complete this tutorial, you need to meet the following prerequisites:



* [Sign up an IBM Cloud account](https://cloud.ibm.com/docs/vmwaresolutions?topic=vmwaresolutions-signing_required_accountssigning_required_accounts-cloud).
PCIeCC3 is also referred to as the IBM 4768 crypto card or the Crypto Express 6S (CEX6S). PCIeCC4 is also referred to as the IBM 4769 crypto card or the Crypto Express 7S (CEX7S). Both CEX6S and CEX7S are Common Criteria EAL4 certified to meet the security requirements defined by the Common Criteria for Information Technology Security Evaluation.

Common Criteria is an international standard (ISO/IEC 15408) to assess the security of computer security products. Common Criteria provides assurance that the process of specification, implementation, and evaluation of a computer security product is complied with the standards and requirements defined.





 FIPS 140-2 Level 4 

The Federal Information Processing Standard (FIPS) Publication 140-2 is a US government computer security standard that is used to approve cryptographic modules.

FIPS 140-2 defines four levels of security, including FIPS 140-2 Level 1, 2, 3, and 4. FIPS 140-2 Level 4 is the highest level of security. At this security level, the physical security mechanisms provide a complete envelope of protection around the cryptographic module with the intent of detecting and responding to all unauthorized attempts at physical access. Penetration of the cryptographic module enclosure from any direction has a high probability of being detected, resulting in the immediate zeroization of all plaintext critical security parameters (CSPs).

Hyper Protect Crypto Services uses the IBM 4768 or IBM 4769 crypto card, which is certified at FIPS 140-2 Level 4, the highest level of certification achievable for commercial cryptographic devices. Hyper Protect Crypto Services is the only cloud HSM in the public cloud market that is built on an HSM designed to meet FIPS 140-2 Level 4 certification requirements. You can check the certificates at the following sites:



* [IBM 4769-001 Cryptographic Coprocessor Security Module](https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/4079)
* [IBM 4768 Cryptographic Coprocessor Security Module](https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/3410)
PCIeCC3 is also referred to as the IBM 4768 crypto card or the Crypto Express 6S (CEX6S). PCIeCC4 is also referred to as the IBM 4769 crypto card or the Crypto Express 7S (CEX7S). Both CEX6S and CEX7S are Common Criteria EAL4 certified to meet the security requirements defined by the Common Criteria for Information Technology Security Evaluation.

Common Criteria is an international standard (ISO/IEC 15408) to assess the security of computer security products. Common Criteria provides assurance that the process of specification, implementation, and evaluation of a computer security product is complied with the standards and requirements defined.





 FIPS 140-2 Level 4 

The Federal Information Processing Standard (FIPS) Publication 140-2 is a US government computer security standard that is used to approve cryptographic modules.

FIPS 140-2 defines four levels of security, including FIPS 140-2 Level 1, 2, 3, and 4. FIPS 140-2 Level 4 is the highest level of security. At this security level, the physical security mechanisms provide a complete envelope of protection around the cryptographic module with the intent of detecting and responding to all unauthorized attempts at physical access. Penetration of the cryptographic module enclosure from any direction has a high probability of being detected, resulting in the immediate zeroization of all plain text critical security parameters (CSPs).

Hyper Protect Crypto Services uses the IBM 4768 or IBM 4769 crypto card, which is certified at FIPS 140-2 Level 4, the highest level of certification achievable for commercial cryptographic devices. Hyper Protect Crypto Services is the only cloud HSM in the public cloud market that is built on an HSM designed to meet FIPS 140-2 Level 4 certification requirements. You can check the certificates at the following sites:



* [IBM 4769-001 Cryptographic Coprocessor Security Module](https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/4079)
* [IBM 4768 Cryptographic Coprocessor Security Module](https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/3410)
The Cryptoki API requires that an application opens one or more sessions with a token to gain access to the objects and functions of the token. A session provides a logical connection between the application and the token. A session can be a read/write (R/W) session or a read-only (R/O) session.

To gain access to the private objects of the token, the normal user needs to log in and is authenticated. See

[PKCS #11 Cryptographic Token Interface Usage Guide](http://docs.oasis-open.org/pkcs11/pkcs11-ug/v2.40/cn02/pkcs11-ug-v2.40-cn02.html_Toc406759989) for an in-depth look at sessions.





 Key object 

Key objects are stored in either the in-memory keystore that resides with the PKCS #11 application or in a database-backed keystore. If the CKA_TOKEN attribute is set to true for the key object, the key object is stored in the database-backed keystore. Otherwise, the key object is stored in the in-memory keystore.

Key objects in the in-memory keystore are not automatically rotated after the master key rotation. If PKCS #11 keystores are enabled in your service instance, you need to restart all active PKCS #11 applications to clear the in-memory keystore after the master key rotation is complete.

As shown in the following diagram, a PKCS #11 key object is an example of a PKCS #11 object class:



* Data: A data object is defined by an application.
* Certificates: A certificate object stores a certificate.
* Keys: A key object stores a cryptographic key. The key can be a public key, a private key, or a secret key. Each type of these keys has subtypes for use in specific mechanisms.



* Public key: The public component of a key pair that is used by anyone to encrypt messages intended for a particular recipient that has access to the private key of the key pair. The public key is also used to verify signatures created by the private key.
ibmcloud iam api-key-create apikeyhpcs -d "API key for Hyper Protect Crypto Services PKCS11"
3. Save the value of the API key for subsequent steps.







 Step 2: Set up the Hyper Protect Crypto Services PKCS 11 library in your Oracle Database environment 



 1. Set up the Oracle Database 

You need an Oracle Database Enterprise Edition installation with Oracle Advanced Security. This tutorial uses a single instance Oracle Database 19.3 Enterprise Edition Docker container. For more information about Oracle Database containers and instructions on building a respective container, see [Oracle Database on Docker](https://github.com/oracle/docker-images/tree/master/OracleDatabase).



1. Start the Oracle Database container:

docker run --name oradb -p 1521:1521 -p 5500:5500 -e ORACLE_PWD=password oracle/database:19.3.0-ee

Wait until instance and database creation are completed.
2. Run the following command from a command line on your host system:

docker exec -it --user root --workdir / oradb bash

This shell can be used to run the commands as root for the subsequent steps.







 2. Configure the Hyper Protect Crypto Services PKCS 11 library 

Now create a configuration file for the Hyper Protect Crypto Services PKCS #11 feature. The configuration file is named grep11client.yaml.

Adapt the following file template and name the file grep11client.yaml:



* Replace <instance_id> with the ID of your Hyper Protect Crypto Services instance.
* Replace <EP11_endpoint_URL> and <EP11_endpoint_port_number> with the respective parameters of the EP11 endpoint address of your Hyper Protect Crypto Services instance.
* Replace <your_api_key> with the value of the API key that you created.



iamcredentialtemplate: &defaultiamcredential
enabled: true
endpoint: "https://iam.cloud.ibm.com"
Introducing EP11 over gRPC - Standard Plan 

Enterprise PKCS #11 (EP11) is designed for customers that are seeking support for open standards and enhanced security. The EP11 library provides a stateless interface, which is similar to the industry-standard

[Public-Key Cryptography Standards (PKCS) #11 API](http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/os/pkcs11-base-v2.40-os.html). PKCS #11 API defines a platform-independent API to cryptographic tokens, such as hardware security modules (HSM) and smart cards. Existing applications that use PKCS #11 can benefit from enhanced security with secure key cryptography as well as a stateless interface, which makes the cryptographic operations much more efficient.

More information about the EP11 Library can be found in the

[Enterprise PKCS #11 (EP11) Library structure document](https://www.ibm.com/security/cryptocards/pciecc4/library). For more information about EP11 capabilities and extensions, see [EP11 introduction](https://www.ibm.com/security/cryptocards/pciecc3/ep11).

IBM Cloud® Hyper Protect Crypto Services provides a set of EP11 over gRPC (GREP11) API calls, with which all the cryptographic functions are executed in the cloud HSM of Hyper Protect Crypto Services. The GREP11 API is a stateless interface for cryptographic operations on cloud.

Hyper Protect Crypto Services leverages frameworks such as gRPC to enable remote application access. gRPC is a modern open source high-performance remote procedure call (RPC) framework that can connect services in and across data centers for load balancing, tracing, health checking, and authentication. Applications access Hyper Protect Crypto Services by calling the EP11 API remotely through gRPC. For more information about gRPC, see [the gRPC documentation](https://grpc.io/docs/guides/index.html).

With the GREP11 API, you can perform the following operations:



* Key generation.
The Partition Security Officer has control of one or more partitions (virtual HSMs) within the SafeNet Luna Network HSM. To access Partition SO functions, you must log in by using the LunaCM utility on a registered client computer. The Partition SO, when logged in to the partition, can do the following actions:



* Modify partition policies
* Back up and restore partition contents
* Initialize the Crypto Officer role







 Crypto Officer (CO) 

The Crypto Officer has full read/write access to the partition through the LunaCM utility on a registered client computer. The Crypto Officer partition credential allows a client application to perform any cryptographic operation, including the following operations:



* Create and delete keys
* Wrap and unwrap
* Encrypt and decrypt
* Sign and verify
* The Crypto Officer can also initialize the optional Crypto User role.







 Crypto User (CU) 

The Crypto User is a restricted read-only client user. After initialization, the authenticated Crypto User can access cryptographic materials that exist on the partition, but can't manipulate those objects.

The Crypto User role is optional. If you don't have security requirement for this role, the CU role can remain uninitialized and all client applications can access the partition by using the Crypto Officer credential.
An application becomes a Cryptoki application by calling the Cryptoki function C_Initialize from one of the threads. After this call is made, the application can call other Cryptoki functions. When the application finishes using Cryptoki, it calls the Cryptoki function C_Finalize and ceases to be a Cryptoki application.





 User 

The PKCS #11 standard defines two types of users for login: a security officer (SO) and a normal user. If a user does not log in using the C_Login Cryptoki function, the user is also known as an anonymous user. Only the normal user can access private objects on the token, and that access is granted only after the normal user is authenticated. In the Hyper Protect Crypto Services PKCS #11 implementation, security officers and normal users are authenticated by API keys. Anonymous users are also supported. For instructions on setting up PKCS #11 user types, see

[Best practices for setting up PKCS #11 user types](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-best-practice-pkcs11-access).





 Session 

The Cryptoki API requires that an application opens one or more sessions with a token to gain access to the objects and functions of the token. A session provides a logical connection between the application and the token. A session can be a read/write (R/W) session or a read-only (R/O) session.

To gain access to the private objects of the token, the normal user needs to log in and is authenticated. See

[PKCS #11 Cryptographic Token Interface Usage Guide](http://docs.oasis-open.org/pkcs11/pkcs11-ug/v2.40/cn02/pkcs11-ug-v2.40-cn02.html_Toc406759989) for an in-depth look at sessions.





 Key object 

Key objects are stored in either the in-memory keystore that resides with the PKCS #11 application or in a database-backed keystore.
autoDiscoverDevices Optional: Automatically discover the available disks on your worker nodes. Enter true or false. 
 hpcsServiceName Enter the name of your Hyper Protect Crypto Services instance. For example: Hyper-Protect-Crypto-Services-eugb. false 
 hpcsInstanceId Enter your Hyper Protect Crypto Services instance ID. For example: d11a1a43-aa0a-40a3-aaa9-5aaa63147aaa. false 
 hpcsSecretName Enter the name of the secret that you created by using your Hyper Protect Crypto Services credentials. For example: ibm-hpcs-secret. false 
 hpcsBaseUrl Enter the public or private endpoint of your Hyper Protect Crypto Services instance. For example: https://api.eu-gb.hs-crypto.cloud.ibm.com:8389. false 
 hpcsTokenUrl Enter https://iam.cloud.ibm.com/identity/token. false 
 ignore-noobaa Enter true if you do not want to deploy MultiCloud Object Gateway. false 







 Version 4.10, 4.11, and 4.12 parameters 



Classic parameter reference for 4.10 to 4.12

 Parameter Description Default value 

 name Note that Kubernetes resource names can't contain capital letters or special characters. Enter a name for your resource that uses only lowercase letters, numbers, - or . N/A 
 osdStorageClassName Enter localblock. N/A 
 osdSize Enter a size for your storage devices. Example: 100Gi. The total storage capacity of your ODF cluster is equivalent to the osdSize multiplied by the numOfOsd. N/A 
 osdDevicePaths Enter a comma separated list of the device paths for the devices that you want to use for the OSD devices. The devices that you specify are used as your application storage in your configuration. Each device must have at least 100GiB of space and must be unformatted and unmounted.
A certificate object stores a certificate. A key object stores a cryptographic key. Each characteristic of the object is defined in an attribute. For more information, see

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





 Mechanism 

A process for implementing a cryptographic operation.





 Enterprise PKCS 11 

Enterprise PKCS #11 (EP11) is designed for customers that are seeking support for open standards and enhanced security. The EP11 library provides a stateless interface, which is similar to the industry-standard PKCS #11 API. The HSM that crypto units run on supports EP11 library, so users can call EP11 API through [gRPC](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-uko-understand-conceptsuko-grpc-concept) for their own key management and data encryption. For more information, see

[Enterprise PKCS #11 (EP11) Library structure document](https://www.ibm.com/security/cryptocards/pciecc4/library).





 gRPC 

gRPC is a modern open source high performance remote procedure call (RPC) framework that can connect services in and across data centers for load balancing, tracing, health checking, and authentication. Applications access Hyper Protect Crypto Services EP11 library by calling the EP11 API remotely through gRPC. 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.
Private indicates that the key is the private key of an asymmetric key pair. Secret indicates that the key is a symmetric key. 
 Version The version number of the key. When the key is first created, version 0 is assigned. The version number is increased by 1 sequentially upon each update, such as using the C_SetAttributeValue function to update a key attribute value. 
 Keystore The unique identifier of the keystore the key is stored in. 
 Type The type of the EP11 key that is managed in Hyper Protect Crypto Services. 



2. To view details of the [key attributes](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-pkcs11-api-refpkcs-attribute-list), click the Actions icon ![Actions icon](https://cloud.ibm.com/docs-content/v1/content/217f108cc44e2ce15fb692d4b57b4c628464e908/icons/action-menu-icon.svg) of the key row, and then select Show more details.

You can also identify the public key, the private key, and the symmetric key by checking the value of the CKA_CLASS attribute. CKO_PUBLIC_KEY indicates a public key; CKO_PRIVATE_KEY indicates a private key; CKO_SECRET_KEY indicates a symmetric key.







 Creating EP11 keys 

For default service access roles that support creating EP11 keys, see [service access roles](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-manage-accessservice-access-roles). If you are to create custom roles, make sure to assign the following actions to the custom role:



* hs-crypto.keystore.listkeystoresbyids
* hs-crypto.keystore.listkeysbyids
* hs-crypto.crypto.generatekey
* hs-crypto.crypto.generatekeypair
* hs-crypto.keystore.storenewkey