IBM Cloud Docs
Using virtual private endpoints for VPC to privately connect to Hyper Protect Crypto Services

Using virtual private endpoints for VPC to privately connect to Hyper Protect Crypto Services

IBM Cloud® Virtual Private Endpoints (VPE) for Virtual Private Cloud (VPC) enables you to connect to Hyper Protect Crypto Services from your VPC network by using the IP addresses of your choosing, allocated from a subnet within your VPC.

VPEs are virtual IP interfaces that are bound to an endpoint gateway created on a per service, or service instance, basis (depending on the service operation model). The endpoint gateway is a virtualized function that scales horizontally, is redundant and highly available, and spans all availability zones of your VPC. Endpoint gateways enable communications from virtual server instances within your VPC and IBM Cloud® service on the private backbone. VPE for VPC gives you the experience of controlling all the private addressing within your cloud. For more information, see About virtual private endpoint gateways.

To connect to Hyper Protect Crypto Services by using a virtual private endpoint, you must use the Hyper Protect Crypto Services API, CLI, or Terraform. The Hyper Protect Crypto Services UI needs to be accessed through the public network from your VPC.

Before you begin

Before you target a virtual private endpoint for Hyper Protect Crypto Services, you must complete the following tasks:

Setting up a VPE for Hyper Protect Crypto Services

When you create a VPE gateway by using the CLI or API, you must specify the Cloud Resource Name (CRN) of the region in which you want to connect to Hyper Protect Crypto Services. Review the following table for the available regions and CRNs to create your VPE gateways.

