Process of Upgrading Data to a Higher Encryption Level

To upgrade your data to a higher encryption level, perform the following tasks:

Verify that all requirements are met.

For information, see "Requirements for Upgrading to a Higher Encryption Level".
Make sure that the input file includes every column that you want to upgrade.

For information, see "Modifying the Input File".
Run the Key Database Manager utility to change the password or add a new key to the database.

For information, see "Managing the Key File Using the Key Database Manager".
Upgrade the data to a higher level of encryption.

For information, see "Running the Encryption Upgrade Utility".

Requirements for Upgrading to a Higher Encryption Level

This topic lists the tasks you must complete before you upgrade your data to a higher encryption level.

This task is a step in "Process of Upgrading Data to a Higher Encryption Level".

To upgrade to a higher encryption level, the following requirements must be fulfilled:

The Siebel Gateway and Siebel Server are installed.
The Siebel repository has been upgraded to the schema for the current release, so that a new column has been created to store the key index for the encrypted column.
If you created or customized columns to use the standard encryptor of Release 6.x or 7.0.x, for each encrypted column that you want to upgrade, you must create a new column to store the key index.
If, in releases prior to release 8.X, you customized business component fields to use the standard encryptor, then verify that you define the correct properties for the columns in the database table that holds encrypted data. For further information, see "Configuring Encryption and Search on Encrypted Data".
Verify that column sizes for custom extension columns are large enough to hold the new AES values.
The key database file (keyfile.bin) must already exist. (A default key file was created in the SIEBEL_ROOT/siebsrvr/admin directory when you installed the Siebel Server.)
If you require AES encryption, then you must upgrade the key database file to use AES encryption (192 and 256 bits). For more information, see "About Siebel Encryption".

Modifying the Input File

Before upgrading to a higher encryption level, you must modify the encrypt_colums.inp input file to list every table column that you want to upgrade. The input file, encrypt_colums.inp, indicates the table and column that store the encrypted data, and the table and column that store the key index.

This task is a step in "Process of Upgrading Data to a Higher Encryption Level".

The following procedure describes how to modify the input file.

To modify the encrypt_colums.inp file

Navigate to the SIEBEL_ROOT/dbsrvr/bin directory where the input file is located.

If you want to execute the Encryption Upgrade Utility from the command line, then place this file in the SIEBEL_ROOT/siebsrvr/bin directory.
Using a text editor, edit the input file to include every column that you want to upgrade.

The first line of the input file indicates a table name with brackets around it. On subsequent lines following the table name, list all the columns to be upgraded for that table.

Each column that stores encrypted data requires a table column to store the key index, which is specified after the column name; for example:
```
[TABLE_NAME]
COLUMN_NAME TABLE_NAME_FOR_KEY COLUMN_NAME_FOR_KEY 
WHERE clause
```

After each table, skip a line, and continue to list the columns for subsequent tables, as shown in the following example:

[S_ORDER]
CC_NUMBER S_ORDER CCNUM_ENCRPKEY_REF
WHERE S.CC_NUMBER='1234567890'
[S_DOC_ORDER]
CC_NUMBER S_DOC_ORDER CCNUM_ENCRPKEY_REF
WHERE S.CC_NUMBER='1231231231'
[S_PER_PAY_PRFL]
PAY_ACCNT_NUM S_PER_PAY_PRFL CCNUM_ENCRPKEY_REF
WHERE S.CC_NUMBER='1231231231'

When you have added information for every table column that you want to upgrade, save the input file.

About Using the Where Clause and Flags in the Input File

On the line following the name of each column to be upgraded, you can optionally specify the WHERE clause, the N flag, and the H flag for the column:

