Configuring SSL/TLS

MySQL   |  PostgreSQL

This page describes how to configure an instance to use SSL/TLS, and how to manage your server and client certificates.

For more information about using SSL/TLS with PostgreSQL, see SSL Support in the PostgreSQL documentation.

Introduction

Cloud SQL supports connecting to an instance using the Transport Layer Security (SSL/TLS) protocol. If you are not connecting to an instance by using the Cloud SQL Proxy, you should use SSL/TLS, so that the data you send to and receive from Cloud SQL is secure.

Cloud SQL uses a self-signed, per-instance server certificate and a certificate (public/private key pair) on the client (for example, an external application accessing the Cloud SQL instance). These certificates work together to enable the server (instance) and client (application) to encrypt their communication. You must have both a valid server certificate and a valid client certificate (key pair) to support encrypted communication.

Note: SSL/TLS is needed to provide security when you connect to Cloud SQL using IP addresses. If you are connecting to your instance only by using the Cloud SQL Proxy or the Java Socket Library, you do not need to configure your instance to use SSL/TLS. Connections from App Engine applications are encrypted by default whether you configure SSL/TLS for the instance or not.

Enforcing SSL/TLS

Setting up your Cloud SQL instance to accept SSL/TLS connections enables SSL/TLS connections for the instance, but unsecure connections are still accepted. If you do not require SSL/TLS for all connections, clients without a valid certificate are allowed to connect. For this reason, if you are accessing your instance using IP, it is strongly recommended that you enforce SSL for all connections.

Connections to your instance through the Cloud SQL Proxy are encrypted whether you configure or enforce SSL/TLS or not. SSL/TLS configuration affects only connections made using IP addresses.

To enforce SSL/TLS for all connections to your instance:

Console

1. Go to the Cloud SQL Instances page in the Google Cloud Platform Console.
   Go to the Cloud SQL Instances page
2. Click the instance name to open its Instance details page.
3. Select the SSL tab.
4. Click Allow Only SSL Connections.

gcloud

gcloud sql instances patch [INSTANCE_NAME] --require-ssl

cURL

ACCESS_TOKEN="$(gcloud auth application-default print-access-token)"
curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     --header 'Content-Type: application/json' \
     --data '{"settings" :
                 { "ipConfiguration" : {
                       "requireSsl" : "true" }}}' \
     -X PATCH \
     https://www.googleapis.com/sql/v1beta4/projects/<PROJECT-ID>/instances/<INSTANCE_NAME>

Managing your server certificates

Cloud SQL creates a server certificate automatically when you create your instance. As long as the server certificate is valid, you do not need to actively manage your server certificate. However, the certificate has an expiration date; after that date, it is no longer valid, and clients are not able to establish a secure connection to your instance using that certificate.

Cloud SQL provides a way to rotate your server certificate, so that a new certificate can be seamlessly swapped in before the old certificate expires.

How server certificate rotation works

About three months before the server certificate expires for a Cloud SQL instance, the project owners will receive an email from Cloud SQL, telling them that the certificate rotation process has been started for that instance. The email provides the name of the instance, and informs the project owners that a new server certificate has been added to the project. The existing server certificate, as well as any client certificates, continue to function normally. In effect, the instance has two server certificates during this time.

The project administrator, or someone with the proper permissions, downloads a new server certificate PEM file, which contains the certificate information for both the current and the new server certificates. Someone must then update all clients that access the Cloud SQL instance using SSL/TLS to use the new PEM file.

After all clients have been updated, the project administrator tells Cloud SQL to rotate to the new server certificate. This means that the old server certificate is no longer recognized, and only the new server certificate can be used.

At this point, the rotation is complete, and no further action is required. The client certificates are unaffected by server certificate rotation.

Rotating your server certificates

If you've received a notice about your certificates expiring, or you have initiated a rotation, then you must take the following steps to complete the rotation:

1. Download the new server certificate information.
2. Update your clients to use the new server certificate information.
3. Complete the rotation, which moves the currently active certificate into the "previous" slot and updates the newly added certificate to be the active certificate.

