Preparing for TLS

Page last updated:

This topic provides an overview of how to prepare for using Transport Layer Security (TLS) with MySQL for Pivotal Cloud Foundry (PCF) to secure communication between apps and service instances.

This topic explains how to provide an existing CA certificate to BOSH CredHub and generate a new CA certificate with BOSH CredHub.

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

Note: This certificate is shared by multiple tiles. If you have already done this procedure, you do not need to repeat it.

However, an operator must rotate the this certificate if it expires or if it becomes compromised. For instructions about how to rotate your CA certificate follow the steps in Rotating CA Certificates.

Overview

When you use TLS, you are provisioned a MySQL for PCF server with a certificate. With this certificate, apps and clients can establish an encrypted connection with the service.

CredHub generates a server certificate using a Certificate Authority (CA) certificate. You can either provide the CA or generate it using CredHub. For an overview of the purpose and functionality of the CredHub component, see CredHub.

Apps and clients use this CA certificate to check that the server certificate is trustworthy. A trustworthy server certificate allows apps and clients to securely communicate with the MySQL for PCF server.

Pivotal Application Service (PAS) shares the CA certificate public component in the following ways:

  • PAS provisions a copy of the CA certificate in the trusted store of each container’s operating system. Apps written in Java and Spring automatically discover the CA certificate in the trusted store.

  • PAS supplies the public CA certificate in an environment variable called VCAP_SERVICES that exists in every container. Apps not written in Java and Spring can retrieve the public component of the CA certificate from VCAP_SERVICES and use it to establish an encrypted connection with the data service.

Prerequisite

Before you do the procedures in this topic, you must install the Credhub CLI. For instructions, see credhub-cli on GitHub.

Workflow

The following workflow describes enabling TLS for MySQL for Pivotal Cloud Foundry (PCF):

  1. An operator provides a CA certificate to CredHub by performing the procedures in Find the CredHub Credentials in Ops Manager and in Add the CA Certificate below.
  2. An operator enables TLS in the tile configuration while installing MySQL for PCF. See Enable TLS in MySQL for PCF below.
  3. A developer enables TLS for an existing service instance. See Using TLS.
  4. A developer modifies their app to communicate securely with the MySQL for PCF server:

Find the CredHub Credentials in Ops Manager

To find the BOSH CredHub client name and client secret:

  1. In the Ops Manager Installation Dashboard, click the BOSH Director tile.
  2. Click the Credentials tab.
  3. In the BOSH Director section, click the link to the BOSH Commandline Credentials. CredHub Credentials
  4. Record the values for BOSH_CLIENT and BOSH_CLIENT_SECRET.

    Here is an example of the credentials page:

    {"credential":"BOSH_CLIENT=ops_manager
    BOSH_CLIENT_SECRET=abCdE1FgHIjkL2m3n-3PqrsT4EUVwXy5
    BOSH_CA_CERT=/var/tempest/workspaces/default/root_ca_certificate
    BOSH_ENVIRONMENT=10.0.0.5 bosh "}
    

    The BOSH_CLIENT is the BOSH CredHub client name and the BOSH_CLIENT_SECRET is the BOSH CredHub client secret.

Add the CA Certificate

To generate and add the CA Certificate to Ops Manager:

  1. Record the information needed to log in to the BOSH Director VM by following the procedure in Gather Credential and IP Address Information.

  2. Log in to the Ops Manager VM by following the procedure in Log in to the Ops Manager VM with SSH.

  3. Set the API target of the CredHub CLI as your CredHub server by running:

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

    Where BOSH-DIRECTOR-IP 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

  4. Log in to CredHub by running:

    credhub login \
        --client-name=CREDHUB-CLIENT-NAME \
        --client-secret=CREDHUB-CLIENT-SECRET
    

    Where

  5. If you are using Ops Manager v2.6 or later, skip this step and the next step. Otherwise, find out if a services CA certificate already is present by running the following command:

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

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

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

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

    • If you do not have a CA certificate: Use the CredHub CLI to generate one by running:

      $ credhub generate \
          --name="/services/tls_ca" \
          --type="certificate" \
          --is-ca \
          --common-name="rootCA"

      Note: When you run the above command, the generated certificate is valid for one year by default. You can use the --duration flag to set the validity period to a specific time. For example, if you add --duration=1825 to the above command, the generated certificate is valid for five years.

    • If you have an existing 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:

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

  7. Record the certificate portion from the CA certificate by running:

    credhub get \
       --name=/services/tls_ca \
       -k ca
    
  8. Navigate to the Ops Manager Installation Dashboard > BOSH Director > Security.

  9. Append the contents of the CA certificate you recorded in the previous step into Trusted Certificates.

  10. Click Save.

Enable TLS in MySQL for PCF

To enable TLS in the MySQL for PCF tile:

  1. Enable TLS by doing one of the following:
  2. Navigate to Ops Manager Installation Dashboard > Review Pending Changes.
  3. Ensure that the CA certificate is deployed to all VMs by selecting:
    • Pivotal Application Service
    • MySQL for Pivotal Cloud Foundry (PCF)
    • The Upgrade All On-Demand Service Instances errand
  4. Click Apply Changes. This restarts all the VMs in your deployment and applies your CA certificate.