Preparing CredHub HSMs for configuration

This topic describes how you can 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.

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 SafeNet Luna Network HSMs product page.

When configuring VMware Tanzu Operations Manager, BOSH CredHub uses a single HSM to store encryption keys. In VMware Tanzu Application Service for VMs (TAS for VMs), you can configure multiple HSMs for runtime CredHub to use as encryption providers.

To configure BOSH CredHub, see Step 3: Configure Director in the BOSH Director configuration topic for your IaaS.

You can configure multiple HSMs for BOSH CredHub using the Tanzu Operations Manager API. For more information, see the Tanzu Operations Manager API documentation.

Configure runtime CredHub with one or more HSMs to securely manage service broker credentials. To configure runtime CredHub, see the TAS for VMs documentation.

Preparation checklist

As you follow these procedures, you can 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

Initialize and configure new HSMs

The procedures in these sections describe how to initialize and configure new HSMs.

Initialize HSM and set policies

To initialize a new HSM and set its policies:

Run:
```
ssh -i path/to/ssh-key.pem manager@HSM-IP-ADDRESS
```
Where HSM-IP-ADDRESS is the IP address of your HSM.
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 Tanzu Operations Manager 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 and Allow network replication policy values are set to On 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 the Allow cloning or Allow network replication policy.
Validate that the SO can reset partition PIN is set correctly. If it is set to Off, consecutive failed login attempts permanently erase the partition once the failure count hits the configured threshold. If it is set to On, the partition locks once the threshold is met. An HSM admin must unlock the partition, but no data is lost. To set the policy to On, 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.

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, review, and delete HSM encryption keys

You can set which key is used for encryption operations by defining the encryption key name in the Director Config pane of the BOSH Director tile for BOSH Credhub, the CredHub pane of the TAS for VMs tile for runtime CredHub, or the Tanzu Operations Manager API. 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.

Review stored keys on a partition

When you generate a new key, you should 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 your partition.

Delete key

Tanzu Operations Manager places extra safeguards around the /api/v0/staged/director/properties endpoint to ensure that you cannot accidentally delete active CredHub encryption keys through the Tanzu Operations Manager API:

You must always have an active key.
You cannot delete keys that are currently active. You can only delete keys after they have been deactivated.

To delete an active CredHub key, you must first deactivate it and activate a new or existing key.

To delete the currently active key:

Deactivate the currently active key by running:

curl "https://OPS-MANAGER-FQDN/api/v0/staged/director/properties" \
  -X PUT \
  -H "Content-Type: application/json" \
  -d '{
        "director-configuration": {
          "encryption": {
            "keys": [
              {
              "provider_name": "hsm",
              "encryption_key_name": "KEY-TO-DEACTIVATE",
              "active": "false"
              },
              {
              "provider_name": "hsm",
              "encryption_key_name": "OTHER-KEY",
              "active": "false"
              }
            ]
          }
        }
      }'

Where:

`OPS-MANAGER-FQDN` is the fully-qualified domain name (FQDN) of your Tanzu Operations Manager instance.
`KEY-TO-DEACTIVATE` is the name of the encryption key you want to deactivate.
`OTHER-KEY` is any other key you may have stored in CredHub.

Activate either a new or existing key.

To activate a new key:

Upload a new key by running:

curl "https://OPS-MANAGER-FQDN/api/v0/staged/director/properties" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
        "director-configuration": {
          "encryption": {
            "keys": [
              {
              "provider_name": "hsm",
              "encryption_key_name": "KEY-TO-UPLOAD"
              }
            ]
          }
        }
      }'

Where:

`OPS-MANAGER-FQDN` is the FQDN of your Tanzu Operations Manager instance.
`KEY-TO-UPLOAD` is the name of the encryption key you want to upload.

Activate the key by running:

    ```
    curl "https://OPS-MANAGER-FQDN/api/v0/staged/director/properties" \
      -X PUT \
      -H "Content-Type: application/json" \
      -d '{
            "director-configuration": {
              "encryption": {
                "keys": [
                  {
                  "provider_name": "hsm",
                  "encryption_key_name": "DEACTIVATED-KEY",
                  "active": "false"
                  },
                  {
                  "provider_name": "hsm",
                  "encryption_key_name": "UPLOADED-KEY",
                  "active": "true"
                  }
                ]
              }
            }
          }'
    ```

Where:

`OPS-MANAGER-FQDN` is the FQDN of your Tanzu Operations Manager instance.
`DEACTIVATED-KEY` is the key you deactivated.
`UPLOADED-KEY` is the name of the encryption key you uploaded in the previous step..

To activate an existing key, run:

    ```console
    curl "https://OPS-MANAGER-FQDN/api/v0/staged/director/properties" \
      -X PUT \
      -H "Content-Type: application/json" \
      -d '{
            "director-configuration": {
              "encryption": {
                "keys": [
                  {
                  "provider_name": "hsm",
                  "encryption_key_name": "DEACTIVATED-KEY",
                  "active": "false"
                  },
                  {
                  "provider_name": "hsm",
                  "encryption_key_name": "KEY-TO-ACTIVATE",
                  "active": "true"
                  }
                ]
              }
            }
          }'
    ```

Where:

OPS-MANAGER-FQDN is the FQDN of your Tanzu Operations Manager instance.
DEACTIVATED-KEY is the key you want to deactivate.
KEY-TO-ACTIVATE is the name of the encryption key you want to activate.

To delete the key you deactivated, you must run a PUT request with the key you want to delete omitted from your keys array. Run:

curl "https://OPS-MANAGER-FQDN/api/v0/staged/director/properties" \
  -X PUT \
  -H "Content-Type: application/json" \
  -d '{
        "director-configuration": {
          "encryption": {
            "keys": [
              {
              "provider_name": "hsm",
              "encryption_key_name": "ACTIVATED-KEY",
              "active": "false"
              }
            ]
          }
        }
      }'

Where:

OPS-MANAGER-FQDN is the FQDN of your Tanzu Operations Manager instance.
ACTIVATED-KEY is the name of the encryption key you activated in the previous step.

For information about running commands with the Tanzu Operations Manager API, see Run API Commands in Using the Tanzu Operations Manager API.