Securing Traffic into Cloud Foundry

Page last updated:

This topic describes the options for securing HTTP traffic into your Cloud Foundry (CF) deployment with TLS certificates. You can configure the location where your deployment terminates TLS depending on your needs and certificate restrictions.

Protocol Support

The Gorouter supports HTTP/HTTPS requests only. For more information about features supported by the Gorouter, see the HTTP Routing topic.

To secure non-HTTP traffic over TCP Routing, terminate TLS at your load balancer or at the application. See TCP Routing for details.

TLS Termination Options for HTTP Routing

There are several options for terminating TLS for HTTP traffic. You can terminate TLS at the Gorouter, your load balancer, or at both.

The following table summarizes TLS termination options and which option to choose for your deployment.

If the following applies to you: Then configure TLS termination at: Related topic and configuration procedure
  • You want the optimum balance of performance and security, and
  • You want to make minimum changes to your load balancer, or
  • You are deploying CF to AWS. For information about AWS limitations, see TLS Cipher Suite Support by AWS ELBs.
Gorouter only Terminating TLS at the Gorouter Only
  • You require TLS termination at a load balancer, or
  • You want the highest level of security, and
  • You do not mind a slightly less performant deployment.
Load Balancer and Gorouter Terminating TLS at the Load Balancer and Gorouter
  • You require TLS termination at a load balancer, and
  • You prefer unencrypted traffic between the Load Balancer and the Gorouter.
Load Balancer only Terminating TLS at the Load Balancer Only

Certificate Requirements

The following requirements apply to the certificates you use to secure traffic into Cloud Foundry:

  • 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.
  • Certificates used in CF 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 may be that of the load balancer or of the originating client.

  • The certificate on the Gorouter must be associated with the correct hostname 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 hostnames, 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 Cloud Foundry, use of wildcard domains is highly recommended to avoid the need for adding an additional certificate for each application.

Multiple Certificates

In order to support custom domains on CF, an operator has to configure the Gorouter with a certificate that represents the domain. It is recommended 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 applications running on a CF platform.

The Gorouter supports SNI and can be configured with multiple certificates, each which may optionally include 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.

How to Configure Multiple Certificate Keypairs

To configure multiple HTTPS certificates for CF, specify those certificate keypairs in the router.tls_pem property.

The following is an example for configuring two certificate keypairs using router.tls_pem

 properties:
    router:
      tls_pem:
      - cert_chain: |
         -----BEGIN CERTIFICATE-----
         MIIFDjBABgkqhkiG9w0BBQ0wMzAbBgkqhkiG9w0BBQwwDg
         MBQGCCqGSIb3DQMHBAgD1kGN4ZslJgSCBMi1xk9jhlPxPc
         9g73NQbtqZwI+9X5OhpSg/2ALxlCCjbqvzgSu8gfFZ4yo+
         A .... MANY LINES LIKE THAT ....
         X0R+meOaudPTBxoSgCCM51poFgaqt4l6VlTN4FRpj+c/Wc
         blK948UAda/bWVmZjXfY4Tztah0CuqlAldOQBzu8TwE7WD
         H0ga/iLNvWYexG7FHLRiq5hTj0g9mUPEbeTXuPtOkTEb/0
         GEs=
         ----END CERTIFICATE-----
        private_key: |
         -----BEGIN EXAMPLE ENCRYPTED PRIVATE KEY-----
         MIIFDjBABgkqhkiG9w0BBQ0wMzAbBgkqhkiG9w0BBQwwDg
         MBQGCCqGSIb3DQMHBAgD1kGN4ZslJgSCBMi1xk9jhlPxPc
         9g73NQbtqZwI+9X5OhpSg/2ALxlCCjbqvzgSu8gfFZ4yo+
         A .... MANY LINES LIKE THAT ....
         X0R+meOaudPTBxoSgCCM51poFgaqt4l6VlTN4FRpj+c/Wc
         blK948UAda/bWVmZjXfY4Tztah0CuqlAldOQBzu8TwE7WD
         H0ga/iLNvWYexG7FHLRiq5hTj0g9mUPEbeTXuPtOkTEb/0
         GEs=
         -----END EXAMPLE ENCRYPTED PRIVATE KEY-----
      - cert_chain: |
         -----BEGIN CERTIFICATE-----
         MIIDXTCCAkWgAwIBAgIJAJC1HiIAZAiIMA0GCSqGSIb3Df
         BAYTAkFVMRMwEQYDVQQIDApTb21lLVN0YXRlMSEwHwYDVx
         aWRnaXRzIFB0eSBMdGQwHhcNMTExMjMxMDg1OTQ0WhcNMT
         A .... MANY LINES LIKE THAT ....
         JjyzfN746vaInA1KxYEeI1Rx5KXY8zIdj6a7hhphpj2E04
         C3Fayua4DRHyZOLmlvQ6tIChY0ClXXuefbmVSDeUHwc8Yu
         B7xxt8BVc69rLeHV15A0qyx77CLSj3tCx2IUXVqRs5mlSb
         vA==
         -----END CERTIFICATE-----
        private_key: |
         -----BEGIN EXAMPLE ENCRYPTED PRIVATE KEY-----
         MIIFDjBABgkqhkiG9w0BBQ0wMzAbBgkqhkiG9w0BBQwwDg
         MBQGCCqGSIb3DQMHBAgD1kGN4ZslJgSCBMi1xk9jhlPxPc
         9g73NQbtqZwI+9X5OhpSg/2ALxlCCjbqvzgSu8gfFZ4yo+
         A .... MANY LINES LIKE THAT ....
         X0R+meOaudPTBxoSgCCM51poFgaqt4l6VlTN4FRpj+c/Wc
         blK948UAda/bWVmZjXfY4Tztah0CuqlAldOQBzu8TwE7WD
         H0ga/iLNvWYexG7FHLRiq5hTj0g9mUPEbeTXuPtOkTEb/0
         GEs=
         -----END EXAMPLE ENCRYPTED PRIVATE KEY-----

