Using service endpoints to privately connect to Hyper Protect Crypto Services

To ensure that you have enhanced control and security over your data when you use Hyper Protect Crypto Services, you have the option of using private routes to IBM Cloud® service endpoints. Private routes are not accessible or reachable over the internet. By using the IBM Cloud private service endpoints feature, you can protect your data from threats from the public network and logically extend your private network.

Understanding the network access policy

A network access policy for Hyper Protect Crypto Services instances is an extra policy that customers can use to block a Hyper Protect Crypto Services instance from getting API requests from public or private networks.

The network access policy applies to newly provisioned and existing instances. For existing instances the network access policy is enforced after it is set.

Two options control network access to Hyper Protect Crypto Services instances:

Public and private network access - this is the default
Private network access only

Public and private network access

The Hyper Protect Crypto Services instance accepts API requests from both public and private endpoints.

Public and private network access is the default setting and is used if a policy is not set.

For example, multiple teams are testing a solution that uses Hyper Protect Crypto Services instances. Development and test teams issue API requests from both outside (public endpoints) and inside (private endpoints) the IBM Cloud. You allow public and private API requests to ensure each team has access to Hyper Protect Crypto Services instances during this phase of the project.

Private network access only

The Hyper Protect Crypto Services instance accepts API requests from only private endpoints.

For example, development and testing are complete and the solution that uses Hyper Protect Crypto Services instances is in production. You want to limit API requests to private networks for security reasons. All Hyper Protect Crypto Services API requests must originate from within the IBM Cloud.

After the network access policy is set to private-only, you cannot make any Hyper Protect Crypto Services API calls from the public network, including the API to change the policy. Make sure that the private environment is set up before setting the network access policy to private-only.

There are several ways for you to update the network settings. However, before you update the network access policy, you need to initialize the service instance first. See Initializing service instances with the IBM Cloud TKE CLI plug-in or Initializing service instances using smart cards and the Management Utilities for instructions.

When you provision a service instance, you can choose between the private-only and public-and-private options using either the UI or CLI.
Manage and update the network settings after you provision and initialize the service instance.

After you enable a private-only network, you are not able to perform further key management actions in the UI. Use either the CLI or API to switch between a private-only network and a public-and-private network instead.

The instance access policy, which controls access to the instance from either public or private IP addresses, is not enforced after the ibmcloud resource service-instance-delete (NAME | ID) command to delete the instance is issued.

After you enable the following network settings, both the key management operations using key management service API and the cryptographic operations using GREP11 and PKCS #11 APIs are affected.

Before you begin

Ensure that your IBM Cloud infrastructure account is enabled for virtual routing and forwarding (VRF).

When you enable VRF, a separate routing table is created for your account, and connections to and from your account's resources are routed separately on the IBM Cloud network. To learn more about VRF technology, see Virtual routing and forwarding on IBM Cloud.

Enabling VRF permanently alters networking for your account. Be sure that you understand the impact to your account and resources. After you enable VRF, it cannot be disabled.
Ensure that your IBM Cloud infrastructure account is enabled for service endpoints.

When you enable service endpoints, you can connect to Hyper Protect Crypto Services by using a private IP that is accessible only through the private network of IBM Cloud. To find out more, see Service endpoints for private connections.

After you enable service endpoints for your account, all existing and future Hyper Protect Crypto Services resources and service instances become available from both the public and private endpoint.

Step 1: Configure the private network of IBM Cloud on your virtual server

Prepare your VSI or test machine by configuring your routing table for the private network of IBM Cloud.

To route traffic to the private network of IBM Cloud, run the following command on your VSI:
```
route add -net 166.9.0.0/16 gw <gateway> dev <gateway_interface>
```
Replace <gateway> (for example, 10.x.x.x) and <gateway_interface> (for example, eth10) with the appropriate values.
Optional: Verify that the route was added successfully by displaying your new routing table.
```
route -n
```

Step 2: Provision a service instance and select the network access

When you provision a service instance, you can choose between the private-only and public-and-private options using either the UI or CLI.

You can always manage and update the network settings after you provision and initialize the service instance. Use either the CLI or API to switch between a private-only network and a public-and-private network.

Step 3: Target the Hyper Protect Crypto Services private endpoint for the TKE CLI plug-in

To perform key management and cryptographic operations thought a private endpoint, you need to first target the private endpoint for the Trusted Key Entry (TKE) CLI plug-in.

