Establishing Secure TCP/IP openGauss Connections in SSL Mode
Tags: opengauss
Published: 2023-03-21 02:04:33

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.

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.

Use 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.

Use the actual name of the CRL.

Default value: empty, indicating that there is no CRL.

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) can be used for the peer end.

ssl_cert_notify_time

Specifies the number of days prior to SSL server certificate expiration that a user will receive a reminder.

Set this parameter based on the site requirements.

Default value: 90

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.

Value and meanings:

disable: only tries setting up a non-SSL connection.
allow: tries setting up a non-SSL connection first, and then an SSL connection if the attempt fails.
prefer: tries setting up an SSL connection first, and then a non-SSL connection if the attempt fails.
require: only tries setting up 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, checks whether the server certificate is issued by a trusted CA, and checks 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

ECDHE-RSA-AES128-GCM-SHA256

TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

HIGH

ECDHE-RSA-AES256-GCM-SHA384

TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

HIGH

ECDHE-ECDSA-AES128-GCM-SHA256

TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256

HIGH

ECDHE-ECDSA-AES256-GCM-SHA384

TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384

HIGH

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

 NOTE:

Currently, only the six encryption algorithm suites listed in the preceding table are supported.
The default value of ssl_ciphers is ALL, indicating that all encryption algorithms listed in the table are supported. 为保持前向兼容保留了DHE算法套件，即DHE-RSA-AES128-GCM-SHA256和DHE-RSA-AES256-GCM-SHA384，根据CVE-2002-20001漏洞披露DHE算法存在一定安全风险，非兼容场景不建议使用，可将ssl_ciphers参数配置为仅支持ECDHE类型算法套件。
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='ECDHE-RSA-AES128-GCM-SHA256;ECDHE-ECDSA-AES128-GCM-SHA256'
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.