Console

Download the new server certificate information:

1. Go to the Cloud SQL Instances page in the Google Cloud Platform Console.
   Go to the Cloud SQL Instances page
2. Click the instance name to open its Instance details page.
3. Select the SSL tab.

4. Click Download.

   The server certificate information, encoded as a PEM file, is displayed and can be downloaded to your local environment.

5. Update all of your clients to use the new information.

After you have updated your clients, complete the rotation:

1. Click Rotate certificate.

2. Confirm that your clients are connecting properly.

   If any clients are not connecting using the newly rotated certificate, you can rollback to the previous configuration.

gcloud

1. Download the certificate information to a local PEM file:

   gcloud beta sql ssl server-ca-certs list --format='value(cert)' \
       --instance=[INSTANCE_NAME] > [FILE_PATH]/[FILE_NAME].pem
   

2. Update all of your clients to use the new information.

3. After you have updated your clients, complete the rotation:

   gcloud beta sql ssl server-ca-certs rotate --instance=[INSTANCE_NAME]
   

4. Confirm that your clients are connecting properly.

   If any clients are not connecting using the newly rotated certificate, you can rollback to the previous configuration.

cURL

1. Download your server certificates:

   ACCESS_TOKEN="$(gcloud auth application-default print-access-token)"
   curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
        -X GET \
        https://www.googleapis.com/sql/v1beta4/projects/<PROJECT-ID>/instances/<INSTANCE_NAME>/listServerCas
   

2. Complete the rotation:

   ACCESS_TOKEN="$(gcloud auth application-default print-access-token)"
   curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
        -X POST \
        https://www.googleapis.com/sql/v1beta4/projects/<PROJECT-ID>/instances/<INSTANCE_NAME>/rotateServerCa
   

Rolling back a certificate rotation operation

After you complete a certificate rotation, your clients must all use the new certificate to connect to your Cloud SQL instance. If the clients were not updated properly to use the new certificate information, they will not be able to connect using SSL/TLS to your instance. If this happens, you can roll back to the previous certificate configuration.

A rollback operation moves the currently active certificate into the "upcoming" slot (replacing any current "upcoming" certificate). The "previous" certificate becomes the currently active certificate, returning your certificate configuration to the state it was in before you completed the rotation.

Note: Certificate rollback is available only until the old certificate expires.

To roll back to the previous certificate configuration:

Console

1. Go to the Cloud SQL Instances page in the Google Cloud Platform Console.
   Go to the Cloud SQL Instances page
2. Click the instance name to open its Instance details page.
3. Select the SSL tab.
4. Click Rollback.

gcloud

  gcloud beta sql ssl server-ca-certs rollback --instance=[INSTANCE_NAME]

cURL

1. Download your server certificates:

   ACCESS_TOKEN="$(gcloud auth application-default print-access-token)"
   curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
        -X GET \
        https://www.googleapis.com/sql/v1beta4/projects/<PROJECT-ID>/instances/<INSTANCE_NAME>/listServerCas
   

2. Copy the sha1Fingerprint field for the version you want to roll back to.

   Look for the version with a createTime value immediately earlier than the version with the sha1Fingerprint value shown as activeVersion.

3. Roll back the rotation:

   ACCESS_TOKEN="$(gcloud auth application-default print-access-token)"
   curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
        --header 'Content-Type: application/json' \
        --data '{"rotateServerCaContext" :
                    { "nextVersion" : "<SHA1FINGERPRINT>"}}' \
        -X POST \
        https://www.googleapis.com/sql/v1beta4/projects/<PROJECT-ID>/instances/<INSTANCE_NAME>/rotateServerCa
   

Initiating a rotation

You do not need to wait for the email from Cloud SQL to start a rotation. You can start one at any time. When you start a rotation, a new certificate is created and placed into the "upcoming" slot. If a certificate was already in the "upcoming" slot, it is deleted; there can be only one upcoming certificate.

To initiate a rotation:

Console

1. Go to the Cloud SQL Instances page in the Google Cloud Platform Console.
   Go to the Cloud SQL Instances page
2. Click the instance name to open its Instance details page.
3. Select the SSL tab.
4. Click Create new CA.
5. Complete the rotation as described in Rotating your server certificates.

gcloud

1. Initiate the rotation:

     gcloud beta sql ssl server-ca-certs create --instance=[INSTANCE_NAME]
   

2. Complete the rotation as described in Rotating your server certificates.

cURL

  ACCESS_TOKEN="$(gcloud auth application-default print-access-token)"
  curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
       -X POST \
       https://www.googleapis.com/sql/v1beta4/projects/<PROJECT-ID>/instances/<INSTANCE_NAME>/rotateServerCa

Complete the rotation as described in Rotating your server certificates.

Getting information about your server certificate

You can get information about your server certificate, such as when it expires or what level of encryption it provides.

Console

1. Go to the Cloud SQL Instances page in the Google Cloud Platform Console.

   Go to the Cloud SQL Instances page

2. Click the instance name to open its Instance details page.

3. Select the SSL tab.

   You can see the expiration date of your server certificate under SSL Configuration. To see the certificate type, use the gcloud command-line tool.

gcloud

gcloud beta sql ssl server-ca-certs list --instance=[INSTANCE_NAME]

cURL

You can see details about the server certificate when you describe your instance:

ACCESS_TOKEN="$(gcloud auth application-default print-access-token)"
curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     --header 'Content-Type: application/json' \
     -X GET \
     https://www.googleapis.com/sql/v1beta4/projects/[PROJECT-ID]/instances/[INSTANCE_NAME]?fields=serverCaCert

Resetting your SSL/TLS configuration

If you need to completely reset your SSL/TLS configuration, you can do so.

Caution: Performing this action removes the ability to connect to your instance using SSL/TLS until you recreate your client certificates.

gcloud

1. Refresh the certificate:

   gcloud sql instances reset-ssl-config [INSTANCE_NAME]
   

2. Create new client certificates.

cURL

1. Refresh the certificate:

   ACCESS_TOKEN="$(gcloud auth application-default print-access-token)"
   curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
        --header 'Content-Type: application/json' \
        --header 'Content-Length: 0' \
        -X POST \
        https://www.googleapis.com/sql/v1beta4/projects/[PROJECT-ID]/instances/[INSTANCE_NAME]/resetSslConfig
   

2. Create new client certificates.

Managing your client certificates

Creating a new client certificate

You can create up to 10 client certificates for each instance. If you lose the private key for a certificate, you must create a new one; the private key cannot be recovered.

Console

1. Go to the Cloud SQL Instances page in the Google Cloud Platform Console.

   Go to the Cloud SQL Instances page

2. Click the instance name to open its Instance details page.
3. In the Client Certificates section, click Create a Client Certificate.
4. In the New client certificate dialog box, give the certificate a name unique for this instance and click Add.
5. In the first section of the New SSL certificate created dialog box, click the link to download the private key to a file named client-key.pem.
   Important: Store this private key securely. If you lose it, you must create a new client certificate.
6. In the second section, click the link to download the client certificate to a file named client-cert.pem.
7. In the third section, click the link to download the server certificate to a file named server-ca.pem.
8. Click Close.

gcloud

1. Create a client certificate using the ssl client-certs create command:

   gcloud sql ssl client-certs create [CERT_NAME] client-key.pem --instance=[INSTANCE_NAME]
   

   Important: Store this private key securely. If you lose it, you must create a new client certificate.

2. Retrieve the public key for the certificate you just created and copy it into the client-cert.pem file with the ssl client-certs describe command:

   gcloud sql ssl client-certs describe [CERT_NAME] --instance=[INSTANCE_NAME] --format='value(cert)' > client-cert.pem
   

3. Copy the server certificate into the server-ca.pem file using the instances describe command:

   gcloud sql instances describe [INSTANCE_NAME]  --format='value(serverCaCert.cert)' > server-ca.pem
   

