Help Center/ GaussDB/ Developer Guide(Distributed_8.x)/ Configuring GUC Parameters/ GUC Parameters/ Connection and Authentication/ Security and Authentication (gaussdb.conf)
Updated on 2024-06-03 GMT+08:00
View PDF
Share

Security and Authentication (gaussdb.conf)

This section describes parameters about client-to-server authentication.

authentication_timeout

Parameter description: Specifies the timeout period for client authentication. If a client is not authenticated by the server within the period, the server automatically disconnects from the client so that the client does not occupy connection resources.

This is a SIGHUP parameter. Set it based on instructions provided in Table 1.

Value range: an integer ranging from 1 to 600. The unit is s.

Default value: 1min

auth_iteration_count

Parameter description: Specifies the number of iterations during the generation of encryption information for authentication.

This is a SIGHUP parameter. Set it based on instructions provided in Table 1.

Value range: an integer ranging from 2048 to 134217728.

Default value: 10000

If the number of iterations is too small, the password storage security is compromised. If the number of iterations is too large, the performance deteriorates in scenarios involving password encryption, such as authentication and user creation. Set the number of iterations based on actual hardware conditions. You are advised to retain the default value.

session_authorization

Parameter description: Specifies the user ID of the current session.

This is a USERSET parameter and can be set only by following the instructions provided in "SQL Reference > SQL Syntax > SET SESSION AUTHORIZATION" in Developer Guide.

Value range: a string.

Default value: NULL

session_timeout

Parameter description: Specifies the longest duration allowed when no operations are performed on a client after it is connected to the server.

Parameter type: integer.

Unit: second

Value range: 0 to 86400 (1d).

  • The value 0 indicates that the timeout setting is disabled.
  • A positive number indicates the maximum duration in which no operation is performed after the connection to the server is set up. When the value of this parameter is exceeded, the client is disconnected from the server.

Default value: 600s

Setting method: This is a USERSET parameter. Set it based on instructions provided in Table 1.

Setting suggestion: Retain the default value.

The gsql client of GaussDB has an automatic reconnection mechanism. For local connection of initialized users, the client reconnects to the server if the connection breaks after the timeout.

ssl

Parameter description: Specifies whether to enable the SSL connection on the server. Before using this option, read "Database Quick Start > Connecting to a Database > Using gsql to Connect to a Database" in Developer Guide.

This is a POSTMASTER parameter. Set it based on instructions provided in Table 1.

Value range: Boolean

  • on indicates that the SSL connection is enabled on the server. Whether SSL encrypted transmission is used during actual communication depends on the client configuration.
  • off indicates that the SSL connection is disabled on the server.

GaussDB supports SSL when a client connects to a CN. You are advised to enable SSL connections only on CNs. The default value is off on DNs. Before setting this parameter to on, ensure that the ssl_cert_file, ssl_key_file, and ssl_ca_file parameters are correctly set. If Chinese cryptographic algorithms are used, ensure that the ssl_enc_cert_file and ssl_enc_key_file parameters are correctly set. Incorrect settings may cause cluster startup failures.

Default value: on (for CNs) or off (for DNs)

comm_ssl

Parameter description: Specifies whether to enable the SSL connection between primary DNs. Before using this option, read "Database Quick Start > Connecting to a Database > Using gsql to Connect to a Database" in Developer Guide.

This is a POSTMASTER parameter. Set it based on instructions provided in Table 1.

Value range: Boolean

  • on indicates that the SSL connection is enabled between primary DNs.
  • off indicates that the SSL connection is disabled between primary DNs.
  • It is recommended that this parameter be enabled only on DNs. The default value on CNs is off.
  • To enable SSL connections, you also need to ensure that parameters such as ssl_cert_file, ssl_key_file, and ssl_ca_file are configured correctly. Incorrect configurations may cause startup failure of the cluster.

Default value: off

require_ssl

Parameter description: Specifies whether the server requires SSL connections. This parameter is valid only when ssl is set to on. Before using this option, read "Database Quick Start > Connecting to a Database > Using gsql to Connect to a Database" in Developer Guide.

This is a SIGHUP parameter. Set it based on instructions provided in Table 1.

Value range: Boolean

  • on indicates that the server requires SSL connections.
  • off indicates that the server does not require SSL connections.

