-
Notifications
You must be signed in to change notification settings - Fork 110
/
securing-traffic.html.md.erb
346 lines (219 loc) · 20.2 KB
/
securing-traffic.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
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
---
title: Securing incoming traffic in Cloud Foundry
owner: CF for VMs Networking
---
<%# Reset page title based on platform type %>
<% if vars.platform_code != 'CF' %>
<% set_title("Securing incoming traffic in", vars.app_runtime_abbr) %>
<% end %>
You can secure HTTP traffic into your <%= vars.app_runtime_abbr %> deployment with TLS certificates. You can also configure the location
where your deployment stops TLS depending on your needs and certificate restrictions.
## <a id="protocol_support"></a> Protocol support
The Gorouter supports HTTP/HTTPS requests only.
For more information about features supported by the Gorouter, see [HTTP Routing](../concepts/http-routing.html).
To secure non-HTTP traffic over TCP routing, terminate TLS at your load balancer or at the app. For more information, see [Enabling TCP Routing](enabling-tcp-routing.html).
## <a id="ssl_options"></a> TLS termination options for HTTP routing
There are several options for terminating TLS for HTTP traffic. You can stop TLS at the Gorouter, your load balancer, or both.
The following table summarizes TLS termination options and which option to choose for your deployment:
<table class="table">
<thead>
<tr>
<th>If the following applies to you:</th>
<th>Then configure TLS termination at:</th>
<th>Related topic and configuration procedure</th>
</tr>
</thead>
<tr>
<td>
<ul>
<li>You want the optimum balance of performance and security, and</li>
<li>You want to make minimum changes to your load balancer, or</li>
<li>You are deploying <%= vars.app_runtime_abbr %> to AWS. For information about AWS limitations, see <a href="#aws_elbs">TLS Cipher Suite Support by AWS ELBs</a>.</li>
</ul>
</td>
<td><b>Gorouter only</b>
</td>
<td> <a href="#gorouter_term">Terminating TLS at the Gorouter Only</a>
</td>
</tr>
<tr>
<td>
<ul>
<li>You require TLS termination at a load balancer, or</li>
<li>You want the highest level of security, and</li>
<li>You do not mind a slightly less performant deployment.</li>
</ul>
</td>
<td>
<b>Load Balancer and Gorouter</b>
</td>
<td><a href="#lb_and_gorouter_term">Terminating TLS at the Load Balancer and Gorouter</a>
</td>
</tr>
<tr>
<td>
<ul>
<li>You require TLS termination at a load balancer, and</li>
<li>You prefer unencrypted traffic between the Load Balancer and the Gorouter.</li>
</ul>
</td>
<td><b>Load Balancer only</b>
</td>
<td><a href="#lb_term">Terminating TLS at the Load Balancer Only</a>
</td>
</tr>
</table>
## <a id="certtypes"></a> Certificate requirements
The following requirements apply to the certificates you use to secure traffic into <%= vars.app_runtime_abbr %>:
* You must obtain at least one TLS certificate for your environment.
* In a production environment, use a signed TLS certificate (trusted) from a known certificate authority (CA).
* In a development or testing environment, you can use a trusted CA certificate or a self-signed certificate. You can generate a self-signed certificate with `openssl` or a similar tool.
<%= vars.ssl_cert_ert %>
* Certificates used in <%= vars.app_runtime_abbr %> must be encoded in the PEM format.
* The Gorouter supports mutual TLS, and validates a client provided certificate chain against its CA certificates if one is provided in the TLS handshake, but does not require it. Depending on whether you choose to terminate at both the load balancer and the Gorouter, or at the Gorouter alone, the client certificate can be that of the load balancer or of the originating client.
* The certificate on the Gorouter must be associated with the correct host name so that HTTPS can validate the request.
* If wildcard certificates are not supported for some or all of your domains, then configure termination requests at the load balancer only. In this type of deployment, the load balancer passes unencrypted traffic to the Gorouter. As a result, you avoid having to reissue and reinstall certificates on the Gorouter for every app or UAA security zone.
* Extended Validation (EV) certificates support multiple host names, like SAN, but do not support wildcards. As the Gorouter has not been tested with EV certificates, if EV certificates are required, then terminate TLS at the load balancer only.
* Given the dynamic and multi-tenant nature of <%= vars.app_runtime_abbr %>, <%= vars.company_name %> highly recommends using wildcard domains to avoid the need for adding an additional certificate for each app.
* To support TLS v1.3, ensure that you use certificates generated with a key larger than 512 bits.
## <a id="multcerts"></a> Multiple certificates
In order to support custom domains on <%= vars.app_runtime_abbr %>, an operator has to configure the Gorouter with a certificate that represents the domain. <%= vars.company_name %> recommends that operators add a new certificate instead of reissuing a single certificate when adding TLS support for an additional domain. Using multiple certificates provides a security benefit in that it prevents clients from discovering all the custom domains of apps running on a <%= vars.app_runtime_abbr %> platform.
The Gorouter supports SNI and can be configured with multiple certificates, each which can optionally have wildcard and alternative names. The Gorouter uses SNI to determine the correct certificate to present in a TLS handshake. It requires clients to support the SNI protocol by sending a server name outside the encrypted request payload. For clients that do not support SNI, the Gorouter presents a default certificate. The default is the first certificate keypair in the Gorouter's configuration.
The Gorouter decides which certificate to provide in the TLS handshake as follows:
* If a client provides an SNI header with a ServerName that matches to a configured certificate keypair, the Gorouter returns the matching certificate.
* If a client provides an SNI header with a ServerName that does not match a configured certificate keypair, the Gorouter returns the default certificate.
The first certificate keypair listed is used as the default.
The Gorouter supports both RSA and ECDSA certificates in PEM encoding. In the case that a certificate chain is required, the order should be as follows: primary certificate, intermediate certificate, then root certificate.
### <a id="how-to-config-mult-certs"></a> How to configure multiple certificate keypairs
<%= vars.multiple_certs_gorouter %>
<% if vars.platform_code == 'CF' %>
<%= partial 'ssl_multicerts_gorouter' %>
<% else %>
<% end %>
## <a id="ciphers"></a> TLS cipher suite support
Some <%= vars.app_runtime_abbr %> components like the Gorouter support additional TLS cipher suites to accommodate older clients. As a security best practice, only configure the TLS cipher suites that you need for your deployment.
### <a id="default"></a> Default Gorouter cipher suites
By default, the Gorouter supports the following TLS cipher suites:
| TLS Version | RFC | OpenSSL |
| ----------- | --- | ------- |
| 1.2 | TLS\_ECDHE\_RSA\_WITH\_AES\_128\_GCM\_SHA256 | ECDHE-RSA-AES128-GCM-SHA256 |
| 1.2 | TLS\_ECDHE\_RSA\_WITH\_AES\_256\_GCM\_SHA384 | ECDHE-RSA-AES256-GCM-SHA384 |
| 1.3 | TLS\_AES\_128\_GCM\_SHA256 | TLS\_AES\_128\_GCM\_SHA256 |
| 1.3 | TLS\_AES\_256\_GCM\_SHA384 | TLS\_AES\_256\_GCM\_SHA384 |
| 1.3 | TLS\_CHACHA20\_POLY1305\_SHA256 | - |
<%= vars.cipher_suites %>
### <a id="aws_elbs"></a> TLS cipher suite support by AWS load balancers
AWS Classic Load Balancers (formerly referred to as ELBs) support configuration of cipher suites for front end connections with clients only. When configuring Classic Load Balancers to forward requests to Gorouters over TLS, oyou might encounter a `Cipher Suite Mismatch` error. This is because the cipher suites supported by Classic Load Balancers for TLS handshakes with back ends (Gorouters in this case) are hardcoded, undocumented, and do not support the Gorouter default cipher suites.
You can configure TLS termination in one of the following ways:
* Configure Classic Load Balancer listeners in TCP mode. This allows TCP connections from clients to pass through the Classic Load Balancer to Gorouters on port 443. With this configuration, Gorouters are the first point of TLS termination.
* If you require TLS termination at an AWS load balancer in addition to terminating at the Gorouter, use [AWS Application Load Balancers (ALBs)](http://docs.aws.amazon.com/elasticloadbalancing/latest/application/introduction.html) that support the Gorouter default cipher suites.
### <a id="tls_1.3"></a> TLS v1.3
You cannot configure cipher suites for TLS v1.3. Gorouter only supports the defaults listed in [Default Gorouter Cipher Suites](#default).
To support TLS v1.3, ensure the Gorouter is configured with certificates generated with a key larger than 512 bits.
### <a id="tls_1.2"></a> TLS v1.2
The following cipher suites are optionally supported for TLS v1.2 only:
| RFC | OpenSSL |
| --- | ------- |
| TLS\_RSA\_WITH\_AES\_128\_GCM\_SHA256 | AES128-GCM-SHA256 |
| TLS\_RSA\_WITH\_AES\_256\_GCM\_SHA384 | AES256-GCM-SHA384 |
| TLS\_ECDHE\_ECDSA\_WITH\_RC4\_128\_SHA | ECDHE-ECDSA-RC4-SHA |
| TLS\_ECDHE\_ECDSA\_WITH\_AES\_128\_CBC\_SHA | ECDHE-ECDSA-AES128-SHA |
| TLS\_ECDHE\_ECDSA\_WITH\_AES\_256\_CBC\_SHA | ECDHE-ECDSA-AES256-SHA |
| TLS\_ECDHE\_RSA\_WITH\_RC4\_128\_SHA | ECDHE-RSA-RC4-SHA |
| TLS\_ECDHE\_RSA\_WITH\_3DES\_EDE\_CBC\_SHA | ECDHE-RSA-DES-CBC3-SHA |
| TLS\_ECDHE\_RSA\_WITH\_AES\_128\_CBC\_SHA | ECDHE-RSA-AES128-SHA |
| TLS\_ECDHE\_RSA\_WITH\_AES\_256\_CBC\_SHA | ECDHE-RSA-AES256-SHA |
| TLS\_ECDHE\_RSA\_WITH\_AES\_128\_GCM\_SHA256 | ECDHE-RSA-AES128-GCM-SHA256 |
| TLS\_ECDHE\_ECDSA\_WITH\_AES\_128\_GCM\_SHA256 | ECDHE-ECDSA-AES128-GCM-SHA256 |
| TLS\_ECDHE\_RSA\_WITH\_AES\_256\_GCM\_SHA384 | ECDHE-RSA-AES256-GCM-SHA384 |
| TLS\_ECDHE\_ECDSA\_WITH\_AES\_256\_GCM\_SHA384 | ECDHE-ECDSA-AES256-GCM-SHA384 |
| TLS\_RSA\_WITH\_AES\_128\_CBC\_SHA256 | AES128-SHA256 |
| TLS\_ECDHE\_ECDSA\_WITH\_AES\_128\_CBC\_SHA256 | ECDHE-ECDSA-AES128-SHA256 |
| TLS\_ECDHE\_RSA\_WITH\_AES\_128\_CBC\_SHA256 | ECDHE-RSA-AES128-SHA256 |
| TLS\_ECDHE\_RSA\_WITH\_CHACHA20\_POLY1305 | ECDHE-RSA-CHACHA20-POLY1305 |
| TLS\_ECDHE\_ECDSA\_WITH\_CHACHA20\_POLY1305 | ECDHE-ECDSA-CHACHA20-POLY1305 |
### <a id="tls_10_11"></a> TLS v1.0 and v1.1
The following cipher suites are optionally supported for TLS v1.0 and TLS v1.1 only:
| RFC | OpenSSL |
| --- | ------- |
| TLS\_RSA\_WITH\_RC4\_128\_SHA | RC4-SHA |
| TLS\_RSA\_WITH\_3DES\_EDE\_CBC\_SHA | DES-CBC3-SHA |
| TLS\_RSA\_WITH\_AES\_128\_CBC\_SHA | AES128-SHA |
| TLS\_RSA\_WITH\_AES\_256\_CBC\_SHA | AES256-SHA |
<%= vars.cipher_suites %>
For more information about supported ciphers, see [Golang Constants](https://github.com/golang/go/blob/release-branch.go1.7/src/crypto/tls/cipher_suites.go#L269-L285) in the Golang repository on GitHub and [Ciphers](https://www.openssl.org/docs/man1.1.1/man1/ciphers.html) in the OpenSSL documentation.
<p class="note">
<span class="note__title"><strong>Note</strong></span>
ECDSA ciphers require a certificate and key for DSA, as opposed to RSA.</p>
## <a id="gorouter_mutual_auth"></a> Mutual authentication with clients
The Gorouter supports validation of client certificates in TLS handshakes with clients, also known as mutual authentication. Operators can choose whether the Gorouter requests client certificates and when requesting certificates, whether or not to require them.
By default, the Gorouter requests but does not require client certificates in TLS handshakes.
## <a id="gorouter_term"></a> Terminating TLS at the Gorouter only
In this configuration, the load balancer does not terminate TLS for <%= vars.app_runtime_abbr %> domains at all. Instead, it passes through the underlying TCP connection to the Gorouter.
<%= vars.company_name %> recommends this more performant option, establishing and terminating a single TLS connection.
The following diagram illustrates communication between the client, load balancer, Gorouter, and app.
The preceding diagram shows communication between the client, load balancer, router, and the app.
Traffic passes from the encrypted client, to the load balancer, to the router, and traffic ends at the app.
Traffic between the load balancer and the Gorouter is encrypted only if the client request is encrypted.
Traffic between the Gorouter and app is encrypted with TLS, unless a Windows stemcell is being used.
### <a id="http_header_gorouter"></a> About HTTP header forwarding
If you stop TLS at the Gorouter only, your load balancer does not send HTTP headers.
The Gorouter appends the `X-Forwarded-For` and `X-Forwarded-Proto` headers to requests forwarded to apps and platform system components.
`X-Forwarded-For` is set to the IP address of the source. Depending on the behavior of your load balancer, this can be the IP address of your load balancer. For the Gorouter to deliver the IP address of the client to apps, configure your load balancer to forward the IP address of the client or configure your load balancer to send the client IP address using the PROXY protocol.
`X-Forwarded-Proto` provides the scheme of the HTTP request from the client. The scheme is HTTP if the client made a request on port 80 (unencrypted) or HTTPS if the client made a request on port 443 (encrypted). The Gorouter sanitizes the `X-Forwarded-Proto` header based on the settings of the `router.sanitize_forwarded_proto` and `router.force_forwarded_proto_https` manifest properties as follows:
* `router.sanitize_forwarded_proto: true` and `router.force_forwarded_proto_https: true`: The Gorouter sets the value of `X-Forwarded-Proto` header to `HTTPS` in requests forwarded to back ends.
* `router.sanitize_forwarded_proto: true` and `router.force_forwarded_proto_https: false`: The Gorouter strips the `X-Forwarded-Proto` header when present in requests from front end clients. When the request is received on port 80 (unencrypted), the Gorouter sets the value of this header to `HTTP` in requests forwarded to back ends, When the request is received on port 443 (encrypted), the Gorouter sets the value of this header to `HTTPS`.
* `router.sanitize_forwarded_proto: false` and `router.force_forwarded_proto_https: true`: The Gorouter passes through the header as received from the load balancer, without modification.
* `router.sanitize_forwarded_proto: false` and `router.force_forwarded_proto_https: false`: The Gorouter passes through the header as received from the load balancer, without modification.
If you configured TLS to stop at the Gorouter only, <%= vars.company_name %> recommends setting <code>router.sanitize_forwarded_proto: true</code> and <code>router.force_forwarded_proto_https: false</code> to secure against header spoofing.
For more information about HTTP headers in <%= vars.app_runtime_abbr %>, see [HTTP Headers](../concepts/http-routing.html#http-headers) in _HTTP Routing_. For more information about configuring the forwarding of client certificates, see [Forward Client Certificate to Apps](../concepts/http-routing.html#forward-client-cert) in _HTTP Routing_.
### <a id="pass-through"></a> Procedure: Gorouter only
<% if vars.platform_code != "CF" %>
<%= partial "/pcf/core/ssl_termin_gorouter_pcf" %>
<% else %>
<%= partial "ssl_termin_gorouter_oss" %>
<% end %>
## <a id="lb_term"></a> Stopping TLS at the load balancer only
In this configuration, your load balancer terminates TLS and passes unencrypted traffic to the Gorouter, which routes it to your app. Traffic between the load balancer and the Gorouter is not encrypted.
<%= vars.company_name %> recommends this option if you cannot use SAN certificates and if you do not require traffic to be encrypted between the load balancer and the Gorouter.
The following diagram illustrates communication between the client, load balancer, Gorouter, and app.
The preceding diagram shows configuration of the the client, load balancer, Gorouter, and app when the TLS terminates at the load balancer with lock icons.
Traffic starts at the encrypted client, passes through the load balancer to the router, and terminates at the app. Traffic is not encrypted past the load balancer.
Traffic between the Gorouter and app is encrypted with TLS, unless a Windows stemcell is being used.
### <a id="http_header_lb"></a> About HTTP header forwarding
If you stop TLS at your load balancer, you must also configure the load balancer to append the `X-Forwarded-For` and `X-Forwarded-Proto` HTTP headers to the HTTP traffic it passes to the Gorouter.
For more information about HTTP headers in <%= vars.app_runtime_abbr %>, see [HTTP Headers](../concepts/http-routing.html#http-headers) in _HTTP Routing_. If you are configuring the forwarding of client certificates, see [Forward Client Certificate to Apps](../concepts/http-routing.html#forward-client-cert) in _HTTP Routing_.
### <a id="lb"></a> Procedure: Load balancer only
<% if vars.platform_code != "CF" %>
<%= partial "/pcf/core/ssl_termin_lb_only_pcf" %>
<% else %>
<%= partial "ssl_termin_lb_only_oss" %>
<% end %>
## <a id="lb_and_gorouter_term"></a> Terminating TLS at the load balancer and Gorouter
In this configuration, two TLS connections are established: one from the client to the load balancer, and another from the load balancer to the Gorouter. This configuration secures all traffic between the load balancer and the Gorouter.
The following diagram illustrates communication between the client, load balancer, Gorouter, and app.
Traffic starts at the encrypted client, moves through the load balancer to the router, and terminates at the unencrypted app.
Traffic is encrypted between the client and load balancer, and between the load balancer and router.
This option is less performant, but allows for termination at a load balancer, as well as secure traffic between the load balancer and the Gorouter.
Traffic between the Gorouter and app is encrypted with TLS, unless a Windows stemcell is being used.
### <a id="cert_guidelines_lb_gorouter"></a> Certificate guidelines
In this deployment scenario, the following guidelines apply:
* Certificates for the <%= vars.app_runtime_abbr %> domains must be stored on the load balancer, as well as on the Gorouter.
* Generate certificates for your load balancer and the Gorouter with different keys. If the key for the certificate on the Gorouter is compromised, then the certificate on the load balancer is not at risk, and vice-versa.
* If you choose to host only one certificate on the Gorouter and many on your load balancer, configure your load balancer with the CA and host name with which to validate the certificate hosted by the Gorouter.
### <a id="hostname_verfication"></a> About host name verification
Host name verification between the load balancer and the Gorouter is unnecessary when the load balancer is already configured with the Gorouter's IP address to correctly route the request.
If the load balancer uses DNS resolution to route requests to the Gorouters, then you should enable host name verification.
### <a id="http_header_lb_gorouter"></a> About HTTP header forwarding
If you terminate TLS at your load balancer, you must configure the load balancer to append the `X-Forwarded-For` and `X-Forwarded-Proto` HTTP headers to requests it sends to the Gorouter.
If you terminate TLS at your load balancer but it does not support HTTP, such that it cannot append HTTP headers, a workaround exists. You should use this workaround **only if your load balancer does not accept unencrypted requests**. Configure your load balancer to send the client IP address using the PROXY protocol, and enable PROXY in the Gorouter. As the `X-Forwarded-Proto` header is stripped, configure the Gorouter to force-set this header to 'HTTPS'.
For more information about HTTP headers in <%= vars.app_runtime_abbr %>, see [HTTP Headers](../concepts/http-routing.html#http-headers) in _HTTP Routing_. If you are configuring the forwarding of client certificates, see [Forward Client Certificate to Apps](../concepts/http-routing.html#forward-client-cert) in _HTTP Routing_.
### <a id="lb-and-router"></a> Procedure: Load balancer and Gorouter
<% if vars.platform_code != "CF" %>
<%= partial "/pcf/core/ssl_termin_gorouter_lb_pcf" %>
<% else %>
<%= partial "ssl_termin_gorouter_lb_oss" %>
<% end %>