FairCom DB Access Configuration

One of the main responsibilities of a FairCom DB Server Administrator is to establish and maintain access to the FairCom Server. Although reviewing this chapter is not required for operating the FairCom Server, FairCom recommends Administrators consider the following features.

Access to the FairCom Server can be controlled in four basic ways:

The details of access and security control through user, file, and group information are covered in this section. Basic concepts needed to understand security operations are covered first. Descriptions of the Administrator Utility used to enter security information for the FairCom Server and monitor users while they are connected to the FairCom Server follow.

Note: The controls discussed here are those available to the Administrator. Applications can also be programmed to allow certain security controls (e.g., change file passwords) to users who have appropriate access to the FairCom Server, using available security functions in FairCom’s FairCom DB API. Consult application documentation or application vendor for further login instructions.

It is important to be aware that the file security provided by the FairCom Server is a function of access to files through the FairCom DB Server. When files are not controlled by the FairCom Server, they may not be secure.

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

Users, Files, Groups, and File Permission Masks

This section covers the security concepts needed to understand and make use of the full range of Administrator security controls offered by the FairCom Server. These security features are designed to work together. For example, security instructions can be arranged allowing only certain sets of users particular rights with respect to a given file.

See Also

• Security Administrator Utility - sa_admin (sa_admin - Command-line security administration utility, Security Administration)

Users

Whenever an application connects to a FairCom Server, it must identify itself to the FairCom Server. The identifying code is called the User ID. To gain access to the FairCom Server, the User ID seeking access to the FairCom Server must be one already authorized as a valid User ID. A password for the User ID may also be required to access the FairCom Server.

If one attempts to log on to a FairCom Server with an invalid User ID (i.e., one not issued by the Administrator or created by changing an existing User ID), the FairCom Server will deny the request and send a message to that effect (i.e., error message 450). An attempt to log on with a valid User ID but an invalid user password will also be denied, with a message stating the reason (i.e., error message 451).

When an application, i.e., a user running a given application, logs on to the FairCom Server, a task user is created to identify the session with the User ID. This is relevant when monitoring or disconnecting clients from the FairCom Server.

The FairCom Server recognizes four kinds of users:

Administrator

The ADMIN account is built into the FairCom server. It cannot be removed or altered. It is the all-powerful, database administrator account (DBA) or “super user”. It is the only built-in account. The name, ADMIN, cannot be changed. Its default password is ADMIN, which is uppercase. You should immediately change this password using the ctpass utility.

Passwords

FairCom strongly recommends assigning strong passwords to each User ID — especially the ADMIN account.

For specifications, see System specifications.

For controlling user password requirements, see Setting password requirements.

Unique User ID

A user or an application must provide a User ID and password to log into a FairCom Server. This ensures only authenticated and authorized accounts can access the server.

Only an administrator can create new User IDs and passwords for other users. An administrator may also assign other User IDs to the ADMIN group to provide them with full administrator capabilities (other than the ability to delete, disable, or alter the ADMIN account).

For specifications, see System specifications.

Guest Users

The following practice is not recommended. The server can be configured to allow connection with an empty User ID and an empty password. When the User ID is empty, the server assigns the name, GUEST to the User ID. This is called a guest login.

To allow guest logons, add the following line to the ctsrvr.cfg configuration file: GUEST_LOGON YES.

Note: Users, including ADMIN, can use the ctpass utility (see User’s Control of Security Options) to change their own password. Members of the ADMIN group can use the FairCom DB Server Administrator Utility, described below, to change the password for a User ID that is not a member of the ADMIN group; only the super ADMIN account (named ADMIN) can change a password for an account that is a member of the ADMIN group.

User ID and Membership in Groups

The Administrator can establish groups of any sort (e.g., a payroll group, a shipping room group, a data entry group) and associate each User ID to as many as 128 of these groups. For example, User ID “B.Smith” could be a member of Group ID “Payroll”. These connections are ordered, from the “1st” to “Nth” group membership, where N is a maximum of 128.

If the Administrator does not assign a given User ID to a group, the FairCom Server automatically assigns that User ID to a special group with the GUEST Group ID. In addition, the special GUEST User ID is automatically assigned to the GUEST group.

A primary (i.e., default) group is always defined for each User ID. This is either the Group ID for the first association or, if no Administrator established associations, the GUEST group. For instance, number 1 on the list of 128 possible connections between the user and groups set up by the Administrator.

These group mechanisms are important in connection with the file permission masks. See Groups for more information.

User ID and Ownership of Files

Each file created by the FairCom Server has an owner. In general, the User ID in effect when a file is created is automatically made the owner of the file. The Administrator can change a current file owner to any other valid User ID. The concept of file owner is important because it can be used with the file permission mask. See Files for more information.

User ID and Logon Limits

The Server Administrator can set several system-wide limits and User ID overrides for those limits. The number of consecutive logon failures, the delay after failure limit is reached, and a minimum time between logons can all be set system-wide with configuration keywords. These settings can be overridden for each User ID using the Server Administration utility, ctadmn, which can also set beginning and ending dates for each User ID. These features are detailed below and in FairCom DB Server Administrator Utility.

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 configuration file. The length of time the logons are blocked is set by LOGON_FAIL_TIME <minutes> in the configuration file.

The FairCom Server can be configured to require user logons within a given period. This ensures all users log on “at-least-once” within the defined time (e.g., at least once a week). If the time expires for a specific user, the server deactivates the user’s profile, preventing access to the server. The Server Administrator, or other ADMIN group user, must reset the user’s account once the time limit has elapsed. To activate this feature, add the following keyword in the server configuration file, ctsrvr.cfg, where <value> is the period in minutes during which the user must logon:

LOGON_MUST_TIME <value>

Files

Database files have several security features in addition to the file permission mask, discussed in a separate section:

File Password

Files created by the FairCom Server, and others, can be assigned a file password when created. File passwords can be changed later by the Administrator or the file’s owner, and then be required for users to access files. For example, a user could be required to enter a file password before initiating the file operations specified in the file permission mask (see File Permission Masks).

File passwords can be up to 9 characters long. Characters can be letters, numbers, or punctuation marks. Passwords are case sensitive (i.e., upper case and lower case characters are treated as different).

File Owner

As explained in Users, when a file is created by the FairCom Server, the User ID requesting the creation is established as the owner of the file.

User accounts in the ADMIN group are treated differently from non-ADMIN users: When a user account in the ADMIN group creates a file, a security resource is stored in the file (unless the file is created with the ctDISABLERES filemode). This means the owner and group of the file is set to the ADMIN user and, if the permission mask is zero, all permissions are set on the file.

Non-ADMIN users must specify a non-zero permission mask to enable security restrictions. If the permission mask is zero, or if you call a file create function that doesn't have a permission mask parameter, the file is created without security features. Remember: A zero permission mask does not mean "no permission"; it means "no security restrictions" (full permission) and no owner and group are assigned.

If you call CreateIFileXtd() or CreateIFileXtd8() and specify a non-zero permission mask, the file is assigned the owner and group of the user creating the file.

The Administrator may change the file owner any time to any other currently valid User ID. The owner is used to define one of the ways file permissions can be granted, e.g., the owner typically has permission to write to the file.

File Group

When created, a file is typically associated with the current primary group of the User ID who created the file. The file group is designed for use with the file permission mask. This can be changed later to any other currently valid Group ID for that User ID by the Administrator or owner. For example, the file permission mask may allow “group permission” to read the file, while no others can (see File Permission Masks). As explained above under "File Owner," if the permission mask is zero, or if you call a file create function that doesn't have a permission mask parameter, the file is created without security features.

If instructed by the user’s application when it creates a file, a file’s Group can be any one of the owner’s other Group IDs, instead of the owner’s primary Group.

The current Owner of a file may use the ctfile utility, after entering both the current User ID password and the current file password, to change: the file password; the file permission mask (see File Permission Masks); the file Group; and even the file Owner itself, which would block the user from accessing the file through the original Owner User ID. User’s Control of Security Options contains a further description of this treatment.

Groups

A Group is an arbitrary category of associated User IDs and files. For example, a business wanting to separate the payroll department and the shipping department could establish a “shipping” Group and a “payroll” Group and associate appropriate User IDs with one or more of these Administrator-defined Groups. By establishing and using groups, the Administrator can offer file-level operation control to selected groups of users. For example, by using Groups along with file permission masks it is possible to enable users in the payroll department to read, but not write, to any file created by anyone else in the payroll department.

See also Two Kinds of Groups.

Two Kinds of Groups

The FairCom Server maintains a GUEST group, to which User IDs are associated if they are not assigned to any Administrator-defined Group ID. This means every User ID is associated with at least one group (i.e., the GUEST Group or a Group ID).

The Administrator can create any number of Groups each of which has a Group ID, a text description (for display), a memory allocation specification, and a list of User IDs associated with the Group ID. As noted, the Administrator can associate a given User ID with as many as 128 Group IDs. A GUEST User cannot be associated with any Group IDs; instead, the FairCom Server automatically assigns a GUEST User to the GUEST Group.

Group IDs can be up to 31 characters long. Characters can be letters, numbers, or punctuation marks. Group IDs are not case-sensitive (i.e., upper and lower case characters are treated as the same).

File Permission Masks

Once a user has access to a given file, which might need both user and file passwords to reach, there is one additional level of access control available. This is the “file permission mask,” a set of controls over who can do what with a given file.

Operations Controlled

User permissions with respect to the following file operations can be controlled with the file permission mask for a given file (i.e., “YES, TYPE X USERS have permission to do this operation” or “NO, TYPE X USERS do not have permission to do this operation”):

• READ the file
• WRITE to the file (i.e., add, update, or delete individual items in the file)
• CHANGE THE DEFINITION(s) of the file, including such characteristics as alternative collating sequences or record schemas (see the FairCom DB Programmer’s Reference Guide for details)
• DELETE the entire file
• Any combination of the above

If a file has no permission mask, any user who can access the file can perform all the above operations. Remember: A zero permission mask does not mean "no permission"; it means "no security restrictions" (full permission) and no owner and group are assigned.

User Controls

Each of these permissions for a given file can be specified for any or all of the following classes of users:

• WORLD access: Allow the specified file operations to any user who can access the file (so users who lack a required User ID and/or file password do not have these file-operation permissions).
• OWNER access: Allow the specified file operations to the current owner of the file. The owner is either the User ID in effect when the file was created or a different User ID who was later assigned as the owner (see Files for details).
• GROUP access: Allow the specified file operations to any User ID currently a member of the same Group as the current File Group.

In summary, a file permission mask permits different degrees of access to a file for the file’s owner, users belonging to the file’s group, and all other users, including guests.

Using the concepts discussed above, the Administrator can establish a sophisticated and flexible security system with the FairCom Server. The mechanism for actually entering information for use by the FairCom Server is a separate program utility, called the Administrator’s Utility, ctadmn.

Informing Users of their Security Options

Users can change the password for their own User ID and they can change security controls for a file if they are the owner of the file. To optimize the use of FairCom DB you may wish to be sure users are aware of these abilities, and how to appropriately apply them.

See User’s Control of Security Options for details.

Advanced Data Encryption

FairCom offers developers several advanced encryption routines, including AES (Rijndael), Blowfish, Twofish, and DES. Advanced encryption must be enabled at runtime via a server configuration keyword. The choice of encryption algorithm and cipher strength is a per-file choice by the application developer at file creation time. A master password is then assigned to the server installation which must be provided in some form at server startup.

When advanced encryption is enabled, FairCom DB prompts for a master password at server startup by default. For high availability, options are available to use a local key store file to maintain and verify the master password. The system administrator may encrypt existing files using the ctcv67 utility.

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

Note: Prior to enabling advanced encryption, understand that there is no practical way to recover encrypted data without knowing the master password that was used to encrypt it. This applies to backed up data as well as live data. If a master password is changed, be sure to retain the old master password for any backups that may still be encrypted with the previous master password.

Enabling Advanced Encryption Support

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

Encrypting Files Using Advanced Encryption

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

Changing the Master Password

You can use the standalone ctencrypt utility or the ctadmn utility to change the master password. Using the ctadmn utility, the Change Server Settings menu has an option to Change advanced encryption master password. This will Quiesce the server and update the master password for all files or a provided list of files, plus some server-controlled files like FAIRCOM.FCS. Using ctadmn to change the master password requires the ALLOW_MASTER_KEY_CHANGE YES option to be specified in ctsrvr.cfg (default: NO).

A function can be used to change the password that is used to encrypt the file-specific encryption keys in the specified files. The function is supported by the FairCom Server and by the standalone c-tree ctencrypt utility.

Changing the master password in client/server mode

There are two ways to change the master password in client/server mode:

• Use the ctadmn utility
• Use the SECURITY() function

Use the ctadmn utility

1. Select option 10. Change Server Settings.
2. Select option 7. Change advanced encryption master password.
3. Enter the name of a file on the client system that contains the names of the c-tree data and index files that are to be modified. The file is a text file that contains one filename per line. Any names of transaction logs that are specified in this file are ignored. (The FairCom Server automatically locates its active, inactive, and template transaction logs and updates them.)
4. Enter the current advanced encryption master password.
5. Enter the new advanced encryption master password. ctadmn prompts twice for the new password to confirm that it was entered correctly.

If the FairCom Server successfully changes the master password for all the specified files, ctadmn displays the message:

Successfully changed the advanced encryption master password

If an error occurs, ctadmn displays the following message:

Error: Failed to change the advanced encryption master password: <error_code>

where <error_code> is the error code indicating the cause of the failure.

In case of an error, check CTSTATUS.FCS, as it might contain more descriptive messages that explain the cause of the error.

Use the SECURITY() function

To change the master password using the SECURITY() function:

1. Call the SECURITY() function with the SEC_CHANGE_ADVENC_PASSWD mode.
2. Specify filno of -1.
3. Set bufptr to point to a buffer that holds the master password change information and set bufsiz to the size of the buffer.
   
   The buffer must conform to the ctENCMOD structure definition shown below:
   
   typedef struct ctencmod
{ LONG options; LONG numfiles; TEXT varinf[4]; }
ctENCMOD, *pctENCMOD;
    
4. Set options to ctENCMODlowl
5. Set numfiles to the number of files whose names are specified in the varinf field (do not include the current and new master passwords in this count even though those values are also specified as the first two strings in the varinf field).
6. In the varinf field, store the following values as null-terminated strings:
   • the current master password
   • the new master password
   • the first c-tree file name
   • the second c-tree file name
   • ...
   • the Nth c-tree file name (where N equals numfiles)

When using the FairCom Server master password change interface, FairCom Server attempts to change the master password for the specified files and for all active, inactive, and template transaction logs that it knows about. If any of the files cannot be changed, the entire operation is undone. When the entire operation is successful, the ctsrvr.pvf file is also updated using the new master password.

If an error happens on the transaction logs but the FairCom Server terminates before it can undo the changes, some files may be left using the new master password but the master password is still set to the old value. In this case, the ctencrypt standalone utility (see Changing the master password using the ctencrypt standalone utility) can be used to change the master password for those c-tree data, index, or transaction log files that need to be changed.

Error Codes

Two error codes have been added:

See c-tree Error Codes for a complete listing of valid c-tree error values.

This also requires that the ALLOW_MASTER_KEY_CHANGE configuration option is enabled, as explained in the FairCom DB Server Administrator's Guide.

Changing the master password using the ctencrypt standalone utility

ctencrypt is a standalone utility that can be used to change the master password for the specified c-tree data, index, and transaction log files. Below is the command-line usage for this utility:

ctencrypt <options> <command>
 

Supported options:

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

Supported 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, 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 to confirm that the new password was properly entered). Then ctencrypt processes the specified files, indicating the status of each file and the total of successful and failed operations.

Unlike the FairCom Server master password change operation, ctencrypt does not undo any changes in case of an error. The files that it lists as successfully updated will use the new master password even if the utility failed to update other files. Also, if you wish to use the ctencrypt utility to modify any transaction logs, their names must be specified in the list file. ctencrypt does not attempt to locate any transaction log files on its own (as the c-tree Server operation does).

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.

Below is sample output from ctencrypt:

FairCom DB(tm) Version 9.5.35095(Build-101118) c-tree file encryption utility

Copyright (C) 1992 - 2010 FairCom Corporation
ALL RIGHTS RESERVED.

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