TLS Cipher Suite Support

Some CF 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.

Default Gorouter Cipher Suites

By default, the Gorouter supports the following TLS cipher suites, both of which require TLS v1.2:

RFC OpenSSL
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 ECDHE-RSA-AES128-GCM-SHA256
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 ECDHE-RSA-AES256-GCM-SHA384

You can override the default cipher suites by changing the router.cipher_suites and router.min_tls_version BOSH manifest properties.

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, operators may encounter a “Cipher Suite Mismatch” error. This is because the cipher suites supported by Classic Load Balancers for TLS handshakes with backends (Gorouters in this case) are hardcoded, undocumented, and do not support the Gorouter default cipher suites.

Operators have two options:

  • Configure Classic Load Balancer listeners in TCP mode so that TCP connections from clients are passed through the Classic Load Balancer to Gorouters on port 443. Then 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) that support the Gorouter default cipher suites.

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

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

You can override the default cipher suites by changing the router.cipher_suites and router.min_tls_version BOSH manifest properties.

See Golang Constants and OpenSSL Cipher Suites for more information about supported ciphers.

Note: ECDSA ciphers require a certificate and key for DSA, as opposed to RSA.

Mutual Authentication with Clients

Gorouter supports validation of client certificates in TLS handshakes with clients, also known as mutual authentication. Operators can choose whether Gorouter requests client certificates and when requesting certificates, whether or not to require them.

By default, Gorouter requests but does not require client certificates in TLS handshakes.

Operators may change this behavior with the property router.client_cert_validation. This property accepts the following values:

  • none: The Gorouter does not request client certificates in TLS handshakes so clients will not provide them and validation of client certificates does not occur. This option is incompatible with forwarded_client_cert: forward or forwarded_client_cert: sanitize_set XFCC configurations because these options require mutual authentication.
  • request: The Gorouter requests client certificates in TLS handshakes. The handshake will fail if the client certificate is not signed by a CA configured in router.ca_certs. This is the default configuration.
  • require: The Gorouter requests client certificates in TLS handshakes. The handshake will fail if a client cert is not provided or if the client certificate is not signed by a CA that the Gorouter trusts.

The behavior controlled by this property is global; it applies to all requests received by Gorouters so configured.

If Gorouter is the first point of TLS termination (your load balancer does not terminate TLS, and passes the request through to Gorouter over TCP), consider the following: - Only option none should be used for Gorouters receiving requests for the system domain. Many clients of CF platform APIs do not present client certificates in TLS handshakes, so the first point of TLS termination for requests to the system domain must not request them. - All options may be used for Gorouters receiving requests only for app domains, as when dedicated routers are used for an Isolation Segment. - Options request and require will trigger browsers to prompt users to select a certificate if the browser is not already configured with a certificate signed by one of the CAs configured in router.ca_certs.

