Configure a custom certificate - PolarDB - Alibaba Cloud Documentation Center

PolarDB for PostgreSQL (Compatible with Oracle) encrypts connections with SSL on the primary endpoint and cluster endpoints. By default, PolarDB provides a system-managed certificate. If your organization requires a specific Certificate Authority (CA) or certificate chain, you can configure SSL with a custom certificate instead.

Prerequisites

Before you begin, make sure that you have:

A PolarDB for PostgreSQL (Compatible with Oracle) cluster running version 2.0 or later with revision version 2.0.14.21.0 or later (required for custom certificates on the primary endpoint)
PolarProxy version 2.3.51 or later (required for custom certificates on the default cluster endpoint or a custom cluster endpoint)
OpenSSL installed on your local machine
Note
Linux distributions include OpenSSL by default. On Windows, download and install the OpenSSL package.

Usage notes

SSL increases CPU utilization and read/write latency.
After you enable SSL, close and reestablish all existing connections for SSL to take effect.
Configuring a custom certificate, modifying the certificate content, or disabling SSL causes a transient connection. Perform these operations during off-peak hours.

Create a custom certificate

Warning

Do not enable password encryption when creating private keys for the server certificate or the self-signed CA certificate. Password-encrypted keys prevent SSL from being enabled.

The following examples use CentOS. On Windows, the openssl commands are the same, but copy and edit files manually instead of using cp and vim.

Create a self-signed CA certificate

Generate 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"

This CA certificate is valid for 3,650 days (about 10 years).

Create a Certificate Signing Request (CSR)

A custom certificate can protect the primary endpoint or one or more cluster endpoints. Choose one of the following methods based on how many endpoints you need to protect.

Protect a single endpoint

Run the following command. Replace the CN value with your actual endpoint:

openssl req -new -nodes -text -out server.csr -keyout server.key -subj "/CN=<your-endpoint>"

Replace <your-endpoint> with the endpoint to protect, for example, pe-xxx.rwlb.rds.aliyuncs.com.

Protect multiple endpoints

To protect multiple endpoints, use Subject Alternative Names (SANs) in an OpenSSL configuration file.

Copy the default OpenSSL configuration file:
Note
On Windows, the openssl.cnf file is in the OpenSSL installation directory under \bin\cnf. Copy it to a working directory.
```
   cp /etc/pki/tls/openssl.cnf /tmp/openssl.cnf
```

Open /tmp/openssl.cnf in a text editor and add the following sections: Replace <endpoint-1> and <endpoint-2> with the actual endpoints, for example, pc-bpxxxxx.rwlb.rds.aliyuncs.com.

   # Add the following 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 with each endpoint as a DNS entry:
   [ alt_names ]
   DNS.1 = <endpoint-1>
   DNS.2 = <endpoint-2>

Save the file and generate the CSR:

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

When prompted, enter the following parameters:

Parameter	Description	Example
Country Name	Country code where the cluster is deployed	CN
State or Province Name	Province or state	ZheJiang
Locality Name	City	HangZhou
Organization Name	Your organization name	Alibaba
Organizational Unit Name	Your department name	Aliyun
Common Name	Auto-populated from the config file. Leave blank	-
Email Address	Leave blank	-
A challenge password	Leave blank	-
An optional company name	Leave blank	-

Sign the server certificate

Use the CA certificate to sign the server certificate (server.crt).

For a single endpoint:

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

For multiple endpoints:

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

The server certificate is valid for 365 days.

Verify generated files

After you complete the preceding steps, verify that the following files exist:

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

File	Description
`server.crt`	Server certificate
`server.key`	Private key for the server certificate
`ca.crt`	Self-signed CA certificate
`ca.key`	Private key for the CA certificate

Enable SSL with the custom certificate

Log on to the PolarDB console.
In the upper-left corner of the Clusters page, select the region where your cluster is deployed.
Find the cluster and click its cluster ID.
In the left-side navigation pane, choose Settings and Management > Security.
On the SSL Settings tab, select the primary endpoint or cluster endpoint to protect, and turn on SSL Status or click Configure Database Certificate.

In the Configure Database Certificate dialog box, select Custom Certificate and fill in the following fields:

Field	What to enter
Server Certificate	Paste the full content of `server.crt`, from `-----BEGIN CERTIFICATE-----` to `-----END CERTIFICATE-----`
Private Key of Server Certificate	Paste the full content of `server.key`, from `-----BEGIN PRIVATE KEY-----` to `-----END PRIVATE KEY-----`

Click OK.

If your certificate covers multiple endpoints (using SANs), each protected endpoint appears under SSL-protected Endpoint.

Connect to the cluster over SSL

After SSL is enabled with a custom certificate, connect to the PolarDB cluster using the sslmode and sslrootcert parameters in your connection string.

Point sslrootcert to the ca.crt file created earlier. For detailed instructions, see Connect to a PolarDB for PostgreSQL (Compatible with Oracle) cluster over SSL.

(Optional) Change the custom certificate

Warning

Changing a custom certificate causes a transient connection. Perform this operation during off-peak hours.

Go to the SSL Settings tab.
Find the primary endpoint or cluster endpoint and click Configure Database Certificate.
In the dialog box, paste the new certificate content and private key.
Click OK.

(Optional) Disable SSL

Warning

Disabling SSL causes a transient connection. Perform this operation during off-peak hours.

Go to the SSL Settings tab.
Find the primary endpoint or cluster endpoint and turn off SSL Status.
In the Disable SSL dialog box, click OK.

PolarDB:Configure a custom certificate

Prerequisites

Usage notes

Create a custom certificate

Create a self-signed CA certificate

Create a Certificate Signing Request (CSR)

Protect a single endpoint

Protect multiple endpoints

Sign the server certificate

Verify generated files

Enable SSL with the custom certificate

Connect to the cluster over SSL

(Optional) Change the custom certificate

(Optional) Disable SSL

Related topics