Using TLS

Page last updated:

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

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.

Prerequisites

The procedures in this topic have the following prerequisites:

  • The PCF operator must have completed the procedure in Preparing for TLS.
  • The PCF operator must have enabled TLS in the tile configuration when doing the procedure in Configure Security.

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:

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.