Repository files navigation

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 toinitialize the service to manage the keys. This module supports the following approaches:

• Provision and initialize the service by using therecovery crypto units method.
• Provision the service andinitialize 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, seecomponents and concepts of HPCS andabout service instance initialization in the Cloud Docs.

If you provision an HPCS instance with aprivate-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.

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

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 releaseresource_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 inDallas (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.

To initialize the instance with a third-party signing service, seeUsing 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-into generate admin signature keys.

• Install theIBM 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 variableCLOUDTKEFILES 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 loginibmcloud target -r <region> -g <resource_group>

• Run the following command to create administrator signature keys. The signature keys are created in the path specified inCLOUDTKEFILES 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 theadmins input variable.

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 releaseresource_group_id="xxXXxxXXxXxXXXXxxXxxxXXXXxXXXXX"region="us-south"name="my-hpcs-instance"tags=["tag1","tag2"]auto_initialization_using_recovery_crypto_units=truenumber_of_crypto_units=3admins=[    {      name="admin1"      key="/cloudTKE/1.sigkey"      token="sensitive1234"    },    {      name="admin2"      key="/cloudTKE/2.sigkey"      token="sensitive1234"    }  ]}

• Convert the signature keys to Base64 encoding.

  cat 1.sigkey| base64cat 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 releaseresource_group_id="xxXXxxXXxXxXXXXxxXxxxXXXXxXXXXX"region="us-south"name="my-hpcs-instance"tags=["tag1","tag2"]auto_initialization_using_recovery_crypto_units=truenumber_of_crypto_units=3base64_encoded_admins=[    {      name="admin1"      key="eyJlbmNrZXkiOiJyYW5kb21fa2V5Iiwia2V5VHlwZSI6InJhbmRvbSIsIm5hbWUiOiJhZG1pbjEiLCJzZWFTYWx0IjoicmFuZG9tIiwic2tpIjoicmFuZG9tIn0="      token="sensitive1234"    },    {      name="admin2"      key="eyJlbmNrZXkiOiJyYW5kb20yX2tleSIsImtleVR5cGUiOiJyYW5kb20yIiwibmFtZSI6ImFkbWluMiIsInNlYVNhbHQiOiJyYW5kb20yIiwic2tpIjoicmFuZG9tMiJ9"      token="sensitive1234"    }  ]}

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

No modules.

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
  }))

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
  }))

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

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