About Key Protect on Satellite

Limitations and scope

The first release of the Key Protect on Satellite provides the basic functions to allow for secure handling of the encryption keys for the key services available in Satellite, such as IBM Cloud Public (ROKS) and Cloud Object Storage (COS).

• At present, the only locations supported in this offering are in user-owned on-prem Satellite locations associated with the IBM Cloud us-east and eu-de host Multi-Zone Regions (MZRs), though eventually it will be available in Satellite locations associated with all IBM Cloud MZRs that Satellite supports. Note that each IBM Cloud MZR can host multiple Satellite locations that are in close proximity to that MZR. While it is possible for a user to have their HSMs in another location as long as there is network connectivity (preferably on a private network) between the worker nodes hosting Key Protect and your HSMs, the preferred method is a close physical proximity between HSMs and worker nodes.
• To use the CLI with your Key Protect on Satellite instance, you must set the KP_PRIVATE_ADDR environment variable to the Key Protect on Satellite endpoint for the CLI to work. You can also make direct calls to the Key Protect APIs, also through the Key Protect on Satellite endpoint. For more information about how to obtain the Key Protect on Satellite endpoint from GhoST, check out Obtaining the Key Protect endpoint.
• All of the metrics that are typically available through IBM Cloud Monitoring and are not available in the initial Key Protect on Satellite release, but will be added in a future release. Because Key Protect does not have the ability to receive logs from an HSM, the security monitoring of the HSMs are the responsibility of the owner of the HSM. To receive auditing logs, you must create an IBM Cloud Activity Tracker instance before provisioning Key Protect on Satellite using the process described in Using IBM Cloud Activity Tracker with Key Protect. Check out Responsibilities for more information about the responsibilities taken on by IBM and those you must cover.
• End-to-end key lifecycle service integrations and sync of associated resources is not currently supported in Key Protect on Satellite.
• While you can assign fine-grained access to a single key, note that calling the list keys API will not return keys that you have been assigned individual access to (that only you can access, in other words). Calling this API will however return the keys in key rings you have access to (if you have access to all of the keys in an instance, you will see all keys). You can, however, see the keys that only you have access to by following the instructions in Granting access to keys to view the key through IAM or by using the API to pass the specific key ID.

Responsibilities

The division of responsibilities between the end-user and IBM for the Key Protect on Satellite service are derived from the responsibilities inherent in Satellite itself, which can be found in Your responsibilities. Study this document carefully, as it outlines a number of important considerations and preparations a user must keep in mind when operating any service on Satellite.

In addition to understanding the responsibilities when using Satellite, there are a number of specific considerations to keep in mind when operating Key Protect on Satellite.

If you're familiar with Understanding your responsibilities with using Key Protect (the fully managed Key Protect on IBM Cloud service), you know that using Key Protect on Satellite shifts several responsibilities from IBM to you.

User responsibilities:

• Ensure your HSM is properly configured to work with Key Protect. The details of the process to configure your HSM can only be obtained by contacting IBM directly. Check out Deploying or modifying an HSM to work with Key Protect for more information.
• Allocate worker nodes and HSM as specified in Before you begin.
• Ensure network connectivity between HSM and worker nodes has been established.
• Provision Key Protect on Satellite using the instructions in Deploying Key Protect on Satellite.
• Give the Key Protect service the following service-to-service authorizations in your Satellite location: Satellite Cluster Creator, Satellite Link Source Access Controller and Satellite Link Administrator. Until these authorizations are given, it is not possible for a Satellite cluster to be created for Key Protect. Once the authorization is set, Key Protect is allowed to start the process of deploying Key Protect on your worker nodes, a process that can take up to several hours. Once the deployment is completed, you will receive a completion status on your Key Protect service provision.
• When you update the operating system in your worker nodes, ensure that it does not disrupt the service. Check out Understanding Satellite location and hosts for more information.

Key Protect on Satellite responsibilities:

• Running Key Protect maintenance and updates in your Satellite location.
• Ensuring the security of key operations and key-related processes.
• Sending audit logs through IBM Cloud Activity Tracker.
• Support for issues related to the proper working of Key Protect.

