LATEST VERSION: 2.5 - RELEASE NOTES

Preparing for TLS

Page last updated:

This topic describes how to provide an existing CA certificate to BOSH CredHub and how to generate a new CA certificate with BOSH CredHub, if you do not already have one.

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

Overview

Enabling TLS provisions a MySQL server with a certificate so that apps and clients can establish an encrypted connection with the data service.

The certificate deployed with the MySQL server is a server certificate. The server certificate is generated by CredHub, a component designed for centralized credential management in PCF, colocated on the BOSH Director.

CredHub generates the server certificate with a Certificate Authority (CA) certificate. The CA certificate must be provided to CredHub by the operator or generated by CredHub.

Apps and clients use the public component of the CA certificate to validate that a server certificate has been generated by a known, trusted CA. Apps and clients that communicate with the MySQL server must have access to the public component of the CA certificate to validate that the server certificate can be trusted.

PCF distributes the public component of the CA certificate to apps in two ways:

  • PCF 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.
  • PCF 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.

Workflow

The following workflow describes enabling TLS for MySQL for PCF:

  1. An operator provides a CA certificate to CredHub by performing the procedures in Provide or Generate a CA Certificate below.
  2. An operator enables TLS in the tile configuration while installing MySQL for PCF. See Configure Security.
  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 server:

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.

Generate and Add a CA Certificate

Follow the procedures below to generate and add a CA certificate.

Find the CredHub Credentials in Ops Manager

You need the BOSH CredHub client name and client secret to complete the Add the CA Certificate procedure below.

To find the BOSH CredHub client name and client secret, do the following:

  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, do the following:

  1. From the Ops Manager VM, set the API target of the CredHub CLI to your BOSH CredHub server.

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

    Run the following command:

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

    Where:

    • CREDHUB-CLIENT-NAME is the value you recorded for BOSH_CLIENT in Find the CredHub Credentials above.
    • CREDHUB-CLIENT-SECRET is the value you recorded for BOSH_CLIENT_SECRET in Find the CredHub Credentials above.

      For example:
      $ credhub login \
      --client-name=credhub \
      --client-secret=abcdefghijklm123456789
      
  3. Use the CredHub CLI to check whether a services CA certificate already is present.

    Run 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. Enter the following command:
      $ credhub generate \
          --name="/services/tls_ca" \
          --type="certificate" \
          --is-ca \
          --common-name="rootCA"
      
    • 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...
      
  5. Use the BOSH CLI v2 to extract the certificate portion from the CA certificate and print it. Run the following command:

    bosh2 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. Click Security.

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

  9. After preparing your environment for TLS, you must enable TLS in the tile configuration while installing MySQL for PCF:

    • Existing Installation: If you have already installed the MySQL for PCF tile, perform the procedures in Configure TLS to enable TLS in the Security section of the tile. Then return to the Ops Manager Installation Dashboard to apply changes:

      1. If you are using Ops Manager v2.3 or later, click Review Pending Changes. For more information about this Ops Manager page, see Reviewing Pending Product Changes.

      2. Enable the checkboxes next to the PAS tile and the MySQL tile.

      3. Click Apply Changes.

      This restarts all the VMs in your PCF deployment and applies your CA certificate.

    • New Installation: If you have not yet installed the MySQL for PCF tile, perform all of the procedures in Installing and Configuring MySQL for PCF. Then return to the Ops Manager Installation Dashboard to apply changes:

      1. If you are using Ops Manager v2.3 or later, click Review Pending Changes. For more information about this Ops Manager page, see Reviewing Pending Product Changes.

      2. Enable the checkboxes next to the PAS tile and the MySQL tile.

      3. Click Apply Changes.

      This deploys MySQL for PCF, restarts all the VMs in your PCF deployment, and applies your CA certificate.

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

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