Security

FairCom DB provides a variety of keywords that can be used for security purposes.

Note FairCom DB File and User Security are available only when using the client/server operational model.

Setting password requirements

To control password requirements, add SUBSYSTEM SECURITY PASSWORD to your ctsrvr.cfg configuration file.

The default values are:

SUBSYSTEM SECURITY PASSWORD {
MINIMUM_LENGTH      15
REQUIRED_CLASSES     0
EXPIRE_IN_DAYS       0
BLOCK_OLD_PASSWORD   0
PASSWORD_HASH        ORIGINAL
PASSWORD_HASH_DIFFICULTY     0
}

MINIMUM_LENGTH - Enforces a minimum length when setting a new password.

Default: 15

V13.0 and earlier default: 0

Maximum: 1024

REQUIRED_CLASSES - Enforces a minimum number of character classes from lower case, upper case, numbers, and symbols when setting a new password.

Default: 0

EXPIRE_IN_DAYS - Passwords to expire after this many days. Login attempts will fail with PWDEXP_ERR (1116). The ADMIN account is excluded from password expiration.

Default: 0 (Never expires).

BLOCK_OLD_PASSWORDS - When a non-zero number (N), password change attempts that reuse any of the N previous passwords for a user will fail with error PASSWORD_BLOCKLIST_ERR(1256).

Default: 0 (No check).

PASSWORD_HASH - In V13.0.4 onwards, allows setting the hash function used when generating new entries in the password database. 

Default: ORIGINAL (SHA2-512 hash scheme)

PASSWORD_HASH_DIFFICULTY - In v13.0.4 onwards, sets a scaling factor for PASSWORD_HASH values.

Default: Depends on PASSWORD_HASH value.

Advanced notes

• This subsystem can be specified in an encrypted server settings file using the ctcfgset utility to prevent these settings from being changed in the configuration file or at runtime.
• If the minimum length and required classes settings are changed in the configuration file or at runtime, they do not affect existing passwords because only a hash of the password is stored. The time to expiration takes effect immediately even for existing user accounts.
• When changing subsystem options at runtime (for example, using ctadmn), either the entire subsystem or particular subsystem options might be blocked by having been specified in a settings file. In both cases, the attempt to change the options fails with error SETO_ERR (804), even if some of the subsystem options are not blocked. If SETO_ERR occurs when specifying multiple options at runtime, check CTSTATUS.FCS for a message indicating which options are blocked and try again with just those options that are not blocked.

ADMIN_ENCRYPT

ADMIN_ENCRYPT <YES | NO>

Encrypt the FAIRCOM.FCS file at the time it is created. Note: This keyword will not encrypt an existing file.

To enable the encryption of the user group information file, FAIRCOM.FCS, set ADMIN_ENCRYPT YES (default). The default setting uses AES encryption, adding an additional level of security for passwords and user definitions stored in the file. FairCom DB File and User Security are available only when using the client/server operational model.

To disable the encryption of this file, set ADMIN_ENCRYPT No.

Note: AES encryption is only available if ADVANCED_ENCRYPTION YES is specified in ctsrvr.cfg.

V13: ADMIN_ENCRYPT has no effect unless ADVANCED_ENCRYPTION is enabled.

Default: YES

ADVANCED_ENCRYPTION

ADVANCED_ENCRYPTION < YES | NO >

Enable advanced encryption for files.

When Advanced Encryption is enabled, FairCom DB prompts for a master password at server startup. Run the ctcpvf utility to generate an encrypted password for use when launching the Advanced Encryption enabled Server. This will generate the file ctsrvr.pvf.

Note Developers can use the FairCom DB SDK to replace this prompt with an application-specific method of retrieving the master password.

Any time you change the advanced encryption setting, you should delete the FAIRCOM.FCS file (which contains user and group information) before restarting FairCom DB as user and group information is encrypted for protection as well. All user and group information must be recreated if the FAIRCOM.FCS file is deleted.

