PolarDB:Configure SSL by using a client certificate

Background information

SSL is a protocol developed to encrypt communications and ensure data security. Starting SSL 3.0, the protocol is renamed Transport Layer Security (TLS). This topic describes how to configure SSL for a cluster by using a cloud certificate.

PolarDB for PostgreSQL clusters allow you to configure SSL by using the following certificates.

Prerequisites

• The cluster runs PolarDB for PostgreSQL 14, 15, or later. If the cluster runs PolarDB for PostgreSQL 14, the revision version is 14.10.21.0 or later. For clusters of these versions, you can configure a custom certificate or a client CA certificate on the primary endpoint. For clusters of earlier versions, you can only configure a cloud certificate.

• The PolarProxy version is 2.3.51 or later. You can configure a custom certificate or a client CA certificate on the default cluster endpoint or a custom endpoint only when the PolarProxy version is 2.3.51 or later. If the PolarProxy version is earlier than 2.3.51, you can configure only a cloud certificate.

• pgAdmin 4 is downloaded.

Usage notes

• The validity period of an SSL cloud certificate is one year. If a cloud certificate is about to expire, renew the certificate at the earliest opportunity and then download and reconfigure the CA certificate again. Otherwise, clients may fail to connect to the cluster over SSL.

• SSL may cause a significant increase in CPU utilization. We recommend that you enable SSL only if you want to encrypt connections that are established to the public endpoint of your cluster. In most cases, connections that are established to the internal endpoint of your cluster are secure and do not require SSL encryption.

• After you enable SSL, close the existing connections and establish new connections for SSL to take effect on the connections.

• A transient connection may occur when you enable a cloud certificate, renew a cloud certificate, change the endpoint protected by a cloud certificate, or disable SSL. We recommend that you perform the operations during off-peak hours.

Step 1: Enable SSL by using a cloud certificate

1. Log on to the PolarDB console.

2. In the upper-left corner of the Clusters page, select the region in which the cluster that you want to manage is deployed.

3. Find the cluster and click the cluster ID.

4. In the left-side navigation pane, choose Settings and Management > Security.

5. On the SSL Settings tab, select the primary endpoint or a cluster endpoint, and turn on SSL Status or click Configure Database Certificate to enable SSL.

6. In the Configure Database Certificate dialog box, select Cloud Certificate and the endpoint on which you want to enable SSL.

7. Click OK. Wait until the status of the cluster changes to Running.

   

Step 2: Download the CA certificate

A PolarDB for PostgreSQL cluster provides a cluster CA certificate that you can download after you enable a cloud certificate for the cluster. When you connect to the PolarDB for PostgreSQL cluster from a remote client, you can use the cluster CA certificate to authenticate the cluster.

1. On the SSL Settings tab, click Download Certificate next to Cloud Certificate to download the certificate.

   

2. Decompress the downloaded CA certificate. The file that you downloaded is a package that contains the following files:

   1. P7B file: contains the CA certificate that can be imported to a Windows operating system.

   2. PEM file: contains the CA certificate that can be imported to an operating system other than Windows or an application that is not run on Windows.

   3. JKS file: the Java truststore file. The password is apsaradb. The file is used to import the CA certificate chain to Java programs.

   Note

   If you want to use a JKS certificate file in Java, you must modify the default JDK security configuration in JDK 7 and JDK 8. In the jre/lib/security/java.security file of the server that connects to the PolarDB cluster, modify the following two configurations:

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

   If you do not modify the configurations, the following error is returned. In most cases, other similar errors are also caused by invalid Java security configurations:

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

Step 3: Connect to the cluster from a client

In this example, pgAdmin is used to connect to the PolarDB for PostgreSQL cluster over SSL.

You can connect to a PolarDB for PostgreSQL cluster by using multiple methods such as psql and Java Database Connectivity (JDBC). For more information, see Connect to a PolarDB for PostgreSQL cluster over SSL.

1. Launch pgAdmin 4.

   Note

   The first time you log on to pgAdmin of a later version, you must specify a master password to protect saved passwords and other credentials.

2. Right-click Servers and choose Register > Server....

   

3. On the General tab of the Register - Server dialog box, enter the name of the server on which pgAdmin is installed.

   

4. Click the Connection tab and configure the parameters that are used to connect to the cluster. The following table describes the parameters.

   

   Parameter	Description
   Host name/address	The primary or cluster endpoint of the PolarDB for PostgreSQL cluster for which SSL is enabled and the port number. If you want to connect to the cluster over an internal network, enter the internal endpoint and internal port of the cluster. If you want to connect to the cluster over the Internet, enter the public endpoint and public port of the cluster.
   Port
   Username	The account and password of the PolarDB for PostgreSQL cluster.
   Password

5. On the Parameters tab, configure the SSL mode and root certificate parameters. The following table describes the parameters.

   Parameter	Description
   SSL mode	For security purposes, we recommend that you set this parameter to Require, Verify-CA, or Verify-Full. Require: encrypts the data connection and does not authenticate the cluster. Verify-CA: encrypts the data connection and authenticates the cluster. Verify-Full: encrypts the data connection, authenticates the cluster, and checks whether the Common Name (CN) or Domain Name System (DNS) specified in the certificate is consistent with the value of the Host name/address parameter.
   Root certificate	Enter the path of the cluster CA certificate. You must configure this parameter if you set the SSL mode parameter to Verify-CA or Verify-Full. Note In this example, the path to the cluster CA certificate is D:\CA\aliyunCA\. You can change the path based on your business requirements. pgAdmin uses a cluster CA certificate in the PEM format.

6. Click Save.

   If the information that you enter is correct, a page that is similar to the following figure appears, which indicates that the connection to the cluster is successful.

   

   Important

   The postgres database is the default system database of PolarDB for PostgreSQL clusters. Do not perform operations on the database.

Step 4: (Optional) Renew the cloud certificate

To renew your cloud certificate, perform the following steps:

1. Log on to the PolarDB console.

2. In the upper-left corner of the Clusters page, select the region in which the cluster that you want to manage is deployed.

3. Find the cluster and click the cluster ID.

4. In the left-side navigation pane, choose Settings and Management > Security.

5. On the SSL Settings tab, select the primary or cluster endpoint and click Update Validity Period.

6. In the message that appears, click OK.

   

   Note

   After you renew the certificate, the cluster is restarted. Proceed with caution.

7. After you renew the certificate, download and reconfigure the certificate.

Step 5: (Optional) Disable SSL

To disable SSL, perform the following steps:

1. Log on to the PolarDB console.

2. In the upper-left corner of the Clusters page, select the region in which the cluster that you want to manage is deployed.

3. Find the cluster and click the cluster ID.

4. In the left-side navigation pane, choose Settings and Management > Security.

5. On the SSL Settings tab, find the primary or cluster endpoint for which you want to disable SSL and turn off SSL Status.