Establishing Secure TCP/IP Connections in SSL Mode

Background

openGauss supports the standard SSL (TLS 1.2). As a highly secure protocol, SSL authenticates bidirectional identification between the server and client using digital signatures and digital certificates to ensure secure data transmission.

Prerequisites

Formal certificates and keys for servers and clients have been obtained from the Certificate Authority (CA). Assume the private key and certificate for the server are server.key and server.crt, the private key and certificate for the client are client.key and client.crt, and the CA root certificate is cacert.pem.

Precautions

When a user remotely accesses the primary node of the database, the SHA-256 authentication method is used.
If internal servers are connected with each other, the trust authentication mode must be used. IP address whitelist authentication is supported.

Procedure

After a database is deployed, openGauss enables the SSL authentication mode by default. The server certificate, key, and root certificates have been configured. You need to set client parameters.

Set digital certificate parameters related to SSL authentication. For details, see Table 1.

Configure client parameters.
The default client certificate, key, root certificate, and key encrypted file have been obtained from the CA authentication center. Assume that the certificate, key, and root certificate are stored in the /home/omm directory.
For bidirectional authentication, set the following parameters:
```
export PGSSLCERT="/home/omm/client.crt"
export PGSSLKEY="/home/omm/client.key"
export PGSSLMODE="verify-ca"
export PGSSLROOTCERT="/home/omm/cacert.pem"
```
For unidirectional authentication, set the following parameters:
```
export PGSSLMODE="verify-ca"
export PGSSLROOTCERT="/home/omm/cacert.pem"
```
Change the client key permission.
The permission of the client root certificate, key, certificate, and encrypted key file should be 600. Otherwise, the client cannot connect to openGauss through SSL.
```
chmod 600 client.key
chmod 600 client.crt
chmod 600 client.key.cipher
chmod 600 client.key.rand
chmod 600 cacert.pem
```

NOTICE: You are advised to use bidirectional authentication for security purposes. The environment variables configured for a client must contain the absolute file paths.

Table 1 Authentication modes

Authentication Mode	Description	Client Environment Variable Setting	Maintenance Suggestion
Bidirectional authentication (recommended)	The client verifies the server's certificate and the server verifies the client's certificate. Connection can be set up after the verification is successful.	Set the following environment variables: PGSSLCERT PGSSLKEY PGSSLROOTCERT PGSSLMODE	This authentication mode is applicable to scenarios that require high data security. When using this method, you are advised to set the PGSSLMODE client variable to verify-ca for network data security purposes.
Unidirectional authentication	The client verifies the server's certificate, whereas the server does not verify the client's certificate. The server loads the certificate information and sends it to the client. The client verifies the server's certificate according to the root certificate.	Set the following environment variables: PGSSLROOTCERT PGSSLMODE	To prevent TCP-based link spoofing, you are advised to use the SSL certificate authentication. In addition to configuring client root certificate, you are advised to set the PGSSLMODE variable to verify-ca on the client.

Authentication Mode

Description

Client Environment Variable Setting

Maintenance Suggestion

Bidirectional authentication (recommended)

The client verifies the server's certificate and the server verifies the client's certificate. Connection can be set up after the verification is successful.

Set the following environment variables:

PGSSLCERT
PGSSLKEY
PGSSLROOTCERT
PGSSLMODE

This authentication mode is applicable to scenarios that require high data security. When using this method, you are advised to set the PGSSLMODE client variable to verify-ca for network data security purposes.

Unidirectional authentication

The client verifies the server's certificate, whereas the server does not verify the client's certificate. The server loads the certificate information and sends it to the client. The client verifies the server's certificate according to the root certificate.

Set the following environment variables:

PGSSLROOTCERT
PGSSLMODE

To prevent TCP-based link spoofing, you are advised to use the SSL certificate authentication. In addition to configuring client root certificate, you are advised to set the PGSSLMODE variable to verify-ca on the client.

Reference

In the postgresql.conf file on the server, set the related parameters. For details, see Table 2.

Table 2 Server parameters

Parameter	Description	Value Range
ssl	Specifies whether to enable the SSL function.	on: indicates that SSL is enabled. off: indicates that SSL is disabled. Default value: on
require_ssl	Specifies whether the server requires the SSL connection. This parameter is valid only when ssl is set to on.	on: The server requires the SSL connection. off: The server does not require the SSL connection. Default value: off
ssl_cert_file	Certificate files for the server, including the public key. The certificate proves the legal identity of the server and the public key is sent to the peer end for data encryption.	Use the actual certificate name. The relative path is relative to the data directory. Default value: server.crt
ssl_key_file	Private key file for the server, used for decryption of data encrypted using the public key.	Use the actual private key name of the server. The relative path is relative to the data directory. Default value: server.key
ssl_ca_file	Root certificate of the CA server. This parameter is optional and needs to be set only when the certificate of a client must be verified.	Refer to the name of the actual root certificate. Default value: cacert.pem
ssl_crl_file	Certificate revocation list (CRL). If the certificate of a client is in the list, the certificate is invalid.	Refer to the actual name of the certificate revocation list. Default value: empty, indicating that there is no certificate revocation list.
ssl_ciphers	Encryption algorithm used for SSL communication.	For details about the supported encryption algorithms, see Table 4. Default value: ALL, indicating that all supported encryption algorithms, excluding ADH, LOW, EXP, and MD5