Client implementation of Advanced Encryption is accomplished through the use of the SetEncryption() function. Refer to the c-tree Plus Function Reference Guide for details on this function. FairCom DB File and User Security are available only when using the client/server operational model.

Default: NO

See Also

• MASTER_KEY_FILE

ALLOW_MASTER_KEY_CHANGE

FairCom DB Server supports a master key file in which the advanced encryption master key can be stored. The MASTER_KEY_FILE configuration option is used to specify a local encrypted key store.

To prevent tampering with advanced encryption keys, the server configuration option ALLOW_MASTER_KEY_CHANGE must be specified to allow changing master passwords via the SECURITY API function (an administrative client-side API call). Default value: NO.

Note The server configuration option MASTER_KEY_FILE now considers a value of NONE to indicate no master key file is in use. This option can be specified in a settings file to prevent a configuration file from using an existing master key file.

BLOCK_OLD_PASSWORDS

CHANGE_ENCRYPTION_ON_COMPACT <YES | NO>

When a non-zero number (N), password change attempts that reuse any of the N previous passwords for a user will fail with error PASSWORD_BLOCKLIST_ERR(1256).

Default: 0 (No check)

Note This keyword only blocks passwords that have been used since BLOCK_OLD_PASSWORDS was turned on. It cannot retrieve passwords from before it was active.

CHANGE_ENCRYPTION_ON_COMPACT

CHANGE_ENCRYPTION_ON_COMPACT <YES | NO>

Allows changing the encryption attributes of a file using the compact API function.

Default: No

If an encrypted file is compacted, the resulting file will be encrypted using the same method.

Note Setting this keyword to YES allows a user to permanently decrypt a file without knowing the master encryption key.

In V11 and later, to change the encryption attributes of a file using the compact function from a client, add the CHANGE_ENCRYPTION_ON_COMPACT YES to ctsrvr.cfg. If this keyword is not present or set to No, the operation fails with error NSUP_ERR (454, not supported).

COMPATIBILITY NO_COMMAND_LINE

COMPATIBILITY NO_COMMAND_LINE

This option is used in conjunction with the tamper-proof settings file under the server. Configuration options that are in the encrypted settings file, ctsrvr.set, cannot be overridden in the ctsrvr.cfg file. This keyword instructs the FairCom DB to ignore the command line arguments.

Default: Not present

See Also

• COMPATIBILITY NO_CONFIG_FILE
• COMPATIBILITY NONE
• DIAGNOSTICS NONE

COMPATIBILITY NO_CONFIG_FILE

COMPATIBILITY NO_CONFIG_FILE

This option is used in conjunction with the tamper-proof settings file under the server. Configuration options that are in the encrypted ctsrvr.set settings file cannot be overridden in the ctsrvr.cfg file. This keyword instructs the FairCom DB to ignore the standard configuration file, ctsrvr.cfg.

Default: Not present

See Also

• COMPATIBILITY NO_COMMAND_LINE
• COMPATIBILITY NONE
• DIAGNOSTICS NONE

COMPATIBILITY NON_ADMIN_SHUTDOWN

COMPATIBILITY NON_ADMIN_SHUTDOWN

Allow non-ADMIN users to shut down the Server.

Default: ADMIN group only may shutdown.

COMPATIBILITY NONADMIN_FILBLK

COMPATIBILITY NONADMIN_FILBLK

Permits a non-ADMIN user to set a file block if the blocking user has the file opened with update permissions.

If a non-ADMIN user attempts to set a file block without this keyword and having update permissions on the file, then error LADM_ERR (589) will be returned.

COMPATIBILITY NONADMIN_QUIET

COMPATIBILITY NONADMIN_QUIET

Permits a non-ADMIN user to call ctQuiet() to quiesce the server.

If a non-ADMIN user attempts to call ctQuiet() without this keyword, then error LADM_ERR (589) will be returned.