GaussDB supports SSL when a client connects to a CN. It is recommended that the SSL connection be enabled only on CNs.

Default value: off

ssl_ciphers

Parameter description: Specifies the list of encryption algorithms supported by SSL. Only the sysadmin user can access the list.

This is a POSTMASTER parameter. Set it based on instructions provided in Table 1.

Value range: a string. Separate multiple encryption algorithms by semicolons (;).

If ssl_ciphers is set incorrectly, the cluster cannot be started properly.

Default value: ALL

ssl_renegotiation_limit

Parameter description: Specifies the allowed traffic volume over an SSL-encrypted channel before the session key is renegotiated. The renegotiation mechanism reduces the probability that attackers use the password analysis method to crack the key based on a huge amount of data but causes big performance losses. The traffic indicates the sum of transmitted and received traffic. The SSL renegotiation mechanism has been disabled because of potential risks. This parameter is reserved for version compatibility and does not take effect.

This is a USERSET parameter. Set it based on instructions provided in Table 1.

Value range: an integer ranging from 0 to 2147483647. The unit is KB. 0 indicates that the renegotiation mechanism is disabled.

Default value: 0

ssl_cert_file

Parameter description: Specifies the name of the file that contains the SSL server certificate. The path is relative to the data directory.

This is a POSTMASTER parameter. Set it based on instructions provided in Table 1.

Value range: a string.

Default value: server.crt

ssl_key_file

Parameter description: Specifies the name of the file that contains the SSL private key. The path is relative to the data directory.

This is a POSTMASTER parameter. Set it based on instructions provided in Table 1.

Value range: a string.

Default value: server.key

ssl_enc_cert_file

Parameter description: Specifies the name of the SSL server certificate file that is encrypted using Chinese cryptographic algorithms. The path is relative to the data directory.

This is a POSTMASTER parameter. Set it based on instructions provided in Table 1.

Value range: a string.

Default value: an empty string.

ssl_enc_key_file

Parameter description: Specifies the name of the file that contains the SSL private key. The path is relative to the data directory.

This is a POSTMASTER parameter. Set it based on instructions provided in Table 1.

Value range: a string.

Default value: an empty string.

ssl_ca_file

Parameter description: Specifies the name of the root certificate that contains CA information. Its path is relative to the data directory.

This is a POSTMASTER parameter. Set it based on instructions provided in Table 1.

Value range: a string. If it is an empty string, no CA file is loaded and client certificate verification is not performed.

Default value: cacert.pem

ssl_crl_file

Parameter description: Specifies the certificate revocation list (CRL). If a client certificate is in the list, the certificate is invalid. The path is relative to the data directory.

This is a POSTMASTER parameter. Set it based on instructions provided in Table 1.

Value range: a string. An empty string indicates that there is no CRL.

Default value: an empty string

ssl_cert_notify_time

Parameter description: Specifies the number of days prior to SSL server certificate expiration that a user will receive a reminder. When the SSL certificate is initialized during connection establishment, if the duration from the current time to the certificate expiration time is shorter than the specified value, an expiration notification is recorded in the log.

This is a SIGHUP parameter. Set it based on instructions provided in Table 1.

Value range: an integer ranging from 7 to 180. The unit is day.

Default value: 90

krb_server_keyfile

Parameter description: Specifies the location of the main configuration file of the Kerberos service. Only the sysadmin user can access the file.

This is a SIGHUP parameter. Set it based on instructions provided in Table 1.

Value range: a string.

Default value: an empty string.

krb_srvname

Parameter description: Specifies the Kerberos service name.

This is a SIGHUP parameter. Set it based on instructions provided in Table 1.

Value range: a string.

Default value: postgres

krb_caseins_users

Parameter description: Specifies whether the Kerberos username is case-sensitive.

This is a SIGHUP parameter. Set it based on instructions provided in Table 1.

Value range: Boolean

  • on indicates that the Kerberos username is case-insensitive.
  • off indicates that the Kerberos username is case-sensitive.

Default value: off

modify_initial_password

Parameter description: After GaussDB is installed, there is only one initial user account (whose UID is 10) in the database. When a user logs in to the database using this initial account for the first time, this parameter determines whether the password of the initial account needs to be modified.

This is a SIGHUP parameter. Set it based on instructions provided in Table 1.

