Using TLS

Page last updated:

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

Overview

For MySQL for PCF v2.5 and later, if your operator has configured TLS in the tile, but did not configure TLS for existing service instances in MySQL for PCF v2.4 and earlier, you must enable TLS using the procedures in Enable TLS, below.

If your operator has configured TLS in the tile, new service instances have TLS enabled by default. In this case, developers do not have to enable TLS.

After TLS is enabled for your service instance, you can establish a TLS connection from your local workstation to a MySQL for PCG service instance. See Establish a TLS Connection to a Service Instance, below.

Enable TLS

The procedure for updating your app depends on the language and framework of your app. Java and Spring apps automatically detect TLS. Apps written in other languages and frameworks must be manually modified to use TLS. To enable TLS on existing service instances, do one of the following:

Prerequisites

To enable TLS for service instances, the operator must do the following:

Activate TLS for Java and Spring Apps

In MySQL for PCF v2.5, if your operator has configured TLS in the tile, new service instances have TLS enabled by default. If your Spring app detects TLS configured in the service instance, it must connect over TLS.

If you did not previously enable TLS in your service instance before upgrading to MySQL for PCF v2.5, you must rebind your Spring apps in order to re-establish connections to your service instance.

Note:Pivotal recommends developers configure their apps to use the MySQL Connector/J instead of the MariaDB Connector/J when TLS is enabled.

Rebind Your App

If your app is bound to an existing service instance, you must re-bind it after enabling TLS for the instance.

To re-bind your app, do the following:

  1. To stop your app, run the following command:

    cf stop YOUR-APP
    

    Where YOUR-APP is the name of your app.

  2. To unbind your app from the service instance, run the following command:

    cf unbind-service YOUR-APP YOUR-SERVICE-INSTANCE
    

    Where:

    • YOUR-APP is the name of your app.
    • YOUR-SERVICE-INSTANCE is the name of your service instance.
  3. To re-bind your app to the service instance, run the following command:

    cf bind-service YOUR-APP YOUR-SERVICE-INSTANCEe
    

    Where:

    • YOUR-APP is the name of your app.
    • YOUR-SERVICE-INSTANCE is the name of your service instance.
  4. To restage your app, run the following command:

    cf restage YOUR-APP
    

    Where YOUR-APP is the name of your app.

Your app now communicates securely with the MySQL service instance.

Activate TLS for Non-Spring Apps

In order to activate TLS for apps not written in Java or Spring, you must modify the app to discover the CA certificate in VCAP_SERVICES and specify the CA component when initiating the connection to the database.

VCAP_SERVICES is an environment variable that exists within every container. It contains runtime-specific information about the app, including metadata supplied by each of the services that are bound to that app. The metadata includes the information needed to connect to the service, such as hostnames, usernames, and passwords.

To activate TLS for your app, do the following:

  1. Modify your app to retrieve the hostname, username, password, database name, and CA certificate for the bound MySQL for PCF service instance from the VCAP_SERVICES environment variable.


    For example, the following Node.js code initializes a variable named mysql_creds, and then populates it with the necessary information from VCAP_SERVICES:

     var mysql_creds = {} ;
     var vcap_services = undefined ;
    
     if (process.env.VCAP_SERVICES) {
         vcap_services = JSON.parse(process.env.VCAP_SERVICES) ;
         mysql_creds["host"] = vcap_services["p.mysql"][0]["credentials"]["hostname"] ;
         mysql_creds["user"] = vcap_services["p.mysql"][0]["credentials"]["username"] ;
         mysql_creds["password"] = vcap_services["p.mysql"][0]["credentials"]["password"] ;
         mysql_creds["port"] = vcap_services["p.mysql"][0]["credentials"]["port"] ;
         mysql_creds["database"] = vcap_services["p.mysql"][0]["credentials"]["name"] ;
         if (vcap_services["p.mysql"][0]["credentials"]["tls"]) {
             mysql_creds["ca_certificate"] = vcap_services["p.mysql"][0]["credentials"]["tls"]["cert"]["ca"];
         } else {
             mysql_creds["ca_certificate"] = undefined ;
         }
     }
    
  2. Modify your app to use the hostname, username, password, and CA certificate to establish a secure connection with the bound MySQL for PCF service instance.

    For example, the following Node.js function establishes a TLS connection with the MySQL service, using the information loaded into mysql_creds:

    function MySQLConnect() {
        clientConfig = {
            host : mysql_creds["host"],
            user : mysql_creds["user"],
            password : mysql_creds["password"],
            port : mysql_creds["port"],
            database : mysql_creds["database"]
        } ;
        if (mysql_creds["ca_certificate"]) {
            clientConfig["ssl"] = { ca : mysql_creds["ca_certificate"] } ;
        }
        dbClient = mysql.createConnection( clientConfig ) ;
        dbClient.connect(CALLBACK-FUNCTION) ;
    }
    
  3. Push your app with cf push.

Establish a TLS Connection to a Service Instance

You can use mysql to establish a TLS connection to a MySQL for PCF service instance that has TLS enabled. For more information about how to enable TLS for a service instance, see Enable TLS, above.

To establish a TLS connection to a service instance, do the following:

  1. Create a new service key for the service instance with TLS enabled. For example:

    $ cf create-service-key my-service-instance my-tls-service-key
    {
    "hostname": "q-n3s3y1.q-g693.bosh",
    "jdbcUrl": "jdbc:mysql://q-n3s3y1.q-g693.bosh:3306/service_instance_db?user=6bf07ae455a14064a9073cec8696366c\u0026password=a22aaa2a2a2aaaaa\u0026=true",
    "name": "service_instance_db",
    "password": "a22aaa2a2a2aaaaa",
    "port": 3306,
    "tls": {
    "cert": {
     "ca": "-----BEGIN CERTIFICATE-----...n-----END CERTIFICATE-----\n"
    }
    },
    "uri": "mysql://6bf07ae455a14064a9073cec8696366c:a22aaa2a2a2aaaaa@q-n3s3y1.q-g693.bosh:3306/service_instance_db?reconnect=true",
    "username": "6bf07ae455a14064a9073cec8696366c"
    }
    
    If the service key does not have a CA certificate under tls.cert.ca, the service key may be stale. Create a new one.

  2. Copy the contents of the CA certificate under tls.cert.ca and paste it into a file. For example:

    $ pbpaste > root.pem

  3. Record the values for username, password, and hostname.

  4. Use mysql to establish a TLS connection to the MySQL instance. Run the following command:

    mysql --host=HOSTNAME \
    --user=USERNAME \
    --password=PASSWORD \
    --ssl-ca=root.pem \
    --ssl-verify-server-cert

    Where:

    • HOSTNAME is the value for hostname retrieved above.
    • USERNAME is the value for username retrieved above.
    • PASSWORD is the value for password retrieved above.

      For example:
      $ mysql --hostname=q-n3s3y1.q-g693.bosh \
      --user=6bf07ae455a14064a9073cec8696366c \
      --password=a22aaa2a2a2aaaaa \
      --ssl-ca=root.pem \
      --ssl-verify-server-cert