Configure environment variables related to SSL authentication on the client. For details, see Table 3.

NOTE: The path of environment variables is set to /home/omm as an example. Replace it with the actual path.

Table 3 Client parameters

Environment Variable	Description	Value Range
PGSSLCERT	Client certificate file, including the client public key. The certificate proves the legal identity of the client and the public key is sent to the peer end for data encryption.	Absolute path of a certificate file, for example: export PGSSLCERT='/home/omm/client.crt' Default value: empty
PGSSLKEY	Private key file of the client, used to decrypt data encrypted using the public key	Absolute path of a certificate file, for example: export PGSSLKEY='/home/omm/client.key' Default value: empty
PGSSLMODE	Specifies whether to negotiate with the server about SSL connection and specifies the priority of the SSL connection.	Values and description: disable: only tries to establish a non-SSL connection. allow: tries establishing a non-SSL connection first, and then an SSL connection if the attempt fails. prefer: tries establishing an SSL connection first, and then a non-SSL connection if the attempt fails. require: only tries establishing an SSL connection. If there is a CA file, perform the verification according to the scenario in which the parameter is set to verify-ca. verify-ca: attempts to set up an SSL connection and checks whether the server certificate is issued by a trusted CA. verify-full: tries setting up an SSL connection, checking whether the server certificate is issued by a trusted CA, and checking whether the host name of the server is the same as that in the certificate. Default value: prefer
PGSSLROOTCERT	Root certificate file for issuing client certificates. The root certificate is used to verify the server certificate.	Absolute path of a certificate file, for example: export PGSSLROOTCERT='/home /omm/certca.pem' Default value: empty
PGSSLCRL	CRL file for checking whether the server certificate is in the CRL. If it is, the certificate is invalid.	Absolute path of a certificate file, for example: export PGSSLCRL='/home/omm/sslcrl-file.crl' Default value: empty

The following table describes the connection results based on the settings of the server parameters ssl and require_ssl and the client parameter sslmode.

ssl (Server)	sslmode (Client)	require_ssl (Client)	Result
on	disable	on	The connection fails, because the server requires SSL but the client has disabled it.
	disable	off	The connection is not encrypted.
	allow	on	The connection is encrypted.
	allow	off	The connection is not encrypted.
	prefer	on	The connection is encrypted.
	prefer	off	The connection is encrypted.
	require	on	The connection is encrypted.
	require	off	The connection is encrypted.
	verify-ca	on	The connection is encrypted and the server certificate is verified.
	verify-ca	off	The connection is encrypted and the server certificate is verified.
	verify-full	on	The connection is encrypted and the server certificate and host name are verified.
	verify-full	off	The connection is encrypted and the server certificate and host name are verified.
off	disable	on	The connection is not encrypted.
	disable	off	The connection is not encrypted.
	allow	on	The connection is not encrypted.
	allow	off	The connection is not encrypted.
	prefer	on	The connection is not encrypted.
	prefer	off	The connection is not encrypted.
	require	on	The connection fails, because the client requires SSL but the server has disabled it.
	require	off	The connection fails, because the client requires SSL but the server has disabled it.
	verify-ca	on	The connection fails, because the client requires SSL but the server has disabled it.
	verify-ca	off	The connection fails, because the client requires SSL but the server has disabled it.
	verify-full	on	The connection fails, because the client requires SSL but the server has disabled it.
	verify-full	off	The connection fails, because the client requires SSL but the server has disabled it.

A series of encryption and authentication algorithms with different strength are supported for SSL transmission. You can modify ssl_ciphers in postgresql.conf to specify the encryption algorithm used by the database server. Table 4 lists the encryption algorithms supported by the SSL.

Table 4 Encryption algorithm suites

OpenSSL Suite Name	IANA Suite Name	Security
DHE-RSA-AES128-GCM-SHA256	TLS_DHE_RSA_WITH_AES_128_GCM_SHA256	HIGH
DHE-RSA-AES256-GCM-SHA384	TLS_DHE_RSA_WITH_AES_256_GCM_SHA384	HIGH
DHE-RSA-AES128-CCM	TLS_DHE_RSA_WITH_AES_128_CCM	HIGH
DHE-RSA-AES256-CCM	TLS_DHE_RSA_WITH_AES_256_CCM	HIGH

NOTE:
Currently, only the four encryption algorithm suites whose security level is HIGH are supported.
The default value of ssl_ciphers is ALL, indicating that all encryption algorithms listed in the table are supported. You are advised to retain the default value, unless there are other special requirements on the encryption algorithm.
To specify the preceding cipher suites, set** ssl_ciphers** to the OpenSSL suite names in the preceding table. Use semicolons (;) to separate cipher suites. For example, set ssl_ciphers in postgresql.conf as follows: ssl_ciphers='DHE-RSA-AES256-GCM-SHA384;DHE-RSA-AES256-CCM'
SSL authentication increases the time spent for login (creating the SSL environment) and logout processes (clearing the SSL environment), and requires extra time for encrypting the data to be transferred. It affects performance especially in frequent login, logout, and short-time query scenarios.
If the certificate validity period is less than seven days, an alarm is generated in the log when a user logs in to the system.