ApsaraDB RDS:Configure the SSL encryption feature

Prerequisites

Before you begin, ensure that:

• Your RDS instance runs one of the following MySQL versions and editions to use SSL encryption:

  MySQL version	RDS High-availability Edition	RDS Cluster Edition	RDS Basic Edition
  8.0	Supported	Supported	Supported
  5.7	Supported	Supported	Supported
  5.6	Supported	—	—

• Your RDS instance meets both of the following requirements to use forceful SSL encryption:

  • Runs MySQL 8.4, 8.0, or 5.7 on Basic Edition, High-availability Edition, or Cluster Edition

  • Runs a minor engine version of 20241130 or later

Check these details on the Basic Information page of your RDS instance. If your instance meets the requirements but the SSL tab is missing, update the minor engine version. For details, see Upgrade the minor engine version. If you change the billing method of a non-serverless RDS instance running Basic Edition to serverless, you must re-enable SSL encryption.

Potential impacts

Restart and switchover behavior:

Perform these operations during off-peak hours, and configure your application to reconnect automatically after a restart.

CPU overhead: SSL-encrypted connections significantly increase CPU utilization. Enable SSL only for endpoints that require encryption — typically the public endpoint.

Forceful SSL: After enabling forceful SSL encryption, non-SSL connections from clients and database proxies are denied.

How it works

When you enable SSL encryption, the RDS instance generates a server certificate, a public key, and a private key.

During an SSL handshake:

1. The RDS instance sends the server certificate (including the public key) to the client.

2. The client encrypts a symmetric key using the received public key.

3. The RDS instance decrypts the symmetric key using its private key.

4. Both sides use the symmetric key to encrypt and decrypt data.

Optionally, the client can verify the server certificate against a certificate authority (CA) certificate to confirm the server's identity and prevent man-in-the-middle attacks.

TLS version support

TLS 1.0 and TLS 1.1 were deprecated by the Internet Engineering Task Force (IETF) in 2021. Use TLSv1.2 or later. For details, see RFC 8996.

Certificate types

Both certificate types protect one endpoint and serve the same purpose: enabling SSL encryption and letting the client authenticate the server.

This topic covers cloud certificates. To use a custom certificate, see Configure a custom certificate.

Step 1: Enable SSL encryption

1. Go to the Instances page. In the top navigation bar, select the region where your RDS instance resides. Find the instance and click its ID.

2. In the left-side navigation pane, click Data Security.

3. On the SSL tab, turn on the switch next to Disabled.

   If the SSL tab does not appear, check that your instance meets all requirements listed in Prerequisites.

4. In the dialog box that appears, select the endpoint to protect — either the internal or public endpoint — and click OK. Only one endpoint can be protected at a time.

5. (Optional) Turn on Forceful Encryption.

   Important

   Forceful SSL encryption requires MySQL 8.4, 8.0, or 5.7 and a minor engine version of 20241130 or later. After enabling forceful SSL encryption, only SSL-encrypted connections are accepted. Non-SSL connections from clients and database proxies are denied.

6. Wait approximately 1 minute for the process to complete. Refresh the page to confirm the feature is enabled.

   Note

   SSL encryption for a read-only instance is independent of the primary instance. Enabling SSL encryption on the primary instance does not automatically enable it on associated read-only instances. To enable SSL encryption for a read-only instance, go to the read-only instance's details page, click Data Security > SSL, and turn on SSL encryption manually.

Step 2: Download the CA certificate

1. Go to the Instances page, find your instance, and click its ID.

2. In the left-side navigation pane, click Data Security. On the SSL tab, click Download CA Certificate.

The downloaded package contains three files:

Step 3: Connect using SSL

After enabling SSL encryption, configure your client to connect over an encrypted connection. The available SSL modes are:

mysql -h <endpoint> -u <username> -p --ssl-mode=PREFERRED

mysql -h <endpoint> -u <username> -p \
  --ssl-mode=VERIFY_CA \
  --ssl-ca=<path-to-certificate>/ApsaraDB-CA-Chain.pem

<dependency>
    <groupId>mysql</groupId>
    <artifactId>mysql-connector-java</artifactId>
    <version>8.0.19</version>
