Preparing for TLS

Page last updated:

This topic provides an overview of how to prepare for using Transport Layer Security (TLS) with the Redis on-demand service to secure communication between apps and service instances.

This topic also includes procedures for providing an existing CA certificate to BOSH CredHub and generating a new CA certificate with BOSH CredHub.

Warning: To enable TLS for Redis for PCF, you must perform the procedures in Provide or Generate a CA Certificate below before installing and configuring the tile.

This certificate is shared by multiple tiles. If you have already performed this procedure, you do not need to repeat it. To change this certificate, follow the steps in Rotating Certificates.

Overview

Enabling TLS co-locates a second TLS-enabled port on Redis for PCF service instances. Apps and clients can use this port to establish encrypted connections with the data service. The certificate used in this connection is a server certificate generated by CredHub.

CredHub is a component designed for centralized credential management in PCF and is co-located on the BOSH Director. CredHub generates the server certificate with a Certificate Authority (CA). The operator can provide a certificate to CredHub or have CredHub generate a new certificate.

Apps and clients that communicate with the Redis for PCF server must have access to the public component of the CA certificate to use the certificate and check that it is trustworthy.

PCF distributes the public component of the CA certificate by provisioning a copy of the CA certificate in the trusted store of each container’s operating system. Apps written in Java and Spring, or C# and Steeltoe, automatically discover the CA certificate in the trusted store.

Workflow for Enabling and Using TLS

The following workflow is required to enable TLS and to allow developers to use it with their apps:

  1. An operator does one of the following:
    • If you are using Ops Manager 2.5 or earlier or want to provide a custom certificate, an operator provides a CA certificate to CredHub by completing the procedures in Provide or Generate a CA Certificate below.
    • If you are using Pivotal Ops Manager v2.6 or later, a default CA certificate is provided by Ops Manager. You do not need to generate the CA certificate. To use the default CA certificate, do the last two steps in Add the CA Certificate below.
  2. An operator enables TLS Optional in the tile configuration while installing Redis for PCF. For more information, see On-Demand Service Settings.
  3. An app developer modifies their app to communicate securely with the Redis server. For more information, see Using TLS.

Note: An operator must also rotate the CA certificate if it expires or if it becomes compromised. For information about how to rotate your CA certificate, see Rotating CA Certificates.

Provide or Generate a CA Certificate

To enable and use TLS, you must complete the procedures below before installing and configuring the tile.

Warning: This procedure requires restarting all of the VMs in your PCF deployment in order to apply a CA certificate. This operation can take a long time to complete.

Create a UAA Client

Note: If you are using Pivotal Ops Manager v2.6 or later and want to use the default CA certificate provided by Ops Manager, do not do the following procedure.

Follow these steps to create a UAA client for CredHub on your UAA server:

  1. Retrieve the IP address of the BOSH Director VM and the Director credentials by completing the steps in Gather Credential and IP Address Information.
    Both the UAA and CredHub servers are co-located on the BOSH Director VM.

  2. SSH into the Ops Manager VM by following the steps in SSH into Ops Manager VM.

  3. From the Ops Manager VM, target the UAA server on the BOSH Director VM by running the following command in the UAA Command Line Interface (UAAC):

    uaac target BOSH-DIRECTOR-IP:8443
    

    Where BOSH-DIRECTOR-IP is the IP address of the BOSH Director VM and 8443 is the port to use. You retrieved the BOSH Director IP address in step 1.

    For example:

    $ uaac target 10.0.0.5:8443
    

  4. In the Credentials tab of the BOSH Director tile, retrieve and record the identity and password values for:

    • UAA Login Client Credentials
    • UAA Admin User Credentials

    Note: These are the credentials for the UAA server that is co-located on the BOSH Director, not the UAA server that is co-located on Pivotal Application Service (PAS).

  5. From the Ops Manager VM, use the UAAC to get a token by running the following command:

    uaac token owner get login --secret=UAA-LOGIN-CLIENT-CRED
    

    Where UAA-LOGIN-CLIENT-CRED is the password value of the UAA login client credentials that you retrieved in the previous step.

    For example:

    $ uaac token owner get \
        login --secret=abcdefghijklm123456789
    

  6. When prompted for a username and password, enter the values for identity and password of the UAA Admin User Credentials that you retrieved in the previous step.

    For example:

    User name:  admin
    Password:  ********************************
    

  7. Add a UAA client for CredHub with the correct grants by running the following command:

    uaac client add \
      --authorized_grant_types client_credentials \
      --authorities credhub.read,credhub.write
    
  8. When prompted for a client ID, enter credhub.

  9. When prompted for a new client secret, enter a secure password of your choice.

    For example:

    Client ID:  credhub
    New client secret:  *******
    Verify new client secret:  *******
      scope: uaa.none
      client_id: credhub
      resource_ids: none
      authorized_grant_types: client_credentials
      autoapprove:
      authorities: credhub.write credhub.read
      name: credhub
      required_user_groups:
      lastmodified: 1518198701452
      id: credhub
      created_by: f609e861-39ec-4a16-8aee-cba9e9b079e3
    