Use the WHERE clause if you want to partition the data to encrypt. Every column name that you specify for the WHERE clause must have the letter S added to the start of the column name. If you do not want to partition data, then omit the WHERE clause, as in the following example:
```
[S_ORDER]
CC_NUMBER S_ORDER CCNUM_ENCRPKEY_REF
WHERE
```
If you have imported data from EIM into an encrypted column, then use the WHERE clause to specify that only the unencrypted EIM records, that is, records where the value of the key index column is NULL, are to be encrypted. For example, the following entry is for a table named S_PER_PAY_PRFL. This table contains an encrypted column, PAY_ACCNT_NUM, which has a key index column, ENCRPKEY_REF:
```
[S_PER_PAY_PRFL]
PAY_ACCNT_NUM S_PER_PAY_PRFL CCNUM_ENCRPKEY_REF
WHERE S.CCNUM_ENCRPKEY_REF IS NULL
```
To support upgrade of non-encrypted fields to use encryption, add the letter N after the column name; for example:
```
[S_NEW_TABLE]
COLUMN_NAME S_NEW_TABLE NAME_KEY_INDEX
N
```
If you want to enable search on the upgraded encrypted column, then add the letter H to the end of the column; for example:
```
[S_NEW_TABLE]
COLUMN_NAME S_NEW_TABLE NAME_KEY_INDEX
H
```
This creates a hash column which stores the values that are returned when you apply the SHA-1 algorithm to the plain text values of the encrypted column.

If you want to enable search on an existing encrypted column, then add the following entry in the input file to create a column which stores the hash value of the plaintext in the encrypted column:
```
[S_TABLE_NAME]
COLUMN_NAME S_TABLE_NAME COLUMN_NAME_ENCRPKEY_REF H
WHERE S.ROW_ID='123123'
```
For information about search on encrypted data, see "Configuring Encryption and Search on Encrypted Data".

Running the Encryption Upgrade Utility

This topic describes how to run the Encryption Upgrade utility. You must run the utility if you want to perform either of the following tasks:

Encrypt data that is not encrypted
Increase the encryption level of data that is already encrypted

This task is a step in "Process of Upgrading Data to a Higher Encryption Level".

Note:

The Encryption Upgrade utility writes output to its own log file which is located in the log subdirectory of your Siebel Server directory. The default filename for the log file is encryptupg.log. You can specify another filename for the log file as described in the following procedure.

To run the encryption upgrade utility

Verify that the input file encrypt_colums.inp includes all the columns that you want to upgrade. If necessary, review "Modifying the Input File".

Run encryptupg.exe by navigating to SIEBEL_ROOT\siebsrvr\bin and entering the following command:

encryptupg.exe /f FromEncrytionStrength /t ToEncryptionStrength /j InputFileName /l Language /u UserName /p Password /c ConfigurationFile /L LogFile

where:

FromEncrytionStrength is the encryption strength that you want to upgrade from. The following table describes valid parameters to enter in this command.

Parameter	Description
`NONE`	Unencrypted data.
`STAND`	Data encrypted by the Siebel Standard Encryptor. This type of encryption is no longer supported.

Caution:

When you run the Encryption Upgrade utility on unencrypted data and specify the NONE parameter, the utility will encrypt the data. Be careful that you do not run the utility in this mode on the same data twice. If you do, then you will encrypt data that is already encrypted, leading to a permanent loss of data.

ToEncryptionStrength is the encryption strength that you want to upgrade to. The recommended value to enter for this parameter is AES.
InputFileName is the filename of your input file (the default is encrypt_columns.inp).
Language is the language code, for example, to specify U.S. English, enter ENU.
UserName is the user name for the database.
Password is the password for the database.
ConfigurationFile is the application configuration file where you specify the data source for the Encryption Upgrade utility to retrieve data from.
LogFile is the log file that the Encryption Upgrade utility writes to; the default file is encryptupg.log.

After the upgrade is complete, make sure that the encrypted database columns specify the value for the encryption method used in the Computation Expression parameter. For more information, see "Configuring Encryption and Search on Encrypted Data".
Update the repository and deliver the updates.