Modifying Apps for TLS

Note: This version of MySQL for Pivotal Platform is no longer supported because it has reached the End of General Support phase. To stay up to date with the latest software and security updates, upgrade to a supported version.

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

If your app is written in Java or Spring, see Activate TLS for Java and Spring Apps. Otherwise, perform the procedures below.

Prerequisites

The procedures in this topic have the following prerequisites:

  • 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 developer must have completed the procedures in Enable TLS to enable TLS for an existing service instance.

Modify Your App for TLS

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

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 have been bound to that app. The metadata includes the information necessary to connect to the service, such as hostnames, usernames, and passwords.

Your app must perform the following tasks:

  1. Retrieve the hostname, username, password, database name, and CA certificate for the bound MySQL for PCF service instance from the VCAP_SERVICES environment variable.
  2. 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 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 ;
    }
}

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) ;
}

Repush or Rebind Your App

After modifying your app, repush it with cf push.

If you app is bound to an existing service instance, you must re-bind it after enabling TLS for 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.