Using TLS

This topic describes how developers can use TLS to secure the communication between their apps and the MySQL for Pivotal Cloud Foundry (PCF) v2 service.

To use TLS with your apps, the PCF operator must have completed the procedures in Preparing for TLS and enabled TLS in the tile configuration when performing the steps in Configure Security.

The procedures below describe how to enable TLS for your service instances, and how to activate TLS for your Java and Spring apps to use TLS. If your app is not written in Java or Spring, see Modifying Apps for TLS.

If you want to use the MySQL client to establish a TLS connection to a MySQL for PCF service instance that has TLS enabled, see Establish a TLS Connection to a Service Instance.

Enable TLS

You cannot automatically configure encryption for a service instance when creating the instance. Instead, you must enable TLS encryption for the instance after creating it. You cannot disable TLS after it is enabled.

Perform the following steps to enable TLS for an existing service instance:

  1. To create a service key, run the following command:

    cf create-service-key SERVICE-INSTANCE SERVICE-KEY
    

    Where:

    • SERVICE-INSTANCE is the name of the existing service instance that you want to secure communication to and from.
    • SERVICE-KEY is a name for the service key you are creating.

    For example:

    $ cf create-service-key my-service-instance my-service-key

  2. To retrieve the service key credentials, run the following command, specifying the same values as above:

    cf service-key SERVICE-INSTANCE SERVICE-KEY
    

    In the output, record the value for hostname.

    For example:

    $ cf service-key my-service-instance my-service-key
    {
    "hostname": "q-n3s3y1.q-g31.bosh",
    "jdbcUrl":    "jdbc:mysql://10.1.16.3:3306/service_instance_db?user=6bf07ae455a14064a9073cec8696366c\u0026password=a22aaa2a2a2aaaaa\u0026",
    "name": "service_instance_db",
    "password": "a22aaa2a2a2aaaaa",
    "port": 3306,
    "uri": "mysql://6bf07ae455a14064a9073cec8696366c:a22aaa2a2a2aaaaa@10.244.16.3:3306/service_instance_db?reconnect=true",
    "username": "6bf07ae455a14064a9073cec8696366c"
    }
    

  3. To update the existing service instance to enable TLS, run the following command:

    cf update-service SERVICE-INSTANCE -c '{"enable_tls": ["HOSTNAME"]}'
    

    Where:

    • SERVICE-INSTANCE is the name of the existing service instance that you want to secure communication to and from.
    • HOSTNAME is the value for hostname.

    For example:

    $ cf update-service my-service-instance -c '{"enable_tls": ["q-n3s3y1.q-g31.bosh"]}'
    
    If you receive the following error message, the operator has not enabled TLS. See the procedures in Preparing for TLS and Configure Security.
    TLS has not been enabled in the service offering. Speak with your Operator to make this available.

  4. To check the status of the operation, run cf services and locate your service instance.

    For example:

    $ cf services
    Getting services in org example / space development as admin...
    OK
    
    name service plan bound apps last operation my-service-instance p.mysql db-small update in progress

    When the operation has completed, update succeeded appears under last operation.

  5. To delete the service key, run the following, specifying the same values as above:

    cf delete-service-key SERVICE-INSTANCE SERVICE-KEY
    

    For example:

    $ cf delete-service-key my-service-instance my-service-key
    

Activate TLS for Java and Spring Apps

For your apps to use TLS, you must update them to request encrypted communications when connecting to the MySQL data service.

The procedure for updating your app depends on the app’s language and framework.

Java and Spring apps automatically detect TLS, while apps written in other languages and frameworks must be manually modified to use TLS:

  • If your app is written in Java or Spring, perform the procedure below.
  • If your app is not written in Java or Spring, see Modifying Apps for TLS.

WARNING: Any apps using an existing service instance must be rebound after enabling TLS for the instance.

To activate TLS for Java and Spring apps, you must stop and rebind the app to the service instance after enabling TLS on the instance. Perform the following steps:

  1. Stop the app. For example:
    $ cf stop my-app
  2. Unbind the app from the service instance. For example:
    $ cf unbind-service my-app my-service-instance
  3. Re-bind the app to the service instance. For example:
    $ cf bind-service my-app my-service-instance
  4. Restage the app. For example:
    $ cf restage my-app

Your app should now communicate securely with the MySQL service instance.