--- name: hs-crypto-secure-connection title: Using service endpoints to privately connect to Hyper Protect Crypto Services description: 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. last-updated: 2026-07-01 --- > ## Documentation Index > The table of contents for this documentation set is at https://cloud.ibm.com/docs/hs-crypto?format=markdown > The index for all IBM Cloud docs is at: https://cloud.ibm.com/docs/llms.txt > Use these files to discover more information as needed. # Using service endpoints to privately connect to Hyper Protect Crypto Services {: #secure-connection} IBM Cloud® Hyper Protect Crypto Services is deprecated. As of 28 March 2026, you can't create new instances, and access to free instances will be removed. Existing premium plan instances are supported until 28 March 2027. Any instances that still exist on that date will be deleted. {: deprecated} 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. {: shortdesc} ## Understanding the network access policy {: #understand-network-access-policies} 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. {: important} 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 {: #public-and-private} 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 {: #private-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`. {: note} 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](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-initialize-hsm&format=markdown) or [Initializing service instances using smart cards and the Management Utilities](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-initialize-hsm-management-utilities&format=markdown) for instructions. * When you [provision a service instance](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-provision&format=markdown), you can choose between the `private-only` and `public-and-private` options using either the UI or CLI. * [Manage and update the network settings](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-managing-network-access-policies&format=markdown) 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. {: important} ## Before you begin {: #private-endpoint-prereqs} 1. Ensure that your IBM Cloud infrastructure account is enabled for [virtual routing and forwarding (VRF)](https://cloud.ibm.com/docs/account?topic=account-vrf-service-endpoint&format=markdown#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](https://cloud.ibm.com/docs/direct-link?topic=direct-link-overview-of-virtual-routing-and-forwarding-vrf-on-ibm-cloud&format=markdown). 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. {: important} 2. Ensure that your IBM Cloud infrastructure account is enabled for [service endpoints](https://cloud.ibm.com/docs/account?topic=account-vrf-service-endpoint&format=markdown#service-endpoint). 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](https://cloud.ibm.com/docs/account?topic=account-service-endpoints-overview&format=markdown). 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. {: note} ## Step 1: Configure the private network of IBM Cloud on your virtual server {: #configure-network} Prepare your VSI or test machine by configuring your routing table for the private network of IBM Cloud. 1. To route traffic to the private network of IBM Cloud, run the following command on your VSI: ```sh route add -net 166.9.0.0/16 gw dev ``` {: pre} Replace `` (for example, `10.x.x.x`) and `` (for example, `eth10`) with the appropriate values. 2. Optional: Verify that the route was added successfully by displaying your new routing table. ```sh route -n ``` {: pre} ## Step 2: Provision a service instance and select the network access {: #service-endpoint-private-endpoints} When you [provision a service instance](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-provision&format=markdown), 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](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-managing-network-access-policies&format=markdown) 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. {: tip} ## Step 3: Target the Hyper Protect Crypto Services private endpoint for the TKE CLI plug-in {: #target-tke-private-endpoint} 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. 1. From the command line, log in to IBM Cloud. ```sh ibmcloud login ``` {: pre} 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. {: note} 2. 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](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-regions&format=markdown#available-regions) that your service instance is created in. ``` export TKE_PRIVATE_ADDR=https://tke.private.us-south.hs-crypto.cloud.ibm.com ``` {: pre} 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..hs-crypto.cloud.ibm.com`. {: important} ## Step 4: Initialize the service instance {: #secure-connection-key-ceremony} 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](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-introduce-service&format=markdown). You can use either [the key part files](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-initialize-hsm&format=markdown) or [smart cards and the Management Utilities](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-initialize-hsm-management-utilities&format=markdown) 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 {: #target-internal-endpoint} 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](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-set-up-grep11-api&format=markdown#form-grep11-api-request). {: note} 1. Optional: Ensure that your account is enabled for VRF and service endpoints. ```sh ibmcloud account show ``` {: pre} 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 ``` {: screen} See [Enabling VRF and service endpoints](https://cloud.ibm.com/docs/account?topic=account-vrf-service-endpoint&format=markdown){: external} to learn how to set up your account for connecting to a private network. {: tip} 2. Set the environment variable to target the Hyper Protect Crypto Services private endpoint. Use the following commands on the [Linux]{: tag-linux} operating system or [macOS]{: tag-macos} only. For how to set environment variables on the [Windows]{: tag-windows} operating system, see [Accessing Key Protect CLI](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-set-up-cli&format=markdown). {: note} Set the KP_PRIVATE_ADDR environment variable to target the private endpoint for the key management service: ``` export KP_PRIVATE_ADDR=https://.api.private..hs-crypto.appdomain.cloud ``` {: pre} 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](https://cloud.ibm.com/apidocs/hs-crypto#getinstance){: external}. The returned value includes the following: ``` { "instance_id": "", "kms": { "public": ".api..hs-crypto.appdomain.cloud", "private":".api.private..hs-crypto.appdomain.cloud" }, "ep11": { "public": ".ep11..hs-crypto.appdomain.cloud", "private":".ep11.private..hs-crypto.appdomain.cloud" } } ``` {: screen} 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. {: important} ## Step 6: Test your private network connection {: #Test-private-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 key](#x6946961){: term} on the private network. 1. [Create a root key](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-create-root-keys&format=markdown) by targeting the private endpoint. ```sh ibmcloud kp create -i ``` {: pre} Replace `` with a human-readable alias for easy identification of your key. Replace `` with [the IBM Cloud instance ID](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-retrieve-instance-ID&format=markdown) that identifies your Hyper Protect Crypto Services service instance. 2. Optional: Verify that the key was created successfully by listing the keys that are available in your Hyper Protect Crypto Services service instance. ```sh ibmcloud kp list -i ``` {: pre} Replace `` with the IBM Cloud instance ID that identifies your Hyper Protect Crypto Services service instance. ## What's next {: #secure-connection-next} To perform key management operations, see: * [The key management service API](https://cloud.ibm.com/apidocs/hs-crypto){: external} * [Key Protect CLI](https://cloud.ibm.com/docs/key-protect?topic=key-protect-key-protect-cli-reference&format=markdown) To perform cryptographic operations, see: * [PKCS #11 API](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-pkcs11-api-ref&format=markdown) * [GREP11 API](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-grep11-api-ref&format=markdown)