Add the CA Certificate

Note: If you are using Pivotal Ops Manager v2.6 or later and want to use the default CA certificate provided by Ops Manager, only do the last two steps in this procedure.

Follow the steps below to log in to CredHub, provide or generate a CA certificate, and add the certificate to Ops Manager.

  1. From the Ops Manager VM, set the API target of the CredHub CLI as your CredHub server by running the following command:

    credhub api https://BOSH-DIRECTOR:8844 --ca-cert=/var/tempest/workspaces/default/root_ca_certificate
    

    Where BOSH-DIRECTOR is the IP address of the BOSH Director VM.

    For example:

    $ credhub api https://10.0.0.5:8844 --ca-cert=/var/tempest/workspaces/default/root_ca_certificate
    

  2. Log in to CredHub by running the following command:

    credhub login --client-name=credhub --client-secret=CLIENT-SECRET
    

    Where CLIENT-SECRET is the new client secret you created earlier in Create a UAA Client.

    For example:

    $ credhub login \
        --client-name=credhub \
        --client-secret=abcdefghijklm123456789
    

  3. Check whether a services CA certificate already exist by running the following command:

    credhub get --name="/services/tls_ca"
    

    If you already have a certificate at the services/tls_ca path, skip step 4.

  4. Use the CredHub CLI to generate a CA certificate or provide an existing one.

    Note: Your PCF deployment can have multiple CA certificates. Pivotal recommends a dedicated CA certificate for services.

    • If you do not have a CA certificate, use the CredHub CLI to generate one by running the following command:

      credhub generate \
        --name="/services/tls_ca" \
        --type="certificate" \
        --no-overwrite \
        --is-ca \
        --common-name="rootCA"
      
    • If you have a CA certificate that you want to use, create a new file called root.pem with the contents of the certificate. Then run the following command, specifying the path to root.pem and the private key for the certificate.

      For example:

      $ credhub set \
          --name="/services/tls_ca" \
          --type="certificate" \
          --certificate=./root.pem \
          --private=ERKSOSMFF...
      

  5. Extract the certificate portion from the CA certificate and print it by running the following command in BOSH CLI v2:

    bosh int <(credhub get \
      --name=/services/tls_ca) \
      --path /value/certificate
    
  6. Copy the output.

  7. Navigate to the Ops Manager Installation Dashboard and select the BOSH Director tile.

  8. Click Security.

  9. Paste the contents of the CA certificate into Trusted Certificates and then click Save.

  10. Ensure relevant app security groups are open for port 16379. This can be done through the cf CLI. For more information, see Managing ASGs with the cf CLI.

  11. After preparing your environment for TLS, enable TLS in the tile configuration by following the appropriate step below.

    Warning: Restarting all of the VMs in your PCF deployment to apply a CA certificate takes a long time to complete.

    • For an existing installation:
      • Complete the steps in Upgrade to Redis for PCF v2.2 to enable TLS in the tile.
      • Click Review Pending Changes.
      • Ensure the upgrade-all-service-instances errand is set to On.
      • Click Apply Changes in the Installation Dashboard. This restarts all the VMs in your PCF deployment and applies your CA certificate. This causes downtime to all on-demand service instances.
    • For a new installation:
      • Complete the procedures in On-Demand Service Settings, including enabling TLS in the On-Demand Service Settings tab.
      • Click Review Pending Changes.
      • Click Apply Changes in the Installation Dashboard. This deploys Redis for PCF, restarts all the VMs in your PCF deployment, and applies your CA certificate.
  12. After enabling TLS Optional, app developers must modify their apps to communicate over TLS. For more information, see Using TLS.