COMPATIBILITY NONADMIN_TRANSFER_FILE

COMPATIBILITY NONADMIN_TRANSFER_FILE

The file transfer API function ctTransferFile() can be used to transfer a file to or from the server. By default, this function is disabled for security reasons and is restricted to a member of the ADMIN group. This configuration keyword permits a non-ADMIN user to call ctTransferFile() to transfer a file.

If a non-ADMIN user attempts to call ctTransferFile() without this keyword, then error LADM_ERR (589) will be returned.

See Also

ENABLE_TRANSFER_FILE_API

COMPATIBILITY SQLIMPORT_ADMIN_PASSWORD

COMPATIBILITY SQLIMPORT_ADMIN_PASSWORD

Instructs ctSQLImportTable() server-side logic to verify the admin password passed in the clear as parameter to the function instead of using the credential of the connected user to perform the link/unlink of the table to SQL.

Support has been added for ADMIN password encryption in V11.5 and later. This compatibility keyword instructs ctSQLImportTable() and the ctsqlimp utility (and ctsqlimp in FairCom RTG) to verify the admin password (if any).This keyword affects only FairCom RTG or Server SDK compiles calling ctSQLImportTable() on the server-side reusing the current session.

This server configuration option can be changed at runtime using the ctadmn utility or the ctSETCFG() API function.

• To enable this option using ctadmn:
  Choose option 10, then option 10, then enter:
  COMPATIBILITY SQLIMPORT_ADMIN_PASSWORD
• To disable this option using ctadmn:
  Choose option 10, then option 10, then enter: COMPATIBILITY ~SQLIMPORT_ADMIN_PASSWORD

History

This option was renamed from COMPATIBILITY SQLIMP_ADM_PASSWD in V11.5 and later.

DEBUG_LOG

DEBUG_LOG <log file>

(optional) For aid in debugging TLS and X.509 configuration and certificate issues, write additional messages to the specified <log file>.

Must be specified within SUBSYSTEM COMM_PROTOCOL SSL (see TLS).

FIPS_ENCRYPTION

FIPS_ENCRYPTION < YES | NO >

When specified, FairComDB uses the OpenSSL 3.0 FIPS module for encryption routines.

ENABLE_TRANSFER_FILE_API

ENABLE_TRANSFER_FILE_API < YES | NO >

The file transfer API function ctTransferFile() can be used to transfer a file to or from the server. By default, this function is disabled for security reasons and is restricted to a member of the ADMIN group. To enable this feature, this keyword must be specified to YES in the FairCom DB configuration file, ctsrvr.cfg. Calling this function without this keyword enabled will result in a NSUP_ERR (454, feature not supported) error returned to the client.

Default: NO

See Also

COMPATIBILITY NONADMIN_TRANSFER_FILE

EXPIRE_IN_DAYS

EXPIRE_IN_DAYS - Passwords to expire after this many days. Login attempts will fail with PWDEXP_ERR (1116). The ADMIN account is excluded from password expiration.

To set this value, see Setting password requirements.

Default: 0 (Never expires).

FILEDEF_SECURITY_LEVEL

FILEDEF_SECURITY_LEVEL <level>

With row-level, system-wide, data filters, it is necessary to protect the resource APIs, ADDRES(), UPDRES(), DELRES(), with safeguards against unauthorized modification of file definition resources such as IFIL definitions, conditional indexes, row-level filters, etc.

The c-tree Server can enforce different levels of File Definition Resource (FCRES) security when users modify data file definition resources such as the IFIL and DODA resources. The actual level of protection enforced for a given resource is determined by the FILEDEF_SECURITY_LEVEL configuration keyword.

The file definition resource security keyword must be specified in the c-tree Server configuration file ctsrvr.cfg. There are three different security levels for this keyword:

FILEDEF_SECURITY_LEVEL LOW

This is the lowest security setting. There is no protection as any user may add or delete data file definition resources. This setting may be used to keep the c-tree Server data compatible with legacy applications.

