Encrypting Data

About Encrypting Data

You can encrypt fields that contain sensitive customer information, such as credit card numbers, to guarantee privacy and prevent unauthorized use. The fields to be encrypted must be in string format. You set up encryption with the Storable Class Editor, which will add a flag attribute in the metadata defining the field in the data dictionary (PIN_FLD_ENCRYPTABLE).

BRM encrypts the fields marked for encryption when storing them in the database and automatically decrypts the fields when retrieving them from the database. For information on how to encrypt fields, see "Encrypting Fields".

You can also encrypt passwords, including the database password and passwords for servers and client applications that connect to the Connection Manager (CM) to access the database. For information, see "About Encrypting Passwords".

About AES Encryption

Note:

The AES encryption method is supported only on systems that have upgraded from BRM 7.5 to BRM 12.0 Patch Set 3 or later.

AES uses a 256-bit encrypted key to protect field data. To set up the database for AES encryption, you:

Generate an encrypted AES key and add it to the Data Manager (DM) pin.conf file with other encryption configuration information. You can have only one encrypted AES key per Oracle DM.

The encrypted AES key gets stored in the database.
Define which fields should be encrypted by setting their PIN_FLD_ENCRYPTABLE flag in Storable Class Editor.

When the Oracle DM starts, it uses the encrypted AES key to transform the fields marked as encryptable from plaintext into ciphertext and from ciphertext into plaintext.

In addition to encrypting data fields, you can use AES to encrypt passwords for these feature:

BRM Data Managers
Pipeline database
Optional managers, such as Account Synchronization Manager
Client applications

About AES Data Encryption Length

The length of AES-encrypted data is different depending on whether the data is stored in the database or not. In both cases, encrypting a field increases its length.

Note:

The maximum length of an encrypted field in the Oracle database is 1,992 bytes, which is 975 bytes in plaintext.

Encryption Length for Fields Stored in the Database

When the AES encryption scheme is used to store database fields, the generated ciphertext is in this format:

&aes|Encrypted_AES_key_index|Ciphertext

where:

aes identifies the encryption scheme used by the database.
Encrypted_AES_key_index is a unique 4-digit ID associated with the encrypted AES key.
Ciphertext is the encrypted data generated from the plaintext data by using the AES key.

The length of the generated ciphertext data is:

(Plaintext_data_length + 16) * 2 + 5 + 5

Two hexadecimal numbers represent each byte in the ciphertext, &aes | is equal to 5 bytes, and Encrypted_AES_key_index is equal to 5 bytes. For example, if Plaintext_data_length is 25, the length of the generated ciphertext data is 92:

(25+16)*2+5+5 = 92

Note:

If Plaintext_data_length is less than 17, the length of the generated ciphertext data is always 79.

Encryption Length for Fields Not Stored in the Database

When the AES encryption scheme is used to encrypt data that is not stored in the database, such as passwords, the generated ciphertext is in this format:

&aes|Ciphertext

where:

aes identifies the encryption scheme used by the database.
Ciphertext is the encrypted data generated from the plaintext data by using the AES key.

The length of the generated ciphertext data is:

(Plaintext_data_length + 16) * 2 + 5

A hexadecimal number represents each byte in the ciphertext, and &aes | is equal to 5 bytes. For example, if Plaintext_data_length is 25, the generated ciphertext data is 87:

(25+16)*2+5 = 87

Note:

If Plaintext_data_length is less than 17, the length of the generated ciphertext data is always 74.

Generating an Encrypted AES Key

An encrypted AES key is used by the DM to encrypt the database fields that are marked as encryptable.

To generate an encrypted AES key:

Run the pin_crypt_app utility:
```
pin_crypt_app -genkey -key AES_key
```
If you do not have an AES key, run the utility with only the -genkey parameter. This generates a random AES key internally and then encrypts it with a hidden key to create the encrypted AES key. The key length must be 64 and can contain only hexadecimal numbers.

The output states whether the key was generated successfully, and if so, provides the encrypted AES key.
Write down the encrypted AES key value or copy it to a text editor. Include the &aes| because it is part of the encrypted key.
Add the encrypted AES key value to the crypt entry in the DM pin.conf file.

You can have only one encrypted AES key per Oracle DM.

Replacing an Encrypted AES Key

You can replace an encrypted AES key with a new key at any time. This does not affect how data is decrypted; the DM can decrypt data encrypted with a previous key.

