Keyindex Command Line Utility for Re-Encrypting Data

In the event that the value of a secret encryption key has become known, any data in the database that may be compromised can be re-encrypted with the keyindex utility.

To use the keyindex utility, you will need to define a series of parameters which include the data source name, database username, password, original key index, new key index and time when processing should be completed. The original key index (From) is used to decrypt data in the database. The data is then re-encrypted with a new key index (To) and stored back to the database.

Because it is designed to perform its task quickly and efficiently, the keyindex utility has no GUI. The re-encryption process is extremely CPU-intensive so this makes any additional application processing impracticable while the keyindex utility is running. This utility should therefore be executed at a time when no other Transactionware GM applications are running such as after the store is closed. It can also be launched as a nightly batch process.

To run this utility the following parameters must be defined:

Parameter	Description
/d	Data source name: name of data source that will be used to connect to database
/u	Database username: name of user that will log on to selected database
/p	Database password: password of user logging on to selected database
/f	‘From’ key index (-1 through 255): key index user will be coming from
/t	‘To’ key index (0 through 255): key index user will be going to
/e	End time 24 hr clock [HH:MM]: military time denoting time to end processing
/s	Silent error message: Indicates that message box error should not be displayed. This is an optional parameter.

The Key Index utility creates output ASCII text files to capture any processing errors as well as the status of the re-encryption process. The output files are created in the directory where the keyindex utility is located. They are defined as follows:

Keyindex.out: Status file denoting current progress of re-encryption process. The file contains a header line signifying time stamp, database, key index (from/to) and end time. Each table processed during a session appears in this file. There are currently only two tables for the BACKOFF.DB database: PA_CUSTOMER and TXN_POS_TRANSACTIONS. Each table is assigned the number of rows remaining to be re-encrypted, the number of rows that have been encrypted, the starting time the table was processed and the ending time the table was last processed. The end time can be either: the time of shutdown or the time all encrypted data in table has been re-encrypted.

Keyindex.n: These are status files which show what stage the current processing session is at. They also trigger specific batch files when the re-encryption process is finished. The possible status values are:
- Keyindex.0: Process successfully finished re-encrypting all data in database
- Keyindex.1: Process detected an error; manual intervention required
- Keyindex.2: Process successfully re-encrypted data; table data remains to be encrypted

Keyindex.err: Error file used to capture error messages for the purpose of diagnosing any potential problems that may have occurred during the execution of the keyindex utility such as invalid command line parameters supplied to program.

The keyindex utility retrieves, decrypts, encrypts and updates data in blocks of approximately 100 rows at a time. When the data is updated back to the database, the re-encrypted data is automatically committed to the database. It is highly recommended to backup the database prior to executing the key index utility. Even though processing in small batches can reduce the likelihood the chances of losing data, it does not reduce the risk of database corruption. Processing in smaller batches mitigates the risk of losing large amounts of data should data corruption, such as a power surge, occur.