This topic describes how to configure SSL encryption for an ApsaraDB RDS for PostgreSQL instance. SSL encryption is used to encrypt the connections to your RDS instance and protect the data that is transmitted over the connections.

Background information

SSL encryption can encrypt connections at the transport layer to increase data security and ensure data integrity.

If you want to encrypt the data that is stored on standard or enhanced SSDs, you must enable disk encryption. For more information, see Configure disk encryption for an ApsaraDB RDS for PostgreSQL instance.

Note
  • The Internet Engineering Task Force (IETF) has upgraded SSL 3.0 to TLS. However, the term SSL encryption is retained because it is more common in the communications industry. In this topic, SSL encryption refers to TLS encryption.
  • ApsaraDB RDS supports TLS 1.0, TLS 1.1, and TLS 1.2.

Prerequisites

  • Your RDS instance runs PostgreSQL 10.0 or later.
  • Your RDS instance uses standard or enhanced SSDs.

Precautions

  • If you use an Alibaba Cloud certificate and you have configured both an internal endpoint and a public endpoint, you can configure SSL encryption for only one of these endpoints. If you use a custom certificate, you can configure SSL encryption for more than one endpoint.
  • After you enable SSL encryption, you must close the existing connection and establish a new connection to your RDS instance. This way, SSL encryption can take effect.
  • All the operations that are performed to configure a certificate for SSL encryption trigger a restart of your RDS instance. These operations include enabling an Alibaba Cloud certificate, enabling a custom certificate, enabling a client certificate, and enabling a certificate revocation list (CRL). We recommend that you perform these operations during off-peak hours.
  • After you enable SSL encryption, both the CPU utilization and the read and write latencies increase.
  • If you enable SSL encryption with the prefer SSL mode specified for the configured access control list (ACL), you can set the PGSSLMODE environment variable to disable on your database client. This way, you can connect to your RDS instance by using a non-SSL connection. If you want to prohibit non-SSL connections, you must enable an SSL mode rather than the prefer SSL mode for the configured ACL after you enable SSL encryption.

Configure SSL encryption

  1. Enable SSL encryption. For more information, see the "Enable SSL encryption" section of this topic.
  2. Optional. Enable a client certificate and a CRL. For more information, see the "Enable a client certificate and a CRL" section of this topic.

    If you use only an Alibaba Cloud or custom certificate for SSL encryption, your database client must validate your RDS instance by using the certificate of the CA that issues a server certificate to your RDS instance. If you want your RDS instance to validate your database client, you must also configure a client certificate. Your RDS instance validates your database client by using the public key of the CA that issues the client certificate. In addition, you can configure a CRL on your RDS instance. The CRL contains all the client certificates that are revoked. After a client certificate is revoked, it cannot pass the validation of your RDS instance.

  3. Optional. Configure an ACL. For more information, see Configure an ACL.
    If you have configured a client certificate and a CRL, you can configure an ACL on your RDS instance to control access from your database client. In this case, your database client can connect to your RDS instance only after you configure SSL encryption for the client and the client passes the validation of the instance.
  4. Connect your database client to your RDS instance. For more information, see the "Connection examples" section of this topic.

    ApsaraDB RDS for PostgreSQL allows you to connect to your RDS instance by using various database clients, such as pgAdmin, PostgreSQL command-line interface (CLI), and Java Database Connectivity (JDBC).

  5. Optional. Update a certificate.
    The Update Reminder Details section displays the certificate that you need to update and the reason why the certificate needs to be updated. In the Select Certificate Source section, click Custom Certificate. Then, specify the Server Certificate parameter and the Private Key of Server Certificate parameter.
  6. Optional. Disable SSL encryption.
    If you want to disable SSL encryption, click Disable SSL next to SSL Encryption.

Enable SSL encryption

Note This operation triggers a restart of your RDS instance. We recommend that you perform this operation during off-peak hours.

The SSL Links section displays the status of SSL encryption.

To enable an Alibaba Cloud certificate, perform the following steps:
  1. Visit the RDS instance list, select a region above, and click the target instance ID.
  2. In the left-side navigation pane, click Data Security. On the page that appears, click the SSL Encryption tab.
  3. In the Select Certificate Source section, click Cloud Certificate. Click Modify next to Configure Database Certificate. Then, select the endpoint that you want to protect. By default, Cloud Certificate is selected in the Select Certificate Source section.

    If you have configured both an internal endpoint and a public endpoint, the Alibaba Cloud certificate can protect only one of these endpoints.

    Select an endpoint
  4. Click Download CA Certificate. The certificate of the CA that issues the Alibaba Cloud certificate is downloaded. When you connect your database client to your RDS instance, you need to use the certificate of the CA. For more information, see the "Connection examples" section of this topic.
