Connecting to external keystores

You can use Unified Key Orchestrator to connect to external keystores with the UI, or programmatically with the Unified Key Orchestrator API.

Before you connect to an external keystore, keep in mind the following considerations:

You can connect to keystores that are external to your service instance on IBM Cloud®, or from other cloud providers such as Microsoft Azure Key Vault, Amazon Web Services (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. Other currencies are applied based on the region the service instance is provisioned in.
A managed key can be used for encryption and decryption only after you activate it in at least one keystore.
A keystore can be assigned to only one vault.

Setting up required user access in external keystores

You need to set up user access before you use Unified Key Orchestrator to access keystores in third-party clouds.

Setting up required user access in Azure Key Vault

To set up user access to Azure Key Vault, complete the following steps:

Create a service principal in Azure.
Set up access policy for the Key Vault, granting access to that service principal.

Unified Key Orchestrator requires the following access to be able to manage keys in Azure Key Vault:

create
import
update
list
delete
get
recover
purge
backup
restore

For more information, check out Assign a Key Vault access policy.

Setting up required user access in AWS keystore

Unified Key Orchestrator requires the following access to be able to manage keys in AWS KMS:

ListKeys
CreateKey
GetParametersForImport
ImportKeyMaterial
DeleteAlias
CreateAlias
TagResource
UntagResource
DescribeKey
DeleteImportedKeyMaterial
ListResourceTags
ListAliases
ScheduleKeyDeletion

For more information, check out AWS KMS permissions.

Setting up required user access in Google Cloud KMS

To set up user access to Google Cloud KMS, complete the following steps:

Create a service account in your Google Cloud project.
Create a service account key to establish the identity of the service account. Select JSON for the key type. The private JSON key file will be downloaded directly on your workstation. You need to provide the JSON key file when you use the Unified Key Orchestrator to connect to your Google Cloud KMS keystore.
Create a principal and associate it with the service account, and assign the required IAM roles to the principal. Unified Key Orchestrator requires the following IAM roles to be able to manage keys in Google Cloud KMS:
- Cloud KMS Admin
- Cloud KMS Crypto Operator

Connecting to external keystores with the UI

To connect to an external keystore by using the UI, complete the following steps:

Log in to the Hyper Protect Crypto Services instance.
Click Keystores from the navigation to view all the available keystores.
To connect to an external keystore, click Add keystore.
Under Vault, select a vault for the keystore for access control, and click Next.

If you want to assign the keystore to a new vault, click Create vault. For more instructions, see Creating vaults.
Under Keystore type, select one of the following types and click Next:
- AWS keystore: Create a keystore that can store AWS KMS keys.
- Azure Key Vault: Create a keystore that can store Azure Key Vault keys, both Azure Key Vault (Premium) and Azure Key Vault (Standard) are supported.
- Google Cloud KMS keystore: Create a keystore that can store Google Cloud KMS keys.
- Key Protect: Create a keystore that can store Key Protect keys.
- IBM Cloud KMS keystore in another instance: Create a keystore that can store KMS keys in another Hyper Protect Crypto Services instance.
You can change the currency that is displayed by selecting your country or location. After you connect to the first external keystore, Unified Key Orchestrator base price applies additionally. For more information about pricing, see the pricing sample.

Under Keystore properties, specify the details of based on the keystore type that you want to connect to.

Table 1. AWS Key Management Service properties
Property	Description
Keystore name	A unique, human-readable name for easy identification of your keystore, with 1–100 characters in length. The first character must be a letter (case-sensitive) or digit (0–9). The rest can also be symbols (.-_) or spaces.
Description	(Optional) An extended description for your keystore, with up to 200 characters in length.
Region on AWS	The geographical location where the AWS keystore is located in.
Access key ID on AWS	All requests to AWS KMS must be signed by using an access key ID and a secret access key. For more information, see Understanding and getting your AWS credentials.
Secret access key on AWS	All requests to AWS KMS must be signed by using an access key ID and a secret access key. The secret access key is available for download only when you create it.

Table 2. Azure Key Vault properties
Property	Description
Keystore name	A unique, human-readable name for easy identification of your keystore, with 1–100 characters in length. The first character must be a letter (case-sensitive) or digit (0–9). The rest can also be symbols (.-_) or spaces.
Description	(Optional) An extended description for your keystore, with up to 200 characters in length.
Service name on Azure	The name must match the name of the Key Vault in Azure.
Resource group on Azure	A logical construct that groups multiple resources. Obtain it from the Azure portal.
Service principal client ID on Azure	Application ID that identifies the application of service principal.
Service principal password on Azure	Only password based authentication is supported for service principals.
Tenant ID on Azure	A tenant is the organization that owns and manages a specific instance of Microsoft cloud services. Use Microsoft Entra ID for authenticating requests to the Key Vault.
Subscription ID on Azure	A GUID that uniquely identifies your subscription to use Azure services.

Table 3. Google Cloud KMS keystore properties
Property	Description
Keystore name	A unique, human-readable name for easy identification of your keystore, with 1–100 characters in length. The first character must be a letter (case-sensitive) or digit (0–9). The rest can also be symbols (.-_) or spaces.
Keystore description	(Optional) An extended description for your keystore, with up to 200 characters in length.
Upload JSON key file	The private key file that is downloaded from your service account on Google Cloud in step 2 of Setting up required user access in Google Cloud KMS. The file type must be `.json` and the maximum file size is 4 KB.
Project on Google Cloud	Read only. The name of your Google Cloud project. It is automatically extracted from the JSON key file that you upload.
Location on Google Cloud	The geographical region where you want to store your Google Cloud KMS resources. For more details about the location, see Google Cloud KMS locations.
Key ring on Google Cloud	A human-readable name of the key ring that organizes your keys. The name must be unique within a location. For more information about key rings, see Key rings.
Private key ID on Google Cloud	Read only. The ID of the public/private RSA key pair in Google. It is used for establishing a secure connection to Google Cloud Platform. It is automatically extracted from the JSON key file that you upload.

Table 4. Key Protect keystore properties
Property	Description
Keystore name	A unique, human-readable name for easy identification of your keystore, with 1–100 characters in length. The first character must be a letter (case-sensitive) or digit (0–9). The rest can also be symbols (.-_) or spaces.
Description	(Optional) An extended description for your keystore, with up to 200 characters in length.
Service instance ID on IBM Cloud	The unique identifier that is assigned to your Key Protect service instance. For more information, see Retrieving your instance ID and cloud resource name.
Key ring ID on IBM Cloud	The unique identifier of the key ring in the Key Protect instance that you want to connect to. For more information, see Grouping keys together using key rings. If you are not sure which key ring to connect to, specify `default` to connect to the default key ring.
Key Protect API endpoint	The service endpoint of your Key Protect instance in the format of `https://<region>.kms.cloud.ibm.com`. For more information, see Regions and endpoints.
IBM Cloud Identity and Access Management endpoint	The endpoint of IAM, which is `https://iam.cloud.ibm.com`.
Service ID API key	A unique code that is passed to an API to identify the calling application. For more information, see Managing service ID API keys.

Table 5. IBM Cloud Hyper Protect Crypto Services KMS keystore properties
Property	Description
Keystore name	A unique, human-readable name for easy identification of your keystore, with 1–100 characters in length. The first character must be a letter (case-sensitive) or digit (0–9). The rest can also be symbols (.-_) or spaces.
Description	(Optional) An extended description for your keystore, with up to 200 characters in length.
Service instance ID on IBM Cloud	The unique identifier that is assigned to your service instance. For more information, see Retrieving your instance ID.
Key ring ID on IBM Cloud	The unique identifier of the key ring in the Hyper Protect Crypto Services instance Standard Plan that you want to connect to. For more information, see Managing key rings. If you are not sure which key ring to connect to, specify `default` to connect to the default key ring.
Key management endpoint	The service endpoint of your Hyper Protect Crypto Services instance in the format of `https://api.<region>.hs-crypto.cloud.ibm.com:<port>`. You can get the `<region>` and `<port>` in your provisioned service instance UI dashboard through Overview > Connect > Key managment endpoint URL**.
IBM Cloud Identity and Access Management endpoint	The endpoint of IAM, which is `https://iam.cloud.ibm.com`.
Service ID API key	A unique code that is passed to an API to identify the calling application. For more information, see Managing service ID API keys.

You cannot make further changes to identifying properties that are marked with a Lock icon after the keystore is connected.

Optionally, click Test connection to test the connection to the external keystore that you configure. When completed, click Next to continue.

You can complete the subsequent steps even if the test fails. To adjust the connection settings in case of a connection failure, check and adjust the connection properties. If you connect to an external keystore of type Microsoft Azure Key Vault, after clicking Test connection, you will be notified that whether the keystore is Azure Key Vault (Premium) or Azure Key Vault (Standard).
Under Summary, view the summary of your Azure Key Vault and the estimated additional cost.
After you confirm the keystore details, click Connect to keystore.

If you connect to an external keystore of type Azure Key Vault, a key named EKMF-BYOK-KEK-FOR-IMPORT is automatically created in the Azure Key Vault instance that you connect to. You can view the key from the Azure Key Vault instance UI. Don't delete this key. Otherwise, you will not be able to create and distribute managed keys to the Azure Key Vault instance. For more information, see Why can't I distribute keys in Azure Key Vault.

You have successfully connected to the external keystore that you select.

Connecting to external keystores with the API

To connect to an external keystore through the API, follow these steps:

Retrieve your service and authentication credentials to work with keystores in the service.
Connect to an external keystore by making a POST call to the following endpoint.
```
https://uko.<region>.hs-crypto.cloud.ibm.com:<port>/api/v4/keystores
```
For detailed instructions and code examples about using the API method, check out the Hyper Protect Crypto Services Unified Key Orchestrator API reference doc.

What's next

To watch a use case video on using Unified Key Orchestrator to manage Azure Key Vault, see Managing compliance of a Microsoft Office 365 environment using Hyper Protect Crypto Services with Unified Key Orchestrator.
To watch a use case video on using Unified Key Orchestrator to manage AWS Key Management Service, see Securely managing AWS S3 encryption keys using Hyper Protect Crypto Services with Unified Key Orchestrator.
To find out how to update the connection to an external keystore, check out Editing connection to external keystores.
To find out how to disconnect from an external keystore, check out Disconnecting from external keystores.