forked from pivotal-cf/docs-pcf-install
-
Notifications
You must be signed in to change notification settings - Fork 0
/
hsm-config.html.md.erb
142 lines (101 loc) · 6.26 KB
/
hsm-config.html.md.erb
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
---
title: Preparing CredHub HSMs for Configuration
owner: CredHub
---
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.
## <a id='overview'></a> Overview
As of <%= vars.product_name %> 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](https://aws.amazon.com/cloudhsm/faqs-classic/) service uses SafeNet Luna HSMs. For more information about SafeNet Luna HSM, see the product page at [SafeNet Luna Network HSMs](https://safenet.gemalto.com/data-encryption/hardware-security-modules-hsms/safenet-network-hsm/).
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](/platform/ops-manager/<%= vars.current_major_version.sub('.', '-') %>/gcp/config-manual.html#director-config). 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](../opsguide/secure-si-creds.html#pas-config).
## <a id='checklist'></a>Preparation Checklist
As you follow the procedure in this topic, record the following resources:
1. Encryption Key Name
1. HSM Certificate
1. Partition name and password
1. Client certificate and private key
1. Partition serial numbers
## <a id="initialize-and-configure"></a>Initialize and Configure New HSMs
Complete the following steps for your HSM.
#### SSH onto the HSM
SSH onto the HSM.
<pre class="terminal">$ ssh -i path/to/ssh-key.pem manager@HSM-IP</pre>
#### Initialize and Set Policies
<ol>
<li>Initialize the HSM and create an Administrator password. Initialize all HSMs into the same cloning domain to guarantee HA.
<pre class="terminal">lunash:> hsm init -label LABEL</pre>
</li>
<li>Log into the HSM using the password you just created.
<pre class="terminal">lunash:> hsm login</pre>
</li>
<li>Confirm that only FIPS algorithms are enabled.
<pre class="terminal">lunash:> hsm changePolicy -policy 12 -value 0</pre>
</li>
<li>Run <code>hsm showPolicies</code> to confirm that <code>Allow cloning</code> and <code>Allow network replication</code> policy values are set to <strong>On</strong> on the HSM. <br/><br>
If these values are not set to <strong>On</strong>, change them by running the following command:
<pre class="terminal">lunash:> hsm changePolicy -policy POLICY-CODE -value 1</pre>
</li>
<li>Validate that the <code>SO can reset partition PIN</code> is set correctly. If it is set to <strong>Off</strong>, consecutive failed login attempts will permanently erase the partition once the failure count hits the configured threshold. <br/><br>
If <code>SO can reset partition PIN</code> is set to <strong>On</strong>, 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 <strong>On</strong>:
<pre class="terminal">lunash:> hsm changePolicy -policy 15 -value 1</pre>
</li>
</ol>
#### <a id="retrieve-hsm-certificate"></a> Retrieve HSM Certificate
Fetch the certificate from the HSM. This is used to validate the identity of the HSM when connecting to it.
<pre class="terminal">$ scp -i path/to/ssh-key.pem \
manager@HSM-IP:server.pem \
HSM-IP.pem
</pre>
#### <a id="create-an-hsm-partition"></a> Create an HSM Partition
<ol>
<li>Create a partition to hold the encryption keys. The partition password must be the same for all partitions in the HA partition group.
<pre class="terminal">lunash:> partition create -partition PARTITION-NAME -domain CLONING-DOMAIN</pre>
</li>
<li>Record the partition serial number labeled <code>Partition SN</code>.
<pre class="terminal">lunash:> partition show -partition PARTITION-NAME</pre>
</li>
</ol>
## <a id='create-register-hsm'></a>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 the Client and the HSMs
<ol>
<li>Create a certificate for the client.
<pre class="terminal">
$ 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
</pre>
</li>
<li>Copy the client certificate to your HSM.
<pre class="terminal">
$ scp -i path/to/ssh-key.pem \
CLIENT-HOSTNAME-OR-IP.pem \
manager@HSM-IP:CLIENT-HOSTNAME-OR-IP.pem
</pre>
</li>
</ol>
#### Register HSM Client Host and Partitions
<ol>
<li>Create a client. The client hostname is the hostname of the planned CredHub instances.
<pre class="terminal">lunash:> client register -client CLIENT-NAME -hostname CLIENT-HOSTNAME</pre>
If you're only planning to run one CredHub instance, it's possible to register a client with the planned CredHub IP.
<pre class="terminal">lunash:> client register -client CLIENT-NAME -ip CLIENT-IP
</pre>
</li>
<li>Assign the partition created in the previous section to the client.
<pre class="terminal">lunash:> client assignPartition -client CLIENT-NAME -partition PARTITION-NAME
</pre>
</li>
</ol>
## <a id="hsm-encryption-keys"></a>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:
<pre class="terminal">lunash:> partition showContents -partition PARTITION-NAME
</pre>