IBM Cloud Hyper Protect Crypto Services

You can use this module to provision an IBM Cloud Hyper Protect Crypto Services (HPCS) instance.

The next step after provisioning an HPCS instance is to initialize the service to manage the keys. This module supports the following approaches:

• Provision and initialize the service by using the recovery crypto units method.
• Provision the service and initialize it manually. For example, by using smart cards or key part files. This approach requires additional steps to execute after provisioning the service instance.
• Provision and initialize the service by using your own hardware security module (HSM).

For more information, see components and concepts of HPCS and about service instance initialization in the Cloud Docs.

If you provision an HPCS instance with a private-only endpoint, both public and private endpoints URLs are included in the output. You can ignore the public endpoint. It is included for convenience in case you need to switch to it temporarily. However, make sure that you switch back to the private endpoint as soon as possible.

Overview

• terraform-ibm-hpcs
• Submodules
  • fscloud
• Examples
  • Basic example
  • Complete example that creates and initialize HPCS instance
  • Financial Services Cloud profile
  • Hybrid-HPCS example
• Contributing

terraform-ibm-hpcs

Usage to create the HPCS instance

provider "ibm" {
  ibmcloud_api_key = "XXXXXXXXXXXXXX"
  region           = "us-south"
}

module "hpcs" {
  source                                          = "terraform-ibm-modules/hpcs/ibm"
  version                                         = "X.X.X" # Replace "X.X.X" with a release version to lock into a specific release
  resource_group_id                               = "xxXXxxXXxXxXXXXxxXxxxXXXXxXXXXX"
  region                                          = "us-south"
  name                                            = "my-hpcs-instance"
  tags                                            = ["tag1","tag2"]
  plan                                            = "standard"
  auto_initialization_using_recovery_crypto_units = false
}

There are multiple ways to initialize the service instance few of them include some manual steps, they are as follows:

• Initializing service instances by using smart cards and the Hyper Protect Crypto Services Management Utilities : This approach gives you the highest security, which enables you to store and manage master key parts using smart cards.
• Initializing service instances by using key part files : You can also initialize your service instance using master key parts that are stored in files on your local workstation. You can use this approach regardless of whether or not your service instance includes recovery crypto units.
• Initializing service instances using recovery crypto units : If you create your service instance in Dallas (us-south) or Washington DC (us-east) where the recovery crypto units are enabled, you can choose this approach where the master key is randomly generated within a recovery crypto unit and then exported to other crypto units.

Create and initialize the Hyper Protect Crypto Services instance

Before you begin: creating administrator signature keys

To initialize the instance with a third-party signing service, see Using a signing service to manage signature keys for instance initialization in the Cloud Docs.

Otherwise, if you are not using a third-party signing service, run the following commands that use the IBM Cloud TKE CLI plug-in to generate admin signature keys.

• Install the IBM Cloud CLI

• Make sure you have a recent version the IBM Cloud Trusted Key Entry (TKE) CLI plug-in installed.

  • Run this command to install the plug-in:

    ibmcloud plugin install tke
    

    Or

  • Run this command to update your plug-in to the latest version with the following command:

    ibmcloud plugin update tke
    

• Set the environment variable CLOUDTKEFILES to specify the directory where you want to save signature key files.

  export CLOUDTKEFILES=<absolute path of directory>
  

• Login in to IBM CLoud CLI and make sure that you're logged in to the correct region and resource group where the service instance locates.

  ibmcloud login
  ibmcloud target -r <region> -g <resource_group>
  

• Run the following command to create administrator signature keys. The signature keys are created in the path specified in CLOUDTKEFILES and stored in files that are protected by passwords. Repeat this step to generate more keys.

  ibmcloud tke sigkey-add
  

ℹ️ Requirement: Make sure that information about the administrator who is associated with the key is set in the admins input variable.

Usage to create and initialize the HPCS instance

provider "ibm" {
  ibmcloud_api_key = "XXXXXXXXXXXXXX"
  region           = "us-south"
}

module "hpcs" {
  source                                          = "terraform-ibm-modules/hpcs/ibm"
  version                                         = "X.X.X" # Replace "X.X.X" with a release version to lock into a specific release
  resource_group_id                               = "xxXXxxXXxXxXXXXxxXxxxXXXXxXXXXX"
  region                                          = "us-south"
  name                                            = "my-hpcs-instance"
  tags                                            = ["tag1","tag2"]
  auto_initialization_using_recovery_crypto_units = true
  number_of_crypto_units                          = 3
  admins = [
    {
      name  = "admin1"
      key   = "/cloudTKE/1.sigkey"
      token = "sensitive1234"
    },
    {
      name  = "admin2"
      key   = "/cloudTKE/2.sigkey"
      token = "sensitive1234"
    }
  ]
}

Usage to create and initialize the HPCS instance using Schematics

• Convert the signature keys to Base64 encoding.

  cat 1.sigkey | base64
  cat 2.sigkey | base64

provider "ibm" {
  ibmcloud_api_key = "XXXXXXXXXXXXXX"
  region           = "us-south"
}

