Configure a custom certificate

Prerequisites

• The cluster runs PolarDB for PostgreSQL 14, 15, or a later version. For PolarDB for PostgreSQL 14, the revision version must be 14.10.21.0 or later. You can configure custom certificates and client CA certificates for the primary endpoint.

• The PolarProxy version of the cluster must be 2.3.51 or later. You can configure custom certificates and client CA certificates for cluster endpoints and custom endpoints.

• The OpenSSL tool is installed.

  Note

  The OpenSSL tool is pre-installed on Linux.

  If you use Windows, obtain and install the OpenSSL package.

Precautions

• Enabling SSL encryption increases CPU utilization and read/write latency.

• After enabling SSL encryption, existing connections must be re-established to be encrypted.

• Configuring or changing a custom certificate, or disabling SSL encryption, causes a transient disconnection. Perform these operations during off-peak hours.

Step 1: Obtain a custom certificate

This topic uses a CentOS system configuration as an example. If you use the Windows operating system, the openssl command is configured in the same way as on a CentOS system. Replace the cp command by manually copying files, and the vim command by manually editing files.

1. Create a self-signed CA certificate (ca.crt) and its private key (ca.key).

   openssl req -new -x509 -days 3650 -nodes -out ca.crt -keyout ca.key -subj "/CN=root-ca"

2. Depending on your requirements, choose one of the following methods to generate the Certificate Signing Request (CSR) (server.csr) and a server private key (server.key). A custom certificate can protect one or more connection endpoints, such as a primary endpoint or any cluster endpoint.

   1. To protect a single connection endpoint, run the following command:

      openssl req -new -nodes -text -out server.csr -keyout server.key -subj "/CN=pe-xxx.rwlb.rds.aliyuncs.com"

      Note

      The endpoint pe-xxx.rwlb.rds.aliyuncs.com is used as an example. Replace it with the primary endpoint or cluster endpoint that you want to protect.

   2. To protect multiple connection endpoints, perform the following steps:

      1. Copy the OpenSSL configuration file for temporary use.

         cp /etc/pki/tls/openssl.cnf  /tmp/openssl.cnf

         Note

         If you use Windows, the openssl.cnf file is in the \bin\cnf directory of the OpenSSL installation path. You can copy this file to any location.

      2. Use the following command to edit the temporarily copied openssl.cnf file.

         vim /tmp/openssl.cnf

      3. Press i to enter edit mode and add the following content:

         # Add this line at the end of the [ req ] section
         req_extensions = v3_req
         # Add the [ v3_req ] section
         [ v3_req ]
         basicConstraints = CA:FALSE
         keyUsage = nonRepudiation, digitalSignature, keyEncipherment
         subjectAltName = @alt_names
         # Add the [ alt_names ] section. After each DNS entry, specify a database connection endpoint to protect.
         [ alt_names ]
         DNS.1 = pc-bpxxxxx.pg.rds.aliyuncs.com
         DNS.2 = pc-bpxxxxx.pg.rds.aliyuncs.com

      4. Press the Esc key to exit edit mode, and then enter :wq to save and exit.

      5. Generate a Certificate Signing Request (CSR) (server.csr) and a server private key (server.key).

         openssl req -new -nodes -text -out server.csr -keyout server.key -config /tmp/openssl.cnf

         When you generate the CSR (server.csr), you are prompted for the following information. Provide your details as requested.

         Parameter	Description	Example
         Country name	The two-letter ISO country code.	CN
         State or province name	The province or state.	ZheJiang
         Locality name	The city.	HangZhou
         Organization name	Your company name.	Alibaba
         Organizational unit name	Your department name.	Aliyun
         Common name	The domain name for which the SSL certificate is requested. This is already configured in the openssl.cnf file. You do not need to enter a value.	-
         Email address	Leave blank.	-
         A challenge password	Leave blank.	-
         An optional company name	Leave blank.	-

3. Generate a server certificate (server.crt).

   • To protect a single connection endpoint, run the following command:

     openssl x509 -req -in server.csr -text -days 365 -CA ca.crt -CAkey ca.key -CAcreateserial  -out server.crt

   • To protect multiple connection endpoints, run the following command:

     openssl x509 -req -in server.csr -text -days 365 -CA ca.crt -CAkey ca.key -CAcreateserial  -out server.crt -extensions v3_req -extfile /tmp/openssl.cnf

After completing the preceding steps, run the ls command to view the generated files:

# ls
ca.crt  ca.key  ca.srl  server.crt  server.csr  server.key

The key files are:

• server.crt: The server certificate file.

• server.key: The server private key file.

• ca.crt: The self-signed CA certificate.

• ca.key: The private key of the self-signed CA certificate.

Step 2: Enable SSL encryption

1. Log on to the PolarDB console.

2. In the upper-left corner of the page, select the region where the cluster is located.

3. Find the target cluster and click the cluster ID.

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

5. On the SSL Settings tab, select the endpoint for which you generated the certificate. Then, click the switch to the right of SSL Status or click Configure Database Certificate to enable SSL encryption.

6. In the Configure Database Certificate dialog box, select Custom Certificate, paste the server certificate and private key, and then click OK.

   Parameter	Value
   Server certificate	Paste the content of the server.crt file from Step 1: Obtain a custom certificate. Include the entire content from -----BEGIN CERTIFICATE----- to -----END CERTIFICATE-----.
   Server private key	Paste the content of the server.key file from Step 1: Obtain a custom certificate. Include the entire content from -----BEGIN PRIVATE KEY----- to -----END PRIVATE KEY-----.

If your certificate protects multiple endpoints, the SSL-protected Endpoint section lists each one after configuration. Each entry shows the endpoint and its SSL connection string.

In addition, the SSL Settings tab displays configuration information, such as SSL Certificate Expiration Date, SSL Certificate Validity, Client CA Certificate Status, and Authentication Method (Client Forgery Prevention). The tab also provides entries for operations such as Configure Client CA Certificate, Configure Client Revocation File, and Configure Authentication Method.

Step 3: Connect to the database

PolarDB for PostgreSQL databases support remote connections over SSL. For more information, see Connect to PolarDB for PostgreSQL databases over SSL.

Step 4: (Optional) Update the certificate

If you need to update the custom certificate, on the SSL Settings page, find the endpoint you want to update and click Configure Database Certificate. Paste the new server certificate and private key, and then click OK.

Step 5: (Optional) Disable SSL encryption

If you need to disable SSL encryption, on the SSL Settings page, find the relevant endpoint and turn off the SSL Status switch. In the Disable SSL dialog box that appears, click OK.