SLT - CloudHSM Demo

An AWS CloudHSM cluster demo with KMS Custom Key Store integration

Storm Library for Terraform

This repository is a member of the SLT | Storm Library for Terraform, a collection of Terraform modules for Amazon Web Services. The focus of these modules, maintained in separate GitHub™ repositories, is on building examples, demos and showcases on AWS. The audience of the library is learners and presenters alike - people that want to know or show how a certain service, pattern or solution looks like, or "feels".

Learn more

Installation

This demo can be built using GitHub Actions. In order to do so

• Install the Storm Library for Terraform
• Deploy this member repository

Deployment of this member will take 40-50 minutes on GitHub resources.

Below is a list of resources taking particularly long to deploy:

aws_cloudhsm_v2_hsm	up to 10 minutes
wait_cluster_active	up to 15 minutes
aws_kms_custom_key_store	up to 30 minutes

Architecture

[Image]

Explore this demo

Follow these steps in order to explore this demo:

1. Find and select the cloudhsm-demo controller in the EC2 > Instances view in the AWS Console

2. Click Connect to login into the instance

3. In the terminal that will open inside the browser, enter

   sudo -i
   /opt/cloudhsm/bin/cloudhsm-cli interactive
   

   in order to login as root in your terminal and start the cloudhsm cli in interactive mode

4. In interactive mode, use help to get an overview over available cloudhsm cli commands

5. Try out cluster hsm-info to obtain details about the HSMs in your cluster

6. Login as cloudhsm admin typing

   login --username admin --role admin

   You will be prompted to enter a password. Check the output of the Apply workflow, searching for the admin_password output value. Copy that value (be careful to not copy the surrounding double quotes), paste it into the Enter password: prompt and press Enter ⮐.

7. Type user list to see the users on your cluster. Notice the kmsuser.

8. Try to login as the kmsuser typing

   login --username kmsuser --role crypto-user

   Again, you will be prompted to enter a password. Check the output of the Apply workflow, search for the kmsuser_password, copy-paste and enter it. Login will fail. This is not because the password was wrong, but because the kmsuser has been configured in our code as the crypto user for our CloudHSM cluster, and the CloudHSM service will rotate the password as soon as it has connected to KMS as a custom key store. Check

   https://docs.aws.amazon.com/kms/latest/developerguide/keystore-cloudhsm.html

   for more details.

9. Use the key list command to list all currently defined keys in your CloudHSM. Initially, the list will show zero keys.

10. Feel free to add customer-managed kms keys to your CloudHSM cluster, but

    Understand that you will be generating costs by doing so.

    Even if you delete a KMS key immediately after creation, it will still be alive for the time of a waiting period with a default of 30 days and a minimum of 7 days that you need to set upon deletion. During this period, your key will create costs. However, as you will probably almost never use your key apart from in this demo, it is maybe worth it. Please get yourself informed about standard KMS key charges. Also note that if you have configured customer-managed KMS keys in your CloudHSM,

    The Destroy workflow won't be able to destroy your custom key store.

    The keystore itself won't create any additional costs, but keep in mind to delete it manually after the waiting period. All other resources should always be destroyed by means of the Destroy workflow, especially the CloudHSM instances, which are the really expensive parts of this demo. Please make sure that they have been properly destroyed.

Reference for CloudHSM CLI commands:

• https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-getting-started-use.html
• https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-reference.html

Terraform Docs

Click to show

Requirements

Name	Version
terraform	>= 1
aws	>= 6
cloudinit	>= 2
local	>= 2
null	>= 3
random	>= 3
tls	>= 4

Providers

Name	Version
aws	>= 6
cloudinit	>= 2
local	>= 2
null	>= 3
random	>= 3
tls	>= 4

Modules

Name	Source	Version
controller	git::https://github.com/stormreply/ssm-managed-instance.git	n/a

Resources

Name	Type
aws_cloudhsm_v2_cluster.cluster	resource
aws_cloudhsm_v2_hsm.hsm_one	resource
aws_cloudhsm_v2_hsm.hsm_two	resource
aws_default_subnet.this	resource
aws_iam_policy.controller	resource
aws_key_pair.controller	resource
aws_kms_custom_key_store.cloudhsm	resource
aws_secretsmanager_secret.password	resource
aws_secretsmanager_secret_version.password	resource
aws_security_group.controller	resource
local_file.private_key	resource
null_resource.copy_customer_ca_crt	resource
null_resource.delete_cloudhsm_log_group	resource
null_resource.private_key_chmod	resource
null_resource.wait_cluster_active	resource
random_string.password	resource
random_string.suffix	resource
tls_private_key.controller	resource
aws_availability_zones.available	data source
aws_caller_identity.current	data source
aws_iam_policy_document.controller	data source
aws_region.current	data source
cloudinit_config.controller	data source
local_file.customer_ca_crt	data source

Inputs

Name	Description	Type	Default	Required
_metadata	Select metadata passed from GitHub Workflows	object({ actor = string # Github actor (deployer) of the deployment catalog_id = string # SLT catalog id of this module deployment = string # slt-<catalod_id>-- ref = string # Git reference of the deployment ref_name = string # Git ref_name (branch) of the deployment repo = string # GitHub short repository name (without owner) of the deployment repository = string # GitHub full repository name (including owner) of the deployment sha = string # Git (full-length, 40 char) commit SHA of the deployment short_name = string # slt-<catalog_id>- time = string # Timestamp of the deployment })	{ "actor": "", "catalog_id": "", "deployment": "", "ref": "", "ref_name": "", "repo": "", "repository": "", "sha": "", "short_name": "", "time": "" }	no

Outputs

Name	Description
_default_tags	Default tags to be used in Terraform provider, cf. providers.tf
_deployment	Value to be used as name property of your resources. If you happen to have multiple resources of the same type, append your -purpose to the _deployment value.
_metadata	Select metadata passed from GitHub Workflows
_name_tag	Name to be used as name property of your resources. OBSOLETE. Use local._deployment instead.
_slt_172_16_vpc_cidr	CIDR to be used if new VPCs need to be created
_slt_172_31_subnet_cidr	Subnet CIDR to be used for subnets in the default VPC
admin_password	n/a
kmsuser_password	n/a