File Security and Encryption

Any time multiple users access a database concerns with file security arise. This is particularly important when you have programs that allow easy access to the database. You must be able to prevent unauthorized access to restricted files, you may want to limit who can add or change records in the database, and it might be important to control who can delete files. The FairCom Server supports several complementary forms of system security: user passwords, file permissions, file passwords and data encryption. Careful use of these features provides complete control over who can access a particular file, and what that user can do with the file once it has been accessed.

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

It is important to note that file security is a function of access via the FairCom Server, therefore access by non FairCom DB programs may not be limited in many operating environments.

Accessing File Security

Extended Functions

In the first several chapters of this manual, we mentioned the extended functions. These functions perform the same operations as their complementary standard functions, with the additional ability to access the FairCom DB file security features. These functions have a suffix of Xtd (for instance, the extended version of InitCTree() is InitCTreeXtd()). The extended functions are:

• CreateDataFileXtd()
• CreateIndexFileXtd()
• CreateIFileXtd()
• CreateISAMXtd()
• InitISAMXtd()
• InitCTreeXtd()
• OpenCtFileXtd()
• OpenFileWithResourceXtd()
• OpenIFileXtd()
• OpenISAMXtd()
• RebuildIFileXtd()
• TempIIndexXtd()

Security function

In addition to the extended functions, FairCom DB provides the Security() function to manipulate file passwords and permissions.

FIPS Support

Note: This does not apply to FairCom JDBC and ADO.NET drivers, and json.db,

FIPS SuFIPS 140.2 is an encryption standard established by the US federal government. Faircom provides support for FIPS 140.2 through OpenSSL 3.0. To enable this support, use server keyword

FIPS_ENCRYPTION YES 

When successfully enabled, the following message is logged to CTSTATUS.FCS at startup:

"OpenSSL FIPS Cryptographic provider in use"

To enable this support for C based clients, set environment variable FAIRCOM_FIPS_CLIENT_MODE=Y before starting the process. To validate the provider is correctly configured or diagnose problems set environment variable FAIRCOM_LOG=<filename>.

When successfully enabled, the following message is logged to <filename> at startup:

"OpenSSL FIPS Cryptographic provider in use"

This affects all FairCom command line utilities, C based API's and other API's that rely on these such as:

• C.isam
• C.lowlevel
• C.nav
• C.sql.direct
• Cpp.nav
• Csharp.nav
• java.jpa.nav
• Java.nav
• Php.sql.pdo
• Python.nav
• Python.sql
• Sql.odbc
• Vb.nav

Unaffected client API's are:

• Sql.jdbc
• csharp.sql.ado.net
• json.db

Note: For unaffected client API's, driver side FIPS support may be possible purely through the host language (java, .NET, etc)

Forms of System Security

FairCom DB provides security in the form of users, user groups, files, and passwords.

Users, Groups, and Passwords

System Administrator

The FairCom Server comes with a System Administrator utility program, as described in the FairCom Server documentation. This utility performs a number of security related tasks.

User ID and Password

For username and password specifications, see System specifications.

For controlling user password requirements, see Setting password requirements.

Groups

The System Administrator will create one or more Groups. Each group is assigned a unique Group ID that is a 32-byte ASCIIZ string.

To provide a convenient way to permit users with related needs to share information, each user is assigned membership in from one to sixteen groups. The Administrator adds the groups to the system and assigns users to the groups. Each user has a default group, which counts as one of the user’s sixteen groups. If a user is not assigned to a group, the user’s default group is the GUEST group.

When an application program logs on to the FairCom Server with one of the extended functions, it sends a User ID and user password to the FairCom Server. Logging on with one of the equivalent standard functions, or sending a NULL User ID with one of the extended functions, automatically assigns the User ID of GUEST and membership in the GUEST group. If a User ID and/or password are sent which do not exist, the initiating call to the FairCom Server returns an error code and the program is not connected to the FairCom Server.

File Permissions

When FairCom DB creates a file, the User ID of the creating user is assigned to the file as the file’s owner. The owner’s default group is also assigned to the file unless the creating function specifies one of the owner’s other Group ID’s.

Further, the user may specify a permission mask that determines the kind of access that users may acquire on subsequent opens. The mask is comprised of three components: owner permissions, group permissions and world permissions. With this structure, you are able to allow different users different levels of access to the file.

When the owner of a file opens that file, that user is given owner’s permissions. Typically this level allows the user the most flexibility in managing the file. If a user who is not an owner of the file opens that file, FairCom DB looks at the groups the user belongs to. If that user is a member of the group assigned to the file then the user is granted group permissions. Finally, a user not falling into these categories is granted world permissions. Generally, permissions become more restrictive as you go from owner to world.

For example, an owner of a file may be able to read, write, and update records, and delete the file if necessary. Another user who is a member of the group for that file could have permission to read, write, and update records, but not to delete the file. Finally, a user who is not an owner, and not a member of the file’s group, may have permission only to read the file.

Permission Mask

When the file is created you will provide a permission mask for that file. The permission mask is formed by OR-ing the appropriate permission constants (found in ctport.h) from the following list:

• “READ” permission grants access to data, but no ability to change the data.
• “WRITE” permission grants update abilities.
• “DEF” permission allows the user to change or set file definition characteristics such as alternative collating sequences and record schemas.
• “DELETE” permission grants the ability to delete the entire file.

For example, to grant the owner all permissions, to grant group members read and update permissions, and to permit no access outside of the group, the permission mask should be defined as:

(OPF_ALL | GPF_READ | GPF_WRITE | WPF_NONE)

If no permission mask is assigned to the file, owner, group and world are granted all permissions. Permission masks, file ownership and group assignment may also be changed by using the Security() function, or by the system administrator.

File Passwords

In addition to permission masks, files may be protected by file passwords. File passwords can be assigned at the time the file is created, by using the Security() function, or by the system administrator. The file password is a 10-byte ASCIIZ string.

A user cannot access the file, regardless of the file’s permission mask, if the correct password is not supplied when the file is opened.

The ADMIN superuser always has full access to files. They do not need to know the file password to access a file.

User Profile

In the InitISAMXtd(), InitCTreeXtd(), CreateISAMXtd(), and OpenISAMXtd() extended functions there is a user profile mask parameter, userprof. We will discuss it here even though it is not a security parameter. You can combine the following values by OR-ing them together.

Automatic TransformKey

When using extended functions to initialize the ISAM system, FairCom DB automatically invokes TransformKey(). A userprof value of USERPRF_NTKEY disables the automatic TransformKey() feature.

Save Current ISAM Record

If you assign the value USERPRF_SAVENV to userprof, each Begin() call automatically includes the ctSAVENV mode. In this case, each Begin() and SetSavePoint() call saves the current ISAM record information, so that a subsequent RestoreSavePoint() or Abort() call automatically restores the current ISAM record information.

Allow ADMIN Access When Max User Limit Hit

One ADMIN group user may connect to FairCom DB when the maximum number of authorized users limit is reached. One client belonging to the ADMIN group can log on to a server, even if the maximum number of connections is used, by setting the USERPRF_ADMSPCL bit of the user profile.

This capability allows the Server Administrator to perform administration tasks even when the server is at its maximum licensed connections. The ctadmn and ctstop utilities take advantage of this feature.

Logon Control Options

FairCom DB security offers several options for controlling attempted logons.

For controlling user password requirements, see Setting password requirements.

Logon Strike-Out Options

FairCom Server configuration options set the default number of consecutive logon failures to allow, the default time to deny logon attempts after the failure limit is reached, and to set beginning and ending dates for User IDs. Options in the Security() function can reset the logon limit and the deny time.

The Server Administrator can set an optional limit on the number of consecutive failed logons that will cause subsequent logon attempts to fail for a specified time interval. The default logon limit is zero (0), which implies the feature is not active. Logons are blocked for 5 minutes by default after exceeding the limit. A logon during this period returns LRSM_ERR (584). Set the logon limit with LOGON_FAIL_LIMIT <logon limit> in the FairCom Server configuration file. The length of time the logons are blocked is set by LOGON_FAIL_TIME <minutes> in the configuration file. Set LOGON_FAIL_TIME -1 to block logon attempts permanently or until reset by an Administrator.

To require user logons within a given period and ensure all users log on “at-least-once” within the defined time (e.g: at least once a week), add the LOGON_MUST_TIME <minutes> keyword in the Server configuration file, ctsrvr.cfg, where <minutes> is the period in minutes during which the user must logon. If the time expires for a specific user, their profile will be deactivated, preventing access to the FairCom Server. The Server Administrator, or other ADMIN group user, must re-set the user’s account once the time limit has elapsed.

A client belonging to the ADMIN group can call Security to reset the values for these logon control options as follows:

A call of the form below, where value is a LONG holding the new LOGON_FAIL_LIMIT value, changes the limit in real time regardless of setting file or configuration file entries. The value is stored in FAIRCOM.FCS and can only be changed by a subsequent call to Security or by replacing FAIRCOM.FCS.

SECURITY(0,&value,(VRLEN) sizeof(value),SEC_FAIL_LIMIT)

A call of the form below, where value is a LONG holding the new LOGON_FAIL_TIME value in minutes, changes the time interval regardless of setting file or configuration file entries. The value is stored in FAIRCOM.FCS and can only be changed by a subsequent call to Security or by replacing FAIRCOM.FCS.

SECURITY(0,&value,(VRLEN) sizeof(value),SEC_FAIL_TIME)

A call of the form below, where value is a LONG holding the new LOGON_MUST_TIME value in minutes, changes the time interval regardless of setting file or configuration file entries. The value is stored in FAIRCOM.FCS and can only be changed by a subsequent call to Security or by replacing FAIRCOM.FCS.

SECURITY(0,&value,(VRLEN) sizeof(value),SEC_MUST_TIME)

The ctadmn utility supports the addition and maintenance of the logon control attributes on a user-by-user basis.

Retrieve the current Server logon control values with the SystemConfiguration() function. The desired values return in the cfgLOGON_FAIL_LIMIT, cfgLOGON_FAIL_TIME, and cfgLOGON_MUST_TIME parameters.

Suspend Server - Block User Logins

This feature blocks non-ADMIN users with the FairCom DB Security function. Four modes support the ability of an ADMIN user to block logons by non-ADMIN users:

The following Security() error and warning code returns apply to these modes:

Note: Only the ADMIN user can upgrade the block from NONADM to NONSUP mode or relax the block from NONSUP to NONADM mode. Other members of the ADMIN group can only use the NONADM block.

Once the block is turned on, a user that attempts to logon, but who does not satisfy the ADMIN requirements, is rejected with an error XUSR_ERR (593)

Suspend the Server

As noted above, the Security() function has the ability to kill all existing clients when setting a logon block. SEC_BLOCK_KILL acts like SEC_BLOCK_NONSUP by blocking logins by any user other than ADMIN, but also kills any clients already logged in.

Only ADMIN can make this call, and only ADMIN can resume logins with mode SEC_BLOCK_OFF. The internal threads that might open files are also suspended:

• The delete node thread and SYSLOG threads are suspended.
• The variable-length space management thread is suspended.
• The checkpoint thread is not suspended since it only searches for open files, it does not open them.

The COMPATIBILITY NO_BLOCK_KILL FairCom Server configuration keyword removes this capability. When COMPATIBILITY NO_BLOCK_KILL is in the configuration file, a call by ADMIN with mode SEC_BLOCK_KILL fails with NSUP_ERR (454).

The ability to suspend the Server gives remote ADMIN clients an added dimension. As an example, say a remote administrator needs to perform some type of operation in which it might be desirable to shut down the FairCom Server. An ADMIN client program can be authored to stop the Server, however restarting the server in a “non-telnet” type of environment might be impossible. By giving the administrator the ability to block new logins and kill existing clients (suspending the server) and then re-allow logins (like a restart) provides a solution to this problem.

Server Keyword: STARTUP_BLOCK_LOGONS

The STARTUP_BLOCK_LOGONS FairCom Server configuration keyword 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.

Once the ADMIN work is finished, call Security() with the following command to allow all user logons:

SECURITY((COUNT)-1,(pVOID)0,(VRLEN)0,SEC_BLOCK_OFF);

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

Advanced File Encryption

FairCom DB supports encryption of data, index, and transaction log files. This technology provides the means to add an extra level of confidentiality to an application’s data. Once encrypted, it becomes difficult for a user to “dump” or “inspect” the data.

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

Advanced File Encryption includes a suite of protocols that will protect user data by what is loosely called strong encryption with a certain amount of performance overhead. Historically, enabling encryption impacted database performance, however with modern hardware performance, the impact of data encryption is approaching negligible levels for most applications. The algorithms and protocols used are based on three primitives:

• Secure One-Way Hash Function (MD5)
• Block Ciphers (DES and AES)
• Pseudo-Random Number Generators

File-Specific Encryption Control

In systems supporting file encryption, control over whether or not to encrypt a file is available on a file-by-file basis.

If file encryption has been enabled by a call to SetEncryption(), an individual file can disable encryption by OR-ing ctNOENCRYP into the x8mode member of the XCREblk structure.

Whether or not SetEncryption() has been called, setting the filkey member of the XCREblk structure to a non-zero value causes the file to be encrypted using the value of the filkey member as the encryption key.

Using Advanced Encryption

Advanced Encryption requires a master encryption key to access encrypted data. This key must be presented at server startup for any access to encrypted data, thereby ensuring ONLY the intended client applications that have access and knowledge of the master encryption key can view the data.

Also note that FairCom DB supports passwords on files, which may further help protect against unwanted access. Proper implementation of user-access controls within FairCom DB is also recommended to prevent unauthorized access to data, even if it is not protected by other means.

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

Current customers: Please be sure to see additional application-level security details in the Knowledge Base in the Support Portal.

Setting Up Encryption

For a FairCom DB file to be protected by Advanced Encryption, it must be created as an encrypted file. The FairCom utility ctcmpcif.exe provides a mechanism for adding encryption support to an existing file. To create a file as encrypted you must call SetEncryption() before your file creation calls:

SetEncryption(pTEXT mod, pTEXT key, VRLEN keylen)

• mod -- reserved for Advanced Encryption options and should be NULL for default encryption.
• key -- pointer to a byte array containing the developer-specified encryption key of length keylen.
• keylen -- length of key.

For more details about using this function, see SetEncryption.

SetEncryption() does NOT assume that key points to a null-terminated ASCII string. The key can be any arbitrary array of bytes and is determined by the programmer. Key lengths of 7 bytes or more should be adequate. All create operations performed after SetEncryption() will result in encrypted files.

To stop encrypting new files, call SetEncryption() with key set to NULL and/or keylen set to zero.

SetEncryption() only affects file creation operations. All files created after a given call to SetEncryption(), with a non-NULL key and a keylen greater than zero, will be encrypted with the same key. Therefore, at the ISAM level, a data file and its associated indexes will be created with the same encryption key. Turning encryption on and off through calls to SetEncryption() only affects whether new files are encrypted. Once a file is set for encryption, it is always encrypted and no special calls are required to read from or write to the file.

Note: key may be thought of as a public key that changes the nature of the encryption, however, is not required to open the file. File passwords should be used to protect the ability to open a file. As described in Hidden Key Support, a hidden key may be embedded within a client executable and FairCom Server to give your application an exclusive ability to decrypt the file.

The following pseudo-code results in the first ISAM data file and its indexes to be encrypted with AES32 advanced encryption and the second ISAM data file and its indexes not to be encrypted:

InitISAM(...)
SetEncryption( (pTEXT)ctAES32,key,(VRLEN) 23)
CreateIFile(..1..)
SetEncryption(NULL,NULL,(VRLEN) 0)
CreateIFile(..2..)

To encode index and data files with a parameter file, use the user profile bit, USERPRF_ENCRYPT, in CreateISAMXtd() to enable encryption. All files created by, and after, CreateISAMXtd() will be encrypted with the same key, selected automatically by FairCom DB. New data and index files created after a call to SetEncryption() with a NULL key and/or zero keylen are not encrypted.

Errors

Two error codes have been defined: DCOD_ERR (606) is returned when an application cannot decode an encrypted file. RCOD_ERR (607) is returned when automatic recovery cannot decode an encrypted file.

Advanced Encryption Configuration

Follow these steps to enable advanced encryption support:

1. When Advanced Encryption is enabled, FairCom DB requires a master password at server startup. Run the ctcpvf utility to generate a new master password for use when launching the Advanced Encryption enabled Server. This will generate the file ctsrvr.pvf. See Master Password Verification Options.
   1. FairCom DB looks for the file ctsrvr.pvf in the server binary area, so this file name should be specified. ctcpvf.exe creates the ctsrvr.pvf file in that same directory where it is run (e.g., the tools directory). On launch, the server looks for ctsrvr.pvf in the server directory, so ctsrvr.pvf needs to be moved or copied to the server directory.
   2. Developers can use the FairCom DB SDK to replace this prompt with an application-specific method of retrieving the master password. See the "Key Store Option" discussion in the ctcpvf utility.
2. To enable Advanced Encryption for the database server, place the following keyword in the ctsrvr.cfg configuration file prior to launching:

ADVANCED_ENCRYPTION YES

To enable Advanced Encryption for standalone models, call ctSetAdvancedEncryption(YES), then call InitIsam()

Important: Advanced Encryption is disabled by default. 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 so user and group information is encrypted for protection. All user and group information must be recreated if the FAIRCOM.FCS file is deleted. Alternatively, ctcv67 can be used with option E to encrypt an existing FAIRCOM.FCS.

See Also

• Master Password Verification File Utility - ctcpvf
• Change Master Password Utility - ctencrypt

Master Password Verification Options

FairCom DB advanced encryption (AES, Blowfish, Twofish, 3DES) requires a master password to protect encrypted file access. Before starting FairCom DB for the first time with Advanced Encryption enabled, the Administrator must use the ctcpvf utility to create the master password verification file. Each time FairCom DB starts, it prompts for the master password to allow it to open encrypted files.

ctcpvf creates the master password verification file. It accepts optional parameters: filename (the file name to create) and password (the master password). If the parameters are not given, ctcpvf will prompt for the required information.

Usage

ctcpvf  [-c <cipher>] [-f <filename>] [-k <key>] [-s <store>]

Where:

• -c <cipher> - Use encryption cipher <cipher>. Supported ciphers: aes256 and aes128. Default is aes256.
• -f <filename> - Create password verification file <filename>. Default is ctsrvr.pvf.
• -k <key> - Use <key> as the master key.
• -s [<store>] - Store key in encrypted file <store>. Default is ctsrvr.fkf.
• -syslevel - Create encrypted store file with system-level encryption: all user accounts on the system can decrypt it.

Note: If you don't use the -syslevel switch, you must run the FairCom Server under the same user account that was used to run the ctcpvf utility that created the master key store file. Using the ‑syslevel switch creates the master key store file so that it can be opened by any user account on that machine, which allows you to run the FairCom Server under any user account on the system. (See Advanced encryption master key store encrypted at system level on Windows.)

Note: FairCom DB looks for the file ctsrvr.pvf in the server binary area, so this file name should be specified. ctcpvf.exe creates the ctsrvr.pvf file in that same directory where it is run (e.g., the tools directory). On launch, the server looks for ctsrvr.pvf in the server directory, so ctsrvr.pvf needs to be moved or copied to the server directory.

Key Store Option

By default, this master key must be presented to FairCom DB on startup as prompted. However, this prompted interaction is not always possible. Consider the case of a failover strategy for business continuity, or the case where no single person should ever know the complete key as keys are built from random secure key generators. FairCom DB supports a key store file to provide this key value at startup.

The ctcpvf utility -s option is used to select the master key length, and to write the master key to an encrypted keystore file <store>.

The FairCom DB configuration option MASTER_KEY_FILE specifies the key store file, <store>, from which FairCom DB reads the master encryption key. On Linux and Unix systems, the master key is stored AES encrypted in a file on disk, with permissions set such that only the user that created the file can read it (permissions are set to 400). For complete security, it is important to use file system access safeguards to fully protect this key store file.

Non-server applications must set the environment variable CTREE_MASTER_KEY_FILE=<keystore> to enable using a key store rather than prompting for the master password at FairCom DB initialization.

Note: The key file (or user key on Linux and Unix) is encrypted using AES. 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 Windows master key approach uses the Microsoft DPAPI to encrypt data with user credentials, and only that user can decrypt the file. Unix support is a bit weaker in this regard as it relies on file permissions, which can potentially be changed such that another user could read and decrypt the key.

ctencrypt - Utility to Change Master Password

The FairCom DB advanced encryption feature uses a master password to encrypt the file-specific advanced encryption key in c-tree data, index, and transaction log files that are encrypted using advanced encryption. ctencrypt is a standalone utility that can be used to change this master password for specified c-tree data, index, and transaction log files.

Operational Model:

• Standalone

Usage:

ctencrypt <options> <command>

Available Options:

• -n <sect> - Node sector size. The default is 64, which corresponds to PAGE_SIZE of 8192.

Available Commands (only one at a time may be specified):

• -chgmpw <filelist> - Change master password for the files whose names are listed in the file <filelist>. <filelist> is the name of a text file created by the end user that lists the names of the files (data and index), one per line, that are to be processed.

ctencrypt requires a password verification file named ctsrvr.pvf that was created using the current master password to exist in its working directory. ctencrypt prompts the user for the current master password and for the new master password (prompting twice in order to confirm that the new password was properly entered).

Note: ctencrypt does not change the master password file, ctsrvr.pvf. The ctcpvf utility will need to create a new file for server startup in coordination with the new password used to re-encrypt the encryption key for the files. Failure to do so will result in DCOD_ERR errors (606, failure to decode file) when opening files.

ctencrypt processes the specified files, indicating the status of each file and the total of successful and failed operations. Note that the FairCom Server must be shut down while these file modifications take place.

ctencrypt creates a temporary directory named temp\ctencrypt.tmp.<process_id> to store its transaction logs. This directory is normally deleted when ctencrypt shuts down.

Important: ctencrypt does not undo any changes in case of error. The files that it lists as successfully updated will use the new master password even if the utility failed to update other files.

Example File List

A semicolon can be specified at the start of a line to indicate a comment which is ignored.

; c-tree Advanced Encryption Conversion Listing File
; -----------------------------------------------------
; Created Wed Dec 01 01:38:00 2010
 
; transaction log files
L0000000.FCT
L0000002.FCA
L0000003.FCA
L0000004.FCA
L0000005.FCA
L0000006.FCS
L0000007.FCS
L0000008.FCS
L0000009.FCS
L0000010.FCT

; data files
  mydatafile.dat
C:\My Documents\test.dat 
vcusti

Note: All physical encrypted files, data and index files, must be specified in order to be modified. No attempt is made to determine associated files.

If the server was cleanly shutdown in such a manner that its transaction logs are no longer necessary, then they will not need to be included as part of this password change. If you wish to use the ctencrypt utility to modify any existing encrypted transaction logs (for example, archive logs for replication), their names must be specified in the list file. ctencrypt does not attempt to locate any transaction log files on its own.

Example Output

c-tree file encryption utility
 
This utility requires a master password in order to start.
Please enter master password:

Enter new master password   :
Confirm new master password :

Changing master password for the specified files...

[  OK   ] SYSLOGDT.FCS
[  OK   ] vcusti
[  OK   ] L0000000.FCT
[  OK   ] L0000002.FCA
[  OK   ] L0000003.FCA
[  OK   ] L0000004.FCA
[  OK   ] L0000005.FCA
[  OK   ] L0000006.FCS
[  OK   ] L0000007.FCS
[  OK   ] L0000008.FCS
[  OK   ] L0000009.FCS
[  OK   ] L0000010.FCT

12 succeeded, 0 failed

Successfully changed master password for all specified files

Error Returns

Two new error codes have been added related new password management features:

• BMPW_ERR (932) - The specified encryption master password is incorrect.
• ICOD_ERR (933) - An encryption operation failed due to an unexpected internal error. See CTSTATUS.FCS for details.

c-tree Client Implementation

Client implementation of Advanced Encryption is accomplished through the use of the SetEncryption() function on a per-file basis.

See Also

• Master Password Verification File Utility - ctcpvf
• Change Master Password Utility - ctencrypt

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

To encrypt files, simply call SetEncryption() before calling the function to create the file. The mod parameter should point to a text string containing one of the constants in the table below (for example., ctENCR to use the default encryption method or ctDES24 to use DES encoding with a 24-byte key. See ctport.h for constants.)

Note: For Advanced Encryption key is unused and keylen should be a non-zero value.

SetEncryption() is only required to create encrypted files. Any standard client can access files encrypted by a FairCom Server configured for advanced file encryption. Encryption and decryption occurs server side, and is not part of the client application.

Example

This example demonstrates full AES32 advanced encryption for a single file:

InitISAM(...)
SetEncryption( (pTEXT)ctAES32, key, (VRLEN) 23)
CreateIFile(..1..)
SetEncryption(NULL, NULL, (VRLEN) 0)

The possible mod values are defined in ctport.h:

Client Operation

When using Advanced File Encryption, SetEncryption() is only required to create encrypted files. Any standard client can access files encrypted by a Custom Server configured for Advanced File Encryption. Encryption and decryption happen behind the scenes, invisible to the client application.

To protect files further, add a file password to each file. Only applications with the file password can open the file. See Security and Encryption (File Security and Encryption) for more details.

Transport Layer Security Secures Data in Transit between Network FairCom DB Clients and Servers

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

FairCom applications can now secure data in transit between c-tree network clients and FairCom servers. Transport Layer Security (TLS, also commonly referred to as its predecessor SSL, Secure Sockets Layer) is a cryptographic protocol designed for secure network communications using public key cryptography for authentication of the communicating party. Symmetric cryptography is used to encrypt transmitted data over the wire. FairCom DB TLS relies on OpenSSL toolkit support and implements TLS protocol V1.3. Earlier versions of TLS (and predecessor SSL) protocols contain known and exploited vulnerabilities. FairCom DB only supports TLS via TCP/IP communications protocols (IPv4 and IPv6). (For more about TLS, see https://en.wikipedia.org/wiki/Transport_Layer_Security.)

Two modes of TLS connections are available: basic and peer authenticated. Basic TLS connections are encrypted using only a server-side certificate; there is no local certificate requirement for a client. This makes deployment and management of secured connections easy.

TLS Certificates

It is the server administrator’s responsibility to ensure a correct and valid certificate pair, as well as proper configuration of allowed TLS connections.

Creation and management of TLS certificates, as well as use of a Certification Authority (CA), is beyond the scope of this document. Consult OpenSSL and other TLS supporting documentation and be sure you firmly grasp all details regarding use of TLS for network security before deploying.

Server certificates may be created and provided as two separate files: a certificate and a key. They can also be combined into a single file. There is no required file naming convention. Certificate files are usually created and/or provided as Base64 encoded X.509 certificate files and denoted with a .pem extension (Privacy Enhanced Mail). They can be identified with this set of surrounding identifiers within the file:

-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----

The private key is likewise identified:

-----BEGIN PRIVATE KEY-----
-----END PRIVATE KEY-----

The private key is often included in the same certificate file or as a separate .key file.

A certificate key can be optionally passphrase protected. However, this then requires the passphrase to be presented at server startup. FairCom key store files provide this ability.

Always securely maintain key files. Store key files only in permissions protected server areas and never distribute.

Server-Side Configuration

To enable TLS (SSL), see keywords for TLS.

Standard c-tree TCP/IP ports are used for connections regardless of TLS configuration. That is, a single ISAM port will handle both TLS encrypted and non-encrypted connections, and likewise for the SQL port. There is no need for separate port configurations.

For the HTTPD plugin you can verify ciphers in use using the system nmap command (Linux) against the HTTPD port when no ciphers are specified in cthttpd.json. This can be done with the linux command:

nmap --script ssl-enum-ciphers -Pn -p 8443

Client-Side Configuration

Both FairCom ISAM and SQL clients support TLS connections.

Peer Authentication - TLS connection with server certificate validation:

By default, a c-tree client requires a PEM file containing the server public certificate—ONLY the public certificate, not the server private key.

Important: The server private key should be securely maintained only at the FairCom Server location at all times.

By default, ISAM and SQL client libraries use the file ctsrvr.pem in the client process' working directory when connecting. An ISAM client can change the file name that the client library searches for by calling the ctSetCommProtocolOption() function with the option ctCOMMOPT_FSSLTCP_SERVER_CERTIFICATE:

ctSetCommProtocolOption(ctCOMMOPT_FSSLTCP_SERVER_CERTIFICATE, "myservercert.pem");

Basic - TLS connection without server certificate validation (ISAM only):

It is also possible to establish a TLS connection from an ISAM client without validating the FairCom certificate. Such a connection is encrypted but there is no guarantee of the server’s identity. To use this option, call the ctSetCommProtocolOption() function with the option ctCOMMOPT_FSSLTCP_SERVER_CERTIFICATE with an empty certificate name before connecting:

ctSetCommProtocolOption(ctCOMMOPT_FSSLTCP_SERVER_CERTIFICATE, "");

When the client does not use a server certificate, the connection is encrypted, but there is no guarantee that the client is connected to that specific server. This implies that a "man in the middle" attack could be possible.

If an error occurs when connecting using SSL, the connection attempt returns error 1104 (SSLCONN_ERR). To get more detailed information enable SSL logging by either:

• calling ctSetCommProtocolOption() with the ctCOMMOPT_FSSLTCP_DEBUG_LOG option:

ctSetCommProtocolOption(ctCOMMOPT_FSSLTCP_DEBUG_LOG, "ssldebug.log");

or

• setting the environment variable CTSSL_DEBUG_LOG to the name of the SSL debug log file.

To request a TLS-enabled ISAM connection, append ^fssltcp to the server name. For example:

ctadmn ADMIN ADMIN "" "FAIRCOMS@localhost^fssltcp"

Note: When you append ^fssltcp to the server name you must quote the entire connection string, for example:

"FAIRCOMS@localhost^f_tcpipv6"

Windows normally interprets the carat as an escape character or line continuation, so the entire server connection string must be quoted when it includes a caret.

 Other examples showing how to specify a desired communication protocol when connecting:

To connect using shared memory (without falling back to TCP/IP if the shared memory connection fails):

FAIRCOMS@localhost^fsharemm 

To connect using TCP/IP v4 without SSL:

FAIRCOMS@localhost^f_tcpip

To connect using TCP/IP v6 without SSL:

FAIRCOMS@localhost^f_tcpipv6

To connect using TCP/IP v6 with SSL:

FAIRCOMS@localhost^fssltcpv6

To request a TLS-enabled connection for a SQL connection, prepend ssl: to the connection string. For example:

isql -u admin -p ADMIN ssl:6597@localhost:ctreesql

Standard FairCom DB SQL interfaces (JDBC, ADO.NET, ODBC, PHP, Python) each have independent standards for connection strings. JDBC and ADO.NET are specifically described later in this chapter.

ctadmn and FairCom DB Monitor show the communication protocol that is in use, including whether or not the connection is using TLS (SSL):

F_TCPIP     indicates an unencrypted ISAM TCP/IP connection.
FSSLTCP     indicates an SSL-enabled ISAM TCP/IP connection.
SQL_TCPIP   indicates an unencrypted SQL TCP/IP connection.
SQL_SSLTCP  indicates an SSL-enabled ISAM TCP/IP connection.

X.509 Support

Support has been added for X.509 client/server authentication. For now, only X.509 authentication when using TLS-encrypted TCP/IP for ctree is supported. Future revisions will extend this to SQL and shared memory protocols.

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

To use X.509 authentication, the client must provide a PEM formatted X.509 certificate with a complete certificate chain using the same root CA as the server certificate. If the client's certificate is successfully validated by the server, the subject field on the client X.509 will be parsed by the server to extract a username. This username is used to determine the database permissions to be granted. A complete certificate chain consists of a PEM formatted file with the certificate for the user, followed by the certificate for the issuer, followed by the certificate for that issuer, and so on, ending in the root CA certificate.

When X.509 authentication is enabled and a certificate is provided by the client, the username and password arguments passed to InitISAMX() are ignored.

New Security keywords have been added to enable X.509. See Client Communications Keywords for TLS.

The following functions have been enhanced for configuring X.509 authentication

• ctSetCommProtocolOption
• InitISAMXtd

Expected TLS Performance

The resource-intensive portion of a TLS connection is the initial creation. A secure communications channel is established via asymmetric encryption requiring a session key exchange. This initial key exchange and encryption process is the slowest computational epoch. Once connected, ongoing connection overhead is negligible. Further, most modern hardware contains dedicated CPU instructions for enhanced encryption performance. Thus, it is important to avoid repeated connections and maintain an established TLS connection when at all possible.

Compatibility

COMPATIBILITY TCPIP_CHECK_DEAD_CLIENTS

Advanced SSL Certificate Options

The ssl_certificate keyword in the config/cthttpd.json web server plug-in configuration supports the fccert.pem, which is a self-signed certificate we supplied. To use your own certificate, use the following keywords to config/cthttpd.json:

• ssl_key: SSL private key - This can be embedded in the same file provided the in ssl_certificate. For example, our default fccert.pem certificate file has both the certificate and the private key, so, ssl_key is not required.
• ssl_ca: SSL Certificate Authority - External authority that issues and validates the certificate.
• ssl_cipher_suites - Colon-delimited list of SSL cipher suites.

Troubleshooting

There is a client-side environment variable for debugging. To enable SSL logging for the client, set the CTSSL_DEBUG_LOG environment variable to the log file name.

For server side SSL debugging, add DEBUG_LOG <logfile> to the SSL subsection.

Testing with Default FairCom DB Certificates

For testing and evaluation purposes only, a self-signed X.509 certificate is included in your default FairCom DB package. OpenSSL was used to create this certificate.

Security Note: It is critical this included certificate is never used in a production setting.

In the example below, a certificate and private key are both included in the file ctree_ssl.pem. Unencrypted TCP/IP connections are allowed, and the specified ciphers are the ones that are allowed to be used in encrypting the SSL connection:

SUBSYSTEM COMM_PROTOCOL SSL {
 SERVER_CERTIFICATE_FILE ctree_ssl.pem
 SSL_CONNECTIONS_ONLY NO
 SSL_CIPHERS ALL:!aNULL:!eNULL:!SSLv2:!LOW:!EXP:!RC4:!MD5:@STRENGTH
}

To enable only TLS-encrypted communications for all connections, change SSL_CONNECTIONS_ONLY to YES, and, optionally, comment Shared Memory communications support to prevent local unencrypted shared memory connections. (FairCom DB Shared Memory connections are not supported for TLS encryption.)

;COMM_PROTOCOL  FSHAREMM

Finally, for peer authentication, an additional cross-check validation against the server certificate, copy ctsrvr.pem to your client working directory. FairCom DB management and administration tools already include this local client certificate file in their working folder:

<faircom>\server

All GUI tool connection dialogs contain specific parameter options for enabling TLS connections. support.faircom.com was specified as the Common Name in provided FairCom DB default certificates. Specify support.faircom.com when testing FairCom DB SQL Explorer for TLS authentication using ADO.NET to succeed using these included certs.

ADO.NET Support for TLS

In V11.5 and later, the FairCom DB ADO.NET provider supports TLS/SSL connections per Microsoft specifications.

The ADO.NET provider uses the local certificate store to locate certificates when using peerAuthentication. The server's CA (or a self-signed) certificate ctsrvr.pem must be added to the trusted root certificate store on the client machine for the .NET framework's certificate authentication to succeed:

CertMgr.exe /add ctsrvr.pem /c /s /r localMachine root

Note that the Common Name specified in the server certificate is the name that the application must specify in the ADO.NET connection string for the TLS option.

For this certificate, we used support.faircom.com as the Common Name, and so the ADO.NET connection string must specify sslcert=support.faircom.com for the TLS authentication to succeed.

If client certificate authentication is desired (V13.1 and later), a certificate chain and private key for the client must first be added to the current user's personal certificate store. This can be done using a PKCS #12 file containing the desired certificate chain and private key.

Connection String

The ADO.NET connection string is similar to the JDBC string. The connection string accepts a new property:

ssl=<value>

which can have two values:

• basic - Basic SSL setting, no peer certificate authentication, only communication encryption as requested by server certificate
• peerAuthentication - Server certificate authentication.

In the case of peerAuthentication the server certificate Common Name must be provided by the new property:

sslcert=<value>

If this property is not specified, the value of the Server setting is used to match the certificate.

If peerAuthentication is enabled, client authentication may also be attempted. If X509_AUTHENTICATION is enabled by the server then a client certificate can replace the normal password based authentication. Identify the Common Name for the client certificate to use:

ClientSSLCert=<value>

The current user's personal certificate store is searched first for this certificate. The localmachine store will also be searched if a matching certificate is not found in the current user's store and the process has permission to access the localmachine's personal store.

If X509_AUTHENTICATION is enabled by the server and the ClientSSLCert is accepted, any UID and PWD values included in the connection string are ignored.

Examples:

"UID=ADMIN;PWD=ADMIN;Database=CtreeSQL;Server=localhost;Service=6597;ssl=basic";
"UID=ADMIN;PWD=ADMIN;Database=CtreeSQL;Server=localhost;Service=6597;ssl=peerAuthentication;sslcert=support.faircom.com";
"Database=CtreeSQL;Server=localhost;Service=6597;ssl=peerAuthentication;sslcert=support.faircom.com;ClientSSLCert=JohnDoe";

ODBC Support for SSL

You can use SSL with an ODBC data source. To configure SSL, open the ODBC Data Source Administrator.

Once you invoke the ODBC Data Source Administrator:

1. In the dialog box for the type of data source you choose, choose the Add button. The Add Data Source dialog box appears.
2. Select FairCom DB SQL from the list of installed drivers and choose Finish. The FairCom DB ODBC Setup dialog box appears.
3. Fill in the dialog box fields as shown in the following figure and choose OK. The ODBC Data Source Administrator writes the values you supply to ODBC.INI or to the DSN file you indicated.

Data Source Name - A local name for the FairCom DB SQL data source for use in connect calls and by the ODBC Administrator.

Description - Optional descriptive text.

Host - Specify the machine name on which the FairCom DB SQL Server is running.

Database - The name of the database where the FairCom DB SQL data source resides.

User ID / Password - User name and password for connecting to the database. The driver uses those values if the application does not supply them in the call. You can leave these fields blank if you want the driver to use the defaults on the server. If no defaults are defined and you leave these fields blank, the user will be prompted when the application connects.

Service - The name of the Service FairCom DB SQL listens to. If empty, sqlnw is used.

Default Fetch Size - This value is the size (in bytes) used by the driver to fetch multiple rows from the server. It reduces network requests resulting in performance gains. If not set, the internal buffer size is 5000 bytes.

• In your connection string, set the attribute "FETCH_SIZE=[number of bytes]"
• In your ODBC.INI file, set the attribute "Default Fetch Size=[number of bytes]"
  Connection string settings take precedence over DSN and ODBC.INI settings.
  Default Query Timeout - it is possible to set the DefaultQuery Timeout (in seconds) in the DSN and in the connection string. 
• In the connection string, the attribute is: QUERY_TIMEOUT=[number of seconds]
• In the ODBC.INI file, the attribute is: Default Query Timeout=[number of seconds]

Settings in the connection string take precedence over the setting in the DSN or ODBC.INI.)

Preserve Cursor - This behavior is configurable from within the ODBC administrator.

Scrollable Cursor - This allows you to enable support for ODBC applications that require a scrollable cursor.

Client Character Set - Use the drop-down list to select the character set used by the client.

SSL - Enter optional parameters to configure the SSL. The following entries can be used to configure the SSL connection:
1) empty - Do not use SSL.
2) BASIC - Use SSL without certificate checking.
3) <certificate file name> - Use SSL with certificate checking using the certificate file specified. If no path is entered, the file must be in the current working directory.

Options - Enter any optional parameters to be included in the connect string.

The Data Source Dialog box reappears, and now includes the newly-added data source.

Configuring SSL in Your Connection String

In the ODBC connection string, it is possible to add "SSL=xyz" where "xyz" is one of the options 2 or 3 from the SSL parameters listed above in the FairCom DB ODBC Setup dialog box.

You can add one of the following to your existing ODBC connection strings to enable TLS/SSL:
"SSL=BASIC" - Encryption with default server certificate.
"SSL=ctsrvr.pem" - Use Peer authentication with explicitly named cert located in the local directory.
"SSL=C*\certs\ctsrvr.pem" - Use Peer authentication with an explicitly named cert with a full path.

JDBC Support for TLS

In FairCom DB V11.2 and later, FairCom DB SQL JDBC supports TLS connections per the JDBC standard. Enable TLS in a JDBC connection URL using the ssl=value parameter string.

TLS connections are enabled in the JDBC connection URL using the new format (it is not supported on the old URL format) and a new parameter ssl.

The new URL format is:

jdbc:ctree://<host>[:portnumber]/<dbname>[?param=value[&param=value]...]

The valid param values are:

• characterEncoding - Replace encoding with a valid Java encoding name (e.g., US‑ASCII, ISO‑8859-1, UTF‑8, etc.).
• password
• user
• ssl - The valid values for ssl are:
  basic
  peerAuthentication
• trustStore - The name of a local trust store that includes the server's CA certificate.
• trustStorePassword - The password for the specified trust store.
• keyStore - The name of a local key store that has the user certificate and private key.
• keyStorePassword - The password for the specified keyStore.

Note: For backward compatibility, the older format ("jdbc:ctree:6597@localhost:ctreeSQL", "ADMIN", "ADMIN") is still supported but should be considered deprecated.

Basic TLS with JDBC clients

Traffic to the server is encrypted, but there is no assurance of the server's identity.

Basic SSL encryption on the client is enabled by the URL parameter ssl, for example:

Connection c = getConnection("jdbc:ctree://localhost:6597/ctreeSQL?ssl=basic");

Peer Authenticated TLS with JDBC clients using System properties

If the client wants to authenticate the server, then the client's trust store must contain the server's CA certificate (or a self-signed server certificate). A Java keystore must first be created that contains this CA certificate.

For example, the following adds the trusted CA certificate ctsrvr.pem to a keystore named server.store

keytool -importcert -file ctsrvr.pem -keystore server.store

keytool is part of the Java distribution, and will prompt you for a password used to encrypt the trust store. In this example we used mypassword as the password.

Client SSL with server authentication is enabled by the URL parameter ssl set to peerAuthentication.

You must set the system properties javax.net.ssl.trustStore and javax.net.ssl.trustStorePassword to reference the trust store for the desired database server.

Example:

System.setProperty("javax.net.ssl.trustStore","server.store");
System.setProperty("javax.net.ssl.trustStorePassword","mypassword");
Connection c = getConnection("jdbc:ctree://localhost:6597/ctreeSQL?ssl=peerAuthentication");

Full TLS authentication with JDBC clients

The FairCom database server may be configured to allow or require client TLS authentication in place of password based authentication. The client needs to both authenticate the server (with the same requirements as for peerAuthentication), and provide proof of identity to the server by providing a client certificate that is trusted by the server. This may be set in the connection string by specifying a trustStore for the server and keyStore for the user.

Example:

Create the trust store with the trusted CA certificate ctsrvr.pem to a keystore named server.store. Keytool is part of the Java distribution, and will prompt you for a password used to encrypt the trust store. In this example we use mypassword as the password.

keytool -importcert -file ctsrvr.pem -keystore server.store

The client must possess a keystore containing their certificate and private key. Here we assume a keystore exists named johndoe.pkcs12 protected with password secret.

Note: The default keystore format is controlled by the java.security configuration file under the property keystore.type. The PKCS12 keystore format is supported by all Java implementations, but prior to Java9 JKS was the default format. You may need to adjust this configuration for your keystore to be accessed by Java.

The following connection string will attempt to connect using these certificate sets for TLS authentication.

Connection c = getConnection("jdbc:ctree://localhost:6597/ctreeSQL?trustStore=server.store&trustStorePassword=mypassword&keyStore=johndoe.pkcs12&keyStorePassword=secret");

See Also:

Java keytool documentation provides examples of how to generate a key pair, request a certificate from a CA, or generate certificates for a server.

Allow ISAM Client to Use SSL without Client Having Server Certificate

The c-tree ISAM client now supports establishing an SSL connection without requiring the client to have the server certificate in the file ctsrvr.pem. By default, the client requires the certificate file, but it can disable this requirement by calling the ctSetCommProtocolOption() function with the following parameters after registering a c-tree instance and before connecting to c-tree Server:

ctSetCommProtocolOption(ctCOMMOPT_FSSLTCP_SERVER_CERTIFICATE, "");

When the client does not use a server certificate, the connection is encrypted, but there is no guarantee that the client is connected to that specific server. This implies that a "man in the middle" attack could be possible.

OpenSSL Headers for Linking FairCom DB Client Applications

