IBM Cloud Docs
Editing connection to external keystores

Editing connection to external keystores

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

You can edit the connection 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.

Editing connection to external keystores with the UI

You can only change the keystore name and connection properties one by one.

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

  1. Log in to the Hyper Protect Crypto Services instance.

  2. Click Keystores from the navigation to view all the available keystores.

  3. Click the external keystore that you want to edit. The Details side panel is displayed.

  4. Click Edit in each property card to update keystore properties.

    Because the keystore connection is already established, you cannot make changes to identifying properties that are marked with a Lock icon.

    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 Read only. The geographical location where the AWS keystore is located in. You cannot edit this property after the keystore is connected.
    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 Read only. The name must match the name of the Key Vault in Azure. You cannot edit this property after the keystore is connected.
    Resource group name on Azure Read only. A logical construct that groups multiple resources together. Obtain it from the Azure portal. You cannot edit this property after the keystore is connected.
    Service principal password on Azure Only password based authentication is supported for service principals.
    Service principal client ID on Azure Application ID that identifies the application of service principal.
    Subscription ID on Azure Read only. A GUID that uniquely identifies your subscription to use Azure services. You cannot edit this property after the keystore is connected.
    Tenant ID on Azure Read only. 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. You cannot edit this property after the keystore is connected.
    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. You cannot edit this property after the keystore is connected.
    Location on Google Cloud The geographical region where you want to store your Google Cloud KMS resources. You cannot edit this property after the keystore is connected. 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. You cannot edit this property after the keystore is connected. 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. You cannot edit this property after the keystore is connected.
    Table 4. IBM 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.
    Key Protect API endpoint Read only. The service endpoint of your Key Protect instance in the format of https://<region>.kms.cloud.ibm.com. You cannot edit this property after the keystore is connected. For more information, see Regions and endpoints.
    IBM Cloud Identity and Access Management endpoint Read only. The endpoint of IAM, which is https://iam.cloud.ibm.com. You cannot edit this property after the keystore is connected.
    Service instance ID on IBM Cloud Read only. The unique identifier that is assigned to your Key Protect service instance. You cannot edit this property after the keystore is connected. For more information, see Retrieving your instance ID and cloud resource name.
    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 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.
    Hyper Protect Crypto Services API endpoint Read only. The service endpoint of your Hyper Protect Crypto Services instance in the format of https://<instance_ID>.uko.<region>.hs-crypto.appdomain.cloud. You can get the <region> and <instance_ID> in your provisioned service instance UI dashboard through Overview > Connect > Unified Key Orchestrator endpoint URL. You cannot edit this property after the keystore is connected.
    IBM Cloud Identity and Access Management endpoint Read only. The endpoint of IAM, which is https://iam.cloud.ibm.com. You cannot edit this property after the keystore is connected.
    Service instance ID on IBM Cloud Read only. The unique identifier that is assigned to your service instance. You cannot edit this property after the keystore is connected. For more information, see Retrieving your instance ID.
    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.
  5. Click Save to save the changes.

You can search for a specific keystore by using the search bar, or filter keystores based on your needs by clicking the Filter icon Filter icon in the Keystores table.

Editing connection to external keystores with the API

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

  1. Retrieve your service and authentication credentials to work with keystores in the service.

  2. Edit the connection to an external keystore by making a PATCH call to the following endpoint.

    https://<instance_ID>.uko.<region>.hs-crypto.appdomain.cloud/api/v4/keystores/<id>
    
    

    Replace <id> with the ID of your keystore.

    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