FairCom ISAM for C

SECURITY (function)

Modifies a file’s security settings, including password, group ID, and permission mask.

Short Name

SECURITY()

Type

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

Declaration

COUNT Security(FILNO filno, pVOID bufptr, VRLEN bufsiz, COUNT mode)

Description

In V12 the file number typedef was formally changed from COUNT, a two-byte value to FILNO, a four-byte value. Refer to this link for compatibility details. Four Byte File Numbering

Security() permits the owner of a file to change a file’s security information, including the file’s password, Group ID, and permission mask. Security() permits members of the ADMIN group to change the default number of allowed consecutive logon failures or the default time to deny logon attempts after the failure limit is reached.

For file security changes to file number filno: bufptr points to the buffer containing the updated security information and bufsiz specifies the length of the buffer. The contents of the buffer will differ based on the mode. See the section below for a description of what to pass in the buffer. See the section below for a description on what to pass in the buffer.

The buffer should contain the old password, NULL terminated, immediately followed by the new information, also NULL terminated, which can be the new file password, new file group ID, new owner user ID, or the new permission mask. If you are changing the permission mask, the value following the NULL terminated old password must be a long integer containing the appropriate OR-ed permission values. To remove a password, simply pass a NULL byte for the new password. If you change the file owner, you will not be able to make additional calls to Security, only the new owner will be able to do so.

Note: FAIRCOM.FCS can be opened only by a member of the ADMIN group. ADMIN group members can read data from FAIRCOM.FCS using low-level or ISAM function calls but cannot update FAIRCOM.FCS, other than through calls through the SECURITY() API function.

mode defines the type of request. The values for mode are:

Value	Symbolic Constant	Interpretation
1	SEC_FILEWORD	Change file password.
2	SEC_FILEGRUP	Change file group.
3	SEC_FILEMASK	Change file permission mask.
4	SEC_FILEOWNR	Change file owner.
5	SEC_FAIL_LIMIT	Set logon failure limit.
6	SEC_TEMPPW	Set temp logon password
7	SEC_FAIL_TIME	Set logon failure time.
8	SEC_MUST_TIME	Set minimum time between logons.
9	SEC_BLOCK_NONADM	Block new logons except ADMIN group members.
10	SEC_BLOCK_NONSUP	Block new logons except ADMIN user ID.
11	SEC_BLOCK_OFF	Stop blocking new logons.
12	SEC_BLOCK_KILL	Block new logons except ADMIN user ID, suspend internal threads that might open files, and kill any current connections and dumps.
13	SEC_ADD_USER	Add user account
14	SEC_REMOVE_USER	Remove user account
15	SEC_CHANGE_USER_GROUPS	Change user group membership
16	SEC_CHANGE_USER_DESC	Change user description
17	SEC_CHANGE_USER_PASSWD	Change user password
18	SEC_CHANGE_USER_MEMORY	Change user memory limit
19	SEC_CHANGE_USER_XINFO	Change user extended settings
20	SEC_ADD_GROUP	Add group
21	SEC_REMOVE_GROUP	Remove group
22	SEC_CHANGE_GROUP_DESC	Change group description
23	SEC_CHANGE_GROUP_MEMORY	Change group memory limit
24	SEC_CHANGE_ADVENC_PASSWD	Change the master password
25	SEC_CHANGE_USER_LOGLMT	Change user logon limit
26	SEC_CHANGE_GROUP_LOGLMT	Change group logon limit
27	SEC_CHECK_ADVENC_PASSWD	Check the master password for advanced encryption

filno is ignored when mode is SEC_FAIL_LIMIT, SEC_FAIL_TIME, or SEC_TEMPPW.

Buffer Contents

SEC_ADD_USER

2-byte extended user settings file number (FAIRCOM.FCS!UVAL.dat)

2-byte group file number (FAIRCOM.FCS!GROUP.dat)

2-byte user group file number (FAIRCOM.FCS!USER.dat)

2-byte FC_USER length

