TLS Connections in PCF Deployments

Pivotal Cloud Foundry (PCF) uses Transport Layer Security (TLS) protocols to secure connections between internal components, app containers, and customer hardware.

Within a PCF deployment, TLS secures connections between components like the Ops Manager Director and service tiles. PCF components also use TLS connections to secure communications with external hardware, such as customer load balancers.

In Elastic Runtime, app instance containers have identity credentials that enable TLS communication by app instances.

App Instance Container Identity Credentials

Each app instance container in PCF has its own identity credentials. This section is meant to help PCF operators and developers understand and use these credentials.

Understanding the Credentials

See the following table to learn about app instance identity credentials.

Attribute Description
Purpose
  • For app developers to enable secure TLS communications from their apps.
  • For PCF to use internally to validate the identities of app instances.
Type
Location
  • PCF presents the certificate and private key to the app instance through the container filesystem.
Properties of certificate
  • The Common Name is the app instance GUID.
  • The Subject of the certificate contains an Organizational Unit in the form of app:APP-GUID.
  • The certificate contains a Subject Alternative Name (SAN) with the IP address for the app instance container.
  • The certificate is valid for 24 hours after being issued.
Contents of certificate file
  • A chain of PEM-encoded certificates, with the instance-specific certificate first in the list and any intermediates following it.
Issuing authority
  • PCF includes a root Certificate Authority (CA) dedicated to app instance identity. This CA is saved in the system trust store for buildpack-based apps and in a file in /etc/cf-system-certificates in all app instance containers.

Using the Credentials

If you want to enable secure TLS communications from an app using container instance identity credentials, ensure that you do the following:

  • Add the credentials to your development stack configuration:

    • The credentials must be present in your development stack configuration for your app to use them. You can retrieve the credentials through following environment variables, which PCF sets to the locations of key and certificate files.

      Credential / Keypair Element Environment Variable Command to Retrieve Credential Value
      Certificate Chain CF_INSTANCE_CERT cf ssh APP-NAME -c 'cat $CF_INSTANCE_CERT'
      Private Key CF_INSTANCE_KEY cf ssh APP-NAME -c 'cat $CF_INSTANCE_KEY'
  • Reload the credential files before they expire:

    • PCF rotates the credentials shortly before the current certificate expires. Apps that use these credentials must reload the certificate and key file contents either periodically or in reaction to filesystem watcher events.
  • Configure external clients or servers to trust the root CA:

    • To enable secure TLS communication between an app and a client or server external to PCF, you must configure the external client or server to trust the CA that issues app instance container identity credentials. See the Issuing Authority row of the table in Understanding the Credentials.

Additional Information

For more information about instance identity credentials, see the Instance Identity document in the diego-release repository.

TLS Cipher Suites

By default, PCF uses a limited set of cipher suites to secure its internal communications. However, some components used in PCF, like Gorouter and HAProxy, may support additional TLS cipher suites to accommodate older clients outside of PCF.

The AWS Classic load balancer does not support the recommended TLS cipher suites. See Securing Traffic into Cloud Foundry for details and mitigations.

For components that allow you to configure TLS cipher suites, only specify the TLS cipher suites that you need.

TLS Cipher Suite Recommendations

The default and recommended version of TLS to use is TLS v1.2.

The recommended TLS cipher suites to use within PCF are the following:

  • TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
  • TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

Gorouter Configuration

As part of your Elastic Runtime networking configuration, you must specify the TLS cipher suites that Gorouter uses to secure its communications. Only specify the cipher suites that you need.

The recommended TLS cipher suites for Gorouter are:

  • ECDHE-RSA-AES128-GCM-SHA256
  • ECDHE-RSA-AES256-GCM-SHA384

You can specify other cipher suites and a different minimum version of TLS support if your deployment requires it. For a list of other cipher suites and other versions of TLS that are optionally supported by Gorouter, see Securing Traffic into Cloud Foundry.

For instructions on how to configure the TLS cipher suites for Gorouter, see the Elastic Runtime installation documentation for the IaaS of your deployment. For example, if you are deploying Elastic Runtime on GCP, see Step 6: Configure Networking.

HAProxy Configuration

As part of your Elastic Runtime networking configuration, you must specify the TLS cipher suites that HAProxy uses to secure its communications. Only specify the cipher suites that you need.

The recommended TLS cipher suites for HAProxy are:

  • DHE-RSA-AES128-GCM-SHA256
  • DHE-RSA-AES256-GCM-SHA384
  • ECDHE-RSA-AES128-GCM-SHA256
  • ECDHE-RSA-AES256-GCM-SHA384

You can specify other cipher suites and a different minimum version of TLS support if your deployment requires it. For a list of other cipher suites and other versions of TLS that are optionally supported by HAProxy, see ciphers - Cipher Suite Names in the OpenSSL documentation.

If you use the default and recommended Gorouter TLS cipher suites in Elastic Runtime, then ensure you have included these Gorouter TLS cipher suites in your HAProxy TLS cipher suite configuration.

If you change the default Gorouter TLS cipher suites in Elastic Runtime, and you change the TLS cipher suites for HAProxy, ensure that you have at least one overlapping TLS cipher suite within the two sets.

For instructions on how to configure the TLS cipher suites for HAProxy, see the Elastic Runtime installation documentation for the IaaS of your deployment. For example, if you are deploying Elastic Runtime on GCP, see Step 6: Configure Networking.

Create a pull request or raise an issue on the source for this page in GitHub