From the command line, log in to IBM Cloud.
```
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.
Set the TKE_PRIVATE_ADDR environment variable to target the private endpoint for the Trusted Key Entry (TKE) plug-in. Replace with the short name of the location that your service instance is created in.
```
export TKE_PRIVATE_ADDR=https://tke.private.<region>.hs-crypto.cloud.ibm.com
```
The TKE_PRIVATE_ADDR environment variable is used to set the API endpoint URL both for public endpoint and private endpoint. If you want to use the public endpoint, unset the TKE_PRIVATE_ADDR environment variable or set the TKE_PRIVATE_ADDR environment variable as the public endpoint URL: https://tke.<region>.hs-crypto.cloud.ibm.com.

Step 4: Initialize the service instance

If you select the private-only option when you provision the service instance, all subsequent actions are performed in a private network, including initializing a service instance. You can use either the key part files or smart cards and the Management Utilities to initialize the service instance. If you select the public-and-private option, you can initialize the service instance in a public network.

After the service initialization is done, you can still update your network settings by following Managing the network settings.

Step 5: Target the Hyper Protect Crypto Services private endpoint for key management service

If you are using the key management service of Hyper Protect Crypto Services, after you configure your VSI to accept the private network traffic of IBM Cloud, you can target the private endpoint for Hyper Protect Crypto Services by using the Key Protect CLI plug-in.

If you are using the GREP11 service, the service handles the private endpoint connection. You need to only switch your GREP11 service endpoint to the private endpoint per instructions in Generating a GREP11 API request.

Optional: Ensure that your account is enabled for VRF and service endpoints.
```
ibmcloud account show
```
The following CLI output shows the account details of a VRF and service endpoint-enabled account.
```
Retrieving account John Doe's Account of john.doe@email.com...
OK

Account ID:                   d154dfbd0bc2edefthyufffc9b5ca318
Currently Targeted Account:   true
Linked Softlayer Account:     1008967
Service Endpoint Enabled:     true
```
See Enabling VRF and service endpoints to learn how to set up your account for connecting to a private network.
Set the environment variable to target the Hyper Protect Crypto Services private endpoint.

Use the following commands on the Linux operating system or macOS only. For how to set environment variables on the Windows operating system, see Accessing Key Protect CLI.

Set the KP_PRIVATE_ADDR environment variable to target the private endpoint for the key management service:
```
export KP_PRIVATE_ADDR=https://api.private.<region>.hs-crypto.cloud.ibm.com:<port>
```
You can find the Key management private endpoint URL listed in the service dashboard under Overview > Connect > Key management private endpoint URL.

Alternatively, you can dynamically retrieve the API endpoint URL. The returned value includes the following:
```
{
  "instance_id": "<instance_ID>",
  "kms": {
    "public": "api.<region>.hs-crypto.cloud.ibm.com:<port>",
    "private":"api.private.<region>.hs-crypto.cloud.ibm.com:<port>"
    },
    "ep11": {
    "public": "ep11.<region>.hs-crypto.cloud.ibm.com:<port>",
    "private":"ep11.private.<region>.hs-crypto.cloud.ibm.com:<port>"
  }
}
```
The private endpoint URL is returned in private. For key management endpoint, use the value that is returned in the kms section. The KP_PRIVATE_ADDR environment variable is used to set the API endpoint URL both for public endpoint and private endpoint. If you want to use the public endpoint, make sure to set the KP_PRIVATE_ADDR environment variable as the public endpoint URL that is returned in the public field in the kms section.

Step 6: Test your private network connection

You might want to test your network connection after you set up your private network.

To test the private network connection for the key management service, use Key Protect CLI to perform an action towards the Hyper Protect Crypto Services service instance. The following example shows how to create a root keyA symmetric wrapping key that is used for encrypting and decrypting other keys that are stored in a data service. on the private network.

Create a root key by targeting the private endpoint.
```
ibmcloud kp create <key_name> -i <instance_ID>
```
Replace <key_name> with a human-readable alias for easy identification of your key. Replace <instance_ID> with the IBM Cloud instance ID that identifies your Hyper Protect Crypto Services service instance.
Optional: Verify that the key was created successfully by listing the keys that are available in your Hyper Protect Crypto Services service instance.
```
ibmcloud kp list -i <instance_ID>
```
Replace <instance_ID> with the IBM Cloud instance ID that identifies your Hyper Protect Crypto Services service instance.

What's next

To perform key management operations, see:

To perform cryptographic operations, see: