Configuring DB2 Databases

Before data can be migrated, CipherTrust Database Protection for DB2 must be installed on the database server and the database must be added to the CipherTrust Manager GUI.

This section provides information on operations that can be performed on the CipherTrust Manager for the CDP for the DB2 client.

Note

All the database management operations mentioned in this chapter need to be performed by a user of the ProtectDB Users group. This user is referred to as the CDP Server Administrator in this document.

Managing Database Connection

This section provides instructions to configure a connection between a DB2 database and the CipherTrust Manager. It also describes how to view, edit, and delete an existing database connection.

Creating a DB2 Database Connection

To create a DB2 database connection:

1. Log on to the CipherTrust Manager GUI.

2. Click the Database Protection tile to open the application. The Databases screen displays the list of existing database connections, if any.

3. Click + Add Database. The Add Database wizard is displayed. Follow the steps to complete the setup.

   • Select Database Type

   • Add connection details

   • Confirmation

Select Database Type

1. Select the database type as DB2.

2. Click Next to go to the Connection Information screen.

Add connection Details

1. On the DB2 Database Configuration screen, configure the following fields:

   Item	Description
   Name (Alias)	Name for the connection information. This field uniquely identifies a database connection.
   Host	IP address of the database server.
   Port	Port on which the database server is listening for connections. Default values: • 50000: If a TCP based connection is used connect the CipherTrust Manager and DB2. • 50005: If an SSL based connection is used to connect the CipherTrust Manager and DB2.
   Database User Name	Database login name that has permission to modify the tables to be migrated. This could be the owner of the database tables or a user with privileges to CREATE, MODIFY, and DROP views, tables, and triggers.
   Database User Password	Password for the database user.
   MetaDatabase User Name	INGRIAN is used as the meta database user. It cannot be changed. The INGRIAN user is created as a requirement before installing the CDP client for DB2.
   MetaDatabase User Password	Password for the meta database user.
   Enable Credentials Caching	Select to save the database credentials for multiple sessions. User authorization is not required to access table/column for a database in different sessions. Possible configurations: • Enabled: The user can directly access the table/column information for a database in multiple sessions. • Disabled: For each session, while accessing the table/column information for a database, user is prompted for database credentials. Once the credentials are validated successfully, further authorization is not required for that session. NOTE: The database authorization is session based. Authorization is mandatory for each session while accessing table/column for a database.
   Protocol	Select the protocol to be used to connect the CipherTrust Manager to a DB2 database. The supported protocols are: • TCP • SSL To create an SSL based connection: — Upload the CA certificate to the CipherTrust Manager. b. On the DB2 Database Configuration page, select the Protocol as SSL.
   Secondary Auth ID	Secondary authentication ID. This field is optional.
   Database Name	Name for the database that contains the tables and columns to encrypt.

2. Click Next to go to the Confirmation screen.

Confirmation

1. On the Confirmation screen, verify the connection details. The Confirmation screen displays Database Type and Connection details.

2. Click Save. The newly added database is added on the Databases screen. The Status column reflects the status of the connection.

3. Click the refresh () icon on the screen if the status is not updated.

   After the database is added, the next step is to create a user mapping. Refer to Managing User Mappings.

Editing Database Connections

To edit an existing database connection:

1. Log on to the CipherTrust Manager GUI.

2. Click the Database Protection tile to open the application. The Databases screen displays the list of existing database connections, if any.

3. Click the overflow icon () corresponding to the desired database connection.

4. Click Edit Connection. The Connection Information screen is displayed in edit mode.

5. Edit the following fields/options as required.

   • Host

   • Port

   • Database User Name

   • Database User Password

   • MetaDatabase User Password

   • Enable Credential Caching

   • Protocol

   • Secondary Auth ID

   • Database Name

6. Click Update. The Status column on the Database screen reflects status of the connection.

7. Click the refresh icon () on the screen if the status is not updated.

Viewing Database Connections

To view the existing database connections:

1. Log on to the CipherTrust Manager GUI.

2. Click Database Protection to open the application. The Databases screen displays the list of existing database connections, if any.

Deleting Database Connections

To delete an existing database connection:

1. Log on to the CipherTrust Manager GUI.

2. Click the Database Protection tile to open the application. The Databases screen displays the list of existing database connections, if any.

3. Click the overflow icon () corresponding to the desired database connection.

4. Click Delete. A dialog box appears prompting to confirm the action.

5. Click Delete. A message, has been deleted appears on screen.

   The database connection is deleted. The Databases screen displays the available list of database connections.

Managing User Mappings

