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 MySQL, see Using Encrypted Connections in the MySQL Reference Manual.Introduction
Cloud SQL supports connecting to an instance using the Transport Layer Security (SSL/TLS) protocol. If you are connecting to an instance using its public IP address, you should use SSL/TLS, so that the data you send to and receive from Cloud SQL is secure.
If you are connecting using private IP, configuring SSL/TLS is optional; private services access traffic stays within Google's network at all times.
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.
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 enforce SSL/TLS for all connections, any issue with your SSL/TLS configuration can cause all connections to default silently to unencrypted. 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
- Go to the Cloud SQL Instances page in the Google Cloud Console.
Go to the Cloud SQL Instances page - Click the instance name to open its Instance details page.
- Select the CONNECTIONS tab.
- Scroll down to the SSL connections section.
- Click Allow only SSL connections.
gcloud
gcloud sql instances patch [INSTANCE_NAME] --require-ssl
cURL
gcloud auth login
ACCESS_TOKEN="$(gcloud auth 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.
How server certificate rotation works
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.
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:
- Download the new server certificate information.
- Update your clients to use the new server certificate information.
- 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:
- Go to the Cloud SQL Instances page in the Google Cloud Console.
Go to the Cloud SQL Instances page - Click the instance name to open its Instance details page.
- Select the CONNECTIONS tab.
- Scroll down to the Configure SSL server certificates section.
- Click Create new certificate.
- Scroll down to Download SSL server certificates section.
Click Download.
The server certificate information, encoded as a PEM file, is displayed and can be downloaded to your local environment.
Update all of your clients to use the new information.
After you have updated your clients, complete the rotation:
- Return to the Configure SSL server certificates section.
- Click Rotate certificate.
Confirm that your clients are connecting properly.
If any clients are not connecting using the newly rotated certificate, you can click Rollback certificate to roll back to the previous configuration.
gcloud
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
Update all of your clients to use the new information.
After you have updated your clients, complete the rotation:
gcloud beta sql ssl server-ca-certs rotate --instance=[INSTANCE_NAME]
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
Download your server certificates:
gcloud auth login ACCESS_TOKEN="$(gcloud auth print-access-token)" curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \ -X GET \ https://www.googleapis.com/sql/v1beta4/projects/<PROJECT-ID>/instances/<INSTANCE_NAME>/listServerCas
Complete the rotation:
ACCESS_TOKEN="$(gcloud auth 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.
To roll back to the previous certificate configuration:
Console
- Go to the Cloud SQL Instances page in the Google Cloud Console.
Go to the Cloud SQL Instances page - Click the instance name to open its Instance details page.
- Select the CONNECTIONS tab.
- Scroll down to the Configure SSL server certificates section.
- Click Rotate certificate. It takes a few seconds for the action to complete.
- Click Rollback certificate.
gcloud
gcloud beta sql ssl server-ca-certs rollback --instance=[INSTANCE_NAME]
cURL
Download your server certificates:
gcloud auth login ACCESS_TOKEN="$(gcloud auth print-access-token)" curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \ -X GET \ https://www.googleapis.com/sql/v1beta4/projects/<PROJECT-ID>/instances/<INSTANCE_NAME>/listServerCas
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
.Roll back the rotation:
ACCESS_TOKEN="$(gcloud auth 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
- Go to the Cloud SQL Instances page in the Google Cloud Console.
Go to the Cloud SQL Instances page - Click the instance name to open its Instance details page.
- Select the CONNECTIONS tab.
- Scroll down to the Configure SSL server certificates section.
- Click Create new certificate.
- Complete the rotation as described in Rotating your server certificates.
gcloud
Initiate the rotation:
gcloud beta sql ssl server-ca-certs create --instance=[INSTANCE_NAME]
Complete the rotation as described in Rotating your server certificates.
cURL
gcloud auth login
ACCESS_TOKEN="$(gcloud auth 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
- Go to the Cloud SQL Instances page in the Google Cloud Console.
- Click the instance name to open its Instance details page.
- Select the CONNECTIONS tab.
- Scroll down to the Configure SSL server certificates section.
You can see the expiration date of your server certificate in the table.
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:
gcloud auth login ACCESS_TOKEN="$(gcloud auth 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
You can completely reset your SSL/TLS configuration.
gcloud
For First Generation instances, this task requires your Cloud SQL instance to be restarted.
Refresh the certificate:
gcloud sql instances reset-ssl-config [INSTANCE_NAME]
For First Generation instances, restart the instance to complete the refresh.
gcloud sql instances restart [INSTANCE_NAME]
- Create new client certificates.
cURL
For First Generation instances, this task requires your Cloud SQL instance to be restarted.
Refresh the certificate:
gcloud auth login ACCESS_TOKEN="$(gcloud auth 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
For First Generation instances, restart the instance:
curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \ --header 'Content-Length: 0' \ -X POST \ https://www.googleapis.com/sql/v1beta4/projects/[PROJECT-ID]/instances/[INSTANCE_NAME]/restart
- 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 (2nd Gen)
- Go to the Cloud SQL Instances page in the Google Cloud Console.
- Click the instance name to open its Instance details page.
- Select the CONNECTIONS tab.
- Scroll down to the Configure SSL client certificates section.
- Click Create new certificate.
- In the Create a client certificate dialog box, give the certificate a name unique for this.
- Click Create.
- In the first section of the New SSL certificate created
dialog box, click Download client-key.pem to download the private
key to a file named
client-key.pem
. - In the second section, click Download client-cert.pem to download
the client certificate to a file named
client-cert.pem
. - In the third section, click Download server-ca.pem to download
the server certificate to a file named
server-ca.pem
. - Click Close.
Console (1st Gen)
This task causes your Cloud SQL instance to be restarted.
- Go to the Cloud SQL Instances page in the Google Cloud Console.
- Click the instance name to open its Instance details page.
- Select the CONNECTIONS tab.
- In the Client Certificates section, click Create a Client Certificate.
- In the New client certificate dialog box, give the certificate a unique name and click Add.
- 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
. - In the second section, click the link to download the client
certificate to a file named
client-cert.pem
. - In the third section, click the link to download the server certificate
to a file named
server-ca.pem
. Click Close and Restart to restart the instance immediately or click Close and manually restart the instance later.
A restart of the instance is required to enable the certificate.
gcloud
For First Generation instances, this task requires your Cloud SQL instance to be restarted.
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]
Retrieve the public key for the certificate you just created and copy it into the
client-cert.pem
file with thessl client-certs describe
command:gcloud sql ssl client-certs describe [CERT_NAME] --instance=[INSTANCE_NAME] --format="value(cert)" > client-cert.pem
Copy the server certificate into the
server-ca.pem
file using theinstances describe
command:gcloud sql instances describe [INSTANCE_NAME] --format="value(serverCaCert.cert)" > server-ca.pem
-
For First Generation instances, restart the instance to enable the certificate and SSL/TLS configuration change.
gcloud sql instances restart [INSTANCE_NAME]
cURL
For First Generation instances, this task requires your Cloud SQL instance to be restarted.
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
-
Copy all of the certificate contents within the quotation marks (but not the
quotation marks themselves) from the response into local files as follows:
- Copy
serverCaCert.cert
intoserver-ca.pem
. - Copy
clientCert.cert
intoclient-cert.pem
. - Copy
certPrivateKey
intoclient-key.pem
.
- Copy
-
For First Generation instances, restart the instance:
curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \ --header 'Content-Length: 0' \ -X POST \ https://www.googleapis.com/sql/v1beta4/projects/[PROJECT-ID]/instances/[INSTANCE_NAME]/restart
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 MySQL client, these three
files are the values for the --ssl-ca
, --ssl-cert
, and
--ssl-key
command options, respectively. For an example connection
using MySQL client and SSL/TLS, see
Connecting with MySQL 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
- Go to the Cloud SQL Instances page in the Google Cloud Console.
- Click the instance name to open its Instance details page.
- Select the CONNECTIONS tab.
- Scroll down to the Configure SSL client certificates section.
- Click a certificate name. The SSL Client Certificate dialog box
opens and shows 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
List the certificates on the instance to get the fingerprint of the certificate you want to retrieve:
gcloud auth login ACCESS_TOKEN="$(gcloud auth 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.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]
-
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 (2nd Gen)
- Go to the Cloud SQL Instances page in the Google Cloud Console.
- Click the instance name to open its Instance details page.
- Select the CONNECTIONS tab.
- Scroll down to the Configure SSL client certificates section.
- Find the certificate you want to delete and click
.
- In the Delete client certificate dialog box, click OK.
Console (1st Gen)
This task causes your Cloud SQL instance to be restarted.
- Go to the Cloud SQL Instances page in the Google Cloud Console.
- Click the instance name to open its Instance details page.
- Select the CONNECTIONS tab.
- Scroll down to the Configure SSL client certificates section,
find the certificate you want to delete and click
delete
.
In the Delete client certificate dialog box, click Restart now.
The instance must be restarted to complete the operation.
gcloud
For First Generation instances, this task requires your Cloud SQL instance to be restarted.
-
Delete the client certificate using the ssl client-certs delete command:
gcloud sql ssl client-certs delete [CERT_NAME] --instance=[INSTANCE_NAME]
-
For First Generation instances, restart the instance:
gcloud sql instances restart [INSTANCE_NAME]
cURL
For First Generation instances, this task requires your Cloud SQL instance to be restarted.
List the certificates on the instance to get the fingerprint of the certificate you want to delete:
gcloud auth login ACCESS_TOKEN="$(gcloud auth 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.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]
For First Generation instances, restart the instance:
curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \ --header 'Content-Length: 0' \ -X POST \ https://www.googleapis.com/sql/v1beta4/projects/[PROJECT-ID]/instances/[INSTANCE_NAME]/restart
What's next
- Connect to your instance with the mysql client using SSL/TLS.
- Learn more about how MySQL uses SSL/TLS.