If the initial user password is not specified during the installation, the initial user password is empty by default after the installation. Before performing other operations, you need to set the initial user password using the gsql client. This parameter no longer takes effect and is reserved only for compatibility with upgrade scenarios.

Value range: Boolean

  • on indicates that the password of the initial account needs to be modified upon the first login after cluster is installed.
  • off indicates that the password of the initial account does not need to be modified after cluster is installed.

Default value: off

password_policy

Parameter description: Specifies whether to check the password complexity when you run the CREATE ROLE/USER or ALTER ROLE/USER command to create or modify the GaussDB account.

This is a SIGHUP parameter. Set it based on instructions provided in Table 1.

For security purposes, do not disable the password complexity policy.

Value range: 0 or 1

  • 0 indicates that no password complexity policy is enabled.
  • 1 indicates that the default password complexity policy is enabled.

Default value: 1

password_reuse_time

Parameter description: Specifies whether to check the reuse interval of the new password when you run the ALTER USER or ALTER ROLE command to change a user password.

This is a SIGHUP parameter. Set it based on instructions provided in Table 1.

When you change the password, the system checks the values of password_reuse_time and password_reuse_max.

Value range: a floating-point number ranging from 0 to 3650. The unit is day.

  • 0 indicates that the password reuse interval is not checked.
  • A positive number indicates that a new password cannot be chosen from passwords in history that are newer than the specified number of days.

password_reuse_max

Parameter description: Specifies whether to check the reuse times of the new password when you run the ALTER USER or ALTER ROLE command to change a user password. Only the sysadmin user can access this parameter.

This is a SIGHUP parameter. Set it based on instructions provided in Table 1.

When you change the password, the system checks the values of password_reuse_time and password_reuse_max.

Value range: an integer ranging from 0 to 1000.

  • 0 indicates that the password reuse times are not checked.
  • A positive number indicates that the new password cannot be the one whose reuse times exceed the specified number.

Default value: 0

password_lock_time

Parameter description: Specifies the duration before a locked account is automatically unlocked.

Parameter type: floating-point.

Unit: day

The locking and unlocking functions take effect only when the values of password_lock_time and failed_login_attempts are positive numbers.

Value range: 0 to 365. The integer part indicates the number of days, and the decimal part can be converted into hours, minutes, and seconds. For example, password_lock_time=1.5 indicates one day and 12 hours.

  • 0 indicates that an account is not automatically locked if the password verification fails.
  • A positive number indicates the duration after which a locked account is automatically unlocked.

Default value: 1

Setting method: This is a SIGHUP parameter. Set it based on instructions provided in Table 1.

Setting suggestion: Retain the default value. Do not set the automatic unlock time to a large value. Set it to a proper value based on the value of failed_login_attempts. If the value of failed_login_attempts is too small but the automatic unlock time is too long, the account cannot be used for a long time after the input fails, affecting user experience.

failed_login_attempts

Parameter description: If the number of incorrect password attempts reaches the value of failed_login_attempts, the current account is locked. The account is automatically unlocked after the number of seconds specified by password_lock_time. During this period, only the sysadmin user can access the account. The automatic account locking policy applies in scenarios such as login and password modification using the ALTER USER command.

Parameter type: integer.

Unit: none

The locking and unlocking functions take effect only when the values of failed_login_attempts and password_lock_time are positive numbers.

Value range: 0 to 1000.

  • 0 indicates that the automatic locking function does not take effect.
  • A positive number indicates that an account is locked when the number of incorrect password attempts reaches the specified number.

Default value: 10

Setting method: This is a SIGHUP parameter. Set it based on instructions provided in Table 1.

Setting suggestion: You are advised to set it to a value ranging from 5 to 10. If this parameter is set to a large value that allows too many incorrect password attempts (less than the maximum value of 1000), but no security measure is taken, security risk occurs. If this parameter is set to a small value (greater than 0 and less than 10), the account may be locked due to failed password attempts, affecting normal use.

password_encryption_type

Parameter description: Specifies the encryption type of a user password. Changing the value of this parameter does not automatically trigger the change of the password encryption type of an existing user. Only the password of a new user or the password changed by an existing user is encrypted using the new encryption type.

Parameter type: enumerated type

Unit: none