A user mapping is an association between a database user or a database role, and a local user on the CipherTrust Manager. CDP uses this user mapping to authenticate with the CipherTrust Manager before submitting any cryptographic requests.

When a database user sends a request to the CipherTrust Manager, CDP searches its list of the user mappings (contained in the ING_AUTHORIZED_USER table in the metadata database). If the database user appears on the list or is a member of a mapped database role, CDP includes the associated CipherTrust Manager user and password in the request. If those credentials are valid and the CipherTrust Manager user has access to the required key, then the crypto operation is performed. If the credentials are invalid or the CipherTrust Manager user does not have access to the key, the operation fails.

If a database user, who is a member of a database role mapped to a local user, is also mapped individually to a local user, the individual user mapping takes precedence.

If a database user belongs to multiple database roles, which are mapped to local users, the user inherits the access privileges of the local user mapped to the role that appears first in the alphabetic ascending order.

Some features may need to be enabled for all database users and database roles not otherwise listed on the List of users screen. To do this, the default mapping value should be associated with a specific CipherTrust Manager user. For example, a CipherTrust Manager user with access to global keys can be created, or a CipherTrust Manager user with access to no specific permissions can be created to enable the replacement value feature.

Note

If a user mapping is changed, a new connection must be established with the database for the changes to take effect.

Default Mapping

The default mapping is a catch-all CipherTrust Manager user connected to the CipherTrust Manager when no user mapping exists for a database user. When there is no default mapping and an unmapped database user attempts to access sensitive data, CDP returns an error message and does not send the request to the CipherTrust Manager. It may be useful to create a default mapping to prevent CDP from automatically returning this error.

When this feature is enabled, instead of returning an error message, CDP connects to the CipherTrust Manager as the default CipherTrust Manager user. How the CipherTrust Manager then responds to requests depends on the CipherTrust Manager configuration. The CipherTrust Manager might return following:

• insufficient permissions

• NULL

• Pre–configured replacement value.

• Return encrypted value

(This behavior is configured on the Database Column Properties screen for the encrypted column.)

When the default mapping is assigned, the system creates an entry in the ING_AUTHORIZED_USER table with the user name, ING_DEFAULT_USER. For this reason, avoid using ING_DEFAULT_USER to represent a specific database user.

This section covers the following topics:

• Viewing/Adding User Mappings

• Deleting/Editing User Mapping

Warning

Although the default mapping can be used for both encryption and decryption operations, it is strongly recommended that it should have no key or group permissions. The point of creating a default mapping is to gracefully handle requests for encrypted data from database users who are not authorized to view that data. Granting key or group permissions to the default mapping potentially allows unauthorized database users to view the sensitive data.

Viewing/Adding User Mappings

Viewing User Mappings

To view the list of existing user mappings for an DB2 database connection:

1. Log on to the CipherTrust Manager GUI.

2. Click the Database Protection tile to open the application. The Databases screen displays the list of existing database connections, if any.

3. Open the connection for which you want to view the user mapping.

4. Click the User Mapping link. It displays the existing user mappings for an DB2 database connection.

   

   Note

   Two database connections with different aliases but pointing to the same database IP will display the same list of user mappings.

Adding User Mapping

To add a new user mapping for an DB2 database connection:

1. Open the connection for which you want to add the user mapping.

2. Click the User Mapping link.

3. Click + Add User.

4. On the Map User screen, enter the mapping details:

   Item	Description
   Database User	The database user or role that can be used to connect to the CipherTrust Manager. To create a default mapping, enter ING_DEFAULT_USER in this field. NOTE: The default mapping value applies to all the database users not otherwise listed on the List of users screen. Refer to Managing User Mappings for additional information on default user mapping.
   Local User	Enter the local user to which the database user is to be mapped. (The local user is a CipherTrust Manager user.)
   Local Password	Enter the password for the local user.

5. Click Save. The new user mapping appears on the List of users screen.

Adding User Mapping in Domain

To add a user mapping in a domain:

1. On the List of users screen, click Map User. The Map User screen is displayed.

2. Enter the mapping details. The local user name should include domain name (for example, my-domain||admin) as shown below:

   

3. Click Save. The new user mapping with domain name appears on the List of users screen.

   

   

   Note

   When the CDP client is configured in local mode and the column is encrypted using a versioned key, then ensure that the local user is part of the Key Users group and the key is shared with the Key Users group.

Deleting/Editing User Mapping

Delete an existing user mapping

1. Open the connection for which you want to add the user mapping.

2. Click the User Mapping link. The list of mapped user mappings is displayed on the screen.

3. Click the overflow icon () corresponding to the desired user mapping and click Delete.

Edit an existing user mapping