cURL

1. Create an SSL/TLS certificate, giving it a unique name for this instance:

   curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
        --header 'Content-Type: application/json' \
        --data '{"commonName" : "[CERT_NAME]"}' \
        -X POST \
        https://www.googleapis.com/sql/v1beta4/projects/[PROJECT-ID]/instances/[INSTANCE_NAME]/sslCerts
   

2. Copy all of the certificate contents within the quotation marks (but not the quotation marks themselves) from the response into local files as follows:
   1. Copy serverCaCert.cert into server-ca.pem.
   2. Copy clientCert.cert into client-cert.pem.
   3. Copy certPrivateKey into client-key.pem.
   Important: Store this private key securely. If you lose it, you must create a new client certificate.

At this point, you have:

• A server certificate saved as server-ca.pem.
• A client public key certificate saved as client-cert.pem.
• A client private key saved as client-key.pem.

Depending on which tool you use to connect, these three items are specified in different ways. For example, when connecting using psql command-line client, these three files are the values for the sslrootcert, sslcert, and sslkey parameters in the psql connection string. For an example connection using psql client and SSL/TLS, see Connecting with psql Client.

Retrieving a client certificate

You can retrieve the public key portion of a client certificate. You cannot retrieve the private key, however. If you have lost your private key, you must create a new certificate.

Console

1. Go to the Cloud SQL Instances page in the Google Cloud Platform Console.

   Go to the Cloud SQL Instances page

2. Click the instance name to open its Instance details page.
3. Select the SSL tab.
4. In the Client Certificates section, click a certificate name to see the client certificate (client-cert.pem).

gcloud

Retrieve the client certificate public key with the ssl client-certs describe command:

gcloud sql ssl client-certs describe [CERT_NAME] --instance=[INSTANCE_NAME] --format='value(cert)' > client-cert.pem

cURL

1. List the certificates on the instance to get the fingerprint of the certificate you want to retrieve:

   ACCESS_TOKEN="$(gcloud auth application-default print-access-token)"
   curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
        -X GET \
        https://www.googleapis.com/sql/v1beta4/projects/[PROJECT-ID]/instances/[INSTANCE_NAME]sslCerts
   

   Record the sha1Fingerprint field for the certificate you want to retrieve. Do not include the quotation marks.

2. Retrieve the certificate:

   curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
        -X GET \
        https://www.googleapis.com/sql/v1beta4/projects/[PROJECT-ID]/instances/[INSTANCE_NAME]/sslCerts/[FINGERPRINT]
   

3. Copy all of the certificate data contained by the quotation marks to a file, for example client-cert.pem. Do not copy the quotation marks themselves.

Deleting a client certificate

Console

1. Go to the Cloud SQL Instances page in the Google Cloud Platform Console.

   Go to the Cloud SQL Instances page

2. Click the instance name to open its Instance details page.
3. Select the SSL tab.
4. In the Client Certificates section, find the certificate you want to delete and click delete .
5. In the Delete client certificate dialog box, click OK.

gcloud

Delete the client certificate using the ssl client-certs delete command:

gcloud sql ssl client-certs delete [CERT_NAME] --instance=[INSTANCE_NAME]

cURL

1. List the certificates on the instance to get the fingerprint of the certificate you want to delete:

   ACCESS_TOKEN="$(gcloud auth application-default print-access-token)"
   curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
        -X GET \
        https://www.googleapis.com/sql/v1beta4/projects/[PROJECT-ID]/instances/[INSTANCE_NAME]/sslCerts
   

   Record the sha1Fingerprint field for the certificate you want to delete. Do not include the quotation marks.

2. Delete the certificate:

   curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
        -X DELETE \
        https://www.googleapis.com/sql/v1beta4/projects/[PROJECT-ID]/instances/[INSTANCE_NAME]/sslCerts/[FINGERPRINT]
   

What's next

• Connect to your instance with the psql client using SSL/TLS.
• Learn more about how PostgreSQL uses SSL/TLS.