module "hpcs" {
  source                                          = "terraform-ibm-modules/hpcs/ibm"
  version                                         = "X.X.X" # Replace "X.X.X" with a release version to lock into a specific release
  resource_group_id                               = "xxXXxxXXxXxXXXXxxXxxxXXXXxXXXXX"
  region                                          = "us-south"
  name                                            = "my-hpcs-instance"
  tags                                            = ["tag1","tag2"]
  auto_initialization_using_recovery_crypto_units = true
  number_of_crypto_units                          = 3
  base64_encoded_admins = [
    {
      name  = "admin1"
      key   = "eyJlbmNrZXkiOiJyYW5kb21fa2V5Iiwia2V5VHlwZSI6InJhbmRvbSIsIm5hbWUiOiJhZG1pbjEiLCJzZWFTYWx0IjoicmFuZG9tIiwic2tpIjoicmFuZG9tIn0="
      token = "sensitive1234"
    },
    {
      name  = "admin2"
      key   = "eyJlbmNrZXkiOiJyYW5kb20yX2tleSIsImtleVR5cGUiOiJyYW5kb20yIiwibmFtZSI6ImFkbWluMiIsInNlYVNhbHQiOiJyYW5kb20yIiwic2tpIjoicmFuZG9tMiJ9"
      token = "sensitive1234"
    }
  ]
}

Required IAM access policies

You need the following permissions to run this module.

• Account Management
  • Resource Group service
    • Viewer platform access
• IAM Services
  • Hyper Protect Crypto Services service
    • Editor platform access
    • Manager service access

Requirements

Name	Version
terraform	>= 1.3.0
ibm	>= 1.49.0, < 2.0.0
local	>= 2.4.0, < 3.0.0

Modules

No modules.

Resources

Name	Type
ibm_hpcs.hpcs_instance	resource
ibm_resource_instance.base_hpcs_instance	resource
local_file.admin_files	resource

Inputs

Name	Description	Type	Default	Required
admins	A list of administrators for the instance crypto units. See instructions to create administrator signature keys. You can set up to 8 administrators. Required if auto_initialization_using_recovery_crypto_units set to true.	list(object({ name = string # max length: 30 chars key = string # the absolute path and the file name of the signature key file if key files are created using TKE CLI and are not using a third-party signing service # if you are using a signing service, the key name is appended to a URI that will be sent to the signing service token = string # sensitive: the administrator password/token to authorize and access the corresponding signature key file }))	[]	no
auto_initialization_using_recovery_crypto_units	Set to true if auto initialization using recovery crypto units is required.	bool	true	no
base64_encoded_admins	A list of up to 8 administrators for the instance crypto units. Required if auto_initialization_using_recovery_crypto_units is set to true. Pass the signature keys as base64 encoded values. For information about administrator signature keys, see the readme file.	list(object({ name = string # max length: 30 chars key = string # base64 encoded value of signature key files if key files are created using TKE CLI and are not using a third-party signing service token = string # sensitive: the administrator password/token to authorize and access the corresponding signature key file }))	[]	no
create_timeout	Create timeout value of the HPCS instance.	string	"180m"	no
delete_timeout	Delete timeout value of the HPCS instance.	string	"180m"	no
hsm_connector_id	The HSM connector ID provided by IBM required for Hybrid HPCS. Available to selected customers only.	string	null	no
name	The name to give the Hyper Protect Crypto Service instance. Max length allowed is 30 chars.	string	n/a	yes
number_of_crypto_units	The number of operational crypto units for your service instance.	number	2	no
number_of_failover_units	The number of failover crypto units for your service instance. Default is 0 and cross-region high availability will not be enabled.	number	0	no
plan	The name of the service plan that you choose for your Hyper Protect Crypto Service instance.	string	"standard"	no
region	The region where you want to deploy your instance.	string	n/a	yes
resource_group_id	The resource group name where the Hyper Protect Crypto Service instance will be created.	string	n/a	yes
revocation_threshold	The number of administrator signatures required to remove an administrator after you leave imprint mode. Required if auto_initialization_using_recovery_crypto_units set to true.	number	1	no
service_endpoints	The service_endpoints to access your service instance. Used only if auto_initialization_using_recovery_crypto_units is set to true. Can be set to private-only if Terraform has access to the private endpoints. Default value is public-and-private.	string	"public-and-private"	no
signature_server_url	The URL and port number of the signing service. Required if auto_initialization_using_recovery_crypto_units set to true and using a third-party signing service to provide administrator signature keys. Used only if auto_initialization_using_recovery_crypto_units is set to true.	string	null	no
signature_threshold	The number of administrator signatures required to execute administrative commands. Required if auto_initialization_using_recovery_crypto_units set to true.	number	1	no
tags	Optional list of resource tags to apply to the HPCS instance.	list(string)	[]	no
update_timeout	Update timeout value of the HPCS instance.	string	"180m"	no

Outputs

Name	Description
crn	HPCS instance crn
endpoints	HPCS instance endpoints
guid	HPCS instance guid
hpcs_name	HPCS instance name
id	HPCS instance id

Contributing

You can report issues and request features for this module in GitHub issues in the module repo. See Report an issue or request a feature.

To set up your local development environment, see Local development setup in the project documentation.