Database Administrator's Guide

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:

Value		Symbolic Constant		Interpretation
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.

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