1. Open the connection for which you want to add the user mapping.

2. Click the User Mapping link. The list of mapped user mappings is displayed on the screen.

3. Click the overflow icon () corresponding to the desired user mapping connection.

4. Click Edit. The Edit Mapped User screen is displayed.

5. Change the Local User and enter its password, if required.

6. Click Save.

Managing Tables

Once a connection between a DB2 database and the CipherTrust Manager is set up, and the user's role is defined, you can perform cryptographic operations on the table and the columns containing the plaintext values.

To perform cryptographic operations:

1. Add a database table

2. Set column-level encryption properties

Adding a Database Table

To add a database table:

1. Log on to the CipherTrust Manager GUI.

2. Click Database Protection to open the application. The Databases screen displays the list of existing database connections, if any.

3. Open the connection for which you want to add tables.

4. Click Tables link. The Tables with Encrypted Columns section is displayed.

   

   Note

   If the credential caching field is not selected when adding a database connection or the database connection is accessed in a new session, you will be prompted to authorize database before accessing the tables.

5. Click Add Table. The Add Table screen is displayed.

   On the Add Table screen, use any of the following options:

   Option 1

   In this option, table is added for the default owner.

   a. Select the table to be encrypted from the available options.

   b. Click Add Table. The table is added to the list.

   Option 2

   a. Change the default owner name.

   b. Click Apply.

   b. Select the table to be encrypted from the available options.

   c. Click Add Table. The table is added to the list.

   You can also manually enter the table name in the Select Table field, if it is not displayed in the drop-down list. The table contains the plaintext values to be encrypted.

Setting Column Level Encryption Properties

To perform migration of a column, set the column-level encryption properties. In this step, select the parameters that are required during the migration process.

To set the column-level encryption properties:

1. Open the table. The list of columns is displayed.

