Preparing CredHub HSMs for Configuration
Page last updated:
Warning: Pivotal Cloud Foundry (PCF) v2.5 is no longer supported because it has reached the End of General Support (EOGS) phase as defined by the Support Lifecycle Policy. To stay up to date with the latest software and security updates, upgrade to a supported version.
This topic describes how to prepare a Hardware Security Module (HSM) to store CredHub encryption keys. Storing CredHub encryption keys in an HSM is more secure than storing them internally.
As of PCF v2.1, SafeNet Luna HSM is the only HSM option that you can use as a CredHub encryption provider. The Amazon Web Services (AWS) CloudHSM Classic service uses SafeNet Luna HSMs. For more information about SafeNet Luna HSM, see the product page at SafeNet Luna Network HSMs.
BOSH CredHub uses a single HSM to store encryption keys. In Pivotal Application Service (PAS), you can configure multiple HSMs for runtime CredHub to use as encryption providers.
To configure BOSH CredHub, see Step 3: Director Config Page. The configuration procedure is identical for all IaaSes.
Note: If you use Ops Manager v2.5.23 or later, you can configure multiple HSMs for BOSH CredHub using the Ops Manager API. For more information, see the Ops Manager API documentation.
Configure runtime CredHub with one or more HSMs to securely manage service broker credentials. To configure runtime CredHub, see the PAS tile configuration instructions in Securing Service Instance Credentials with Runtime CredHub.
As you follow the procedure in this topic, record the following resources:
- Encryption Key Name
- HSM Certificate
- Partition name and password
- Client certificate and private key
- Partition serial numbers
Complete the following steps for your HSM.
SSH onto the HSM
SSH onto the HSM.
$ ssh -i path/to/ssh-key.pem manager@HSM-IP
Initialize and Set Policies
- Initialize the HSM and create an Administrator password. Initialize all HSMs into the same cloning domain to guarantee HA.
lunash:> hsm init -label LABEL
- Log into the HSM using the password you just created.
lunash:> hsm login
- Confirm that only FIPS algorithms are enabled.
lunash:> hsm changePolicy -policy 12 -value 0
hsm showPoliciesto confirm that
Allow network replicationpolicy values are set to On on the HSM.
If these values are not set to On, change them by running the following command:
lunash:> hsm changePolicy -policy POLICY-CODE -value 1
- Validate that the
SO can reset partition PINis set correctly. If it is set to Off, consecutive failed login attempts will permanently erase the partition once the failure count hits the configured threshold.
SO can reset partition PINis set to On, the partition locks once the threshold is met. An HSM Admin must unlock the partition, but no data will be lost. Use the following command to set the policy to On:
lunash:> hsm changePolicy -policy 15 -value 1
Fetch the certificate from the HSM. This is used to validate the identity of the HSM when connecting to it.
$ scp -i path/to/ssh-key.pem \ manager@HSM-IP:server.pem \ HSM-IP.pem
- Create a partition to hold the encryption keys. The partition password must be the same for all partitions in the HA partition group.
lunash:> partition create -partition PARTITION-NAME -domain CLONING-DOMAIN
- Record the partition serial number labeled
lunash:> partition show -partition PARTITION-NAME
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 the Client and the HSMs
- Create a certificate for the client.
$ 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
- Copy the client certificate to your HSM.
$ scp -i path/to/ssh-key.pem \ CLIENT-HOSTNAME-OR-IP.pem \ manager@HSM-IP:CLIENT-HOSTNAME-OR-IP.pem
Register HSM Client Host and Partitions
- Create a client. The client hostname is the hostname of the planned CredHub instances.
lunash:> client register -client CLIENT-NAME -hostname CLIENT-HOSTNAMEIf you’re only planning to run one CredHub instance, it’s possible to register a client with the planned CredHub IP.
lunash:> client register -client CLIENT-NAME -ip CLIENT-IP
- Assign the partition created in the previous section to the client.
lunash:> client assignPartition -client CLIENT-NAME -partition PARTITION-NAME
Set which key is used for encryption operations by defining the encryption key name in the BOSH Director tile Director Config pane for BOSH CredHub, or the PAS tile CredHub pane for runtime CredHub. If a key already exists on the HSM, CredHub uses it by default. If a key does not exist on the HSM, CredHub creates one 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:
lunash:> partition showContents -partition PARTITION-NAME