prepare-tls.html.md.erb

---
title: Preparing for TLS
owner: MySQL
---

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.
<p class="note"><strong>Note</strong>: If you want to enable TLS for MySQL for Pivotal Cloud Foundry (PCF),
	you must perform the procedures in this topic <strong>before</strong> installing and configuring the tile.</p>

<p class="note warning"><strong>WARNING</strong>: This procedure involves restarting all of the VMs in your PCF deployment in order to apply a CA certificate. The operation can take a long time to complete.</p>

##<a id='overview'></a> 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
in order 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.

##<a id='workflow'></a> Workflow

The following workflow describes enabling TLS for MySQL for PCF:

<ol>
<li>An operator provides a CA certificate to CredHub by performing the procedures in <a href="#provide-generate-pcf">Provide or Generate a CA Certificate</a> below.</li>
<li>An operator enables TLS in the tile configuration while installing MySQL for PCF.
    See <a href="install-config.html#security">Configure Security</a>.</li>
<li>A developer enables TLS for an existing service instance.
    See <a href="using-tls.html#enable-tls">Enable TLS</a>.</li>
<li>A developer modifies their app to communicate securely with the MySQL server:
    <ul><li>For Java and Spring apps, see <a href="using-tls.html#activate-apps">Activate TLS for Java and Spring Apps</a>.</li>
    <li>For all other apps, see <a href="modify-apps-tls.html">Modifying Apps for TLS</a>.</li>
</li>
</ol>

<p class="note"><strong>Note</strong>: An operator must also rotate the CA certificate if it expires or if it becomes compromised.
For information on how to rotate your CA certificate, see <a href="rotating-ca.html">Rotating CA Certificates</a>.</p>

##<a id="provide-generate-pcf"></a> Provide or Generate a CA Certificate

Perform the following procedures to create a UAA client for CredHub,
log in to CredHub, and provide or generate a CA certificate.

###<a id='uaa'></a> Create UAA Client

Perform the following 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 performing the steps
   in [Gather Credential and IP Address Information](https://docs.pivotal.io/pivotalcf/2-0/customizing/trouble-advanced.html#gather).<br><br>
   Both the UAA and CredHub servers are colocated on the BOSH Director VM.

1. SSH into the Ops Manager VM by performing the steps in [SSH into Ops Manager VM](https://docs.pivotal.io/pivotalcf/2-0/customizing/trouble-advanced.html#ssh). 

1. From the Ops Manager VM, use the UAA Command Line Interface (UAAC) to target the UAA server on the BOSH Director VM. 
    In the UAAC command, specify the IP address for the BOSH Director VM and port 8443.
    <br><br> 
    Run the following command:

    ```
    uaac target BOSH-DIRECTOR:8443
    ```
    <br>
    Where `BOSH-DIRECTOR` is the IP address of the BOSH Director VM.
    You retrieved this address from the **Status** tab of the Ops Manager Director tile in step 1.
    <br><br>
    For example:
    <pre class="terminal">
    $ uaac target 10.0.0.5:8443
    </pre>

1. In the **Credentials** tab of the Ops Manager Director tile, retrieve the **Uaa Login Client Credentials** and record the `identity` and `password` values. 
    <p class="note"><strong>Note</strong>: These are the credentials for the UAA server colocated on the BOSH Director, not the UAA server colocated on Pivotal Application Service.</p> 

1. Retrieve the **Uaa Admin User Credentials** and record the `identity` and `password` values.

1. From the Ops Manager VM, use the UAAC to get a token.
    <br><br> 
    Run the following command:

    ```
    uaac token owner get login --secret=UAA-LOGIN-CLIENT-CRED
    ```
    <br>
    Where `UAA-LOGIN-CLIENT-CRED` is the `password` value of the **Uaa Login Client Credentials** that you retrieved in step 4.
    <br><br>
    For example:
    <pre class="terminal">
    $ uaac token owner get \
        login --secret=abcdefghijklm123456789
    </pre> 

1. When prompted for a user name and password, enter the values for `identity` and `password` of the **Uaa Admin User Credentials**
   that you retrieved in step 5. 
    For example:
    <pre class="terminal">
    User name:  admin
    Password:  ********************************
    </pre>

1. Add a UAA client for CredHub with the correct grants. 
    <br><br>
    Enter the following command:

    <pre class="terminal">
    $ uaac client add \
    	--authorized_grant_types client_credentials \
    	--authorities credhub.read,credhub.write
    </pre>

1. When prompted for Client ID, enter `credhub`.
   When prompted for `New client secret`, enter a secure password of your choice.
    For example:
    <pre class="terminal">
    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
    </pre>

1. If you are using PCF v1.12, perform the steps in [Downloading the CredHub CLI](credhub-cli.html) to download the CredHub CLI on the Ops Manager VM. 
  In PCF v2.0 and later, the Ops Manager VM ships with the CredHub CLI already installed.

###<a id='add-ca-cert'></a> Add the CA Certificate

Perform the following steps 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 to your CredHub server.
    <br><br>
    Run the following command:

    ```
    credhub api https://BOSH-DIRECTOR:8844 --ca-cert=/var/tempest/workspaces/default/root_ca_certificate
    ```
    <br>
    Where `BOSH-DIRECTOR` is the IP address of the BOSH Director VM. 
    <br><br>
    For example:
    <pre class="terminal">
    $ credhub api http<span>s:</span>//10.0.0.5:8844 --ca-cert=/var/tempest/workspaces/default/root_ca_certificate
    </pre>

1. Log in to CredHub.
    <br><br>
    Run the following command:

    ```
    credhub login --client-name=credhub --client-secret=CLIENT-SECRET
    ```
    <br>
    Where `client-secret` is the client secret you set in step 9 above.
    <br><br>
    For example:
    <pre class="terminal">
    $ credhub login \
    	--client-name=credhub \
    	--client-secret=abcdefghijklm123456789
    </pre>

1. Use the CredHub CLI to generate a CA certificate or provide an existing one.
    <p class="note"><strong>Note</strong>: Your PCF deployment may have multiple CA certificates.
       Pivotal recommends a dedicated CA certificate for services.</p> 
	* If you do not have a CA certificate, use the CredHub CLI to generate one.
          Enter the following command:
		<pre class="terminal">
		$ credhub generate \
			--name="/services/tls_ca" \
			--type="certificate" \
			--is-ca \
            --common-name="rootCA"
		</pre>
    * 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 enter the following command, specifying the path to `root.pem` and the private key for the certificate:
        <pre class="terminal">
        $ credhub set \
            --name="/services/tls_ca" \
            --type="certificate" \
            --certificate=./root.pem \
            --private=ERKSOSMFF...
        </pre>

1. 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
    ```
1. Copy the output.
1. Navigate to the Ops Manager **Installation Dashboard** and select the Ops Manager Director tile. 
Click **Security**.
1. Paste the contents of the CA certificate into **Trusted Certificates** and click **Save**.
1. 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](install-config.html#tls) to enable TLS in the **Security** section of the tile. Then return to the Ops Manager Installation Dashboard and 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](install-config.html). When you click **Apply Changes**, this deploys MySQL for PCF, restarts all the VMs in your PCF deployment, and applies your CA certificate.
    <p class="note warning"><strong>WARNING</strong>: Restarting all of the VMs in your PCF deployment in order to apply a CA certificate takes a long time to complete.</p>