2. Click Set Value corresponding to the column.

   Item	Description
   Name	Displays the new column name. The new column name will be in the format <column>_NEW. As part of the data migration process, the system creates a new column to hold the encrypted data. This field displays the original column. Once the column properties are saved here, do not modify the column name in the database. Discrepancies between the column name in the database and the encryption instructions cause an error. If such an error occurs during the migration, restore the original column name shown in the error message.
   Type	Data type of the column.
   Width	Width of the column, before and after encryption. NOTE: The selected algorithm impacts the column width for the encrypted data.
   Encryption Type	The type of encryption to be performed. The possible values are: • Standard: Encryption without retaining the format of the input data. • FPE: Encryption while retaining the format of the input data.
   Algorithm	Algorithm to be used for encryption. Possible values are: • TDES • ARIA • AES • SEED The CipherTrust Manager supports PKCS5Padding and NoPadding options. PKCS5Padding is used for all block ciphers (SEED, TDES, ARIA, and AES). NOTE: For FPE encryption type, only AES algorithm is applicable.
   Key	Key to be used for encryption and decryption. Only keys that apply the selected algorithm and to which the user has access are available. NOTE: The selected key must be available to the database users that perform the migration. The Key drop-down list displays both versioned and non-versioned keys. NOTE: For FPE, only non-versioned AES keys are used.
   Mode/Cardinality	For Standard encryption, the following options are available when AES, SEED, TDES, or ARIA algorithm is selected: • CBC • ECB It is recommended that you use block ciphers (SEED, TDES, ARIA, and AES) in the CBC mode unless there is a compelling reason to use the ECB mode. CBC is considered to be a more secure mode for a variety of reasons: • ECB’s biggest disadvantage is that for a given key, two identical plaintexts will correspond to an identical ciphertext; whereas, CBC uses the ciphertext of the previous block of plaintext as the initialization vector for the encryption of the next block of plaintext. This succeeds in guaranteeing that two identical plaintext blocks will not result in the same ciphertext. • CBC detects if blocks arrive out of order, which prevents a block switching attack. For format preserving encryption, the following option is available (only AES algorithm is supported for PFE): • CARD10: To encrypt data consisting of digits 0-9. Special characters, including space, if present in input data, are retained as it is. NOTE: For FPE, if the input data has characters other than digits 0-9 and special characters including space during migration, then the invalid input data error will be encountered. Also, if the table is already migrated, then inserting such data will return the invalid input data error.
   IV	Initialization Vector (IV) method. An Initialization vector (IV) is a sequence of random bytes appended at the start of the plaintext before it is encrypted by a block cipher. The IV method is available only for the following algorithms: • AES • TDES • The size of the IV is dependent on the algorithm used Important Notes on IV when performing Standard Encryption • The size of the IV is dependent on the algorithm used. The IV should be specified in the hexadecimal format. For example, an eight-byte IV requires 16 characters and 16-byte IV requires 32 characters. • For DES and DES-EDE algorithm, IV must be of eight-bytes. • For AES algorithm, IV must be of 16-bytes. • IV is only supported for CBC mode. For ECB mode, IV is not supported. Using an IV eliminates the possibility that the initial ciphertext block will be the same for any two encryption operations, which use the same key. You can apply IVs at the field-level or column-level. Once the encryption is done, the IV field on the Database Column Properties screen displays the IV used.
   Padding	Padding mode to be used when encrypting the column. The default value is PKCS5Padding. NOTE:Not applicable for FPE encryption.
   FPE Encryption Format	The formats the user may use to determine the structure of the output. Following formats are supported for FPE: • NONE - No format is applied with FPE. In this case, complete plaintext will be considered as an input for crypto operation. • FIRST_SIX - This format allows the user to keep intact the first six digits of the plaintext input. So, after encryption, the first six digits of the output ciphertext will remain same as input plaintext and rest digits will be encrypted using FPE. • FIRST_SIX_LAST_FOUR - This format allows the user to keep intact the first six and last four digits of the plaintext input. So, after encryption the first six and last four digits of the output ciphertext will remain same as input plaintext and rest digits will be encrypted using FPE. • FIRST_TWO_LAST_FOUR - This format allows the user to keep intact the first two and last four digits of the plaintext input. So, after encryption the first two and last four digits of the output ciphertext will remain same as input plaintext and rest digits will be encrypted using FPE. • LAST_FOUR - This format allows the user to keep intact the last four digits of the plaintext input. So, after encryption the last four digits of the output ciphertext will remain same as input plaintext and rest digits will be encrypted using FPE. NOTE: The effective data length (excluding special characters) of input plaintext to be encrypted must be greater than the selected format. For example, for FIRST_SIX format, if the input plaintext is 12345678@#, then encryption will be performed on 78 after retaining the first six characters and the special characters @#. Suppose the input plaintext was 12345@#, then the encryption will not be performed on this, as the effective data to be encrypted is less than six even though the input plaintext has seven characters.
   Tweak Algorithm	The hashing algorithm to be applied to specified tweak data in case of FPE. Select from the available options: • NONE • SHA1 • SHA256 If NONE is selected in the FPE Encryption Format field, then NONE, SHA1, and SHA256 options are available for Tweak Algorithm. If any encryption format is selected, then only SHA1 and SHA256 options are available. Enter the tweak data for the selected Tweak Algorithm in the text field. Tweak data is an ASCII string of maximum 256 characters. It accepts any ASCII value for SHA1 and SHA256 and any valid hex encoded value for “NONE” like “1111111111111111”.
   Attributes	Displays the attributes applied to the column that is being configured for encryption, such as nullable. Some attributes, such as nullable, will not prevent the encryption of a column; other attributes, such as foreign key, will prevent encryption. Some attributes, such as primary key should be considered very carefully because it is possible that the key is referenced implicitly as a foreign key.
   Decryption Behavior of users with Insufficient Permissions	The value the system returns when a user with insufficient access permissions attempts to query the database. Available options are: • Return with "insufficient permissions" error - Unauthorized requests return an error. • Return NULL - Returns a NULL value when unauthorized requests are made in this column. The query executes without generating an error, and the value returned for the decrypted column is NULL. • Return replacement value - Selecting this option allows specifying the value that is returned when a user makes an unauthorized attempt to decrypt the data in this column. The specified value must be a valid value for the data type and length of the column being configured. A query by an unauthorized user will return successfully, and the specified value will be returned in place of the actual decrypted value. • Return encrypted value - Returns the encrypted value when a user makes an unauthorized attempt to decrypt the data in this column. This option is applicable for FPE encryption only. NOTE: Replacement values are not returned if a query yields a NULL value. When a query results in a NULL value, no cryptographic process is required, so CDP does not interact with the CipherTrust Manager and the replacement values feature is not activated. NOTE: An invalid user is one that is mapped to any group which do not have permission on the key and also the user is not part of Key Admins group (it is a system defined group). For such an invalid user only, the error replacement behavior is applicable.

3. Click Save to save the column properties values. (Clicking Cancel returns you to the List of columns screen.)

   

   Note

   Once the encryption properties for a column are saved, these can be edited on the List of columns screen.

After configuring the encryption properties for a column, you can now perform tasks such as encryption, decryption, and delete old data. Refer to tasks for details. These tasks can also be performed using the pdbctl utility. Refer to pdbctl Utility documentation for details.

Note

The rekey operation can only be performed through the pdbctl utility.