vania-janet/multiturn-rag-retrieval-data huggingface dataset:
The app manages the metadata for GitHub repositories and provides access to the statistics for data analytics. The traffic data is collected from GitHub either on-demand in the app or when triggered by Code Engine events, e.g., daily. The app discussed in this tutorial implements a multi-tenant-ready solution with the initial set of features supporting a single-tenant mode.

Code Engine Db2 on Cloud

+1

App ID



* 1 hour
* 2023-06-16



[Using Hyper Protect Crypto Services PKCS #11 for IBM Db2 native encryption](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-tutorial-db2-pkcs11)Using Hyper Protect Crypto Services PKCS #11 for IBM Db2 native encryption

IBM Db2® native encryption protects key database files and database backup images from inappropriate access while they are stored on external storage media. The database system automatically encrypts and decrypts data when it is used by authorized users and applications. Typically, database users do not need to be aware of native encryption and database client applications do not need to be adapted specifically.

Hyper Protect Crypto Services



* 2 hours
* 2023-02-08



[Configuring KMIP for key management and distribution in Hyper Protect Crypto Services Standard Plan](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-tutorial-kmip-vmware)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.

Hyper Protect Crypto Services



* 2 hours
* 2023-07-04
Managing your keys with the key management service API 

IBM Cloud® Hyper Protect Crypto Services provides a [key management service API](https://cloud.ibm.com/apidocs/hs-crypto) to store, retrieve, and generate encryption keys.



 Retrieving your IBM Cloud credentials 

To work with the API, you need to generate your service and authentication credentials. To gather your credentials:



1. [Generate an IBM Cloud IAM access token](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-retrieve-access-token).
2. [Retrieve the instance ID that uniquely identifies your Hyper Protect Crypto Services service instance](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-retrieve-instance-ID).







 Forming your key management service API request 

When you make an API call to the service, structure your API request according to how you initially provisioned your instance of Hyper Protect Crypto Services.

To build your request, pair a [regional service endpoint](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-regions) with the appropriate authentication credentials. For example, if you created a service instance for the us-south region, use the following endpoint and API headers to browse keys in your service:

curl -X GET 
https://api.us-south.hs-crypto.cloud.ibm.com:<port>/api/v2/keys 
-H 'accept: application/vnd.ibm.collection+json' 
-H 'authorization: Bearer <access_token>' 
-H 'bluemix-instance: <instance_ID>'



* Replace <port> with the port number of your API endpoint. You can get the <port> in your provisioned service instance dashboard through Overview > Key management endpoint URL. Or, you can dynamically [retrieve the API endpoint URL](https://cloud.ibm.com/apidocs/hs-cryptogetinstance).
Check whether the crypto units that you want to zeroize are marked as true. If not, add the crypto units by running the following command:

ibmcloud tke cryptounit-add

A list of the crypto units in the target resource group under the current user account is displayed. When prompted, enter crypto unit numbers to be zeroized to the selected crypto unit list.







 Step 2: Zeroize crypto units 

If you initialize your service instance and load the

master keyto the service instance, you need to set the crypto units back to imprint mode with the following steps:



1. Clear all crypto unit administrators and the master key registers with one of the following options:



* If you initialize your service instance through IBM Cloud Trusted Key Entry (TKE) command-line interface (CLI) plug-in, run the following command to zeroize the crypto units in the TKE CLI plug-in:

ibmcloud tke cryptounit-zeroize
* If you initialize your service instance through the Management Utilities, in the user interface of the TKE application, select Imprint mode > Zeroize crypto unit.



2. To zeroize the crypto units, enter the password for the administrator signature key to be used when prompted. Make sure that your signature key files are properly saved either on your workstation or on your smart cards. Otherwise, you are not able to perform this action.



After you zeroize the crypto unit, the administrator

signature keysand the master key are cleared from the crypto unit, which means you are not able to access keys that are protected by the master key. Any resources that are associated with the root keys cannot be accessed. However, you might still be charged for the resources, such as the [Immutable Object Storage](https://cloud.ibm.com/docs/cloud-object-storage?topic=cloud-object-storage-immutable), as long as the policy is enforced.





 Step 3: Optional - Uninstall the Hyper Protect Crypto Services utilities 

Before you delete the service instance, you might want to uninstall the utilities that are associated with Hyper Protect Crypto Services first.
Understanding your responsibilities when using IBM Cloud Hyper Protect Crypto Services 

Learn about the management responsibilities and terms and conditions that you have when you use IBM Cloud® Hyper Protect Crypto Services. For a high-level view of the service types in IBM Cloud and the breakdown of responsibilities between the customer and IBM for each type, see [Shared responsibilities for IBM Cloud offerings](https://cloud.ibm.com/docs/overview?topic=overview-shared-responsibilities).

Review the following sections for the specific responsibilities for you and for IBM when you use Hyper Protect Crypto Services. For the overall terms of use, see [IBM Cloud Terms and Notices](https://cloud.ibm.com/docs/overview/terms-of-use?topic=overview-terms).



 Incident and operations management 

Incident and operations management includes tasks such as high availability, monitoring, and incident management. You and IBM share responsibilities for the set up and maintenance of your Hyper Protect Crypto Services service instance for your application workloads. You are responsible for incident and operations management of your application data.



Table 1. Responsibilities for incident and operations

 Task IBM responsibilities Your responsibilities 

 Monitoring Provide integration with select third-party partnership technologies, such as IBM Cloud® Activity Tracker. Use the provided tools to [review instance logs and activities](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-at-events). 
 Incidents Provide notifications for planned maintenance, security bulletins, or unplanned outages. Set preferences to [receive emails about platform notifications](https://cloud.ibm.com/docs/overview?topic=overview-uiemail-prefsl), and monitor the [IBM Cloud status page](https://cloud.ibm.com/status?selected=announcement) for general announcements. 
 Firmware updates Provide firmware updates for multiple crypto units in a sequential manner with no impact to running workloads. Perform tasks as usual. 
 Connecting to third-party cloud Provide error messages when access to the third-party keystores does not work. Contact affected third-party cloud service provider to resolve access or connection issues. 







 Change management
Create a crypto map to pull together the various elements of the VPN tunnel, and activate it on the outside interface. 150.239.170.57 is the public IP of the IBM policy-based VPN gateway.

crypto map ibm_vpc 1 match address outside_cryptomap_ibm_vpc_zone2
crypto map ibm_vpc 1 set peer 150.239.170.57
crypto map ibm_vpc 1 set ikev2 ipsec-proposal ibm-vpc-proposal
crypto map ibm_vpc 1 set pfs group19
crypto map ibm_vpc interface outside

If you have NAT rules on the ASAv devices, you must exempt the traffic on the VPN from the NAT rules.

nat (inside,outside) source static on-premise-subnets on-premise-subnets destination static ibm-vpc-zone2-subnets ibm-vpc-zone2-subnets

Configure TCP MSS clamping on ASAv to avoid unnecessary fragmentation:

sysopt connection tcpmss 1360





 Connecting an IBM static, route-based VPN to a Cisco ASAv peer 

These instructions are based on Cisco ASAv, Cisco Adaptive Security Appliance Software Version 9.10(1).

The first step in configuring your Cisco ASAv for use with VPN for VPC is to ensure that the following prerequisite conditions are met:



* Cisco ASAv is online and functional with a proper license.
* A password for the Cisco ASAv is enabled.
* There's at least one configured and verified functional internal interface.
* There's at least one configured and verified functional external interface.



When a Cisco ASAv VPN receives a connection request from VPN for VPC, it uses IKE Phase 1 parameters to establish a secure connection and authenticate to VPN for VPC. Then, if the security policy permits the connection, the Cisco ASAv establishes the tunnel using IPsec Phase 2 parameters and applies the IPsec security policy. Key management, authentication, and security services are negotiated dynamically through the IKE protocol.

To support these functions, the following general configuration steps must be performed on the Cisco ASAv VPN:
Import symmetric keys to Hyper Protect Crypto Services by making a POST call to the following endpoint.

https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys



1. [Retrieve your service and authentication credentials to work with keys in the service](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-set-up-kms-api).
2. Call the [Hyper Protect Crypto Services key management service API](https://cloud.ibm.com/apidocs/hs-crypto) with the following cURL command:

curl -X POST 
https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys 
-H 'authorization: Bearer <IAM_token>' 
-H 'bluemix-instance: <instance_ID>' 
-H 'content-type: application/vnd.ibm.kms.key+json' 
-d '{
"metadata": {
"collectionType": "application/vnd.ibm.kms.key+json",
"collectionTotal": 1
},
"resources": [
{
"type": "application/vnd.ibm.kms.key+json",
"name": "<key_alias>",
"description": "<key_description>",
"expirationDate": "<YYYY-MM-DDTHH:MM:SS.SSZ>",
"payload": "<key_material>",
"extractable": <key_type>
}
]
}'

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



Table 2. Describes the variables needed to add a root key with the API

 Variable Description 

 region Required. The region abbreviation, such as us-south or au-syd, that represents the geographic area where your Hyper Protect Crypto Services instance is located.
Supported parameters for provisioning a service instance with Terraform

 Parameter Description 

 name Required. The name of your Hyper Protect Crypto Services instance. 
 location Required. The region abbreviation, such as us-south, that represents the geographic area where the operational crypto units of your service instance are located. For more information, see [Regions and locations](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-regions). As recovery crypto units are available only in us-south and us-east, only these two regions are supported if you want to use Terraform for instance initialization. 
 plan Required. The pricing plan for your service instance. 
 units Required. The number of operational crypto units for your service instance. Valid values are 2 or 3. 
 failover_units Not applicable. Cross-region high availability is not currently supported for Unified Key Orchestrator. 
 service_endpoints Not applicable. The default setting is public-and-private. 
 tags Optional. Tags that are associated with your instance are used to organize your resources. For more information about tags, see [Working with tags](https://cloud.ibm.com/docs/account?topic=account-tag). 
 resource_group_id Optional. The resource group where you want to organize and manage your service instance. If you do not specify the value, the default resource group is Default. 
 signature_threshold Required. The number of administrator signatures that is required to execute administrative commands. The valid value is in the range 1 - 8. You need to set it to at least 2 to enable quorum authentication. 
 revocation_threshold Required. The number of administrator signatures that is required to remove an administrator after you leave imprint mode. The valid value is in the range 1 - 8. 
 admins Required. The list of administrators for the instance crypto units. You can set up to eight administrators and the number needs to be equal to or greater than the thresholds that you specify. The following values need to be set for each administrator:<br><br>name: <br>The name of the administrator.
Be sure to submit a single request to delete or create crypto, and then expect a wait time of at least 10 minutes before you submit another request. If you don't allow for sufficient time between requests, it's possible for requests to be crossed or errors to occur in creating or updating the crypto.



 Required CSR contents 

For the CSR to be valid, the following information must be entered when you create the CSR:



* Country name: A two-digit code for the country or region. For example, US is the country code for the United States. For other countries or regions, before you create the CSR, check the [list of ISO country codes](https://www.iso.org/obp/ui/search).
* State or province: The full, unabbreviated name of the state or province.
* Locality: The full name of the city or town.
* Organization: The full name of the business or company, as legally registered in your locality, or personal name. For companies, be sure to include the registration suffix, such as Ltd., Inc., or NV.
* Organization unit: The branch name of your company that is ordering the certificate, such as accounting or marketing.
* Common name: The fully qualified domain name (FQDN) for which you’re requesting the SSL certificate. Wildcards are not supported in the common name.



You can use Subject Alternative Names (SAN), but the provided host names must not be issued in other deployed certificates to prevent CN collisions.

A certificate is issued by a certificate authority and is digitally signed by that authority. After you create the CSR, you can generate your SSL certificate on a public certificate authority.







 Uploading SSL certificates 

You can apply a security protocol to provide communication privacy for your app to prevent eavesdropping, tampering, and message forgery. If you have a Lite account, you must upgrade your account to upload a certificate.

In order to use TLS certificates in IBM Cloud Foundry custom domains you need to perform few steps:



1.
Hyper Protect Crypto Services has dependencies on the following IBM Cloud services:



* [IBM Cloud® Identity and Access Management (IAM)](https://cloud.ibm.com/docs/account?topic=account-iamoverview)
* [IBM Cloud Databases for PostgreSQL](https://cloud.ibm.com/docs/databases-for-postgresql?topic=databases-for-postgresql-getting-started)
* [IBM Cloudant](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-getting-started-with-cloudant)
* [IBM Log Analysis](https://cloud.ibm.com/docs/log-analysis?topic=log-analysis-getting-started)
* [IBM Cloud Activity Tracker](https://cloud.ibm.com/docs/activity-tracker?topic=activity-tracker-getting-started)
* [IBM Cloud Monitoring](https://cloud.ibm.com/docs/monitoring?topic=monitoring-getting-started)
Configure IBM Cloud Hyper Protect Crypto Services (HPCS) 

In this section, you can find details on how to configure HPCS and add [IBM Cloud Hyper Protect Crypto Services (HPCS)](https://www.ibm.com/cloud/hyper-protect-crypto) as a keystore in Data Security Broker Manager.



 Overview 

[IBM Cloud Hyper Protect Crypto Services](https://www.ibm.com/cloud/hyper-protect-crypto) offers a cloud hardware security module (HSM) and key management service. It aims to give you control over your cloud hardware security models and cloud data encryption keys as it is the only service in the market built on FIPS 140-2 Level 4-certified hardware.

The HPCS service, which is based on IBM LinuxONE technology, helps to guarantee that only you have access to your keys. Using a dedicated customer-controlled HSM that provides single-tenant key management and key vaulting makes it simple to create encryption keys. You can also bring your own encryption keys to manage instead.





 Configure HPCS instance: 

Configure IBM Cloud Hyper Protect Crypto Services by following the steps below.



1. Get an IBM HPCS Instance ID in one of the following ways:



* Using the IBM CLI – Login to your IBM CLI and execute the following command:





ibmcloud resource service-instance 'HPCS-DSB-1'

Note: If you are using the IBM Cloud web console, navigate to Services and Software and select the HPCS instance. The GUID is displayed in the sidebar and the instanceID is the same as the GUID.



1. Create and retrieve API Key, in the following way: a) Open a web browser and navigate to [https://cloud.ibm.com/iam/apikeys](https://cloud.ibm.com/iam/apikeys). b) Select Create an IBM Cloud API Key and provide a name for the key. c) Copy or download the key after it is created.
2. Create Cloud Object Storage in the resource group.
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 3. Describes command variables to set the target region and resource group for a Hyper Protect Crypto Services instance with Unified Key Orchestrator

 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 hpcs-hourly-uko <region_name> [-p '{"units": <number_of_operational_crypto_units>']

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



 Variables Description 

 instance_name Required. The name of your Hyper Protect Crypto Services service instance. 
 region_name Required. 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).
A target keystore is keystore that is assigned to a vault. You need to create an internal keystore in only one vault, or assign an external keystore to a vault when you connect your service instance to it.

You need to activate a key in a keystore before you can encrypt or decrypt data by using the key.



* Internal keystores

An internal keystore is a keystore that is created in your Hyper Protect Crypto Services instance.

For more information about creating internal keystores, see [Creating internal keystores](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-create-internal-keystores).



* KMS keystores

The key management service component within Hyper Protect Crypto Services provides the Keep Your Own Key (KYOK) feature for IBM Cloud services to ensure that you have access to only the authorized keystores.

You can create up to five free KMS keystores to manage your keys. If you need more keystores for cross-region key distribution or specified access permissions, you are charged. For more information about the pricing, see [FAQs: Pricing](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-faq-pricing).



* External keystores

External keystores are keystores that are not in your service instance. You can connect to keystores that are external to your service instance, such as another Hyper Protect Crypto Services or Key Protect instance, potentially in another region. Or, you can connect to external keystores from other cloud providers such as Key Vault, AWS Key Management Service (KMS), and Google Cloud KMS.

You can connect to one external keystore at no initial cost, regardless of the type. You are charged for additional external keystores. For more information about the pricing, see [FAQs: Pricing](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-faq-pricing).
* 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"
 Keep the 'apikey' empty. It will be overridden by the Anonymous user API key configured later.
apikey:
 The Universally Unique IDentifier (UUID) of your Hyper Protect Crypto Services instance.
instance: "<instance_id>"

tokens:
0:
grep11connection:
 The EP11 endpoint address starting from 'ep11'.
 For example: "ep11.us-south.hs-crypto.cloud.ibm.com"
address: "<EP11_endpoint_URL>"
 The EP11 endpoint port number
port: "<EP11_endpoint_port_number>"
tls:
 Grep11 requires TLS connection.
enabled: true
 Grep11 requires server only authentication, so 'mutual' needs to be set as 'false'.
mutual: false
 'cacert' is a full-path certificate file.
 In Linux with the 'ca-ca-certificates' package installed, this is normally not needed.
cacert:
 Grep11 requires the server-only authentication, so 'certfile' and 'keyfile' need to be empty.
certfile:
keyfile:
storage:
filestore:
enabled: false
storagepath:
 'remotestore' needs to be enabled if you want to generate keys with the attribute CKA_TOKEN.
remotestore:
enabled: true
users:
0: The index of the Security Officer (SO) user MUST be 0.
 The name for the Security Officer (SO) user. For example: "Administrator".
For App Namespace, enter a string to identify the application.
6. For IBM Cloud Hyper Protect Crypto Services Alias, get the Alias name of the Key which has been created in the HPCS instance.
7. For the IAM API Key, use the key you created using Step 2 in Configuring the HPCS section.
8. For IBM region, specify the region for the IBM Cloud Hyper Protect Crypto Services instance. See [Available IBM region listing](https://docs.baffle.io/v1/docs/configure-ibm-key-protect-and-add-it-as-a-keystore-baffleavailable-ibm-region-listing) for more information.
9. For the IBM Cloud Object Storage URL, specify the IBM endpoint URL for COS, for example: [https://s3.us-south.cloud-object-storage.appdomain.cloud](https://s3.us-south.cloud-object-storage.appdomain.cloud)
10. Enter the cos_hmac_keys for the Access Key ID and Secret Key.
11. Click Add Keystore.