Hyper Protect Crypto Services feature Supported endpoints CRN
Key management service api.private.au-syd.hs-crypto.appdomain.cloud crn:v1:bluemix:public:hs-crypto:au-syd:::endpoint: .api.private.au-syd.hs-crypto.appdomain.cloud
api.private.eu-de.hs-crypto.appdomain.cloud crn:v1:bluemix:public:hs-crypto:eu-de:::endpoint: .api.private.eu-de.hs-crypto.appdomain.cloud
api.private.us-east.hs-crypto.appdomain.cloud crn:v1:bluemix:public:hs-crypto:us-east:::endpoint: .api.private.us-east.hs-crypto.appdomain.cloud
api.private.us-south.hs-crypto.appdomain.cloud crn:v1:bluemix:public:hs-crypto:us-south:::endpoint: .api.private.us-south.hs-crypto.appdomain.cloud
api.private.eu-gb.hs-crypto.appdomain.cloud crn:v1:bluemix:public:hs-crypto:eu-gb:::endpoint: .api.private.eu-gb.hs-crypto.appdomain.cloud
api.private.jp-tok.hs-crypto.appdomain.cloud crn:v1:bluemix:public:hs-crypto:jp-tok:::endpoint:api.private.jp-tok.hs-crypto.appdomain.cloud
api.private.eu-es.hs-crypto.appdomain.cloud crn:v1:bluemix:public:hs-crypto:eu-es:::endpoint:api.private.eu-es.hs-crypto.appdomain.cloud
api.private.br-sao.hs-crypto.appdomain.cloud crn:v1:bluemix:public:hs-crypto:br-sao:::endpoint:api.private.jbr-sao.hs-crypto.appdomain.cloud
api.private.ca-tor.hs-crypto.appdomain.cloud crn:v1:bluemix:public:hs-crypto:ca-tor:::endpoint:api.private.ca-tor.hs-crypto.appdomain.cloud
Enterprise PKCS #11 (EP11) .ep11.private.au-syd.hs-crypto.appdomain.cloud crn:v1:bluemix:public:hs-crypto:au-syd:::endpoint: .ep11.private.au-syd.hs-crypto.appdomain.cloud
ep11.private.eu-de.hs-crypto.appdomain.cloud crn:v1:bluemix:public:hs-crypto:eu-de:::endpoint: .ep11.private.eu-de.hs-crypto.appdomain.cloud
ep11.private.us-east.hs-crypto.appdomain.cloud crn:v1:bluemix:public:hs-crypto:us-east:::endpoint: .ep11.private.us-east.hs-crypto.appdomain.cloud
ep11.private.us-south.hs-crypto.appdomain.cloud crn:v1:bluemix:public:hs-crypto:us-south:::endpoint: .ep11.private.us-south.hs-crypto.appdomain.cloud
ep11.private.eu-gb.hs-crypto.appdomain.cloud crn:v1:bluemix:public:hs-crypto:eu-gb:::endpoint:ep11.vpc.private.eu-gb.hs-crypto.appdomain.cloud
ep11.private.jp-tok.hs-crypto.appdomain.cloud crn:v1:bluemix:public:hs-crypto:jp-tok:::endpoint:ep11.vpc.private.jp-tok.hs-crypto.appdomain.cloud
ep11.private.eu-es.hs-crypto.appdomain.cloud crn:v1:bluemix:public:hs-crypto:eu-es:::endpoint:ep11.vpc.private.eu-es.hs-crypto.appdomain.cloud
ep11.private.br-sao.hs-crypto.appdomain.cloud crn:v1:bluemix:public:hs-crypto:br-sao:::endpoint:ep11.vpc.private.jbr-sao.hs-crypto.appdomain.cloud
ep11.private.ca-tor.hs-crypto.appdomain.cloud crn:v1:bluemix:public:hs-crypto:ca-tor:::endpoint:ep11.vpc.private.ca-tor.hs-crypto.appdomain.cloud
Trusted Key Entry (TKE) tke.private.au-syd.hs-crypto.cloud.ibm.com crn:v1:bluemix:public:hs-crypto:au-syd:::endpoint:tke.private.au-syd.hs-crypto.cloud.ibm.com
tke.private.eu-de.hs-crypto.cloud.ibm.com crn:v1:bluemix:public:hs-crypto:eu-de:::endpoint:tke.private.eu-de.hs-crypto.cloud.ibm.com
tke.private.us-east.hs-crypto.cloud.ibm.com crn:v1:bluemix:public:hs-crypto:us-east:::endpoint:tke.private.us-east.hs-crypto.cloud.ibm.com
tke.private.us-south.hs-crypto.cloud.ibm.com crn:v1:bluemix:public:hs-crypto:us-south:::endpoint:tke.private.us-south.hs-crypto.cloud.ibm.com
tke.private.eu-gb.hs-crypto.cloud.ibm.com crn:v1:bluemix:public:hs-crypto:eu-gb:::endpoint:tke.vpc.private.eu-gb.hs-crypto.cloud.ibm.com
tke.private.jp-tok.hs-crypto.cloud.ibm.com crn:v1:bluemix:public:hs-crypto:jp-tok:::endpoint:tke.vpc.private.jp-tok.hs-crypto.cloud.ibm.com
tke.private.eu-es.hs-crypto.cloud.ibm.com crn:v1:bluemix:public:hs-crypto:eu-es:::endpoint:tke.vpc.private.eu-es.hs-crypto.cloud.ibm.com
tke.private.br-sao.hs-crypto.cloud.ibm.com crn:v1:bluemix:public:hs-crypto:br-sao:::endpoint:tke.vpc.private.jbr-sao.hs-crypto.cloud.ibm.com
tke.private.ca-tor.hs-crypto.cloud.ibm.com crn:v1:bluemix:public:hs-crypto:ca-tor:::endpoint:tke.vpc.private.ca-tor.hs-crypto.cloud.ibm.com
Key Management Interoperability Protocol (KMIP) adapter kmip.private.au-syd.hs-crypto.appdomain.cloud crn:v1:bluemix:public:hs-crypto:au-syd:::endpoint: .kmip.private.au-syd.hs-crypto.appdomain.cloud
kmip.private.eu-de.hs-crypto.appdomain.cloud crn:v1:bluemix:public:hs-crypto:eu-de:::endpoint: .kmip.private.eu-de.hs-crypto.appdomain.cloud
kmip.private.us-east.hs-crypto.appdomain.cloud crn:v1:bluemix:public:hs-crypto:us-east:::endpoint: .kmip.private.us-east.hs-crypto.appdomain.cloud
kmip.private.us-south.hs-crypto.appdomain.cloud crn:v1:bluemix:public:hs-crypto:us-south:::endpoint: .kmip.private.us-south.hs-crypto.appdomain.cloud
kmip.private.eu-gb.hs-crypto.appdomain.cloud crn:v1:bluemix:public:hs-crypto:eu-gb:::endpoint:kmip.private.eu-gb.hs-crypto.appdomain.cloud
kmip.private.jp-tok.hs-crypto.appdomain.cloud crn:v1:bluemix:public:hs-crypto:jp-tok:::endpoint:kmip.private.jp-tok.hs-crypto.appdomain.cloud
kmip.private.eu-es.hs-crypto.appdomain.cloud crn:v1:bluemix:public:hs-crypto:eu-es:::endpoint:kmip.private.eu-es.hs-crypto.appdomain.cloud
kmip.private.br-sao.hs-crypto.appdomain.cloud crn:v1:bluemix:public:hs-crypto:br-sao:::endpoint:kmip.private.jbr-sao.hs-crypto.appdomain.cloud
kmip.private.ca-tor.hs-crypto.appdomain.cloud crn:v1:bluemix:public:hs-crypto:ca-tor:::endpoint:kmip.private.ca-tor.hs-crypto.appdomain.cloud
Table 1. Available region endpoints and CRNs for creating VPE gateways

