TLS Connections in Pivotal Platform

Page last updated:

This topic describes the different paths through which external clients, internal components, app containers, and app services communicate in Pivotal Platform, and how the platform uses Transport Layer Security (TLS) protocols to secure these communications.

Types of Network Communication in Pivotal Platform

This section describes the different types of network communication in Pivotal Platform and how they are secured with TLS.

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

Between an External Client and an App

The following diagram illustrates the flow of communication from a client making a request to an app:

Ingress traffic

The following table describes each component involved in receiving a client request and where their certificates for TLS termination originate.

Component Certificate Source
External Load Balancer Enterprise Root CA.
Gorouter Enterprise Root CA.
App Pivotal Platform root CA dedicated to app instance identity. For more information, see App Instance Container Identity Credentials.

Between Platform Components

The following diagram illustrates communication between platform components, secured with TLS.

Platform components

The CredHub instance in BOSH generates certificates for all components in Pivotal Platform. The certificates are self-signed by default. To issue certificates signed by your enterprise, you can add a custom CA to CredHub.

Note: Traffic between the Gorouter and Windows stemcells is not encrypted with TLS.

Component Communication Details

The following topics list the paths, ports, and protocols that subsystems within Pivotal Application Service (PAS) use to communicate.

Between Apps

The following diagram illustrates TLS communications between apps running on Pivotal Platform. In this example, the frontend-blue and frontend-green apps both receive client requests, but only the frontend-green app is allowed to communicate with the backend app.

Between app traffic

Apps can communicate with each other over TLS using certificates generated by a Pivotal Platform root CA dedicated to app instance identity. For more information, see App Instance Container Identity Credentials.

Developers specify which apps are allowed to communicate using container networking policies. For more information, see Configuring Container-to-Container Networking.

Between Apps and On-Platform Services

The following diagram illustrates TLS communication between apps and managed, on-platform services. It uses Pivotal Cloud Cache as an example of a managed service.

Apps services

BOSH CredHub issues certificates to the Pivotal Cloud Cache components. For the app, the developer must retrieve a copy of this certificate using the CredHub API and place it in the truststore for the app. For more information, see Developing an App Under TLS in the Pivotal Cloud Cache documentation.

Separately, PAS Runtime CredHub might store credentials for the app to access a service over the TLS connection, adding a second layer of security. For more information, see Securing Services Instance Credentials with Runtime CredHub.

Between Apps and External Services

The following diagram illustrates communications between apps and external, brokered services secured with TLS.

Apps external services

The developer must retrieve the certificate from the external service and provide it to their app. One way to do this is by placing the certificate in Runtime CredHub and modifying your app to consume the certificate through the CredHub Service Broker. For more information, see the CredHub Service Broker for Pivotal Platform documentation.

App Instance Container Identity Credentials

Each app instance container in Pivotal Platform has its own identity credentials. This section describes how to understand and use these credentials.

About App Instance Identity Credentials

To learn about app instance identity credentials, see the following table:

Attribute Description
Purpose
  • For app developers to enable secure TLS communications from their apps.
  • For Pivotal Platform to use internally to validate the identities of app instances.
Type
Location
  • Pivotal Platform 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
  • Pivotal Platform 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 Pivotal Platform 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:

    • Pivotal Platform 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 Pivotal Platform, you must configure the external client or server to trust the CA that issues app instance container identity credentials. For more information, see the Issuing Authority row of the table in About App Instance Identity Credentials.

Additional Information

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

TLS Cipher Suites

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

Note: The AWS Classic load balancer does not support the recommended TLS cipher suites. For details and mitigations, see the TLS Cipher Suite Support section of the Securing Traffic into PAS topic.

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 Pivotal Platform are:

  • 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 PAS networking configuration, you must specify the TLS cipher suites that the Gorouter uses to secure its communications. Only specify the cipher suites that you need.

The recommended TLS cipher suites for the 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 the Gorouter, see the TLS Cipher Suite Support section of the Securing Traffic into PAS topic.

For instructions on how to configure the TLS cipher suites for the Gorouter, see the Configure Networking section of the Configuring PAS topic.

HAProxy Configuration

As part of your PAS 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 PAS, 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 PAS, 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 Configure Networking section of the Configuring PAS topic.