Value range: 0, 1, 2, or 3

  • 0 indicates that passwords are encrypted with MD5.
  • 1 indicates that passwords are encrypted with SHA-256 and MD5.
  • 2 indicates that passwords are encrypted with SHA-256.
  • 3 indicates that the passwords are encrypted with SM3.

The MD5 encryption algorithm is not recommended because it has lower security and poses security risks.

Default value: 2

Setting method: This is a SIGHUP parameter. Set it based on instructions provided in Table 1.

Setting suggestion: Retain the default value.

password_min_length

Parameter description: Specifies the minimum length of an account password. Only the sysadmin user can access this parameter.

This is a SIGHUP parameter. Set it based on instructions provided in Table 1.

Value range: an integer ranging from 6 to 999.

Default value: 8

password_max_length

Parameter description: Specifies the maximum length of an account password. Only the sysadmin user can access this parameter.

This is a SIGHUP parameter. Set it based on instructions provided in Table 1.

Value range: an integer ranging from 6 to 999.

Default value: 32

password_min_uppercase

Parameter description: Specifies the minimum number of uppercase letters that an account password must contain. Only the sysadmin user can access this parameter.

This is a SIGHUP parameter. Set it based on instructions provided in Table 1.

Value range: an integer ranging from 0 to 999

  • 0 means no limit.
  • An integer ranging from 1 to 999 indicates the minimum number of uppercase letters required in a password when you create an account.

Default value: 0

password_min_lowercase

Parameter description: Specifies the minimum number of lowercase letters that an account password must contain. Only the sysadmin user can access this parameter.

This is a SIGHUP parameter. Set it based on instructions provided in Table 1.

Value range: an integer ranging from 0 to 999

  • 0 means no limit.
  • An integer ranging from 1 to 999 indicates the minimum number of lowercase letters required in a password when you create an account.

Default value: 0

password_min_digital

Parameter description: Specifies the minimum number of digits that an account password must contain. Only the sysadmin user can access this parameter.

This is a SIGHUP parameter. Set it based on instructions provided in Table 1.

Value range: an integer ranging from 0 to 999

  • 0 means no limit.
  • An integer ranging from 1 to 999 indicates the minimum number of digits required in a password when you create an account.

Default value: 0

password_min_special

Parameter description: Specifies the minimum number of special characters that an account password must contain. Only the sysadmin user can access this parameter.

This is a SIGHUP parameter. Set it based on instructions provided in Table 1.

Value range: an integer ranging from 0 to 999

  • 0 means no limit.
  • An integer ranging from 1 to 999 indicates the minimum number of special characters required in a password when you create an account.

Default value: 0

password_effect_time

Parameter description: Specifies the validity period of an account password.

Parameter type: floating-point.

Unit: day

Value range: 0 to 999. The integer part indicates the number of days, and the decimal part can be converted into hours, minutes, and seconds. For example, password_lock_time=0.5 indicates 0 days and 12 hours.

  • 0 indicates that the validity period restriction is disabled.
  • A floating-point number from 1 to 999 indicates the number of days for which an account password is valid. When the password is about to expire or has expired, the system prompts the user to change the password.

Default value: 0

Setting method: This is a SIGHUP parameter. Set it based on instructions provided in Table 1.

Setting suggestion: For security purposes, you are advised to retain the default value.

password_notify_time

Parameter description: Specifies how many days in advance a user is notified before a password expires.

This is a SIGHUP parameter. Set it based on instructions provided in Table 1.

Value range: an integer ranging from 0 to 999. The unit is day.

  • 0 indicates that the reminder is disabled.
  • An integer ranging from 1 to 999 indicates the number of days prior to password expiration that a user will receive a reminder.

Default value: 7

enable_innertool_cert

Parameter description: Specifies whether internal tools use certificate-based authentication.

This is a SIGHUP parameter. Set it based on instructions provided in Table 1.

Value range: Boolean

  • on: indicates that internal tools use certificate-based authentication.
  • off: indicates that internal tools do not use certificate-based authentication.
Default value: off
  • This parameter takes effect only when both this parameter and ssl are enabled.
  • By default, the certificate in the $GAUSSHOME/share/sslcert/gsql directory is used. The Common Name of the certificate must be the same as the initial user. Otherwise, the authentication fails.
  • After this parameter takes effect, the initial user uses certificate-based authentication, and other users use password-based authentication.
  • If this parameter is enabled, the initial user can remotely connect to the database using certificate-based authentication.