To enable a custom certificate, perform the following steps:
Notice When you create a private key for a server certificate or self-signed certificate, do not use a password for encryption. If you use a password for encryption, you cannot enable SSL encryption.
  1. Before you enable a custom certificate, obtain a server certificate and the private key of the server certificate. We recommend that you obtain the server certificate from a CA or Alibaba Cloud SSL Certificates Service. For more information, see the What is SSL Certificates Service?.
  2. In the left-side navigation pane, click Data Security. On the page that appears, click the SSL Encryption tab.
  3. In the Select Certificate Source section, click Custom Certificate. Click Modify next to Configure Database Certificate. Then, enter the server certificate in the Server Certificate field and the private key of the server certificate in the Private Key of Server Certificate field. Enable a custom certificate
    If you have configured both an internal endpoint and a public endpoint, the custom certificate can protect one or more of these endpoints. CentOS is used in the following examples:
    • Configure the custom certificate to protect one endpoint.
      1. Generate a certificate signing request (CSR).
        openssl req -new -nodes -text -out server.csr -keyout server.key -subj "/CN=pgm-bpxxxxx.pg.rds.aliyuncs.com"
      2. Submit the CSR to the CA and obtain a server certificate. Then, click Modify next to Configure Database Certificate. In the dialog box that appears, enter the server certificate in the Server Certificate field and the private key of the server certificate in the Private Key of Server Certificate field.
    • Configure the custom certificate to protect multiple endpoints.
      1. Copy the openssl.cnf file for temporary use.
        cp /etc/pki/tls/openssl.cnf  /tmp/openssl.cnf
      2. Modify the openssl.cnf file.
        # Add the following content following the [ req ] element.
        req_extensions = v3_req
        
        # Add the [ v3_req ] element.
        [ v3_req ]
        basicConstraints = CA:FALSE
        keyUsage = nonRepudiation, digitalSignature, keyEncipherment
        subjectAltName = @alt_names
        
        # Add the [ alt_names ] element. Then, enter the endpoint that you want to protect following each DNS record.
        [ alt_names ]
        DNS.1 = pgm-bpxxxxx.pg.rds.aliyuncs.com
        DNS.2 = pgm-bpxxxxx.pg.rds.aliyuncs.com
      3. Use the openssl.cnf file to generate a CSR.
        openssl req -new -nodes -text -out server.csr -keyout server.key -config /tmp/openssl.cnf
      4. Submit the CSR to the CA and obtain a server certificate. Then, click Modify next to Configure Database Certificate. In the dialog box that appears, enter the server certificate in the Server Certificate field and the private key of the server certificate in the Private Key of Server Certificate field. Enable a custom certificate
  4. Use the custom certificate to connect your database client to your RDS instance. For more information, see Connection examples.

Enable a client certificate and a CRL

If you use only an Alibaba Cloud or custom certificate for SSL encryption, your database client must validate your RDS instance by using the certificate of the CA that issues a server certificate to your RDS instance. If you want your RDS instance to validate your database client, you must also configure a client certificate. Your RDS instance validates your database client by using the public key of the CA that issues the client certificate. In addition, you can configure a CRL on your RDS instance. The CRL contains all the client certificates that are revoked. After a client certificate is revoked, it cannot pass the validation of your RDS instance.

Note
  • This operation triggers a restart of your RDS instance. We recommend that you perform this operation during off-peak hours.
  • Before you enable a CRL, you must enable a client certificate.
