Product Documentation

Database Integrity Utilities

Previous Topic

Next Topic

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.

TOCIndex