</dependency>

package com.aliyun.sample;

import com.mysql.cj.jdbc.MysqlDataSource;
import java.sql.Connection;
import java.sql.SQLException;

public class Sample {

    public static void main(String[] args) {

        Connection conn = null;
        MysqlDataSource mysqlDS = null;

        try {
            mysqlDS = new MysqlDataSource();

            // Set the SSL mode. Options: DISABLED, PREFERRED, REQUIRED, VERIFY_CA, VERIFY_IDENTITY.
            mysqlDS.setSslMode("VERIFY_IDENTITY");

            // The truststore holds the CA certificate. This example uses JKS format.
            mysqlDS.setTrustCertificateKeyStoreType("JKS");
            // Replace with the actual path to ApsaraDB-CA-Chain.jks on your system.
            mysqlDS.setTrustCertificateKeyStoreUrl("file:/D:\\ApsaraDB-CA-Chain\\ApsaraDB-CA-Chain.jks");
            // The JKS file password is always apsaradb.
            mysqlDS.setTrustCertificateKeyStorePassword("apsaradb");

            // Replace the following values with your actual RDS instance details.
            mysqlDS.setServerName("rm-xxxxxx.mysql.rds.aliyuncs.com"); // RDS endpoint
            mysqlDS.setPort(3306);
            mysqlDS.setUser("xxxxxx");          // Database account username
            mysqlDS.setPassword("xxxxxx");      // Database account password
            mysqlDS.setDatabaseName("xxxxxx");  // Database name

            conn = mysqlDS.getConnection();

        } catch (Exception e) {
            e.printStackTrace();
        } finally {
            try {
                if (conn != null) conn.close();
            } catch (SQLException e) {
                e.printStackTrace();
            }
        }
    }
}

# Install PyMySQL: pip install pymysql

import pymysql

try:
    ssl_config = {
        "ca": "/path/to/ApsaraDB-CA-Chain.pem",  # Path to the CA certificate
        "mode": "VERIFY_CA"                        # SSL mode
    }
    conn = pymysql.connect(
        host="******.mysql.rds.aliyuncs.com",
        user="*****",
        passwd="******",
        db="*****",
        ssl=ssl_config
    )
    cursor = conn.cursor()
    cursor.execute("SELECT VERSION()")
    data = cursor.fetchone()
    print("Database version:", data[0])
    cursor.close()
except pymysql.Error as e:
    print(e)

Additional operations

-- Check the cipher suite used by the current session.
-- A non-empty result confirms the connection is encrypted.
SHOW STATUS LIKE 'Ssl_cipher';

-- Check the TLS version used by the current session.
SHOW STATUS LIKE 'Ssl_version';

ALTER USER 'testuser'@'%' REQUIRE SSL;

openssl x509 -in <path-to-certificate>/ApsaraDB-CA-Chain.pem -text

FAQ

Can I configure mutual authentication that verifies both the server and client identities?

ApsaraDB RDS for MySQL does not support client identity verification during the SSL handshake. Use whitelists and account management to control access.

How do I configure SSL encryption for a read/write splitting endpoint?

See Configure SSL encryption for a database proxy endpoint.

Java application: `javax.net.ssl.SSLHandshakeException: DHPublicKey does not comply to algorithm constraints`

This error occurs with default JDK 7 or JDK 8 security settings. In the jre/lib/security/java.security file on your application host, set:

jdk.tls.disabledAlgorithms=SSLv3, RC4, DH keySize < 224
jdk.certpath.disabledAlgorithms=MD2, RSA keySize < 1024

Java application: `javax.net.ssl.SSLHandshakeException: No appropriate protocol (protocol is disabled or cipher suites are inappropriate)`

MySQL Connector/J 8.0.18 and earlier disable TLSv1.2 when connecting to MySQL 5.6 or 5.7 instances. Fix this using one of the following options:

• Upgrade MySQL Connector/J to 8.0.19 or later

• Upgrade the RDS instance to MySQL 8.0

• Specify the TLS version explicitly by setting enabledTLSProtocols or tlsVersions to TLSv1.2 in your connection configuration

API reference

• DescribeDBInstanceSSL

• ModifyDBInstanceSSL