Using Hardware Security Modules with CredHub
Page last updated:
This topic describes how to configure AWS CloudHSM devices to work with CredHub.
Note: If you use a Luna SafeNet HSM, rather than AWS, skip over the device allocation portion and start with Initialize and Configure New HSMs.
If you store critical data in CredHub, configuring at least two Hardware Security Modules (HSMs) replicates your keys and provides redundancy and security in the event of an HSM failure. With a single HSM, device failure renders your CredHub data inaccessible.
Preparation Checklist
As you follow these procedures, you should collect or create these resources:
The name of your encryption key
Your HSM certificate
Your HSM partition name and password
Your client certificate and private key
Your HSM partition serial numbers
Create New AWS CloudHSMs
These sections describe how to create new AWS CloudHSMs.
AWS Environment Prerequisites
Note: For high availability (HA), use at least two HSM instances. AWS documentation recommends that you also use a subnet for a publicly available Control Instance, but for this product that is unnecessary. CredHub acts as a Control Instance.
Before creating new AWS CloudHSMs, you must have:
A Virtual Private Cloud (VPC)
For each HSM instance: One private subnet in its own Availability Zone (AZ)
An IAM role for the HSM with a policy equivalent to
AWSCloudHSMRole
policyThe Security Group must allow traffic from the CredHub security group on ports 22 (SSH) and 1792 (HSM)
Create New Devices
To create new AWS CloudHSMs:
Install the AWS CLI from AWS CloudHSM Command Line Tools in the AWS documentation.
Create SSH keypairs for all planned HSMs by running:
ssh-keygen -b 4096 -t rsa -N PASSWORD -f PATH-TO-SSH-KEY.pem
Where:
PASSWORD
is the password you create for the SSH key.PATH-TO-SSH-KEY
is the filepath of your SSH key PEM file.
Create the
cloudhsm.conf
file with these values:aws_access_key_id=ACCESS-KEY-ID aws_secret_access_key=SECRET-ACCESS-KEY aws_region=AWS-REGION
Where:
ACCESS-KEY-ID
is your AWS access key ID.SECRET-ACCESS-KEY
is your AWS secret access key.AWS-REGION
is your AWS region.
To create each HSM and place it in the appropriate subnet, run:
cloudhsm create-hsm \ --conf_file PATH-TO-CLOUDHSM.conf \ --subnet-id SUBNET-ID \ --ssh-public-key-file PATH-TO-SSH-KEY.pem.pub \ --iam-role-arn IAM-HSN-ROLE-ARN
Where:
PATH-TO-CLOUDHSM
is the filepath to yourcloudhsm.conf
file.SUBNET-ID
is the ID of the subnet in which you want to place your HSM.PATH-TO-SSH-KEY
is the filepath to your public SSH key PEM key.IAM-HSM-ROLE-ARN
is the Amazon Resource Name (ARN) of your HSM’s IAM role. For more information, see IAM ARNs in IAM Identifiers in the AWS documentation.
Assign the security group to each HSM:
Retrieve the Elastic Network Interface ID
EniID
of the HSM by running:cloudhsm describe-hsm -H HSM-ARN -r AWS-REGION
Where:
HSM-ARN
is the ARN of your HSM.AWS-REGION
is the AWS region of your HSM.
Edit the network interface to assign the security group by running:
aws ec2 modify-network-interface-attribute \ --network-interface-id ENI-ID \ --groups SECURITY-GROUP-ID
Where:
ENI-ID
is theEniID
you retrived in the previous step.SECURITY-GROUP-ID
is the ID of the security group you want to assign to this HSM.
Initialize and Configure New HSMs
These sections describe the steps to initialize and configure your HSMs, whether they are Luna HSMs or AWS CloudHSMs. You must follow this procedure for each HSM you created.
SSH Onto the HSM
To SSH onto the HSM you want to initialize and configure:
Retrieve the IP address of your HSM by running:
cloudhsm describe-hsm -H HSM-ARN -r AWS-REGION
Where:
HSM-ARN
is the ARN of your HSM.AWS-REGION
is the AWS region of your HSM.
SSH onto the HSM by running:
ssh -i path/to/ssh-key.pem manager@HSM-IP
Where
HSM-IP
is the IP address you retrieved in the previous step.
Initialize and Set Policies
To initialize your HSM and set its policies:
Initialize the HSM and create an admin password when prompted by running:
lunash:> hsm init -label LABEL
Where
LABEL
is the label you want to give the HSM.
Initialize all HSMs into the same cloning domain to guarantee high availability for your Cloud Foundry deployment.Log in to the HSM using the password you just created by running:
lunash:> hsm login
Confirm that only FIPS algorithms are enabled. Run:
lunash:> hsm changePolicy -policy 12 -value 0
To confirm that
Allow cloning
andAllow network replication
policy values are set toOn
on the HSM, run:hsm showPolicies
If these values are not set to
On
, change them by running:lunash:> hsm changePolicy -policy POLICY-CODE -value 1
Where
POLICY-CODE
is the numerical code of theAllow cloning
orAllow network replication
policy.Validate that the
SO can reset partition PIN
is set correctly. If it is set toOff
, consecutive failed login attempts permanently erase the partition once the failure count hits the configured threshold. If it is set toOn
, the partition locks once the threshold is met. An HSM admin must unlock the partition, but no data is lost. To set the policy toOn
, run:lunash:> hsm changePolicy -policy 15 -value 1
Retrieve HSM Certificate
To retrieve your HSM certificate:
Run:
scp -i path/to/ssh-key.pem \ manager@HSM-IP-ADDRESS:server.pem \ HSM-IP-ADDRESS.pem
Where
HSM-IP-ADDRESS
is the IP address of your HSM.
BOSH CredHub uses this certificate to validate the identity of the HSM when connecting to it.
Create an HSM Partition
To create an HSM partition to hold the encryption keys:
Run:
lunash:> partition create -partition PARTITION-NAME -domain CLONING-DOMAIN
Where:
PARTITION-NAME
is the name you give the partition.CLONING-DOMAIN
is the cloning domain of the HSM.
When prompted to do so, create a password for the partition. The partition password must be the same for all partitions in the highly available partition group.
To retrieve the partition serial number, run:
lunash:> partition show -partition PARTITION-NAME
Where
PARTITION-NAME
is the name of the partition you created.Record the
Partition SN
shown in the output of the command you ran in the previous step.
Create and Register HSM Clients
Clients that communicate with the HSM must provide a client certificate to establish a client-authenticated session. You must set up each client’s certificate on the HSM and assign access rights for your partition.
Establish a Network Trust Link Between Client and HSMs
To establish a network trust link between a client and your HSMs:
Create a certificate for the client by running:
openssl req \ -x509 \ -newkey rsa:4096 \ -days NUMBER-OF-DAYS \ -sha256 \ -nodes \ -subj "/CN=CLIENT-HOSTNAME-OR-IP" \ -keyout CLIENT-HOSTNAME-OR-IP.pem \ -out CLIENT-HOSTNAME-OR-IP.pem
Where:
NUMBER-OF-DAYS
is the number of days you want the network trust link to be valid.CLIENT-HOSTNAME-OR-IP
is the hostname or IP address of the client.
Copy the client certificate to your HSM by running:
scp -i path/to/ssh-key.pem \ CLIENT-HOSTNAME-OR-IP.pem \ manager@HSM-IP:CLIENT-HOSTNAME-OR-IP.pem
Where
CLIENT-HOSTNAME-OR-IP
is the hostname or IP address of the client.
Register HSM Client Host and Partitions
To register a client host and partitions for your HSM:
Create a client by running:
lunash:> client register -client CLIENT-NAME -hostname CLIENT-HOSTNAME
Where:
CLIENT-NAME
is the name of the client.CLIENT-HOSTNAME
is the hostname of your planned CredHub instances.
(Optional) If you are only planning to run one CredHub instance, you can also register a client with the planned CredHub IP address by running:
lunash:> client register -client CLIENT-NAME -ip CLIENT-IP-ADDRESS
Where:
CLIENT-NAME
is the name of the client.CLIENT-IP-ADDRESS
is the IP address of your planned CredHub instance.
Assign the partition created in the previous section to the client by running:
lunash:> client assignPartition -client CLIENT-NAME -partition PARTITION-NAME
Where:
CLIENT-NAME
is the name of the client.PARTITION-NAME
is the name of the partition you created.
Set HSM Encryption Keys
Set which key used for encryption operations by defining the encryption key name in the deploy manifest. By default, a key that exists on the HSM is used for encryption operations. If a key does not exist on the HSM, CredHub creates it automatically in the referenced partition.
When you generate a new key, review the list of keys on each HSM to validate that key replication is occurring. If new keys do not propagate among the HSMs, you could get locked out of HSMs.
To review stored keys on a partition:
Run:
lunash:> partition showContents -partition PARTITION-NAME
Where
PARTITION-NAME
is the name of the partition on which your keys are stored.
Ready for Deployment
Now you can deploy CredHub with your new HSMs.
Edit your manifest as shown below:
credhub:
properties:
encryption:
keys:
- provider_name: primary
encryption_key_name: ENCRYPTION-KEY-NAME
active: true
providers:
- name: primary
type: hsm
partition: PARTITION-NAME
partition_password: PARTITION-PASSWORD
client_certificate: CLIENT-CERTIFICATE
client_key: CLIENT-PRIVATE-KEY
servers:
- host: 10.0.0.1
port: 1792
certificate: HSM-CERTIFICATE
partition_serial_number: PARTITION-SERIAL-NUMBER
- host: 10.0.0.10
port: 1792
certificate: HSM-CERTIFICATE
partition_serial_number: PARTITION-SERIAL-NUMBER
Where:
ENCRYPTION-KEY-NAME
is the encryption key you set in Set HSM Encryption Keys.PARTITION-NAME
is the name of the partition you created in Create an HSM Partition.PARTITION-PASSWORD
is the password of the partition you created in Create an HSM Partition.CLIENT-CERTIFICATE
is the client certificate you created in Establish a Network Trust Link Between Client and HSMs.CLIENT-PRIVATE-KEY
is the private key you created in Establish a Network Trust Link Between Client and HSMs.HSM-CERTIFICATE
is one of the HSM certificates you retrieved in Retrieve HSM Certificate.PARTITION-SERIAL-NUMBER
is the partition serial number you retrieved in Create an HSM Partition.
Renew or Rotate a Client Certificate
The generated client certificate has a fixed expiration date after which the HSM no longer accepts it. To rotate or renew this certificate at any time:
Generate a new certificate for the client by running:
openssl req \ -x509 \ -newkey rsa:4096 \ -days NUMBER-OF-DAYS \ -sha256 \ -nodes \ -subj "/CN=CLIENT-HOSTNAME-OR-IP" \ -keyout CLIENT-HOSTNAME-OR-IPKey.pem \ -out CLIENT-HOSTNAME-OR-IP.pem
Where:
NUMBER-OF-DAYS
is the number of days you want the network trust link to be valid.CLIENT-HOSTNAME-OR-IP
is the hostname or IP address of the client.
Copy the client certificate to each HSM by running:
scp -i path/to/ssh-key.pem \ CLIENT-HOSTNAME-OR-IP.pem \ manager@HSM-IP:CLIENT-HOSTNAME-OR-IP.pem
Where
CLIENT-HOSTNAME-OR-IP
is the hostname or IP address of the client.(Optional) Review the client’s partition assignments by running:
lunash:> client show -client CLIENT-NAME
Where
CLIENT-NAME
is the name of the client.Remove the existing client by running:
lunash:> client delete -client CLIENT-NAME
Where
CLIENT-NAME
is the name of the client.Note: When you remove the existing client, all partition assignments are deleted.
Re-register the client by running:
lunash:> client register -client CLIENT-NAME -ip CLIENT-IP
Where:
CLIENT-NAME
is the name of the client.CLIENT-IP
is the IP address of the client.
Re-assign partition assignments by running:
lunash:> client assignPartition -client CLIENT-NAME -partition PARTITION-NAME
Where:
CLIENT-NAME
is the name of the client.PARTITION-NAME
is the name of the partition to which the client is assigned.
(Optional) Validate the new certificate fingerprint by running:
lunash:> client fingerprint -client CLIENT-NAME
Where
CLIENT-NAME
is the name of the client.
If you need to, you can compare the fingerprint to your locally stored certificate by running:openssl x509 -in clientcert.pem -outform DER | md5sum