vania-janet/multiturn-rag-retrieval-data huggingface dataset:
IA-7 - Cryptographic Module Authentication 



  Control requirements 

IA-7 - 0
:   The information system implements mechanisms for authentication to a cryptographic module that meet the requirements of applicable federal laws, Executive Orders, directives, policies, regulations, standards, and guidance for such authentication.





  IBM Cloud for Financial Services profile 

The rules related to this control that follow are part of the IBM Cloud for Financial Services v1.2.0 profile in [IBM Cloud® Security and Compliance Center](https://cloud.ibm.com/docs/security-compliance?topic=security-compliance-getting-started).



*  Check whether multifactor authentication (MFA) is enabled at the account level
*  Check whether IAM roles are used to create IAM policies for IBM resources
*  Check whether IAM users are attached to at least one access group
*  Check whether Hyper Protect Crypto Services is accessible only through private endpoints
*  Check whether Hyper Protect Crypto Services instance is enabled with a dual authorization deletion policy







  NIST supplemental guidance 

Authentication mechanisms may be required within a cryptographic module to authenticate an operator accessing the module and to verify that the operator is authorized to assume the requested role and perform services within that role.
In some cases, a crypto unit administrator can also be a master key custodian. 
 Master key custodian Provides master key parts for initializing a service instance. In some cases, a master key custodian can also be a crypto unit administrator. 
 Service user Manages root keys and standard keys through user interface and the API, and performs cryptographic operations through the PKCS #11 API or the Enterprise PKCS #11 over gRPC (GREP11) API. Based on the [platform access roles](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-uko-manage-accessuko-platform-mgmt-roles) and [service access roles](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-uko-manage-accessuko-service-access-roles), service users can be further categorized with various permissions. 





 IAM platform access roles 

With Cloud Identity and Access Management (IAM), you, as an account owner or a service administrator, can manage and define access for service users and resources in your IBM Cloud account.

To simplify access, Hyper Protect Crypto Services aligns with [IAM roles](https://cloud.ibm.com/docs/account?topic=account-userroles) so that each user has a different view of the service, according to the role the user is assigned. If you are a service administrator, you can assign Cloud IAM roles that correspond to the specific Hyper Protect Crypto Services permissions you want to grant to members of your team.

The following table lists the IBM Cloud IAM roles in the context of Hyper Protect Crypto Services. For complete IAM documentation and how to assign access, see [Best practices for setting up custom roles for Unified Key Orchestrator](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-uko-role-best-practices).

Use IBM Cloud platform access roles to grant permissions at the account level, such as the ability to create or delete instances in your IBM Cloud account.



Table 2. Lists platform management roles as they apply to Hyper Protect Crypto Services
All crypto units in a service instance need to be configured the same. If one availability zone in the region where your instance is located can't be accessed, the operational crypto units can be used interchangeably for load balancing or for high availability.

Crypto units that are assigned to an IBM Cloud user start in a cleared state that is known as

imprint mode.

The master key registers in all crypto units in a single service instance must be set the same. The same set of administrators must be added in all crypto units, and all crypto units must exit imprint mode at the same time.



* To display the service instances and crypto units in the target resource group under the current user account, use the following command:

ibmcloud tke cryptounits

The following output is an example that is displayed. The SELECTED column in the output table identifies the crypto units that are targeted by later administrative commands that are issued by the TKE CLI plug-in.

SERVICE INSTANCE: 482cf2ce-a06c-4265-9819-0b4acf54f2ba
CRYPTO UNIT NUM SELECTED TYPE LOCATION
1 false OPERATIONAL [us-south].[AZ3-CS3].[02].[03]
2 false OPERATIONAL [us-south].[AZ2-CS2].[02].[03]
3 false FAILOVER [us-east].[AZ2-CS2].[03].[04]
4 false FAILOVER [us-east].[AZ3-CS3].[01].[07]

SERVICE INSTANCE: 96fe3f8d-9792-45bc-a9fb-2594222deaf2
CRYPTO UNIT NUM SELECTED TYPE LOCATION
5 false OPERATIONAL [us-south].[AZ1-CS4].[00].[03]
6 false OPERATIONAL [us-south].[AZ2-CS5].[03].[03]
Make sure that you note your endpoint in the correct format. Example: https://api.us-south.hs-crypto.cloud.ibm.com:<port>. For more information, see the [Hyper Protect Crypto Services API documentation](https://cloud.ibm.com/apidocs/hs-cryptogetinstance).



2. Encode the endpoint to base64.

echo -n "<endpoint>" | base64
3. [Edit the Kubernetes secret that you created to include the correct endpoint for your KMS provider](https://cloud.ibm.com/docs/openshift?topic=openshift-storage_portworx_encryption).

oc edit <secret-name> -n portworx
4. Save and close your Kubernetes secret to reapply it to your cluster.



If you find information that you entered incorrectly or you must change the setup of your cluster, correct the information or the cluster setup.
When the application finishes using Cryptoki, it calls the Cryptoki function C_Finalize and ceases to be a Cryptoki application.

If you are running a Java PKCS #11 application using the SunPKCS11 provider on the IBM Z (s390x) platform, make sure that you use the latest IBM Semeru JVM and specify the -Xjit:noResumableTrapHandler Java option when starting your application. You can download the latest s390x version of the IBM Semeru JVM by changing the Architecture filter field to s390x on the [IBM Semeru Runtime Downloads page](https://developer.ibm.com/languages/java/semeru-runtimes/downloads/?license=IBM).





 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
Make sure that you note your endpoint in the correct format. Example: https://api.us-south.hs-crypto.cloud.ibm.com:<port>. For more information, see the [Hyper Protect Crypto Services API documentation](https://cloud.ibm.com/apidocs/hs-cryptogetinstance).



2. Encode the endpoint to base64.

echo -n "<endpoint>" | base64
3. [Edit the Kubernetes secret that you created to include the correct endpoint for your KMS provider](https://cloud.ibm.com/docs/containers?topic=containers-storage_portworx_encryption).

kubectl edit <secret-name> -n portworx
4. Save and close your Kubernetes secret to reapply it to your cluster.



If you find information that you entered incorrectly or you must change the setup of your cluster, correct the information or the cluster setup.
The following use cases show how Hyper Protect Crypto Services can work with other IBM Cloud services to manage your regulated workloads. For a complete list of IBM Cloud services that can integrate with Hyper Protect Crypto Services, see [Integrating IBM Cloud services with Hyper Protect Crypto Services](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-integrate-services).



 Managing VMware regulated workloads with Hyper Protect Crypto Services 

VMware vSphere® encryption is the tool the IBM Cloud for VMware® Regulated Workloads relies on to secure management and production virtual machines while at-rest or in-transit. Hyper Protect Crypto Services through the Key Management Interoperability Protocol (KMIP) on the IBM Cloud is the KMS required for the vCenter. Hyper Protect Crypto Services is a mandatory service. On-premises key management service integration is possible through Hyper Protect Crypto Services.

For more information about how the encryption works, see [the VMware reference doc](https://cloud.ibm.com/docs/vmwaresolutions?topic=vmwaresolutions-vrw-encryption).

A detailed tutorial on how to encrypt VMware regulated workloads by using Hyper Protect Crypto Services, see [Tutorial: 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). A [demo video](https://mediacenter.ibm.com/media/1_e5gk6ktn) is also available for your reference.





 Managing IBM Cloud Object Storage regulated workloads with Hyper Protect Crypto Services 

IBM Cloud Object Storage is an IBM Cloud service for you to store unlimited amounts of data in the assigned bucket so that the data can be accessed anywhere from the cloud. Hyper Protect Crypto Services helps you protect encryption keys for data that is stored in Object Storage with the highest security level in the industry and gives only you the access to these keys.
hs-crypto.keystore.listkeystoresbyids View EP11 keystores. 
 hs-crypto.keystore.storenewkey Store an EP11 key. 
 hs-crypto.keystore.updatekey Update an EP11 key. 







 EP11 crypto events 

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



Table 10. EP11 crypto actions

 Action Description 

 hs-crypto.ep11.use Cryptographic operation 









 Viewing events 

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

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



Table 11. Activity Tracker regions

 Deployment region Activity Tracker region 

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







 Analyzing successful events 

Most successful requests have unique requestData and responseData associated with each related event. In requestData and responseData properties there are available full payloads from requests and responses except sensitive data. The list of field, endpoints, and payloads is available in API docs.

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

The list of sensitive field values that are hidden using the [redacted] placeholder:



* service_principal_password
* secret_access_key
* access_key_id
* api_key





 Common fields 

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



Table 12.
When the verification is successful, Verified OK is displayed.
4. Verify the authenticity and validity of the signing certificate with the following command:

openssl ocsp -no_nonce -issuer digicert_cert.pem -cert signing_cert.pem -VAfile digicert_cert.pem -text -url http://ocsp.digicert.com -respout ocsptest

When the verification is successful, Response verify OK and signing_cert.pem: good are displayed in the output.
5. If the verification fails, cancel the installation and [contact IBM for support](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-getting-help).







 Step 3: Set up the PKCS 11 configuration file 

In order to connect the PKCS #11 library to the Hyper Protect Crypto Services cloud HSM to perform cryptographic functions, you need to complete the following steps to set up the configuration file.



1. Create a configuration file that is named grep11client.yaml based on the following example. The [library repository](https://github.com/IBM-Cloud/hpcs-pkcs11/releases) also provides a template for you to adapt. You can refer to the comments in the code to understand each field.

iamcredentialtemplate: &defaultiamcredential
enabled: true
endpoint: "https://iam.cloud.ibm.com"

tokens:
0:
grep11connection:
 The EP11 endpoint address starting from 'ep11'. For example: "ep11.us-south.hs-crypto.cloud.ibm.com"
address: "<EP11_endpoint_URL>"
port: "<EP11_endpoint_port_number>" The EP11 endpoint port number
tls:
enabled: true EP11 requires TLS connection.
 Set it 'true' if you want to enable mutual TLS connections.
Initializing your service instance - Standard Plan 

Before you can use IBM Cloud® Hyper Protect Crypto Services to manage encryption keys and perform cryptographic operations, you need to initialize your service instance first.

Service instance initialization is the process of loading the master key, so that you can take the ownership of the cloud

hardware security module (HSM)of Hyper Protect Crypto Services and own the root of trust that encrypts the entire hierarchy of encryption keys.

To initialize your service instance, you need to create

signature keysforcrypto unitadministrators, set quorum authentication thresholds to exit theimprint mode, and load themaster keyto the crypto units.



 Understanding administrators and signature keys 

A crypto unit is composed of an HSM and the corresponding software stack that is dedicated to the HSM. Each crypto unit can manage up to 5000 digital keys. If you're setting up a production environment, it is suggested to assign at least two crypto units for high availability when you create a Hyper Protect Crypto Services instance. The crypto units are located in different availability zones within the region that you select when you create the service instance. All crypto units in a service instance need to be configured the same. If one availability zone cannot be accessed, the crypto units in a service instance can be used interchangeably. Crypto units contain the master key that encrypts the contents of key storage, including root keys and standard keys in the key management keystore and Enterprise PKCS #11 (EP11) keys in the EP11 keystore.

To issue commands for crypto units to perform actions, you need to assign administrators to the crypto units. Each administrator has an associated signature key for identity authentication. The following flow chart shows how the signature keys are created and assigned to a service instance with two crypto units.

Zoom

![Creating and assigning signature keys](https://cloud.ibm.com/docs-content/v1/content/217f108cc44e2ce15fb692d4b57b4c628464e908/hs-crypto//images/sigkey-flow.svg)

Figure 2. Creating and assigning signature keys
SC-12 - Cryptographic Key Establishment and Management 



 Control requirements 

SC-12 - 0
: The organization establishes and manages cryptographic keys for required cryptography employed within the information system in accordance with [Assignment: organization-defined requirements for key generation, distribution, storage, access, and destruction].





 Additional IBM Cloud for Financial Services specifications 

The organization must implement cryptographic key establishment and management processes including:



* Key management responsibilities and key usage activities must be provided or agreed to by the customer
* All keys must be established for a discrete purpose
* Keys are rotated in accordance with operational timeframes
* Keys are stored within a proper KeyStore (e.g. a FIPS 140-2 Level 3 compliant hardware security module)
* Only authorized personnel are permitted access to key recovery functions.



Organizations providing cloud and multi-tenant services, must implement cryptographic key establishment and management processes including:



* Key management responsibilities and key usage activities must consider data categorization, sensitivity, and regulatory requirements
* Dedicated encryption keys per customer tenancy and external application for data in transit and at rest







 Implementation guidance 

See the resources that follow to learn more about how to implement this control.



* [Data encryption at rest](https://cloud.ibm.com/docs/framework-financial-services?topic=framework-financial-services-shared-encryption-at-rest)
* [Data encryption in transit](https://cloud.ibm.com/docs/framework-financial-services?topic=framework-financial-services-shared-encryption-in-transit)







 IBM Cloud for Financial Services profile 

The rules related to this control that follow are part of the IBM Cloud for Financial Services v1.2.0 profile in [IBM Cloud® Security and Compliance Center](https://cloud.ibm.com/docs/security-compliance?topic=security-compliance-getting-started).



* Check whether permissions for API key creation are limited and configured in IAM settings for the account owner
* Check whether Hyper Protect Crypto Services encryption keys that are generated by the service are rotated automatically at least every # months
* Check whether Hyper Protect Crypto Services instance is enabled with a dual authorization deletion policy







 NIST supplemental guidance
* UI
* CLI
* API







 Importing standard keys 

You can add your existing encryption keys with the IBM Cloud console, or programmatically with the Hyper Protect Crypto Services key management service API.



 Importing standard keys with the IBM Cloud console 

[After you create an instance of the service](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-provision), complete the following steps to enter your existing standard key with the Hyper Protect Crypto Services GUI.



1. [Log in to the IBM Cloud console](https://cloud.ibm.com/login).
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. To import a key, select the KMS keys tab in the side menu.
5. In the Keys table, click Add key and select Import a key.

Specify the key's details:



Table 1. Describes the settings to import a standard key

 Setting Description 

 Key type The type of key that you would like to manage in Hyper Protect Crypto Services. From the list of key types, select [Standard key](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-understand-conceptsstandard-key-concept). 
 Key name A unique, human-readable alias for easy identification of your key. To protect your privacy, ensure that the key name does not contain personally identifiable information (PII), such as your name or location. 
 Key alias (Optional) One or more unique, human-readable aliases that you want to assign to your key for easy recognition. Alias size can be 2 - 90 characters. You can set up to five key aliases for the key, with each separated by a comma.<br><br>Note: Each alias must be alphanumeric, case-sensitive, and cannot contain spaces or special characters other than dashes (-) or underscores (_).
Log in to IBM Cloud through the IBM Cloud CLI with the following command:

ibmcloud login

If the login fails, run the ibmcloud login --sso command to try again. The --sso parameter is required when you log in with a federated ID. If this option is used, go to the link listed in the CLI output to generate a one-time passcode.
3. Select the region and resource group where you want to create a Hyper Protect Crypto Services service instance. You can use the following command to set your target region and resource group.

ibmcloud target -r <region_name> -g <resource_group_name>

Replace the variables in the sample command according to the following table.



Table 1. Describes command variables to set the target region and resource group

 Variables Description 

 region_name The region abbreviation, such as us-south or au-syd, 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-regions). 
 resource_group_name The resource group where you organize and manage the instance. You can select the initial resource group that is named Default or other groups that you create. For more information, see [Creating and managing resource groups](https://cloud.ibm.com/docs/account?topic=account-rgs). 



4. Run the following command to create a Hyper Protect Crypto Services instance:

ibmcloud resource service-instance-create <instance_name> hs-crypto standard <region_name> [-p '{"units": <number_of_operational_crypto_units>, "allowed_network": "<network_access>", "failover_units": <number_of_failover_crypto_units>}']

Replace the variables in the example command according to the following table.



Table 2. Describes command variables to create a Hyper Protect Crypto Services service instance

 Variables Description 

 instance_name Required.
[Retrieve your authentication credentials to work with the API](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-set-up-kms-api).

To change a network access policy, you must be assigned a Manager access policy for your Hyper Protect Crypto Services instance. To learn how IAM (identity and access management) roles map to Hyper Protect Crypto Services service actions, check out [Service access roles](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-manage-accessservice-access-roles).
2. Update the network access policy for your Hyper Protect Crypto Services instance by running the following cURL command.

$ curl -X PUT "https://api.<region>.hs-crypto.cloud.ibm.com/api/v2/instance/policies?policy=allowedNetwork" -H "accept: application/vnd.ibm.kms.policy+json" -H "authorization: Bearer <IAM_token>" -H "bluemix-instance: <instance_ID>" -H "content-type: application/vnd.ibm.kms.policy+json" -d '{
"metadata": {
"collectionType": "application/vnd.ibm.kms.policy+json",
"collectionTotal": 1
},
"resources": [
{
"policy_type": "allowedNetwork",
"policy_data": {
"enabled": true,
"attributes": {
"allowed_network": "<access_type>"
}
}
}
]
}'

Replace the variables in the example request according to the following table.



Table 1. Describes the variables needed to set a network access policy at the instance level

 Variable Description 

 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.