FILEDEF_SECURITY_LEVEL MEDIUM

This is the default security setting. Any user may add or delete data file definition resources, but the file must be opened exclusive. This default setting may be enough to keep the c-tree Server data compatible with most legacy applications.

FILEDEF_SECURITY_LEVEL HIGH

This is the highest security setting. A user must have file definition permission before a definition resource is added or deleted. The file must be opened exclusive. This setting is appropriate for applications that require the highest level of security and may cause compatibility problems with existing legacy applications.

Default: MEDIUM.

Note This feature is NOT currently enabled.

KEY_EXCHANGE_PARAMS

KEY_EXCHANGE_PARAMS <filename>

(optional) - This is the name of a PEM-encoded file containing parameters for Diffe-Hellman key exchange. In V13 the default is to use the predefined group "ffdhe2048". These parameters may also be included in the SERVER_CERTIFICATE_FILE, which takes precedence over any parameters specified by KEY_EXCHANGE_PARAMS.

Example

KEY_EXCHANGE_PARAMS DHparams.pem

See Also

SERVER_CERTIFICATE_FILE

LOG_ENCRYPT

LOG_ENCRYPT YES

LOG_ENCRYPT enables encryption of the FairCom Server transaction logs adding an additional level of security for user data stored in the logs. Note: This keyword will not encrypt an existing file.

• With LOG_ENCRYPT YES and ADVANCED_ENCRYPTION NO (or not specified) (V13) Not allowed.
• With LOG_ENCRYPT YES and ADVANCED_ENCRYPTION YES logs are encrypted with AES 256-bit encryption. (Highest strength available.)

Before changing this setting, delete existing transaction logs (L0*.FCS), log templates (L0*.FCT), and start files (S0*.FCS).

Default: NO

LOGON_FAIL_LIMIT

LOGON_FAIL_LIMIT <attempts>

The optional limit on the number of consecutive failed logons that causes subsequent logon attempts to fail for LOGON_FAIL_TIME minutes. A logon which fails during this period returns LRSM_ERR (584).

Default: 0 (no limit)

See Also

LOGON_FAIL_TIME

LOGON_MUST_TIME

LOGON_FAIL_TIME

LOGON_FAIL_TIME <minutes>

The length of time logons are blocked after the logon limit is exceeded. A value of -1 indicates that there should be a permanent “log-on block” placed on a user until the Server ADMIN intervenes.

Default: 5

See Also

LOGON_FAIL_LIMIT

LOGON_MUST_TIME

LOGON_MUST_TIME

LOGON_MUST_TIME <minutes>

The LOGON_MUST_TIME keyword, when set with a non-zero value, requires users to log on “at-least-once” within the defined time (e.g: LOGON_MUST_TIME 10080 means a user must logon at least once a week). If the time expires for a specific user, their profile will be deactivated, preventing access to the FairCom DB Server.

This keyword accepts any value up to 35,791,394 minutes, which is 24855 days or approximately 68 years.

The Server Administrator, or other ADMIN group user, must reset the user’s account once the time limit has elapsed.

Default: 0 (no limit)

See Also

LOGON_FAIL_LIMIT

LOGON_FAIL_TIME

MASTER_KEY_FILE

MASTER_KEY_FILE  <filename>

Specifies a file from which c-tree reads the master encryption key. On Linux 2.6 and later kernel systems, c-tree uses the keyutils support to create a user-specific key in which the master key is stored. On other Unix systems, the master key is stored in a file on disk, with permissions set so that only the user that created the file can read it (permissions are set to 400).

The file (or user key on Linux) is encrypted using AES, however, the encryption is intended to only prevent casual inspection of the data when the file's contents are viewed. The permissions on the file are the defense against an unauthorized user reading the file.

The ctcpvf utility's -s option is used to create the master key file.

This configuration option can include an environment variable name that will be substituted with its value when the configuration file is read.

