<commit_before>---
title: Securing Traffic into Cloud Foundry
owner: Routing
---

<strong><%= modified_date %></strong>

This topic describes how to secure traffic into your Cloud Foundry (CF) deployment with SSL/TLS certificates. You can configure your deployment to specify where to terminate TLS depending on your needs. 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 router.

The advantages of securing the connection between your load balancer and router instances include:

* A high level of security.
* The ability to secure a deployment that shares a load balancer with other deployments.
* The ability to manage certificates as part of your deployment manifest, which eliminates the need for out-of-band configuration of your load balancer.

##<a id="requirements"></a> Requirements

* You must obtain a SSL/TLS certificate. In a production environment, use a signed SSL/TLS certificate from a known certificate authority (CA). In a development or testing environment, you may use a self-signed certificate generated with `openssl` or a similar tool.
* The CF router only supports HTTP requests. Whatever configuration you choose for securing traffic, it must result in the CF router receiving HTTP requests.
* The CF router currently only supports configuring a single HTTPS certificate. [Subject Alternative Name](https://tools.ietf.org/html/rfc5280#section-4.2.1.6), an X.509 extension, can be used to associate multiple domains, including wildcard domains, to a single certificate.

##<a id="pass-through"></a> Terminate TLS at Router Only
<p class='note'><strong>Note</strong>: This is the recommended approach.</p>
<%= image_tag("pass-through.png") %>

In this configuration, the load balancer does not terminate TLS for CF domains at all. Instead, it passes through the underlying TCP connection to the router. This is the more performant option, establishing and terminating a single TLS connection. The certificate on the router must be associated with the correct hostname so that HTTPS can validate the request, and signed by a trusted CA.

Traffic between the load balancer and the router is encrypted only if the client request is encrypted.

To enable this configuration, perform the following steps:

1. Configure your load balancer to pass through requests from the client to the CF router.
1. Configure your load balancer to append the X-Forwarded-For and X-Forwarded-Proto headers to client requests if possible. If the HTTP request that reaches the router does not include the X-Forwarded headers, the router sets X-Forwarded-For to the IP address of the load balancer, and X-Forwarded-Proto to the scheme of the client request.
1. Insert the certificate into your deployment manifest for the CF router:
	1. Use `bosh edit deployment` to open your release manifest for editing.
	1. Copy the contents of your certificate file into the `properties.router.ssl_cert` field and the contents of the private key file associated with your certificate into the `properties.router.ssl_key` field. Set `enable_ssl` to `true`.

		```
		properties:
		  router:
		    ssl_cert: |
		      -----BEGIN CERTIFICATE-----
		      SSL_CERTIFICATE_SIGNED_BY_PRIVATE_KEY
		      -----END CERTIFICATE-----
		    ssl_key: |
		      -----BEGIN RSA PRIVATE KEY-----
		      RSA_PRIVATE_KEY
		      -----END RSA PRIVATE KEY-----
		    enable_ssl: true
		```

##<a id="lb-and-router"></a> Terminate TLS at Load Balancer and Router
<%= image_tag("lb-and-router.png") %>

<p class='note'><strong>Note</strong>: Hostname verification between the load balancer and CF router is unnecessary when the load balancer is already configured with the CF router's IP address to correctly route the request. If DNS resolution is being used by the load balancer to route requests to the CF routers, you should enable hostname verification.</p>

In this configuration, CF establishes and terminates two TLS connections: one from the client to the load balancer, and another from the load balancer to the CF router. This option is less performant, but it does allow for multiple certificates to be used, meaning multiple domains can be verified when using HTTPS. Certificates for the CF domains must be stored on the load balancer and, if hostname validation is enabled, on the CF router (using a single certificate). The certificate on the CF router only needs to be trusted by the load balancer, and the domain does not need to match the request as long as hostname verification is not enabled on the load balancer.

This configuration secures all traffic between the load balancer and the router.

<p class="note"><strong>Note</strong>: If your CF deployment uses a self-signed certificate, the client needs to install only the certificate stored on the load balancer.</p>

To enable this configuration, perform the following steps:

1. Add your certificate to your load balancer and configure its listening port. The procedures vary depending on your IaaS.
1. Configure your load balancer to append the X-Forwarded-For and X-Forwarded-Proto headers to client requests.

	<br/>If the load balancer cannot be configured to provide the X-Forwarded-For header, the CF router will append it in requests forwarded to applications and system components, set to the IP address of the load balancer.

	<p class='note'><strong>Note</strong>: If the load balancer accepts unencrypted requests, it <strong>must</strong> provide the X-Forwarded-Proto header. Conversely, if the load balancer cannot be configured to send the X-Forwarded-Proto header it should not accept unencrypted requests. Otherwise, applications and platform system components that require encrypted client requests will accept unencrypted requests when they shouldn't.</p>

1. Insert the certificate into your deployment manifest for the CF router:
	1. Use `bosh edit deployment` to open your release manifest for editing.
	1. Copy the contents of your certificate file into the `properties.router.ssl_cert` field and the contents of the private key file associated with your certificate into the `properties.router.ssl_key` field. Set `enable_ssl` to `true`.

		```
		properties:
		  router:
		    ssl_cert: |
		      -----BEGIN CERTIFICATE-----
		      SSL_CERTIFICATE_SIGNED_BY_PRIVATE_KEY
		      -----END CERTIFICATE-----
		    ssl_key: |
		      -----BEGIN RSA PRIVATE KEY-----
		      RSA_PRIVATE_KEY
		      -----END RSA PRIVATE KEY-----
		    enable_ssl: true
		```


##<a id="lb"></a> Terminate TLS at Load Balancer Only
<%= image_tag("lb.png") %>

In this configuration, your load balancer terminates TLS, and passes unencrypted traffic to the router, which routes it to your app. Traffic between the load balancer and the router is not encrypted.

To enable this configuration, you must perform the following steps:

1. Configure your load balancer to append the X-Forwarded-For and X-Forwarded-Proto headers to client requests.

	<br/>If the load balancer cannot be configured to provide the X-Forwarded-For header, the CF router will append it in requests forwarded to applications and system components, set to the IP address of the load balancer.

	<p class="note"><strong>Note</strong>: When terminating TLS at the load balancer only, the load balancer <strong>must</strong> be configured to forward the X-Forwarded-Proto header. Otherwise requests to some applications and system components will result in redirect loops, as they will redirect requests to HTTPS.</p>

1. Add your certificate to your load balancer and configure its listening port. The procedures vary depending on your IaaS.<commit_msg>clarifying consequences for LB not sending headers<commit_after>---
title: Securing Traffic into Cloud Foundry
owner: Routing
---

<strong><%= modified_date %></strong>

This topic describes how to secure traffic into your Cloud Foundry (CF) deployment with SSL/TLS certificates. You can configure your deployment to specify where to terminate TLS depending on your needs. 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 router.

The advantages of securing the connection between your load balancer and router instances include:

* A high level of security.
* The ability to secure a deployment that shares a load balancer with other deployments.
* The ability to manage certificates as part of your deployment manifest, which eliminates the need for out-of-band configuration of your load balancer.

##<a id="requirements"></a> Requirements

* You must obtain a SSL/TLS certificate. In a production environment, use a signed SSL/TLS certificate from a known certificate authority (CA). In a development or testing environment, you may use a self-signed certificate generated with `openssl` or a similar tool.
* The CF router only supports HTTP requests. Whatever configuration you choose for securing traffic, it must result in the CF router receiving HTTP requests.
* The CF router currently only supports configuring a single HTTPS certificate. [Subject Alternative Name](https://tools.ietf.org/html/rfc5280#section-4.2.1.6), an X.509 extension, can be used to associate multiple domains, including wildcard domains, to a single certificate.

##<a id="pass-through"></a> Terminate TLS at Router Only
<p class='note'><strong>Note</strong>: This is the recommended approach.</p>
<%= image_tag("pass-through.png") %>

In this configuration, the load balancer does not terminate TLS for CF domains at all. Instead, it passes through the underlying TCP connection to the router. This is the more performant option, establishing and terminating a single TLS connection. The certificate on the router must be associated with the correct hostname so that HTTPS can validate the request, and signed by a trusted CA.

Traffic between the load balancer and the router is encrypted only if the client request is encrypted.

To enable this configuration, perform the following steps:

1. Configure your load balancer to pass through requests from the client to the CF router.
1. Configure your load balancer to append the X-Forwarded-For and X-Forwarded-Proto headers to client requests if possible. If the HTTP request that reaches the router does not include the X-Forwarded headers, the router sets X-Forwarded-For to the IP address of the load balancer, and X-Forwarded-Proto to the scheme of the client request.
1. Insert the certificate into your deployment manifest for the CF router:
	1. Use `bosh edit deployment` to open your release manifest for editing.
	1. Copy the contents of your certificate file into the `properties.router.ssl_cert` field and the contents of the private key file associated with your certificate into the `properties.router.ssl_key` field. Set `enable_ssl` to `true`.

		```
		properties:
		  router:
		    ssl_cert: |
		      -----BEGIN CERTIFICATE-----
		      SSL_CERTIFICATE_SIGNED_BY_PRIVATE_KEY
		      -----END CERTIFICATE-----
		    ssl_key: |
		      -----BEGIN RSA PRIVATE KEY-----
		      RSA_PRIVATE_KEY
		      -----END RSA PRIVATE KEY-----
		    enable_ssl: true
		```

##<a id="lb-and-router"></a> Terminate TLS at Load Balancer and Router
<%= image_tag("lb-and-router.png") %>

<p class='note'><strong>Note</strong>: Hostname verification between the load balancer and CF router is unnecessary when the load balancer is already configured with the CF router's IP address to correctly route the request. If DNS resolution is being used by the load balancer to route requests to the CF routers, you should enable hostname verification.</p>

In this configuration, CF establishes and terminates two TLS connections: one from the client to the load balancer, and another from the load balancer to the CF router. This option is less performant, but it does allow for multiple certificates to be used, meaning multiple domains can be verified when using HTTPS. Certificates for the CF domains must be stored on the load balancer and, if hostname validation is enabled, on the CF router (using a single certificate). The certificate on the CF router only needs to be trusted by the load balancer, and the domain does not need to match the request as long as hostname verification is not enabled on the load balancer.

This configuration secures all traffic between the load balancer and the router.

<p class="note"><strong>Note</strong>: If your CF deployment uses a self-signed certificate, the client needs to install only the certificate stored on the load balancer.</p>

To enable this configuration, perform the following steps:

1. Add your certificate to your load balancer and configure its listening port. The procedures vary depending on your IaaS.
1. Configure your load balancer to append the X-Forwarded-For and X-Forwarded-Proto headers to client requests.

	<br/>If the load balancer cannot be configured to provide the X-Forwarded-For header, the CF router will append it in requests forwarded to applications and system components, set to the IP address of the load balancer.

	<p class='note'><strong>Note</strong>: If the load balancer accepts unencrypted requests, it <strong>must</strong> provide the X-Forwarded-Proto header. Conversely, if the load balancer cannot be configured to send the X-Forwarded-Proto header it should not accept unencrypted requests. Otherwise, applications and platform system components that require encrypted client requests will accept unencrypted requests when they shouldn't.</p>

1. Insert the certificate into your deployment manifest for the CF router:
	1. Use `bosh edit deployment` to open your release manifest for editing.
	1. Copy the contents of your certificate file into the `properties.router.ssl_cert` field and the contents of the private key file associated with your certificate into the `properties.router.ssl_key` field. Set `enable_ssl` to `true`.

		```
		properties:
		  router:
		    ssl_cert: |
		      -----BEGIN CERTIFICATE-----
		      SSL_CERTIFICATE_SIGNED_BY_PRIVATE_KEY
		      -----END CERTIFICATE-----
		    ssl_key: |
		      -----BEGIN RSA PRIVATE KEY-----
		      RSA_PRIVATE_KEY
		      -----END RSA PRIVATE KEY-----
		    enable_ssl: true
		```


##<a id="lb"></a> Terminate TLS at Load Balancer Only
<%= image_tag("lb.png") %>

In this configuration, your load balancer terminates TLS, and passes unencrypted traffic to the router, which routes it to your app. Traffic between the load balancer and the router is not encrypted.

To enable this configuration, you must perform the following steps:

1. Configure your load balancer to append the X-Forwarded-For and X-Forwarded-Proto headers to client requests.

	<br/>If the load balancer cannot be configured to provide the X-Forwarded-For header, the CF router will append it in requests forwarded to applications and system components, set to the IP address of the load balancer.

	<p class="note"><strong>Note</strong>: When terminating TLS at the load balancer only, the load balancer <strong>must</strong> be configured to forward the X-Forwarded-Proto header. Otherwise requests to some applications and system components will result in redirect loops, as they will redirect requests believed to be unencrypted to HTTPS.</p>

1. Add your certificate to your load balancer and configure its listening port. The procedures vary depending on your IaaS.
{'fraction_non_alphanumeric': 0.06444906444906445, 'fraction_numerical': 0.0029885654885654887, 'mean_word_length': 4.132710903634544, 'pattern_counts': {'":': 0, '<': 83, '<?xml version=': 0, '>': 83, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 2, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3685186', 'n_tokens_mistral': 3933, 'n_tokens_neox': 3661, 'n_words': 2113}