Using TLS

Note: In v2.9 and later, MySQL for VMware Tanzu is named VMware Tanzu SQL with MySQL for VMs.

Page last updated:

This topic describes how developers can use TLS to secure the communication from their apps and local workstations to the VMware Tanzu SQL with MySQL for VMs service.

Overview

For v2.5 and later and Tanzu SQL for VMs 2.7 and later, if your operator has configured TLS in the tile, but did not configure TLS for existing service instances in 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 Tanzu SQL for VMs service instance. See Establish a TLS Connection to a Service Instance, below.

Warning: Mutual TLS (mTLS) is not supported in Tanzu SQL for VMs. Because of this, the server certificate does not validate apps. If an app presents a certificate to the MySQL server, the connection closes and a network error appears in the app logs. To resolve this issue, you must disable mTLS in your apps.

Warning: Mutual TLS (mTLS) is not supported in Tanzu SQL for VMs. Because of this, the server certificate does not validate apps. If an app presents a certificate to the MySQL server, the connection closes and a network error appears in the app logs. To resolve this issue, you must disable mTLS in your apps.

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, an operator must:

Activate TLS for Java and Spring Apps

In 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 v2.5, you must rebind your Spring apps in order to re-establish connections to your service instance.

Note: VMware recommends developers configure their apps to use the MySQL Connector/J v5.1.42 or later instead of the MariaDB Connector/J.

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:

  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-INSTANCE
    

    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.

Warning: If a developer rebinds an app to the Tanzu SQL for VMs service after unbinding, they must also rebind any existing custom schemas to the app. When you rebind an app, stored code, programs, and triggers break. For more information about binding custom schemas, see Use Custom Schemas.

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 Tanzu SQL for VMs 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 Tanzu SQL for VMs 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 Tanzu SQL for VMs 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:

  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