FC_USER data

2-byte FC_UVAL length

FC_UVAL data

1-byte number of groups

group 0 name, group 1 name, ... (NULL terminated strings)

SEC_REMOVE_USER

2-byte extended user settings file number (FAIRCOM.FCS!UVAL.dat)

2-byte user group file number (FAIRCOM.FCS!USER.dat)

null-terminated user name

SEC_CHANGE_USER_PASSWD

null-terminated user name

null-terminated user password

SEC_CHANGE_USER_GROUPS

2-byte group file number

2-byte user group file number

null-terminated user ID

1-byte number of groups

group 0 name, group 1 name, ... (NULL terminated strings)

SEC_CHANGE_USER_DESC

null-terminated user name

null-terminated user description

SEC_CHANGE_USER_MEMORY

null-terminated user name

4-byte user memory

4-byte user memory attribute

SEC_CHANGE_USER_XINFO

2-byte extended user settings file number

2-byte user group file number

2-byte FC_UVAL length

FC_UVAL data

SEC_CHANGE_USER_LOGLMT

null-terminated user name

4-byte user logon limit

SEC_ADD_GROUP

2-byte FC_GROUP length

FC_GROUP Data

SEC_CHANGE_GROUP_DESC

null-terminated group name

null-terminated group description

SEC_CHANGE_GROUP_MEMORY

null-terminated group name

4-byte group memory

4-byte group memory attribute

SEC_CHANGE_GROUP_LOGLMT

null-terminated group name

4-byte group logon limit

SEC_FILEWORD

null-terminated password

SEC_FILEMASK

1-byte set to 0

filemask

SEC_FILEGRUP

null-terminated group name

SEC_FILEOWNR

null-terminated owner name

SEC_CHECK_ADVENC_PASSWD

Check if the specified master encryption password matches FairCom Server's current master encryption password. This feature is only supported in client/server mode and can only be done by a user account that is a member of the ADMIN group. To use this feature, call the SECURITY() function as described below:

FILNO filno - Set to -1.
pVOID bufptr - Pass the advanced encryption password as a null-terminated string.
VRLEN bufsiz -Set to the length of the advanced encryption password in bytes including the null terminator.
COUNT mode - Set to SEC_CHECK_ADVENC_PASSWD.

If called by a user account that is not a member of the ADMIN group, the function returns error LADM_ERR (589).

If advanced encryption is not enabled, the function call returns error NSUP_ERR (454).

If the specified master password does not match the master password that FairCom Server is currently using, the function returns error BMPW_ERR (932).

One-Time Password

To establish a one-time password that another client can use, along with the user ID matching the caller that set the password, set bufptr to a special, (0x01 in first byte), one-time password and plen to the length of the password. filno is ignored. The password is available until it is used by the subsequent client with a matching user ID or the caller of Security logs off. The password set by the original caller MUST begin with a byte of value 0x01, otherwise it will be ignored.

To change the Logon Fail Limit in real time regardless of setting file or configuration file entries, point bufptr to a LONG holding the new LOGON_FAIL_LIMIT value. The value is stored in FAIRCOM.FCS and can only be changed by a subsequent call to Security or by replacing FAIRCOM.FCS. filno is ignored.

To change the time interval regardless of setting file or configuration file entries, point bufptr to a LONG holding the new LOGON_FAIL_TIME value in minutes. The value is stored in FAIRCOM.FCS and can only be changed by a subsequent call to Security or by replacing FAIRCOM.FCS. filno is ignored.

FC_UVAL Structure

The FC_UVAL structure holds settings used by the SECURITY() function. Some of the mode settings require setting values in this structure.

