Skip to content

README.md

Latest commit

 

History

History
192 lines (146 loc) · 10.8 KB

README.md

File metadata and controls

192 lines (146 loc) · 10.8 KB

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

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_hsmup to 10 minutes
wait_cluster_activeup to 15 minutes
aws_kms_custom_key_storeup 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:

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
_slt_config Map of SLT configuration
admin_password n/a
kmsuser_password n/a