Configuring an endpoint gateway

To configure a virtual private endpoint gateway, follow these steps:

  1. List the available services, including IBM Cloud infrastructure services available (by default) for all VPC users.

  2. Create an endpoint gateway for your Hyper Protect Crypto Services instance that you want to be privately available to the VPC.

    If you are creating a VPE gateway by using the UI, perform the following steps:

    1. Select the Menu icon Menu icon, and then click VPC Infrastructure > Virtual private endpoint gateways in the Network section, and then click Create. The New virtual private endpoint gateway for VPC page is displayed.

    2. In the Cloud service section, enable your Hyper Protect Crypto Services instance:

      • Under Cloud service offerings, select Hyper Protect Crypto Services.
      • Under Cloud service regions, verify the corresponding region is pre-filled for your provisioned Hyper Protect Crypto Services instance.
      • Select the private endpoint that you are going to use to connect with your VPC instance. If you are connecting to an EP11 private endpoint, make sure that you select all EP11 private endpoints for all available zones.
  3. Bind a reserved IP address to the endpoint gateway.

  4. View the created VPE gateways associated with the Hyper Protect Crypto Services instance. For more information, see Viewing details of an endpoint gateway.

Now your virtual server instances in the VPC can access your Hyper Protect Crypto Services instance privately through it.

Using your VPE for Hyper Protect Crypto Services

After you create an endpoint gateway for your Hyper Protect Crypto Services instance, follow these steps to use private endpoints.

Using the VPE with the CLI

  • Using the VPE for the TKE CLI plug-in

    1. Update the TKE CLI plug-in to the latest version with the following command:

      ibmcloud plugin update tke
      
    2. To initialize service instances with the TKE CLI plug-in, set the TKE_PRIVATE_ADDR environment variable to target the TKE private endpoint:

      export TKE_PRIVATE_ADDR=https://tke.private.<region>.hs-crypto.cloud.ibm.com
      
  • Using the VPE for the Key Protect CLI plug-in

    1. Update the Key Protect CLI plug-in to the latest version with the following command:

      ibmcloud plugin update key-protect -r "IBM Cloud"
      
    2. To perform key management operations with the Key Protect CLI plug-in, set the KP_PRIVATE_ADDR environment variable to target the key management service private endpoint:

      export KP_PRIVATE_ADDR=https://<instance_ID>.api.private.<region>.hs-crypto.appdomain.cloud
      

Using the VPE with the API

  • Using the VPE for the key management service API

    To perform key management operations with the key management service API, use the key management service private endpoints in the API request URL to access the service. For example,

    curl GET \
      https://<instance_ID>.api.private.<region>.hs-crypto.appdomain.cloud/api/v2/keys   \
      -H 'authorization: Bearer <IAM_token>'   \
      -H 'bluemix-instance: <instance_ID>'   \
      -H 'accept: application/vnd.ibm.kms.key+json'
    
  • Using the VPE for the PKCS #11 API

    To perform cryptographic operations with the PKCS #11 API, set the address field to the EP11 private endpoint in the configuration file. For more information, see Set up the PKCS #11 configuration file.

  • Using the VPE for the GREP11 API

    To perform cryptographic operations with the GREP11 API, specify the server address with the EP11 private endpoint in the code. For more information, see Generating a GREP11 API request.

Using the VPE with Terraform

To use VPE with Terraform, set the service_endpoints parameter to private-only in the resource block. For more information, see Setting up Terraform for Hyper Protect Crypto Services.

  • If you plan to use private endpoints to initialize your service instance, make sure to set the IBMCLOUD_HPCS_TKE_ENDPOINT environment variable to target the TKE private endpoint. For example,:

    export IBMCLOUD_HPCS_TKE_ENDPOINT=https://tke.private.<region>.hs-crypto.cloud.ibm.com
    
  • If you plan to use private endpoints to manage your key management service keys, make sure to set the IBMCLOUD_KP_API_ENDPOINT environment variable to target the key management service private endpoint. For example,:

    export IBMCLOUD_KP_API_ENDPOINT=https://<instance_ID>.api.private.<region>.hs-crypto.appdomain.cloud