See Also

• ADVANCED_ENCRYPTION

MASTER_KEY_LIB

It is now possible to implement custom solutions for retrieving the advanced encryption master key from an arbitrary library. This feature eases the way the developers can customize the master key prompt.

The new ctsrvr.cfg configuration keyword, MASTER_KEY_LIB, takes a string defining the complete library name to load, for example:

MASTER_KEY_LIB maskeylib.dll 

or

MASTER_KEY_LIB libmaskey.so

The master key library must link with the OpenSSL libraries that are used to secure the master key exchange and implement the following functions:

• int ctGetSecretVersion(void) - returns the version of the master key library SDK used to implement it.
• int ctGetSecret(ctGetSecretParams_t * GetSecretParams) - returns the master key encrypted by calling ctSecureMasterKey as a member of the ctGetSecretParams_t structure.

Both functions are called by the server code in ctcryp.c. If the version does not match or ctGetSecret returns something different than 0, the master key will not be loaded and the server will be shut down.

To correctly return the encrypted master key, the following must be called to encrypt the master key before returning 0 in ctGetSecret:

int ctSecureMasterKey(ctSecureMasterKeyParams_t *SecureMasterKeyParams)

MINIMUM_LENGTH

MINIMUM_LENGTH - Enforces a minimum length when setting a new password.

To set this value, see Setting password requirements.

Default: 15

V13.0 and earlier default: 0

Maximum: 64

NULL_STRING

NULL_STRING null

This option is used in conjunction with the tamper-proof settings file under the server. Configuration options that are in the encrypted settings file, ctsrvr.set, cannot be overridden in the ctsrvr.cfg file. The NULL_STRING keyword lets you define a symbol that represents a null string so that options can be blocked in the settings file without activating them.

LOCAL_DIRECTORY null

With the above entry example in the server settings file, LOCAL_DIRECTORY is blocked from use in the standard ctsrvr.cfg file but it is not activated.

This configuration option can include an environment variable name that will be substituted with its value when the configuration file is read.

Default: Not enabled

OPENSSL_ENCRYPTION

OPENSSL_ENCRYPTION NO|YES

FairCom now supports an updated AES algorithm based on the OpenSSL standard by default. Previous algorithm implementation can be restored by specifying in ctsrvr.cfg the keyword OPENSSL_ENCRYPTION NO.

This change is expected to provide security and, with internal testing, we have seen an up to 20% performance improvements.

This modification changes file passwords encrypted on the client-side for secure transmission to use OpenSSL.

PASSWORD_HASH

Password_Hash

In V13.1 onwards, allows setting the hash function used when generating new entries in the password database.

Set scaling factor using PASSWORD_HASH_DIFFICULTY.

Clients must support the hash algorithm configured by the server. Using PBKDF2 or ARGON2 requires the BouncyCastle third-party cryptography library for both JDBC and ADO.net.*

Options:

ORIGINAL - uses SHA2-512 hash scheme. This is the only supported option in V10-V13.0.3.

PBKDF2_SHA2_512 - uses PBKDF2(SHA2-512)

PBKDF2_SHA3_512 - uses PBKDF2(SHA3-512)

Defaults to ORIGINAL.

More information:

Changes to PASSWORD_HASH will only take effect when each user's password is next added or changed.

Note To use BouncyCastle with JDBC, either the main application must run:

Security.addProvider(new BouncyCastleProvider());

Or you can add it to your java runtime configuration:

conf/security/java.security

It will be resolved at runtime if the .jar is available:

security.provider.<n>=org.bouncycastle.jce.provider.BouncyCastleProvider

PASSWORD_HASH_DIFFICULTY

Password_Hash_Difficulty

In V13.1 onwards, sets a scaling factor for PASSWORD_HASH values.

The higher the value, the higher the computational cost on the client and server during password authentication, and the more resistant the password database will be to offline brute force attacks.

