profiles.conf

To streamline the invocation of the encrypt_cbc(), decrypt_cbc(), encrypt_fpe(), decrypt_fpe(), encrypt_ff1(), and decrypt_ff1() UDFs, the file profiles.conf is used. This file contains named profiles that include several values required as input to these UDFs. Provide the profile name as a parameter when invoking the UDF. The UDF looks up the profile name and uses the parameters that are grouped under that profile name.

An example file named profiles.conf.sample is provided with the installation software. Make your own copy of this file and change the name to profiles.conf.

Be sure to set the file permissions for profiles.conf appropriately. The file should be owned by the root user, who can create and edit the file. Other users should be able to view the file, so they can see the profile names to reference them in their own UDF calls. It is not recommended to allow users other than root to edit profiles.conf. Set the file permissions to 644.

Using profiles.conf with Unicode Block Cipher UDFs

Profiles that are to be used with the UDFs encrypt_cbc() and decrypt_cbc() must contain the following key-value pairs:

method = aes_cbc_pad
iv = Initialization Vector Number
keyname = Name of the CipherTrustthales encryption key to use

The following is a sample profiles.conf file that contains two profiles named ccnum and address:

[ccnum]
method = aes_cbc_pad
iv = 000102030405060708090A0B0C0D0E0F
keyname = KEY_1
[address]
method = aes_cbc_pad
iv = 0F0E0D0C0B0A09080706050403020100
keyname = KEY_1

With these profile definitions, the following UDF calls can be made:

encrypt_cbc('1234-9876-5678-6543', 'ccnum')
encrypt_cbc('2860 Junction Avenue, San Jose, CA 95134', 'address')

Using profiles.conf with FPE

Profiles that are to be used with the UDFs encrypt_fpe() and decrypt_fpe() must contain the following key-value pairs:

method = fpe
tweak = 8-byte tweak | auto
charset = One of the values specified in [character_sets]
keyname = Name of the thales encryption key to use

If tweak is set to auto, the tweak is generated automatically for you.

In the [character_sets] section of profiles.conf, specify one or more named character sets which can be used to tokenize the cleartext input. Define each character set as one or more comma-separated Unicode ranges in UTF16 Big Endian format. In charset, provide one of the names from this section.

Also, note that FPE-related UDFs can optionally set the parameter allowSingleCharInputs to yes to permit passing through any NULL or single-character input without encrypting it, while the remaining data are encrypted as expected.

Example

The following is a sample profiles.conf file for use with encrypt_fpe() and decrypt_fpe(). It defines several character sets, including a Latin character set, and two profiles named tokenize_name and tokenize_address.

[character_sets]
latin = 0020-007E
alphanumeric = 0030-0039,0041-005A,0061-007A
hindi = 0905-0939,0958-0961
custom = 0905-0939,0030-0039
[tokenize_name]
method = fpe
tweak = D8E7920AFA330A73
charset = latin
keyname = KEY_FPE_1
[tokenize_address]
method = fpe
tweak = auto
charset = alphanumeric
keyname = KEY_FPE_1

With these profile definitions, the following UDF calls can be made:

encrypt_fpe('John Doe', 'tokenize_name')
encrypt_fpe('2860 Junction Avenue, San Jose, CA 95134', 'tokenize_address')

Using profiles.conf with FF1

Profiles that are to be used with the UDFs encrypt_ff1() and decrypt_ff1() must contain the following key-value pairs:

method = ff1 | ff1v2
tweak = 8-byte tweak | auto
charset = One of the values specified in [character_sets]
keyname = Name of the CipherTrust encryption key to use

Specify in method whether the method is FF1 (ff1) or FF1 version2 (ff1v2).

If tweak is set to auto, the tweak is generated automatically for you.

In the [character_sets] section of profiles.conf, specify one or more named character sets which can be used to tokenize the cleartext input. Define each character set as one or more comma-separated Unicode ranges in UTF16 Big Endian format. In charset, provide one of the names from this section.

Also, note that FF1-related UDFs can optionally set the parameter allowSingleCharInputs to yes to permit passing through any NULL or single-character input without encrypting it, while the remaining data are encrypted as expected.

Example

The following is a sample profiles.conf file for use with encrypt_ff1() and decrypt_ff1(). It defines several character sets, including a Latin character set, and three profiles named tokenize_name, tokenize_address, and tokenize_address_fips.

[character_sets]
latin = 0020-007E
alphanumeric = 0030-0039,0041-005A,0061-007A
hindi = 0905-0939,0958-0961
custom = 0905-0939,0030-0039
[tokenize_name]
method = ff1
tweak = D8E7920AFA330A73
charset = latin
keyname = KEY_FF1_1
[tokenize_address]
method = ff1
tweak = auto
charset = alphanumeric
keyname = KEY_FF1_1
[tokenize_address_fips]
method = ff1v2
tweak = auto
charset = alphanumeric
keyname = KEY_FF1v2_1

With these profile definitions, the following UDF calls can be made:

encrypt_ff1('John Doe', 'tokenize_name')
encrypt_ff1('2125 Zanker Avenue, San Jose, CA 95131', 'tokenize_address')
encrypt_ff1('1234 Main Street, Anytown, CA 55555', 'tokenize_address_fips')

Migration from old FF1 Algorithm to the new FF1 FIPS Algorithm

To migrate from an old FF1 algorithm to the new FIPS-compliant FF1 algorithm:

1. Decrypt previously encrypted columns using the old algorithm.

2. Modify the existing FF1 profiles method name with method=ff1v2 inside the profiles.conf file.

3. Re-encrypt columns using the new algorithm.

Migration is completed.

Allowing Single Character or NULL Inputs

Untranslatable character errors sometimes occur when passing in data to FPE or FF1-related UDFs that include NULL values or values with insufficient characters to encrypt. You can avoid this error by using the configuration parameter allowSingleCharInputs.

When you set the parameter allowSingleCharInputs to yes in the profiles.conf file, CTP passes through any NULL or single-character input without encrypting it, while the remaining data are encrypted as expected.

Versioned Keys

Versioned keys can be used in both normal and fast modes, when CTP is configured with the CipherTrust Manager (CM) key manager.

To use a versioned key, first create the versioned key on the CM key manager, making sure to select the set as versioned key for backwards compatibility option. CTP automatically performs the encrypt/decrypt operations, based on the versioned key validation.