This procedure assumes you have already configured the DM for AES encryption. See "Configuring the Data Manager for AES Encryption".

To replace an encrypted AES key:

Generate a new encrypted AES key. See "Generating an Encrypted AES Key".
Open the DM pin.conf file.
In the crypt aes entry, replace the existing encrypted AES key with the new encrypted AES key:
```
- crypt aes|BRM_home/lib/libpin_crypt_aes4dm.so "&aes|New_encrypted_aes_key"
```
Save the file.
Stop and restart the DM.

About Masking Data in Log Files

Currently, fields defined as encryptable are encrypted by the DM when they are stored in the database and decrypted when they are retrieved. Data passed through the CM by opcodes and data in the client applications is in plaintext. Therefore, when BRM opcodes are called and high log levels are set on flist operations, the contents of the encryptable fields are saved to a log file. The fields may contain sensitive data that is defined as encryptable but still appears in plaintext. To hide this information, you can define a field as masked. The masked data will be displayed as "XXXX" in the log files rather than as plaintext.

For information on how to mask encrypted fields during flist logging, see "Defining Masked Fields".

Encrypting Fields

You mark fields for encryption by using the Storable Class Editor. You can enable new or existing object fields for encryption at any time.

Note:

You can disable encryption for a field at any time; however, it is recommended that you only do so during upgrades.
Make sure the field is in string format. Only strings may be encrypted.

Defining Masked Fields

You can mask BRM fields and custom fields.

To define masked fields:

Create a custom file for your masked fields, and define the fields in this file. Use the following syntax:
```
Custom_field_name masked
```
For example, you might create a file named custom_field_attributes that contains the following mask definitions:
```
CUST_FLD_CC_NUMBER masked
CUST_FLD_EXPIRY_DATE masked
```
Generate the source file for your custom fields. By default, this file is called custom_fields.h.
Copy the contents of both files (the custom masked file and the source file) to a new file. For example, name the new file custom_masked_fields.
Run the parse_custom_ops_fields Perl script, and use the custom masked fields file as the input:
```
parse_custom_ops_fields -L language -I input -O output -P java_package
```
For applications written with PCM C, add the following entry to the pin.conf file for each PCM C application:
```
- - ops_fields_extension_file ops_flds_ext
```
For applications written using Java PCM, including Developer Center, copy the contents of the InfranetPropertiesAdditions.properties file and paste it in the Infranet.properties files for each Java application.

For more information about field masking, see "About Masking Data in Log Files".

About Encrypting Passwords

You can encrypt passwords for the BRM database, optional managers such as GSM Manager, server applications, and client applications that use a password to connect to the CM.

These passwords can be encrypted manually (one at a time) by running the pin_crypt_app utility or automatically (all at one time) by running the encryptpassword.pl script.

Note:

You must use the pin_crypt_app utility to encrypt client application passwords or passwords associated with customizations (for example, custom passwords in BRM-provided configuration files or passwords in non-BRM configuration files that support custom applications).

For information on the encryptpassword.pl script, see "About the encryptpassword.pl Script".

For information about configuring client applications to connect to the CM without a password, see "Using CM Proxy to Allow Unauthenticated Log On" in BRM System Administrator's Guide.

To customize password encryption, use the PCM_OP_CUST_POL_ENCRYPT_PASSWD, PCM_OP_CUST_POL_COMPARE_PASSWD, and PCM_OP_CUST_POL_DECRYPT_PASSWD opcodes. See BRM Opcode Guide.

Note:

When you change a password, it is not automatically encrypted. You must encrypt the new password and update the entry in the appropriate configuration file.

About the encryptpassword.pl Script

You run the encryptpassword.pl script to encrypt the passwords for all BRM components at one time, including the Oracle DM password. BRM authenticates these passwords before connecting to the CM or to the BRM database.

Note:

This script does not encrypt passwords for client applications or optional managers that are not part of base BRM. In addition, it does not encrypt passwords associated with customizations; for example, custom passwords in BRM-provided configuration files or passwords in non-BRM configuration files that support custom applications. To encrypt such passwords, run the pin_crypt_app utility.

The encryptpassword.pl script has no parameters. You run it from the UNIX prompt on the system running the BRM database by entering the following command:

perl encryptpassword.pl

This script performs the following tasks on the machine on which it runs:

Creates a back up copy of all pin.conf and Infranet.properties configuration files in which it finds a password.
Replaces the plaintext password in each configuration file with an encrypted password.
Adds all encrypted passwords to the pin_setup.values file.
Adds the ENABLE_ENCRYPTION entry with a YES value to the pin_setup.values file. This field enables password encryption.

Encrypting Passwords Automatically for BRM Base Components

To encrypt passwords for all BRM base components at one time:

Log into the system running the BRM database.
Go to the BRM_home/setup/scripts directory.
Run the encryptpassword.pl script:
```
perl encryptpassword.pl
```
Follow the instructions at each prompt.

Passwords are encrypted in the OZT format.

Note:

If you are running optional managers or server applications on a system that does not contain the BRM database, run the encryptpassword.pl script on each applicable system.
If you change an encrypted password, you must update the entry in the configuration file and the pin_setup.values file.

For more information on the encryptpassword.pl script, see "About the encryptpassword.pl Script".

Encrypting Passwords Manually with OZT

To encrypt passwords manually with OZT:

Log in to the system running the BRM manager.

Note:

For data managers, this is generally the system running the BRM database; for client applications, it is the application host system.
Run the pin_crypt_app utility with the -useZT parameter:
```
pin_crypt_app -useZT -enc
```
At the prompt, enter the plaintext password to encrypt and then re-enter it again.

The output is the OZT-encrypted password.
Write down the encrypted password or copy it to a text editor.

Note:

When you change a password, it is not automatically encrypted. You must encrypt the new password and update the entry in the appropriate configuration file.

To set this password as the Oracle DM password or an optional manager password, add the password to the manager's pin.conf file. See "Configuring the Data Manager for Oracle ZT PKI Encryption".

To set this password as the CM password for a client application, add the password to the application's pin.conf file and to the Infranet.properties file. By default, the Infranet.properties file is located in C:\Program Files\Common Files\Portal Software.

Encrypting Passwords Manually with AES

To encrypt passwords manually with AES:

Log in to the system running the BRM manager.

Note:

For data managers, this is generally the system running the BRM database. For client applications, it is the application host system.
Run this command to transform a plaintext password into ciphertext:
```
pin_crypt_app -enc
```
At the Enter the plaintext to encrypt prompt, enter your plaintext password.
Re-enter your plaintext password.

The output is the AES-encrypted password.
Write down the encrypted password or copy it to a text editor.

To set this password as the Oracle DM password or an optional manager password, add the password to the manager's pin.conf file. See "Configuring the Data Manager for AES Encryption".

To set this password as the Pipeline Manager password, add the password to the DataPool section of the Pipeline startup registry file.

To set this password as the CM password for a client application, add the password to the application's pin.conf file and to the Infranet.properties file.

Generating a Root Encryption Key

The root encryption key is used for encrypting the data and password using the Oracle ZT PKI–approved encryption algorithm.

To generate a root encryption key:

Go to BRM_home/bin.
Run the following command, which creates a root key wallet:
```
orapki wallet create -wallet wallet_location -pwd password
```
where:
- wallet_location is the directory in which the root key wallet is to be created.
- password is the password used to make changes to the root key wallet.
Run the following command:
```
pin_crypt_app -genrootkey
```
A root encryption key is generated and is stored in the root key wallet.

Note:

The root key wallet is generated at only one location. You can copy the root key wallet to the other locations.

Configuring the Data Manager for AES Encryption

The Oracle DM configuration file (pin.conf) specifies the user name and password needed to log in to the BRM database as well as the encryption method to use for data stored in the BRM database.

To configure the Oracle DM for AES encryption:

If necessary, generate an encrypted AES key and an AES encrypted password. See "Generating an Encrypted AES Key" and "Encrypting Passwords Manually with AES".
Open the BRM_home/sys/dm_oracle/pin.conf file in a text editor.
Add the AES encrypted password for logging in to your BRM database to the sm_pw entry:
```
- dm sm_pw Encrypted_password
```
The password can use any character from the US7ASCII character set except for the hash character (#). BRM interprets the hash character as a comment and will ignore any subsequent characters in the password.
Set AES as the encryption method for your data by using the crypt entry:
```
- crypt aes|Encryption_library "&aes|Encrypted_aes_key"
```
where:
- Encryption_library is the path and filename of the AES encryption library (pin_crypt_aes4dm). The prefix for the library is lib for Solaris and Linux, or null "" for Windows. The extension for the library is .so for Solaris and Linux, and .dll for Windows.
- Encrypted_aes_key is your encrypted AES key. See "Generating an Encrypted AES Key".
Save the file.
Stop and restart the DM.

Configuring the Data Manager for Oracle ZT PKI Encryption

The Oracle ZT public key infrastructure (PKI) encryption algorithm uses the pin_crypt_app and pin_config_editor utilities to encrypt files, plain text, passwords, and root keys.

The Oracle DM configuration file (pin.conf) specifies encryption settings for the database.

To configure the Oracle DM to use OZT encryption:

If necessary, generate an OZT encrypted password. See "Encrypting Passwords Manually with OZT".
Run the following command to generate an encrypted Oracle ZT PKI key:
```
pin_crypt_app -useZT genkey [-key Key]
```
where Key is a 256-bit key in hexadecimal notation.
Write down the encrypted Oracle ZT PKI key value, or copy it to a text editor.

Note:

Include &ozt| because it is part of the encrypted Oracle ZT PKI key value.
Go to BRM_home/sys/dm_oracle.
Open the Oracle DM pin.conf file in a text editor.
Enable the Oracle ZT PKI encryption algorithm by adding the following entry:
```
- crypt ozt|Encryption_library "&ozt|Encrypted_key"
```
where
- Encryption_library is the path and filename of the OZT encryption library (pin_crypt_ozt4dm64). The prefix for the library is lib for Solaris and Linux, or null "" for Windows. The extension for the library is .so for Solaris and Linux, and .dll for Windows.
- Encrypted_key is the OZT encrypted key that you generated in step 2.
Save the file.
Stop and restart the Oracle DM.

Generating a Root Encryption Key

The root encryption key is used for encrypting the data and password using the Oracle ZT PKI–approved encryption algorithm.

To generate a root encryption key:

Go to BRM_home/bin.
Run the following command, which creates a root key wallet:
```
orapki wallet create -wallet wallet_location -pwd password
```
where:
- wallet_location is the directory in which the root key wallet is to be created.
- password is the password used to make changes to the root key wallet.
Run the following command:
```
pin_crypt_app -genrootkey
```
A root encryption key is generated and is stored in the root key wallet.

Note:

The root key wallet is generated at only one location. You can copy the root key wallet to the other locations.

Modifying a Root Encryption Key

Before you modify the root encryption key, do the following:

Back up the CRYPTKEY_T table in the BRM database. See your database documentation for more information on performing database table backups.
Back up the root key wallet in which the existing root encryption key is stored.

Note:

Store the backup in a safe location. The data in the backed up CRYPTKEY_T table and the root key wallet will become necessary if you encounter any issues in modifying the root encryption key.
The data keys in the CRYPTKEY_T table should be in synchronization for all schemas while modifying the root encryption key.

Modifying the Root Encryption Key on Single-Schema Systems

To modify the root encryption key on single-schema systems:

Go to the BRM_home/sys/test directory.
Run this command:
```
pin_crypt_app -genrootkey
```
A new root encryption key is generated and the existing root encryption key in the root key wallet is updated with the new root encryption key. The utility re-encrypts the data keys in the CRYPTKEY_T table with the new root encryption key.

Modifying the Root Encryption Key on Multischema Systems

To modify the root encryption key on multischema systems:

On each secondary installation machine, run the following commands which grant permissions on the CRYPTKEY_T table in that secondary schema to the primary schema:
```
sqlplus login@database_alias
Enter password: password

SQL>GRANT ALL ON CRYPTKEY_T TO schema_name;
SQL>exit
```
where:
- login is the user name for the database schema you are updating.
- password is the password for login.
- database_alias is the BRM database alias of the secondary schema you are updating.
- schema_name is the name of the primary schema.
On the primary installation machine, do the following:
1. Go to the BRM_home/sys/test directory.
2. Run the following command:
```
pin_crypt_app -genrootkey
```
  A new root encryption key is generated and the existing root encryption key in the root key wallet is updated with the new root encryption key. The utility re-encrypts the data keys in the CRYPTKEY_T table with the new root encryption key for all the secondary schemas.

After the root encryption key is modified, ensure that both the primary and secondary schemas can access the root key wallet in which the new root encryption key is stored.