Defaults:

The default value for PASSWORD_HASH_DIFFICULTY depends on the value set for PASSWORD_HASH:

More information:

Changes to PASSWORD_HASH_DIFFICULTY will only take effect when each user's password is next added or changed.

Clients must support the hash algorithm configured by the server. This may be a consideration for users with older non-native clients that may have more limited encryption support.

Warning Increasing PASSWORD_HASH_DIFFICULTY values may lead to noticeable login delays after user passwords are changed to use the new difficulty. Ensure you change a test account password after making this change and use that account for performance testing on a variety of anticipated client hardware, as clients without hardware support for the underlying cryptographic hash function(e.g. SHA512 or SHA3-512) may be significantly slower.

READONLY_SERVER

READONLY_SERVER Yes|No

This option is available only if licensed. This configuration option sets the server in read-only mode. By default, this option is off. To enable this option, add READONLY_SERVER YES to ctsrvr.cfg.

This option can also be enabled or disabled at run-time by calling the ctSETCFG() function or using the ctadmn utility: Select menu option 10 and then menu option 10 (Change the specified configuration option) again to change a server configuration option value.

Runtime changes to this setting are persisted as documented in Dynamic Configuration Changes Now Persisted in New ctsrvr.cfg Location and Default Additions.

The Replication Manager API command ctMemphisSetDBEngineReadOnly can be used to set this keyword.

REQUIRED_CLASSES

REQUIRED_CLASSES - Enforces a minimum number of character classes from lower case, upper case, numbers, and symbols when setting a new password.

To set this value, see Setting password requirements.

Default: 0

SERVER_CERTIFICATE_FILE

SERVER_CERTIFICATE_FILE <filename> 

(required) - This is the name of a PEM-encoded certificate file containing the FairCom DB server certificate. It can also optionally include the private key. The server certificate can be self-signed.

Must be specified within SUBSYSTEM COMM_PROTOCOL SSL (see TLS).

Example

SERVER_CERTIFICATE_FILE 

SERVER_ENCRYPTED_STORE_FILE

SERVER_ENCRYPTED_STORE_FILE <store filename> 

(optional) - If the private key is encrypted, use the ctcpvf utility to create an encrypted store file containing the pass phrase used to decrypt the private key and specify the name of the encrypted store file with this option.

Must be specified within SUBSYSTEM COMM_PROTOCOL SSL (see TLS).

SERVER_PRIVATE_KEY_FILE

SERVER_PRIVATE_KEY_FILE <filename>

(optional) - If the private key is in a different file than the certificate, use this option to indicate the name of the file containing the private key. If this option is not specified, the private key is expected to be found in the file whose name is specified by the SERVER_CERTIFICATE_FILE option.

Must be specified within SUBSYSTEM COMM_PROTOCOL SSL (see TLS).

SSL_CIPHERS

SSL_CIPHERS 

(optional) - If specified this option sets the encryption ciphers that are allowed to be used for encrypting the SSL connection. Ciphers are separated by a colon, (:). An exclamation point (!) explicitly disables a cipher. @STRENGTH sorts the list in order of encryption algorithm key length. For more information, see https://www.openssl.org/

Must be specified within SUBSYSTEM COMM_PROTOCOL SSL (see TLS).

Default SSL_CIPHERS (as of FairCom DB V12.5)

ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256

SSL_CONNECTIONS_ONLY

SSL_CONNECTIONS_ONLY <YES/NO> 

(optional) - Default: NO. If this option is specified with a value of YES, only TCP/IP connections that use SSL/TLS are permitted to connect to the FairCom DB Server. Otherwise, both unencrypted and SSL-enabled TCP/IP connections are allowed.

Must be specified within SUBSYSTEM COMM_PROTOCOL SSL (see TLS).

STARTUP_BLOCK_LOGONS

STARTUP_BLOCK_LOGONS 

Prevents non-ADMIN user logons when the server is started. Only users in the ADMIN group are allowed to logon.