If Gorouter is not the first point of TLS termination, this property can be used to secure communications between the Load Balancer and Gorouter. Gorouter must be configured with the CA used to sign the client certification the load balancer will present, using router.ca_certs.

Terminating TLS at the Gorouter Only

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 Gorouter.

This option is the recommended and more performant option, establishing and terminating a single TLS connection.

The following diagram illustrates communication between the client, load balancer, Gorouter, and app.

Pass through

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

About HTTP Header Forwarding

If you terminate 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 applications 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 may be the IP address of your load balancer. For the Gorouter to deliver the IP address of the client to applications, 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. The Gorouter will set X-Forwarded-Proto to the scheme of the client request.

For more information about HTTP headers in CF, see HTTP Headers. If you are configuring the forwarding of client certificates, see Forward Client Certificate to Applications.

Procedure: Gorouter Only

To enable this configuration, perform the following steps:

  1. Configure your load balancer to pass through requests from the client to the Gorouter.
  2. Insert the certificates into your deployment manifest for the Gorouter:

    1. Open your release manifest using your preferred text editor.
    2. Copy the contents of your certificate chain and private key associated with your certificate into the properties.router.tls_pem field.
    3. Set enable_ssl to true.

      properties:
        router:
          tls_pem:
          - cert_chain: |
              -----BEGIN CERTIFICATE-----
              SSL_CERTIFICATE_SIGNED_BY_PRIVATE_KEY
              -----END CERTIFICATE-----
            private_key: |
              -----BEGIN EXAMPLE RSA PRIVATE KEY-----
              RSA_PRIVATE_KEY
              -----END EXAMPLE RSA PRIVATE KEY-----
          enable_ssl: true
      

Terminating 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.

This option is recommended 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.

Lb

About HTTP Header Forwarding

If you terminate TLS at your load balancer, then 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 CF, see HTTP Headers. If you are configuring the forwarding of client certificates, see Forward Client Certificate to Applications.

Procedure: Load Balancer Only

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

  1. Add your certificates to your load balancer and configure its listening port. The procedures vary depending on your IaaS.
  2. Configure your load balancer to append the X-Forwarded-For and X-Forwarded-Proto headers to client requests.
    • If the load balancer cannot be configured to provide the X-Forwarded-For header, the Gorouter appends it in requests forwarded to applications and system components, set to the IP address of the load balancer.

      Important: You must configure the load balancer to forward the X-Forwarded-Proto header. Otherwise requests to some applications and system components result in redirect loops, as requests determined to be unencrypted are redirected to HTTPS.

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.

Lb 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.

Certificate Guidelines

In this deployment scenario, the following guidelines apply:

  • Certificates for the Cloud Foundry 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 hostname with which to validate the certificate hosted by the Gorouter.

About Hostname Verification

Hostname 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 hostname verification.

About HTTP Header Forwarding

If you terminate TLS at your load balancer, then 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. We recommend you 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 will not be present, configure the Gorouter to force-set this header to ‘HTTPS’.

For more information about HTTP headers in CF, see HTTP Headers. If you are configuring the forwarding of client certificates, see Forward Client Certificate to Applications.

Procedure: Load Balancer and Gorouter

To enable this configuration, perform the following steps:

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


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

    Note: If the load balancer accepts unencrypted requests, it must 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 depend on the X-Forwarded-Proto header to reject unencrypted client requests will accept unencrypted requests.

  3. Insert the certificates into your deployment manifest for the Gorouter:

    1. Open your release manifest using your preferred text editor.
    2. Copy the contents of your certificate chain and private key associated with your certificate into the properties.router.tls_pem field.
    3. Set enable_ssl to true.

      properties:
        router:
          tls_pem:
          - cert_chain: |
              -----BEGIN CERTIFICATE-----
              SSL_CERTIFICATE_SIGNED_BY_PRIVATE_KEY
              -----END CERTIFICATE-----
            private_key: |
              -----BEGIN EXAMPLE RSA PRIVATE KEY-----
              RSA_PRIVATE_KEY
              -----END EXAMPLE RSA PRIVATE KEY-----
          enable_ssl: true
      
Create a pull request or raise an issue on the source for this page in GitHub