typedef struct {

TEXT userid[32];

ULONG begstamp; /* beginning date for valid user logon */

ULONG endstamp; /* last valid date for user logon */

LONG lgonover; /* limit on consecutive logon failures */

LONG reserved;

ULONG rsmstamp; /* temporary logon block */

LONG lgonfail; /* current number of failed login attempts */

ULONG lgonany; /* last logon attempt date */

ULONG lgonok; /* last successful login date */

ULONG lgonbad; /* last failed login date */

LONG lgonoknum; /* Total number of successful logins(ever) */

LONG lgonbadnum; /* Total number of failed logins(ever) */

ULONG disstamp; /* when logon was disabled */

LONG lgonmust; /* user must login within this period */

ULONG lastpasschg; /* time of last change to password */

ULONG passvaliddays; /* number of days that password is valid */

TEXT resrv[92];

} FC_UVAL;

When calling SECURITY() with mode of SEC_FAIL_LIMIT to set the logon failure limit, set the maximum limit in lgonover.

When calling SECURITY() with mode of SEC_FAIL_TIME to set the logon failure time, set the maximum time (in seconds) in lgonmust.

When calling SECURITY() with mode of SEC_CHANGE_USER_XINFO to set an expiration date on a user account password, set the passvaliddays field of the FC_UVAL structure to the password validity period in days. A value of zero sets no password expiration. When a user account's password has expired, attempting to log on to the user account fails with error 1116 (PWDEXP_ERR). This feature is also available in the ctadmn and sa_admin utilities.

Return

Value	Symbolic Constant	Explanation
0	NO_ERROR	Successful open of ISAM files.
22	FNUM_ERR	File number is out of range.
47	FINT_ERR	c-tree has not been initialized.
48	FMOD_ERR	Invalid mode value.
62	LERR_ERR	File must be opened exclusively.
153	VBSZ_ERR	Input does not match size of LONG.
447	BOWN_ERR	Only the user/owner can change the user/file password.
448	DEFP_ERR	File definition permission denied.
451	LPWD_ERR	The old password is not valid.
455	SGRP_ERR	The file owner does not belong to the new group.
456	SACS_ERR	Group access denied.
458	SWRT_ERR	Write permission not granted.
580	FSEC_ERR	Negative value input.
584	LRSM_ERR	Logon fail limit exceeded, wait for timeout.
589	LADM_ERR	User not a member of the ADMIN group.
924	SADM_ERR	Only the super administrator user account (named ADMIN) can perform this operation.
925	SCMP_ERR	The FairCom DB client is attempting to use features of the SECURITY() API function that this FairCom Server does not support. Update your FairCom Server.

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

API Call to Verify Server Master Password

The SECURITY() function now supports the ability to check if the specified master encryption password matches the FairCom Server's current master encryption password. It provides the ability to check that the user is able to connect as ADMIN.

This feature is only supported in client/server mode and can only be accessed by a user account that is a member of the ADMIN group. To use this feature, call the SECURITY() function as described below:

SECURITY() parameters:

COUNT filno: Set to -1.
pVOID bufptr: Pass the advanced encryption password as a null-terminated string.
VRLEN bufsiz: Set to the length of the advanced encryption password in bytes including the null terminator.
COUNT mode: Set to SEC_CHECK_ADVENC_PASSWD.

Function return values for this mode:

The function returns NO_ERROR(0) on success.
If called by a user account that is not a member of the ADMIN group, the function returns error LADM_ERR (589).
If advanced encryption is not enabled, the function call returns error NSUP_ERR (454).
If the specified master password does not match the master password that c-tree Server is currently using, the function returns error BMPW_ERR (932).

Changing the Master Password

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

Call the SECURITY() function with the SEC_CHANGE_ADVENC_PASSWD mode.
Specify filno of -1.
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;
Set options to ctENCMODlowl
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).
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:

Value

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

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.

Ability to Validate against Advanced Encryption Master Password

FairCom Server now supports the ability to check if a client-provided master encryption password matches FairCom Server's current master encryption password. The use case for this feature is an elevated level of access beyond ADMIN authentication. Knowing the master encryption password implies the calling user has elevated privileges.

The server is assumed already started with a valid master key. A new SECURITY() (SECURITY (function), Security) API mode makes this check against the current master key.