This feature allows the server to start for ADMIN purposes before authorizing access by non-ADMIN users. This could include creating or adjusting files, adjusting security options, or any other operations that require a functioning Server but are more conveniently accomplished when users are not connected to the Server.

Default: Allow logons

Allow SIGNAL_READY and ADMIN SQL Connections

A revision changes the behavior of STARTUP_BLOCK_LOGON for FairCom DB SQL Server so that SIGNAL_READY and the SQL listener threads run immediately. For SQL connections there is a choice of two behaviors when logons are blocked at server startup:

1. The configuration option STARTUP_BLOCK_LOGON YES only allows ISAM connections by the ADMIN user. SQL connections are rejected with the new error code 1158 (SQL_LOGON_BLOCKED_ERR, "SQL connection is blocked from logon due to server startup logon block").
2. The configuration option STARTUP_BLOCK_LOGON YES:ALLOW_SQL allows both ISAM and SQL connections by the ADMIN user.

Compatibility Change: This revision changes the behavior of STARTUP_BLOCK_LOGON for FairCom DB SQL Server.

Affected Components: c-treeSQL Server

VERIFY_CLIENT_CERTIFICATE

VERIFY_CLIENT_CERTIFICATE { YES | NO }

default NO - The server requires the client to supply an X.509 certificate. Unless X509_AUTHENTICATION is enabled, a username and password must still be supplied by the client.

Must be specified within SUBSYSTEM COMM_PROTOCOL SSL (see TLS).

X509_AUTHENTICATION

x509_AUTHENTICATION  { YES | NO }

Default is NO. If the client provides an X.509 certificate at logon, use it for authentication and database authorization rather than a username/password. By default, the only trusted CA is the root CA of the SERVER_CERTIFICATE_FILE. The SERVER_CERTIFICATE_FILE must provide a complete certificate chain beginning with the certificate of the server and ending with the root CA. The client X.509 certificate must be signed by the same root CA as the server. Combine with VERIFY_CLIENT_CERTIFICATE YES to make X.509 authentication mandatory.

Must be specified within SUBSYSTEM COMM_PROTOCOL SSL (see TLS).

Note X.509 authentication is not supported in combination with LDAP authentication.

If X509_AUTHENTICATION is enabled, the following keywords are used to extract a username from the subject field of a successfully authenticated client X.509 certificate.

Note All name matching is case insensitive, as is the resulting user name used for login.

• X509_PATH <RDN> - Mandatory. Specifies which relative distinguished name (RDN) component of the full distinguished name (DN) to parse. This should be specified using the short form name, such as CN rather than CommonName. Typical values would be X509_PATH CN or X509_PATH emailAddress
• X509_PREFIX <prefix> - Optional. If specified the value found in X509_PATH must contain this prefix, which is removed when forming the username.
• X509_DELIMITER <suffix> - Optional. If specified the value found in X509_PATH must contain this suffix, which is removed when forming the username.
• X509_REQUIREMENT_PATH <RDN> - Optional. If specified, the DN must contain this RDN.
• X509_REQUIREMENT <value> - Optional. If specified, the RDN specified by X509_REQUIREMENT_PATH must match this value.

Example

Given the following server configuration:

   X509_AUTHENTICATION YES
   X509_PATH CN
   X509_REQUIREMENT_PATH O
   X509_REQUIREMENT faircom inc

A valid certificate with the subject:

   Subject: C=US, ST=Missouri, O=FairCom Inc, OU=R&D, CN=John Doe/emailAddress=john.doe@faircom.com

would resolve the user name as “John Doe”.

A valid certificate with the subject:

   Subject: C=US, ST=Missouri, O=Acme Inc, OU=R&D, CN=admin/emailAddress=john.doe@gmail.com

would not resolve a user name, as “Acme Inc” does not match the x509_REQUIREMENT “FairCom Inc” and an error would be returned.