Configuring SQL Server Databases

Before data can be migrated, CipherTrust Database Protection for SQL Server 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 SQL Server client.

Managing Database Connection

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

Creating a SQL Server Database Connection

To create a SQL Server database connection:

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. Click + Database and select SQL Server from the available options. The SQL Server Database Configuration page is displayed.

4. Enter the Connection Information details in the respective fields.

   

   The following table lists the parameters that are required when creating or managing a SQL Server database connection.

   Item	Description
   Name (Alias)	Enter a name for the connection information. This field uniquely identifies a database connection.
   Host	Enter the IP address of the database server.
   Connect With	The possible values are: • Port Number: If SQL Server is connected with the CipherTrust Manager using a fixed port. •Instance Name: If SQL Server is connected with the CipherTrust Manager using dynamic ports.
   Port Number/Instance Name	Enter the port number or the instance name. The default port is 1433. If the Instance name is used to connect the SQL Server with the CipherTrust Manager, enter the instance name of the SQL Server that you want to connect to the CipherTrust Manager.
   Database User Name	Enter the database user 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	Enter the password for the database user.
   MetaDatabase User Name	Enter the database user name that has permission to connect to the CDP metadata. This login is usually sa, the user that you specified in the Database User Name field on the SQL Server Database Configuration screen. To modify metadata tables and call extended stored procedures, the metadatabase user must have the sysadmin privileges.
   MetaDatabase User Password	Enter the 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.
   Database Name	Enter the name for the database that contains the tables and columns to encrypt.
   Meta-Database Name	Enter the name for the database where CDP metadata is installed.
   Schema Name	Enter the name associated with the database. To encrypt the tables owned by the schema other than dbo, enter the schema name. This field is optional. If you do not specify any schema name, dbo will act as the default schema.
   Enter Description	Enter description for the database. This field is optional.

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

6. 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 Database Protection 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

   • Connect With

   • Port Number/Instance Name

   • Database User Name

   • Database User Password

   • MetaDatabase User Name

   • MetaDatabase User Password

   • Enable Credential Caching

   • Database Name

   • Meta-Database Name

   • Schema Name

   • Description

6. Click Save to save the new configuration. 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 Database Protection 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.

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.

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

Viewing/Adding User Mappings

Viewing User Mappings

To view the list of existing user mappings for a SQL Server database connection:

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. Click the overflow icon () corresponding to the desired database connection.

   

4. Click Manage User Mapping. The List of users screen is displayed. It displays the existing user mappings for a DB2 database connection.

   

Adding User Mapping

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

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

   

2. 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.

3. 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.

   

Deleting/Editing User Mapping

To delete or edit an existing user mapping:

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. Click the overflow icon () corresponding to the desired database connection.

   

4. Click Manage User Mapping. The List of users screen is displayed. It displays the list of existing user mappings for a SQL Server database connection.

   

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

   

6. (Optional) Click Delete. Skip this step if you do not want to delete an existing user mapping.

7. Confirm the delete operation when prompted. The user mapping is deleted from the List of users screen.

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

   

9. Click Edit. The Edit User Mapping screen is displayed.

   

10. Change the Local User and enter its password.

11. Click Save.

The user mapping is updated on the List of users screen.

Managing Tables

After a connection between a SQL Server 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. Click the overflow icon () corresponding to the desired database connection.

   

4. Click Manage Tables. The List of tables screen is displayed.

   

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

   

   On the Add Table screen, use one of the options:

   a. Select the table for the schema used in add connection.

   b. Change Schema Name.

   • Enter Schema Name and click Change Owner.

   • Select table from the drop-down list and click Save.

   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.

   The List of columns screen is displayed. The screen displays the list of available columns in the table with the column details, such as data type, width, and attributes of the column.

   

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. Select the column for which you want to set the column-level encryption properties. The Database Column Properties screen is displayed.

   

2. Enter the encryption properties for the column. The following table lists the parameters that are required when setting column-level encryption properties.

   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 over the ECB 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 available options are: • CARD10: To encrypt data consisting of digits 0-9. • CARD62: To encrypt data consisting of digits 0-9, lowercase alphabets (a-z), and uppercase alphabets (A-Z). NOTE: • When NONE is selected in the FPE Encryption Format field, then the alphabets, special characters, and extended characters if present in the input data are retained as it is in the local mode. For remote mode, encryption is not supported for such cases. • CARD62 is supported only in the local mode. Special characters and extended characters, if present in the input data are retained as it is. FPE formats are not supported for CARD62.
   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. Important Notes on IV when performing FPE Encryption • FPE accepts a HEX encoded MAXb integer. IV is always provided but is used only if the length of data exceeds MAXb (block size: 56 bytes for CARD10 and 32 bytes for CARD62). FPE breaks long data into MAXb integer blocks and uses block chaining algorithm similar to CBC mode to perform encryption. — a 56 bytes IV in hex encoded form having a cardinality 10 when data size is > 56 bytes — A valid value of IV for FPE can be a 112 characters hex encoded s-integers (0-9) 0401030003040604090301030705 0205050305070401080801020207 0402070201030407040009010502 0603000002020906070004010200 — A valid value of IV can be a 64 characters hex encoded s-integers (0-9) 0401030003040604090301030705 0205050305070401080801020207 04020702
   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. CARD62 does not support this option. CARD10 supports this option only for non-CHAR data types. • Return replacement value - Allows you to specify the value that is returned when a user makes an unauthorized attempt to decrypt the data in this column. The value that you specify 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. CARD62 does not support this option. CARD10 supports this error replacement option only when NONE is selected in the FPE Encryption Format field. • Return encrypted value - Returns the encrypted value when a user makes an unauthorized attempt to decrypt the data in this column. This option is available for FPE encryption only. For CARD62, this option is supported only for CHAR data type family. NOTE: It is not recommended to set Return encrypted value option as error replacement for integer data type, as the returned encrypted value may exceed the maximum limit value applicable for the integer data type and error replacement will not work. 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. The error replacement values feature requires that the CDP settings are identical on all cluster members.

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

Operations Using pdbctl Utility

After the column-level encryption properties are set, you can perform migration using the pdbctl utility.

Migrating data using the pdbctl utility includes the following steps:

1. Adding a database connection.

   ./pdbctl adddb -a <demoalias> -u <database_user> -d <database_name> -p <database_password> -t SQLServer -i <10.1.1.1> -m <meta_user_password> -o <port> -b <naeuser> -c <naepassword>
   

   Note

   Here, naeuser corresponds to the CipherTrust Manager local user. The user should have the encryption/decryption permission on the key used for configuring encryption properties for the column

2. Migrating the data.

   ./pdbctl migrate -a <database_alias> -t <table_name>
   

For more information on the pdbctl utility, refer to the pdbctl Utility User Guide.