To enable a client certificate, perform the following steps:
  1. Create a public key for the CA that issues a client certificate, a client certificate, and a private key for the client certificate. The ca.crt, ca.key, client.crt, and client.key files are used in the following examples:
    1. Generate a self-signed certificate and a private key for the self-signed certificate. The self-signed certificate and the private key are used to validate a client certificate. The self-signed certificate is contained in a file named ca.crt, and the private key is contained in a file named ca.key.
      openssl req -new -x509 -days 3650 -nodes -out ca.crt -keyout ca.key -subj "/CN=root-ca"
    2. Generate a CSR file named client.csr.
      openssl req -new -nodes -text -out client.csr -keyout client.key -subj "/CN= The username that is used on your database client to establish a connection"
      Note In the preceding command, set the CN parameter following the -subj parameter to the username that is used on your database client to establish a connection to your RDS instance. When your database client connects to your RDS instance over SSL by using the verify-full SSL mode, the system checks whether the value of the CN parameter in the issued client certificate is the same as the username that is used to establish a connection.
    3. Use the self-signed certificate to generate a client certificate. The client certificate is contained in a file named client.crt.
      openssl x509 -req -in client.csr -text -days 365  -CA ca.crt -CAkey ca.key -CAcreateserial  -out client.crt
  2. In the left-side navigation pane, click Data Security. On the page that appears, click the SSL Encryption tab.
  3. In the Configure Client CA Certificate section, click Enable Client CA Certificate. Enable a client certificate
  4. In the Enter Public Key from Client Certificate CA dialog box, copy the content of the ca.crt file to the Public Key field. Enter the public key of the CA
  5. Connect your database client to your RDS instance. During this process, the following content is used: the certificate of the CA that issues the server certificate, the client certificate, and the private key of the client certificate. For more information, see the "Connection examples" section of this topic.
To enable a CRL, perform the following steps:
  1. Generate a CRL.
    1. Configure the index.txt and crlnumber system files.
      touch /etc/pki/CA/index.txt
      echo 1000 > /etc/pki/CA/crlnumber
    2. Revoke the client certificate that is contained in the client.crt file. During this process, the following content is used: the self-signed certificate and the private key of the self-signed certificate. The self-signed certificate is contained in the ca.crt file, and the private key is contained in the ca.key file.
      openssl ca -revoke client.crt -cert ca.crt -keyfile ca.key
    3. Generate a CRL file named client.crl.
      openssl ca -gencrl -out client.crl -cert ca.crt -keyfile ca.key
  2. In the left-side navigation pane, click Data Security. On the page that appears, click the SSL Encryption tab.
  3. In the Upload or Update Revocation File of Client Certificate section, click Enable Certificate Revocation File. Enable a CRL
  4. In the Enter Revocation File of Client Certificate dialog box, copy the content of the client.crl file to the Revocation File field. Configure a CRL
  5. Connect your database client to your RDS instance by using the client certificate that is contained in the client.crt file. The connection fails because the client certificate has been revoked.

Configure an ACL

If you have configured a client certificate and a CRL, you can configure an ACL on your RDS instance to control access from your database client. In this case, your database client can connect to your RDS instance only after you configure SSL encryption for the client and the client passes the validation of the instance.

Note When no ACLs are configured, your database client connects to your RDS instance over an SSL connection if SSL encryption is enabled and over a common connection if SSL encryption is not enabled.
ApsaraDB RDS for MySQL supports the following SSL modes and validation rules:
  • cert: A client certificate rather than a password is used to validate your database client. An SSL connection is established. In addition, the system checks the validity of the client certificate and whether the value of the CN parameter in the client certificate is the same as the username that is used to connect to your RDS instance.
  • prefer: An SSL connection is established. If you set the PGSSLMODE environment variable to disable on your database client, you can connect your database client to your RDS instance over a non-SSL connection.
  • verify-ca: An SSL connection is established. In addition, the system checks the validity of the client certificate.
  • verify-full: An SSL connection is established. In addition, the system checks the validity of the client certificate and whether the value of the CN parameter in the client certificate is the same as the username that is used to connect to your RDS instance. This SSL mode is supported only for PostgreSQL 12.
  1. Enable a client certificate and a CRL. For more information, see the "Enable a client certificate and a CRL" section of this topic.
  2. Click Modify next to Configure ACL or Configure Replication ACL. In the dialog box that appears, select an SSL mode.
    Select an SSL mode