The OpenSSL headers have been included in this package for your convenience. These headers must be compiled and linked into your project. Examine your opensslv.h header in the ctree.drivers/include/openssl folder for the current version included in your build.

The OpenSSL include files are located under /ctree/include.

Libraries are provided for multiple build platforms and are located in /ctree.drivers/lib/License.Lib/openssl, where you'll find:

• libeay32.lib
• ssleay32.lib

Choose the appropriate build platform from the provided versions.

OpenSSL Now Provides Default Faster AES Encryption

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.

TLS/SSL Tutorials

As an example of linking with OpenSSL libraries, you can view the Tutorial makefiles and IDE Projects in the SDK directories. For example:

/linux.x64.64bit/sdk/ctree.ctdb/tutorials/cmdline/Makefile

AWS Security

(This technology is not included in the default package. It is available upon request.)

Master Encryption Key management is challenging. Keys must be remembered or securely retained, or data is permanently lost. To aid secure master key storage, FairCom Server can now integrate with an AWS Secrets Manager® service. This support requires an AWS account and a configured Secrets Manger service, which is not included nor maintained by FairCom.

Please contact FairCom with your specific Advanced Encryption Key management request for Amazon AWS support.

Support for Using AWS Secrets Manager as External Encryption key Store

FairCom Server now supports retrieving its master encryption key from AWS Secrets Manager.® This option is an alternative to FairCom Server's MASTER_KEY_FILE option. It has the advantage that the key is not stored locally. To logon to the AWS Secrets Manager, FairCom Server displays a dialog box that prompts the user to enter the AWS Secrets Manager credentials.

To configure FairCom Server to use AWS Secrets Manager, add the following option to ctsrvr.cfg:

SUBSYSTEM EXTERNAL_KEY_STORE AWS {
 KEY_ID <key_id>
 REGION <region>
 TIMEOUT <timeout>
}

<key_id> is the key ID that you assign to the encryption key when you store it in AWS Secrets Manager.

<region> is the AWS region where the AWS Secrets Manager stores your key.

<timeout> is the maximum amount of time, in seconds, to wait for the user to enter the AWS Secrets Manager credentials when FairCom Server starts. The default is 30 seconds. If the timeout period passes before the user enters the credentials, FairCom Server logs the following messages to CTSTATUS.FCS and shuts down:

 - User# 00001  Failed to retrieve AWS credentials: CTAWS(324): abandoning wait for AWS credential prompt to complete after <seconds> second(s) due to timeout
 - User# 00001  The master password must be entered in order to start this server.  The server will now shut down.

How to use AWS Secrets Manager to store the master encryption key for c-tree Server:

1. Login to AWS Secrets Manager.
2. Select "Store a new secret."
3. Select secret type of "Other type of secrets."
4. Enter the key and its value. For the key, use the name ctreeServerMasterEncryptionKey. For the value, enter the encryption master key.
5. Select encryption key of "DefaultEncryptionKey" and click Next.
6. Give the secret a name. This name is the value that you will specify for the KEY_ID value in the ctsrvr.cfg file.
7. Optionally add a description. Click Next.
8. Disable automatic rotation and click Next.
9. Click Store.

In standalone mode (ctrdmp utility for example), the configuration options are set by setting these environment variables to the desired values:

CTAWS_KEY_ID
CTAWS_REGION
CTAWS_TIMEOUT

If FairCom Server is configured to use AWS Secrets Manager and the DLL cannot be loaded, an error is logged to CTSTATUS.FCS:

- User# 00001  Could not load AWS support: CTDLL_LOAD: Failed to load module ctaws.dll: The specified module could not be found.: 981

FairCom Server supports changing the master encryption key when it is stored in AWS Secrets Manager.

DLL for FairCom Server to Access AWS Secrets Manager

A new DLL, ctaws.dll, exports a set of API functions that FairCom Server uses to access AWS Secrets Manager on Windows. FairCom Server dynamically loads this DLL when it is configured to use AWS Secrets Manager to store its master encryption key.

This DLL requires the Amazon provided AWS C++ SDK DLLs aws-cpp-sdk-core.dll and aws-cpp-sdk-secretsmanager.dll, which contain the AWS core and Secrets Manager functions respectively.

Product Installation Requirements:

To use AWS Secrets Manager as FairCom Server’s encryption key store, the DLLs ctaws.dll, aws-cpp-sdk-core.dll, and aws-cpp-sdk-secretsmanager.dll must be installed in the same directory as the FairCom Server binary.

Note: When using AWS key store support on servers that are licensed for multiple remote desktop sessions, the password prompt may not be presented unless the database process is run as a normal process (not a Windows service). Because this might involve file permissions changes, it is recommended to install the database in this non‑service configuration on such systems.

Visual Prompt Utility for AWS Credentials

To read FairCom Server's master encryption key from AWS Secrets Manager, we prompt the user to enter the AWS credentials using a graphical interface on Windows.

The ctawssmp utility is a process that displays a dialog prompting the user to enter the AWS Secrets Manager login credentials. FairCom Server launches this process when it starts up if it is configured to use AWS Secrets Manager as its encryption key store.

This Windows application displays the following message which prompts the user to enter the AWS Secrets Manager credentials:

Access Key ID and Secret Access Key are randomly-generated values created by an AWS account administrator. They require the proper access permissions to the AWS Secrets Manager to be able to read the secret referenced by the KEY_ID. For details about these values, see the Amazon document: https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html

Product Installation Requirements:

To use AWS Secrets Manager as FairCom Server’s encryption key store, ctawssmp.exe must be installed in the same directory as the FairCom Server binary.

Ensure recoverability if server terminates while changing master encryption key

The changing of the master encryption key involves multiple steps. If an error occurs, the work is undone, but if the server terminates we did not ensure that the changes were all undone. This could render the server unable to start or unable to decrypt files.

If FairCom Server terminates while the master encryption key is being changed, the encrypted files (data and index files and transaction logs) might have been left in a state that is inconsistent with the current master key, causing them to fail to open with errors 606, 607, or 66 on the next restart of FairCom Server.

A write-ahead recovery log has been implemented for the master encryption key change. The log file, named CMPRECOV.FCS, is created in the same directory as the transaction logs. It records the change we are about to make to a file before we apply the change. When FairCom Server starts up, if this log file exists FairCom Server uses the information in this recovery log to undo all the changes to the files so the data, index, and transaction log files are all using the original master encryption key. This log also allows c-tree to undo the changes to non-transaction files, which are not recorded in c-tree's transaction logs.

Encrypted Data Master Key Library

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)