Using TLS

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.

For MySQL for Pivotal Cloud Foundry 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 MySQL for Pivotal Cloud Foundry v2.4 and earlier, you must activate TLS using the procedures in Activate TLS.

If your operator has configured TLS in the tile, new service instances have TLS activated by default. In this case, developers don’t have to activate TLS.

After TLS is activated for your service instance, you can establish a TLS connection from your local workstation to a Tanzu SQL for VMs service instance.

For more information on how to establish a TLS connection, see Establish a TLS Connection to a Service Instance.

Caution 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 deactivate mTLS in your apps.

Activate 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 activate TLS on existing service instances, do one of the following:

If your app is written in Java or Spring, see Activate TLS for Java and Spring Apps.
If your app is not written in Java or Spring, see Activate TLS for Non-Spring Apps.

Prerequisites

To activate TLS for service instances, you must:

Complete the procedure in Preparing for TLS.
Activate TLS in the tile configuration when doing the procedure in Configure Security.

Activate TLS for Java and Spring Apps

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

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

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 rebind it after activating TLS for the instance.

To rebind your app:

To stop your app, run the following command:
```
cf stop YOUR-APP
```
Where YOUR-APP is the name of your app.
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.
To rebind 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.
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.

Important 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.

Activating 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:

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

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

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 activated.

For more information about how to activate TLS for a service instance, see Activate TLS.

To establish a TLS connection to a service instance:

Create a new service key for the service instance with TLS activated. 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 might be stale. Create a new service key.

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

$ pbpaste > root.pem

Record the values for username, password, and hostname.

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 previously retrieved.
USERNAME is the value for username previously retrieved.
PASSWORD is the value for password previously retrieved.

For example:

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