Connection examples

  • To connect to your RDS instance by using pgAdmin, perform the following steps:
    Note For more information about how to configure the parameters on the General and Connection tabs of pgAdmin, see Use the pgAdmin 4 client to connect to an RDS instance.
    Select an SSL mode and configure a certificate.
    • If you use an Alibaba Cloud certificate, set Root certificate to the CA certificate that you have downloaded from the ApsaraDB RDS console.
    • If you use a custom certificate, set Root certificate to the public key of the CA that issues the custom certificate.
    • If you use a client certificate, set Root certificate to the public key of the CA that issues the custom certificate, set Client certificate to the client certificate, and then set Client certificate key to the private key of the client certificate.
    pgAdmin
  • To connect to your RDS instance by using the PostgreSQL CLI, perform the following steps:
    1. The server receives the postgresql.crt file that is stored in the ~/.postgresql home directory on your database client. In addition, you require a matched postgresql.key file. The postgresql.key file cannot be open to all users or specific users from a user group. You can run the following command to configure the postgresql.key file:
      chmod 0600 ~/.postgresql/postgresql.key
      Note The client certificate can be signed by an intermediate CA rather than by a CA that is trusted by the server. In this case, the certificate of the intermediate CA must be added to the postgresql.crt file until a CA that is trusted by the server is found and signs the client certificate.
    2. Configure the environment variables.
      export PGSSLMODE="require"  # Specify the SSL mode.    
      export PGSSLCERT="/var/lib/pgsql/.postgresql/postgresql.crt"    # Specify the save path of the postgresql.crt file.
      export PGSSLKEY="/var/lib/pgsql/.postgresql/postgresql.key"     # Specify the save path of the postgresql.key file.
      Note The save paths of the certificate and key files can be overwritten by the sslcert and sslkey parameters or by the PGSSLCERT and PGSSLKEY environment variables.
    3. Connect to your RDS instance.
      psql -h pgm-bpxxxxx.pg.rds.aliyuncs.com -p 1921 -d Database name -U Username
    4. If your RDS instance is connected, the following information appears:
      SSL connection (protocol: TLSv1.2, cipher: ECDHE-RSA-AES256-GCM-SHA384, bits: 256, compression: off)
  • To connect to your RDS instance by using JDBC, perform the following steps:
    1. Obtain the client certificate, the private key of the client certificate, and the public key of the CA that issues the client certificate. You must convert the private key into the PK8 format.
      openssl pkcs8 -topk8 -inform PEM -in client.key -outform der -out client.pk8 -v1 PBE-MD5-DES
      # Enter the password that is used to connect to your RDS instance.
      Enter Encryption Password:
      Verifying - Enter Encryption Password:
    2. In this example, Maven is used to manage your database project. In this case, import the Maven dependencies of your RDS instance into the pom.xml file.
        <dependency>
          <groupId>org.postgresql</groupId>
          <artifactId>postgresql</artifactId>
          <version>42.2.10</version>
        </dependency>
    3. Configure the following parameters that are used to connect to your RDS instance over an SSL connection:
       // Specify the save path of the client certificate file. 
       String path= "D:\\ssl\\";  
       // Specify the endpoint that is used to connect to your RDS instance.     
       String hostname = "pgm-bpxxxxx.pg.rds.aliyuncs.com";   
       // Specify the port number that is used to connect to your RDS instance.
       String port = "1921";   
       // Specify the name of the specific database that you want to connect on your RDS instance.
       String dbname = "postgres";  
      
       String jdbcUrl = "jdbc:postgresql://" + hostname + ":" + port + "/" + dbname+"?binaryTransfer=true";
      
       Properties properties = new Properties();
       //Specify the username that is used to connect to your RDS instance.
       properties.setProperty("user", "username"); 
       // Specify the password that is used to connect to your RDS instance.
       properties.setProperty("password", "*****");   
      
       // Configure SSL encryption.
       properties.setProperty("ssl", "true");
       // Specify the public key of the CA.
       properties.setProperty("sslrootcert", path + "/" + "root.crt");
       // Specify the private key of the client certificate.
       properties.setProperty("sslkey", path + "/" + "client.pk8");  
       // Specify the client certificate.
       properties.setProperty("sslcert", path + "/" + "client.crt");  
       // Enter the password that you specified when you converted the private key into the PK8 format.
       properties.setProperty("sslpassword", "*****"); 
      
       // Specify the SSL mode, which can be require, verify-ca, or verify-full.
       properties.setProperty("sslmode", "verify-ca"); 
      
        try {
            Class.forName("org.postgresql.Driver");
            Connection connection = DriverManager.getConnection(jdbcUrl, properties);
            PreparedStatement preparedStatement = connection.prepareStatement("select * from " +
                    "example");
            ResultSet resultSet = preparedStatement.executeQuery();
            while (resultSet.next()) {
                ResultSetMetaData rsmd = resultSet.getMetaData();
                int columnCount = rsmd.getColumnCount();
                Map map = new HashMap();
                for (int i = 0; i < columnCount; i++) {
                    map.put(rsmd.getColumnName(i + 1).toLowerCase(), resultSet.getObject(i + 1));
                }
                System.out.println(map);
            }
        } catch (Exception exception) {
            exception.printStackTrace();
        }