Preparing CredHub HSMs for Configuration

Page last updated:

Warning: Pivotal Cloud Foundry (PCF) v2.3 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.

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.

Preparation Checklist

As you follow the procedure in this topic, record the following resources:

  1. Encryption Key Name
  2. HSM Certificate
  3. Partition name and password
  4. Client certificate and private key
  5. Partition serial numbers

Initialize and Configure New HSMs

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

  1. Initialize the HSM and create an Administrator password. Initialize all HSMs into the same cloning domain to guarantee HA.
    lunash:> hsm init -label LABEL
  2. Log into the HSM using the password you just created.
    lunash:> hsm login
  3. Confirm that only FIPS algorithms are enabled.
    lunash:> hsm changePolicy -policy 12 -value 0
  4. Run hsm showPolicies to confirm that Allow cloning and Allow network replication policy 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
  5. Validate that the SO can reset partition PIN is 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.

    If SO can reset partition PIN is 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

Retrieve HSM Certificate

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 \

Create an HSM Partition

  1. 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
  2. Record the partition serial number labeled Partition SN.
    lunash:> partition show -partition PARTITION-NAME

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.

  1. 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
  2. Copy the client certificate to your HSM.
    $ scp -i path/to/ssh-key.pem \

Register HSM Client Host and Partitions

  1. Create a client. The client hostname is the hostname of the planned CredHub instances.
    lunash:> client register -client CLIENT-NAME -hostname CLIENT-HOSTNAME
    If 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
  2. Assign the partition created in the previous section to the client.
    lunash:> client assignPartition -client CLIENT-NAME -partition PARTITION-NAME

Encryption Keys on the HSM

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