-
Notifications
You must be signed in to change notification settings - Fork 34
/
_rotate-ca.html.md.erb
219 lines (168 loc) · 8.72 KB
/
_rotate-ca.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
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
<p class="note warning"><strong>WARNING</strong>: Do not attempt to rotate a CA certificate on your own.
Contact <a href="https://support.pivotal.io">Pivotal Support</a>
and perform the following procedures with their help.</p>
##<a id='overview'></a> Overview
To rotate CA certificates, you must do the following:
1. [Add a New CA Certificate](#add)
1. [Regenerate Internal Certificates](#regenerate)
1. [Rebind Your App](#rebind)
1. [Remove Old the CA Certificate](#remove)
## <a id="add"></a> Add a New CA Certificate
<p class="note warning"><strong>WARNING</strong>: This procedure involves restarting
all of the VMs in your PCF deployment to apply a CA certificate. The
operation can take a long time to complete.</p>
To add a new CA certificate, follow the procedures you must do the following:
1. [Find the CredHub Credentials in Ops Manager](#credhub-creds)
1. [Regenerate and Add the New CA Certificate](#regenerate-cert)
###<a id='credhub-creds'></a> Find the CredHub Credentials in Ops Manager
You need the BOSH CredHub client name and client secret to complete the
[Regenerate and Add a New CA Certificate](#regenerate-cert) procedure below.
To find the BOSH CredHub client name and client secret, do the following:
1. In the Ops Manager Installation Dashboard, click the BOSH Director tile.
1. Click the **Credentials** tab.
1. In the BOSH Director section, click the link to the BOSH Commandline Credentials.
1. Record the values for `BOSH_CLIENT` and `BOSH_CLIENT_SECRET`.<br>
For example:
```
{"credential":"BOSH_CLIENT=ops_manager
BOSH_CLIENT_SECRET=abCdE1FgHIjkL2m3n-3PqrsT4EUVwXy5
BOSH_CA_CERT=/var/tempest/workspaces/default/root_ca_certificate
BOSH_ENVIRONMENT=10.0.0.5 bosh "}
```
The `BOSH_CLIENT` is the BOSH CredHub client name and the `BOSH_CLIENT_SECRET` is
the BOSH CredHub client secret.
###<a id='regenerate-cert'></a> Regenerate and Add the New CA Certificate
To regenerate and add the CA Certificate to Ops Manager, do the following:
1. To log in to the Ops Manager VM, do the following procedures:
1. To gather the information needed to log in to the BOSH Director VM,
see [Gather Credential and IP Address Information](https://docs.pivotal.io/pivotalcf/2-4/customizing/trouble-advanced.html#gather).
1. To log in to the Ops Manager VM, see [Log in to the Ops Manager VM with SSH](https://docs.pivotal.io/pivotalcf/2-4/customizing/trouble-advanced.html#ssh).
1. From the Ops Manager VM, to set the API target of the CredHub CLI to your BOSH
CredHub server, run the following:
```
credhub api https://BOSH-DIRECTOR:8844 --ca-cert=/var/tempest/workspaces/default/root_ca_certificate
```
Where `BOSH-DIRECTOR` is the IP address of the BOSH Director VM you recorded in step 1.a above.
<br><br>
For example:
<pre class="terminal">
$ credhub api http<span>s:</span>//10.0.0.5:8844 --ca-cert=/var/tempest/workspaces/default/root_ca_certificate
</pre>
1. To log in to CredHub, run the following:
```
credhub login --client-name=CREDHUB-CLIENT-NAME --client-secret=CREDHUB-CLIENT-SECRET
```
Where:<br>
* `CREDHUB-CLIENT-NAME` is the value you recorded for `BOSH_CLIENT` in step 4 in
[Find the CredHub Credentials](#credhub-creds) above.
* `CREDHUB-CLIENT-SECRET` is the value you recorded for `BOSH_CLIENT_SECRET` in step 4 in [Find the CredHub Credentials](#credhub-creds) above.
<br><br>
For example:
<pre class="terminal">
$ credhub login \
--client-name=credhub \
--client-secret=abcdefghijklm123456789
</pre>
1. To generate a CA certificate or provide an existing one, do one of the following:
<p class="note"><strong>Note</strong>: Your PCF deployment can have
multiple CA certificates.
Pivotal recommends using a dedicated CA certificate for services.</p>
* If you do not have a CA certificate, to generate a CA certificate run the following:
```
credhub regenerate --name="/services/tls_ca"
```
* If you have an existing CA certificate that you want to use, create
a new file called `root.pem` with the contents of the certificate.
Then run the following command:
```
credhub set \
--name="/services/tls_ca" \
--type="certificate" \
--certificate=PEM-PATH/root.pem \
--private=CERT-KEY...
```
Where:
* `PEM-PATH` is the path to the `root.pem` file.
* `CERT-KEY` is the private key for the certificate.
1. To extract and print the `certificate` portion from the CA certificate,
run the following command:
```
bosh int <(credhub get \
--name=/services/tls_ca) \
--path /value/certificate
```
1. Copy the output.
1. Navigate to the **Installation Dashboard** in Ops Manager and select the BOSH Director tile.
Click **Security**.
1. Append the contents of the new CA certificate to the old CA certificate under **Trusted Certificates**. Do not remove the old CA certificate. Click **Save**.
9. Return to the **Installation Dashboard** in Ops Manager and click **Apply Changes**.
This restarts all the VMs in your PCF deployment and applies your CA certificate.
## <a id="regenerate"></a> Regenerate Internal Certificates
To regenerate your internal certificates and redeploy your service instances, follow the procedure below:
1. To log in to CredHub, run the following:
```
credhub login --client-name=CREDHUB-CLIENT-NAME \
--client-secret=CREDHUB-CLIENT-SECRET
```
Where:
* `CREDHUB-CLIENT-NAME` is the value you recorded for `BOSH_CLIENT` in step 4 in
[Find the CredHub Credentials](#credhub-creds) above.
* `CREDHUB-CLIENT-SECRET` is the value you recorded for `BOSH_CLIENT_SECRET` in step 4 in [Find the CredHub Credentials](#credhub-creds) above.
<br><br>
For example:
<pre class="terminal">
$ credhub login \
--client-name=credhub \
--client-secret=abcdefghijklm123456789
</pre>
1. To regenerate all certificates signed by the old CA certificate, run the following
```
curl "https://BOSH-DIRECTOR/api/v1/bulk-regenerate"" -X POST \
-d '{ "signed_by": "/services/tls_ca" }'\
-H "authorization: bearer $(credhub --token)"\
-H 'content-type: application/json'
```
Where `BOSH-DIRECTOR` is the IP address of the BOSH Director VM.
1. To redeploy all service instances with the new certificates, run the following:
```
bosh -d p-mysql-GUID run-errand upgrade-all-service-instances
```
Where `pivotal-mysql-GUID` is the BOSH deployment name for your MySQL service broker.
## <a id='rebind'></a> Rebind Your App
If your apps do not use the trusted store to validate server certificates, developers must re-bind apps to the service instance to receive the updated CA certificate. Apps not written in Java and Spring do not use the trusted store.
If you are rotating your CA certificate because it was compromised, you must remove your old CA certificate before rebinding your app. If you have not removed your old CA certificate, see [Remove Old the CA Certificate](#remove) below.
To re-bind your app, do the following:
1. To stop your app, run the following command:
```
cf stop YOUR-APP
```
Where `YOUR-APP` is the name of your app.
1. To unbind your app from the service instance, run the following command:
```
cf unbind-service YOUR-APP YOUR-SERVICE-INSTANCE
```
Where:
+ `YOUR-APP` is the name of your app.
+ `YOUR-SERVICE-INSTANCE` is the name of your service instance.
1. To re-bind your app to the service instance, run the following command:
```
cf bind-service YOUR-APP YOUR-SERVICE-INSTANCE
```
Where:
+ `YOUR-APP` is the name of your app.
+ `YOUR-SERVICE-INSTANCE` is the name of your service instance.
1. To restage your app, run the following command:
```
cf restage YOUR-APP
```
Where `YOUR-APP` is the name of your app.
## <a id="remove"></a> Remove Old the CA Certificate
<p class="note warning"><strong>WARNING!</strong> This procedure involves restarting
all of the VMs in your PCF deployment to apply a CA certificate. The
operation can take a long time to complete.</p>
After your apps have reconnected to service instances with certificates generated by the new CA, do the following to remove the old CA certificate:
1. Navigate to the **Installation Dashboard** in Ops Manager and click the BOSH Director tile. Click **Security**.
1. Remove the old CA certificate in Trusted Certificates and click **Save**.
1. Return to the **Installation Dashboard** in Ops Manager and click **Apply Changes**. This restarts all the VMs in your deployment.
1. If you are rotating your CA certificate because it was compromised, you must rebind your apps to update the CA certificate. See [Rebind Your App](#rebind) above.