It is recommended to coordinate with the Key Protect support team when maintaining your HSM, rotating keys, or performing other kinds of infrastructure maintenance.

Using IBM Cloud Activity Tracker with Key Protect

All activity in Key Protect is audited using IBM Cloud Activity Tracker. To get auditing logs through IBM Cloud Activity Tracker, you must first create an IBM Cloud Activity Tracker instance in IBM Cloud and then pass an ingestion key during the deployment of Key Protect. This ingestion key allows Key Protect logs to be sent to your IBM Cloud Activity Tracker instance, where you can view them. For more information on IBM Cloud Activity Tracker events, check out Key Protect events.

For more information on creating an ingestion key, check out the IBM Logging API reference doc.

In Key Protect on Satellite, the target.ResourceGroupID value is always blank and the target.name is only visible if the resource targeted is a single Key Protect key. To find the relevant events for your instance when either target.ResourceGroupID or target.name is returned blank, search using the cloud resource name (CRN) of your Key Protect on Satellite service. For more information about how to determine your CRN using the UI, CLI, or API, check out Retrieving your instance ID and cloud resource name (CRN).

Deploying IBM Cloud Databases on Satellite

After you have provisioned a PostgreSQL ICD instance into your account, you must extract information about your instance and share it with your service representative.

First, create a service key credential for the instance by issuing:

ibmcloud resource service-key-create $service_key_name --instance-id $db_instance_guid

Then issue the following query:

ibmcloud resource service-key --output json $service_key_name

This will output a lot of information. You will need six specific values:

1. db name (e.g., ibmclouddb), which can be found at: credentials.connection.postgres.database
2. db connection hostname, which can be found at: credentials.connection.postgres.hosts.hostname
3. db connection port number, which can be found at: credentials.connection.postgres.hosts.port
4. db authentication username, which can be found at: credentials.connection.postgres.authentication.username
5. db authentication password, which can be found at: credentials.connection.postgres.authentication.password
6. db connection certificate (in base64 encoded format), which can be found at: credentials.connection.postgres.certificate.certificate_base64

Obtaining the Key Protect endpoint

To use the CLI or the APIs to perform key actions against Key Protect on Satellite, you must set the KP_PRIVATE_ADDR environment variable to the Key Protect on Satellite endpoint and target the endpoint for your service. This endpoint is created dynamically during the creation process.

To get the endpoint of your service:

1. Log in to the IBM Cloud CLI.

2. Before you can set your Satellite location, you must retrieve it, which you can do by issuing: ibmcloud sat endpoint get --location {Your_Satellite_Location} --endpoint KP-SATLINK-ENDPOINT --output json | jq -r .server_host

3. You can then set your Satellite location by issuing: export KP_PRIVATE_ADDR=<Value output from step 2>"

High availability and fault tolerance

Because your Satellite location is an extension of the host IBM Cloud MZR, it maintains periodic communication to the host MZR using IBM Cloud Satellite Link connectivity. To avoid Key Protect availability impacts due to possible communication disruptions, it is important to follow high availability best practices.

Key Protect caches authorization requests for up to 30 minutes to maintain availability to existing active users. As a result, if the link goes down for less than 30 minutes, existing active users will not be affected, since their authorizations can be verified from the cache. However, new policy changes (for example, to revoke access from a user) made during the down time will not be effective and Key Protect will continue to allow access based on the previous policy. Similarly, users added during the down time remain unknown to Key Protect and will be denied access until communication is restored.

Auditing logs cannot be sent to your IBM Cloud Activity Tracker instance during the down time. However, these logs are stored and when the link has been restored will resume at the interruption point

If the disruption between the Satellite location and IBM Cloud lasts longer than 30 minutes, the authorization cache will expire and Key Protect on Satellite will be unavailable. Similarly, if the storage limit for auditing logs is reached, additional logs can no longer be stored. At this point, only the logs that have already been stored are sent when service is resumed.