12 Customizing Information Stored in the Database

This chapter explains how to customize information stored in the Oracle Communications Billing and Revenue Management (BRM) database by tracking changes to specific object fields and by encrypting specific object fields.

About Tracking Changes to Object Fields

You can enable fields in objects to trigger an audit trail when they are modified. This allows you to track many changes to the BRM system. For information on why you enable an audit trail, see "About Maintaining an Audit Trail of BRM Activity" in BRM Managing Customers.

Audit Trail Architecture

You enable audit trails for an individual field, but the entire object that contains the field is versioned and stored to ensure consistency with other members of the object class. When fields marked for auditing are created or modified, copies are made of the top-level object class to which the field belongs as well as that object's subclasses. The audit trail is composed of the versioned and stored object copies, which are called shadow objects. It is created at the end of a transaction, prior to transaction commit.

For example, if a field marked for auditing in the /payinfo/cc object is modified in the first, fifth, seventh, and eighth revision of the original object, the shadow objects shown in Figure 12-1 are created in the audit trail:

Figure 12-1 /payinfo/cc Shadow Objects

Description of ''Figure 12-1 /payinfo/cc Shadow Objects''

The revision number is the revision number of the object's Portal object ID (POID).

When you mark a field for auditing, the Storable Class Editor calls the PCM_OP_SDK_SET_DD opcode. This opcode creates a shadow class for the top-level class in which the auditable field is modified and for all of that class's subclasses.

The auditability of a field is specified in the PIN_FLD_AUDITABLE meta-level field in the data dictionary. The value 1 (AUDIT_ENABLED) indicates the field is marked for auditing, and the value 0 (AUDIT_DISABLED) indicates the field is not marked for auditing.

The following example shows the input flist of the PCM_OP_SDK_SET_DD opcode after the PIN_FLD_DEBIT_NUM field is marked for auditing in the /payinfo/cc object class. The PIN_FLD_AUDITABLE meta-level field is set to 1, which indicates that the PIN_FLD_DEBIT_NUM field is marked for auditing.

0 PIN_FLD_OBJ_DESC      ARRAY [133] allocated 20, used 4
1     PIN_FLD_NAME            STR [0] "/payinfo/cc"
1     PIN_FLD_DESCR           STR [0] "Credit Card payment
                                       information class."
1     PIN_FLD_OBJ_ELEM      ARRAY [0] allocated 20, used 14
2         PIN_FLD_FIELD_TYPE      INT [0] 9
2         PIN_FLD_FIELD_NAME      STR [0] "PIN_FLD_CC_INFO"
2         PIN_FLD_DESCR           STR [0] "Array to hold the
                                           credit card specific
                                           information. There
                                           can be only one
                                           array element. The
                                           array element id is not
                                           significant."
2         PIN_FLD_ORDER           NUM [0] 0.000000
2         PIN_FLD_OBJ_ELEM      ARRAY [0] allocated 20, used 8
3             PIN_FLD_FIELD_TYPE      INT [0] 5
3             PIN_FLD_FIELD_NAME      STR [0] "PIN_FLD_ADDRESS"
...
...
2         PIN_FLD_OBJ_ELEM      ARRAY [4] allocated 20, used 8
3             PIN_FLD_FIELD_TYPE      INT [0] 5
3             PIN_FLD_FIELD_NAME      STR [0] "PIN_FLD_DEBIT_NUM"
3             PIN_FLD_DESCR           STR [0] "Credit card
                                               number."
3             PIN_FLD_ORDER           NUM [0] 0.000000
3             PIN_FLD_LENGTH          INT [0] 30
3             PIN_FLD_AUDITABLE    INT [0] 1
3             PIN_FLD_CREATE_PERMISSION    STR [0] "Required"
3             PIN_FLD_MOD_PERMISSION    STR [0] "Writeable"
3             PIN_FLD_SM_ITEM_NAME    STR [0] "debit_num"
...
...

After a shadow class is created, it is not deleted even if auditing is disabled later. For example, if you disable auditing for the PIN_FLD_DEBIT_NUM field in the /payinfo/cc object, the existing audit trail for that field is retained and accessible to you if you need it.

About Shadow Objects

Shadow objects use an au prefix. For example, a change to a field marked for auditing in the /payinfo/cc object results in the following shadow objects: /au_payinfo, /au_payinfo/cc, /au_payinfo/inv, /au_payinfo/subord, and so on. The shadow object is a replica of the original object, so it stores the POID the object had when auditing occurred. The unique revision number of the POID is used to extract audit trail information from the database.

The shadow object contains the same fields as the original object plus the PIN_FLD_AU_PARENT_OBJ field that captures information about the audited class. The PIN_FLD_AU_PARENT_OBJ field is a pointer to the revision of the original object copied to the audit trail; its value is derived from the original object field.

Specifying Audit Trail Tablespaces

You can specify the tablespace for the audit trail schema when you install BRM. The default tablespace for a shadow object is the same as that of its original object.

Audit Trail Tablespace Names

The tablespace name for a shadow object is the same as that of its original object with the addition of an au prefix. There is a 32-character limit on tablespace names. If the addition of the au prefix exceeds the 32-character limit, the shadow object tablespace name is truncated, causing its tablespace name to be different than that of the original object.

Fields Marked for Auditing by Default

Table 12-1 shows the fields that are marked for auditing by default in BRM, the top-level class associated with those fields, the event objects created when those fields are modified, and the BRM activity being audited:

Table 12-1 Fields Marked by Default for Auditing

Top-Level Class	Audited Fields	Event Object Created	BRM Activity Audited
/deal	All fields	/event/audit/price/deal	Changes to internal BRM price lists
/payinfo	PIN_FLD_DEBIT_NUM and PIN_FLD_DEBIT_EXP	/event/audit/customer/payinfo/cc	Changes to customer credit card numbers and expiration dates
/plan	All fields	/event/audit/price/plan	Changes to internal BRM price lists
/product	All fields	/event/audit/price/product	Changes to internal BRM price lists
/rate	All fields	/event/audit/price/rate	Changes to internal BRM price lists
/rate_plan	All fields	/event/audit/price/rate_plan	Changes to internal BRM price lists
/rate_plan_selector	All fields	/event/audit/price/rate_plan_selector	Changes to internal BRM price lists

Enabling Auditing for a Field

You can enable new or existing object fields for auditing at any time. For information on why you would mark a field for auditing, see "About Maintaining an Audit Trail of BRM Activity" in BRM Managing Customers.

Performance Tips

Keep an audit trail only for the BRM activity that is absolutely necessary for your business. Enabling an audit trail decreases system performance significantly.
Do not mark fields in the /account object for auditing. Because the /account object is large and is modified by many types of system activity, it is not recommended for auditing.
Mark the /purchased_product and /purchased_discount objects for auditing to audit products and disounts for an account.
If you mark an array or substruct for auditing, changes to any field in that array or substruct will trigger auditing. If you only want to track changes to one field in an array or substruct, mark only that field for auditing and not the entire array or substruct.

You mark a field for auditing by using the Storable Class Editor. For detailed instructions, see the Storable Class Editor Help.

Disabling Auditing for a Field

You can disable auditing for a field at any time. You disable auditing for a field with the Storable Class Editor. For detailed instructions, see the Storable Class Editor Help.

Accessing Audit Trail Information

This section summarizes the information you need and the steps necessary to access audit trail data. You can access audit trail information manually by using the testnap utility to retrieve specific revisions of an object given the object's POID. You can also write your own application to access audit trail changes in the database.

For a description of how audit trails work, see "Audit Trail Architecture".

Required Information

To access audit trail data, you must:

Obtain the account number of the customer for whom you need audit trail data (as shown in Customer Center).
Obtain the general time period in which the event that was audited occurred. For example, the date or month the customer changed his credit card number.
Know the name of the event object BRM generates for each type of auditing. For example, when a customer changes the credit card number on his account, BRM generates the event object /event/audit/customer/payinfo/cc.

For the names of the event objects generated for default auditing, see "Fields Marked for Auditing by Default".

Finding the Audit Trail Data

To find audit trail data:

Use the customer's account number to obtain the /account object associated with the account number.
Browse the event objects for the /account object in the general time period to locate the event.

For example, to find a changed credit card number, browse the events to locate the /event/audit/customer/payinfo/cc event created at the time the customer changed his credit card number.
Use the event object to obtain the POID of the original object that was audited.

For example, the /event/audit/customer/payinfo/cc event contains the POID of the /payinfo/cc object that was audited when the customer's credit card number was changed. The POID provides the revision number of the object when it was audited. This number is stored in the shadow object.
Retrieve the shadow objects by calling the PCM_OP_READ_OBJ opcode with one of the following flags. (For examples of how to do this by using the testnap utility, see "Using testnap to Retrieve Shadow Objects".)
- Use the PCM_OPFLG_USE_POID_GIVEN flag to send a request to the BRM database Data Manager (DM) to execute a search-and-read operation for the exact POID you specify (the POID of the shadow object in the audit trail).
- Use the PCM_OPFLG_USE_POID_PREV flag to send a request to the BRM database DM to execute a search-and-read operation for the shadow object POID that contains a revision number preceding the revision number you specify in your POID.
- Use the PCM_OPFLG_USE_POID_NEXT flag to send a request to the BRM database DM to execute a search-and-read operation for the shadow object POID that contains a revision number that is one or more numbers higher than the revision number you specify in your POID.
- Use the PCM_OPFLG_USE_POID_NEAREST flag to send a request to the BRM database DM to execute a search-and-read operation for the exact audit trail revision number that you specify (the POID of the shadow object); if the exact POID is not found, to obtain the POID with a revision number that precedes the revision number you specify in your POID.

Using testnap to Retrieve Shadow Objects

The following code samples show how to retrieve shadow objects by using testnap. This example accesses the audit trail of the /payinfo/cc object given the object's POID near the time auditing occurred.

# Flists and opcode for testnap to access the audit-trail
# of the /payinfo/cc object.
#
# Syntax: xop PCM_OP_READ_OBJ flags buffer
#
# where the buffer contains the following flist with the
# flags as described below:
# 
# 
0 PIN_FLD_POID POID [0] 0.0.0.1 /payinfo 10001 0
  
  
# NOTE: Replace the database number, the POID_ID, and 
# the version as required.
  
#Use the following flags:
  
# PCM_OPFLG_USE_POID_GIVEN (0x0040): To access the exact revision.
# e.g. "xop PCM_OP_READ_OBJ 0x0040 1" on the buffer flist 
# 0 PIN_FLD_POID POID [0] 0.0.0.1 /payinfo 10001 3
# This retrieves audit trail with revision 3, or NOT_FOUND.
  
# PCM_OPFLG_USE_POID_PREV (0x2000): To access the 
# previous revision.
# e.g. "xop PCM_OP_READ_OBJ 0x2000 1" on the buffer flist 
# 0 PIN_FLD_POID POID [0] 0.0.0.1 /payinfo 10001 3
# This retrieves audit trail with revision 2, assuming revision
# 2 is the previous revision to 3 in the audit-trail. Otherwise,
# the next revision lower than revision 3 is retrieved.
  
# PCM_OPFLG_USE_POID_NEXT (0x4000+): To access the next revision.
# e.g. "xop PCM_OP_READ_OBJ 0x4000 1" on the buffer flist 
# 0 PIN_FLD_POID POID [0] 0.0.0.1 /payinfo 10001 3
# This retrieves audit trail with revision 4, assuming revision
# 4 is the next revision to 3 in the audit trail. Otherwise, the
# next revision higher than revision 3 is retrieved.
  
  
# PCM_OPFLG_USE_POID_NEAREST (0x8000): To access the nearest
# revision.
# e.g. "xop PCM_OP_READ_OBJ 0x8000 1" on the buffer flist 
# 0 PIN_FLD_POID POID [0] 0.0.0.1 /payinfo 10001 3
# This retrieves audit trail with revision 3, if the revision 3
# exists; otherwise, it retrieves a revision preceding
# revision 3.

Archiving Audit Data

Remove unwanted audit data from your Pipeline Manager audit tables. Purging the audit tables improves system performance, reduces memory usage, and makes the results returned by the DAT_Account module smaller and more efficient.

Note:

The purge_audit_tables.pl script does not delete objects from the database; it only purges the object rows stored in a table.

To purge objects from audit tables:

Open the BRM_Home/sys/archive/oracle/purge_audit_tables.conf file.
In the storage_clause entry, specify the tablespace for the history tables.
In the time entry, specify the column name to be used for comparing the cutoff date specified in the purge_audit_tables.pl script's -d parameter.
In the cutoff_for_purge entry, specify the percentage based on which it will invoke the archiveindirect mode rather than the archivedirect mode to archive the tables.

For example, if the cutoff_for_purge value is 70, and a table contains more then 70% data that must be archived, temporary tables are used to transfer the data efficiently (archiveindirect mode). If the table contains less then 70% data that must be archived, the data is transferred directly to the history tables (archivedirect mode).

The BRM_Home/sys/archive/oracle/purge_audit file contains more information about the configuration entries.
With a text editor, open the BRM_Home/sys/archive/oracle/purge_audit file.
In the first line of the script, replace __PERL__ with the location of the Perl executable.
Run the purge_audit_tables.pl script.

Note:
To run in debug mode, set the environment variable ARCHIVE_DEBUG at the system prompt before you run the script. As the script runs, processing data, including the functions that are called, is printed to the screen.

About Encrypting Information

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 BRM 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".

Note:

You can encrypt fields by using AES (Advanced Encryption Standard) encryption or MD5 (Message-Digest algorithm 5) encryption; Oracle suggests you use the AES scheme. For more information about these encryption methods, see "About AES Encryption" and "About MD5 Encryption".

Important:

You cannot encrypt customer account passwords with the AES or MD5 scheme. Instead, you use the customer opcodes to perform the encryption. For more information, see "Encrypting Fields".

About AES Encryption

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. This encrypted AES key gets stored in the database. Then you define which fields should be encrypted by setting their PIN_FLD_ENCRYPTABLE flag. When the DM starts, the Oracle DM uses the encrypted AES key to transform the fields marked as encryptable from plaintext into ciphertext and from ciphertext into plaintext.

Note:

You can have only one encrypted AES key per Oracle DM. For information on changing the encrypted AES key, see "Replacing an Encrypted AES Key".

In addition to encrypting data fields, you can encrypt passwords for the following features to secure your BRM system:

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

For more information, see "About Encrypting Passwords".

About AES Data Encryption Length

The length of AES-encrypted data is different, depending on whether the data is stored in the database. In both cases, when fields are encrypted, their lengths increase.

Important:

If you are storing the information in an Oracle database, the maximum length of an encrypted field is 1992 bytes, which is 975 bytes in plaintext.

For information on how to encrypt fields, see "Encrypting Fields".

Encryption Length for Fields Stored in the Database

When the AES encryption scheme is used to store database fields, the generated ciphertext is in the following 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.

To calculate the length of the generated ciphertext data, the following formula is used:

(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 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, rather than to store it in the database (for example, to generate encrypted passwords), the generated ciphertext is in the following 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.

To calculate the length of the generated ciphertext data, the following formula is used:

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

About MD5 Encryption

MD5 encryption is a cryptographic hash function with a 128-bit hash value. A hash function takes a long string (or message) of any length as input and generates a fixed-length string as output.

Note:

dm_oracle and dm_fusa support data encrypted by using MD5.

BRM does not support MD5 encryption for passwords; passwords must use AES encryption.

Important:

Because of MD5's simple encryption format and known weaknesses, you should encrypt BRM by using the AES encryption scheme. For more information on the AES scheme, see "About AES Encryption".

About MD5 Data Encryption Length

When fields are encrypted with the MD5 scheme, their length can increase. The new length is at most 15 characters longer than the unencrypted length.

Important:

If you are storing the information in an Oracle database, the maximum length of an encryptable field is 1992 bytes, which is 975 bytes in plaintext.

To calculate the number of characters, use the following formula on the unencrypted string:

f(N) = (N div 16) * 16) + ((N mod 16) > 0 ? 16 : 0) + 5

which is the same as twice the next multiple of 16 greater than N plus 5. Therefore, for 16-digit credit card numbers, the encrypted length is 16 + 5. For anything larger than 16, but less than 32 characters, the encrypted length is 32 + 5, and so on.

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, Oracle recommends that you do so only during upgrades.
Make sure the field is in string format. Only strings may be encrypted.

See the Storable Class Editor Help for detailed instructions on how to mark a field for encryption and how to disable encryption for a field.

Defining Masked Fields

You can mask BRM fields and custom fields. For information on creating custom fields, see "Creating Custom Fields and Storable Classes".

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. See the Storable Class Editor Help for detailed instructions.
Copy the contents of both files (the custom masked file generated in Step 1 and the source file generated in Step 2) 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 created in Step 3 as the input. Use the following syntax:
```
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".

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, then encrypts it with a hidden key to create the encrypted AES key.
- If you have an AES key, run the utility with the -genkey and -key parameters, and specify the AES key value:
  
  Important:
  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. For example, if you use both the -genkey and -key parameters as shown here:
```
pin_crypt_app -genkey -key E00D841567828BBA12C86820D018D3B6AE9BEB3B5486D2EBA1CBFC51823755C7
  
```
The output is:
```
Generation of Encrypted AES key is successful. 
Encrypted key is: 
&aes|0D5E11BFDD97D2769D9B0DBFBD1BBF7E9554B3A6D438FB19025E12540F9B122C6EB6A4A467E15944F18447ADE052E35A
  
```
Write down the encrypted AES key value or copy it to a text editor.

Important:
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. See "Configuring the Data Manager for AES Encryption".

Note:
You can have only one encrypted AES key per Oracle DM. For information on changing the encrypted AES key, see "Replacing an Encrypted AES Key".

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.

Note:

This procedure assumes you have already configured the DM for AES encryption. For more information, 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 Encrypting Passwords

You can encrypt passwords for the BRM database, Pipeline Manager database, optional managers such as the Account Synchronization DM, 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.

Important:

You must use the pin_crypt_app utility to encrypt the Pipeline Manager password, 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 more information, see "Encrypting Passwords Manually".

For more information, see:

Encrypting Passwords Manually
Encrypting Passwords Automatically for BRM Base Components

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

For information on 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.

Encrypting Passwords Manually

To encrypt passwords manually:

Log on to the system running the BRM manager.

Note:
For Data Managers, this is the generally the system running the BRM database; for client applications, it is the application host system.
Run the following command which transforms a plaintext password into ciphertext:
```
pin_crypt_app -enc plaintext_password
  
```
where plaintext_password is the password to encrypt.

The output is the AES tag followed by a vertical bar and the encrypted password. For example:
```
&aes|0D5E11BFDD97D2769D9B0DBFBD1BBF7EE03F1642861DFA57502C7FB85A654267
  
```
Write down the encrypted password or copy it to a text editor.
Do one of the following:
- 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. By default, the Infranet.properties file is located in C:\Program Files\Common Files\Portal Software.
  
  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.
Save the file.
Stop and restart the DM.

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.

Important:

This script does not encrypt passwords for client applications or optional managers that are not part of base BRM, including the Pipeline Manager password. 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. For more information, see "Encrypting Passwords Manually".

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

perl encryptpassword.pl

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

Creates a backup 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.

Important:
The encryptpassword.pl script does not enable field-level encryption. If you set the encryptable value for database fields, refer to the steps in "Configuring the Data Manager for AES Encryption" after you run the script to enable field-level AES encryption for your database.

Encrypting Passwords Automatically for BRM Base Components

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

Log on to the system running the BRM database.
Go to the BRM_Home/setup/scripts directory.
Run the following command:
```
perl encryptpassword.pl
```
Follow the instructions at each prompt.

Passwords are encrypted in the AES format.

Important:

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.

Note:

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

Configuring the Data Manager for MD5 decryption

The DM configuration file (pin.conf) specifies encryption settings for the database. You must set the DM decrypt entry under the following circumstances:

When you are not upgrading from MD5 to AES, and AES is the encryption scheme for your database.
When AES is the active encryption scheme. In this case, you must decrypt the existing MD5-encrypted data so it can be encrypted with the AES method.

By default, the pin.conf file is located in BRM_Home/sys/dm_oracle .

For more information about setting the decrypt entry and configuring the DM for encryption, see "Configuring the Data Manager for AES Encryption".

Configuring the Data Manager for AES Encryption

The DM configuration file (pin.conf) specifies the user name and password needed to log in to the BRM database. It also contains other encryption settings you must set.

Encrypting the Password

By default, the Oracle pin.conf file is in the BRM_Home/sys/dm_oracle directory.

To encrypt the password:

If necessary, generate an encrypted password and an encrypted AES key. See "Encrypting Passwords Manually" and "Generating an Encrypted AES Key".
Open the DM pin.conf file.
Add the encrypted password to the sm_pw entry:
```
- dm sm_pw Encrypted_password
  
```
For example:
```
- dm sm_pw &aes|04|0D5E11BFDD97D2769D9B0DBFBD1BBF7E8762529ADB84F705B831FB1340B31687EB
  
```
Note:
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.
Save the file.
Stop and restart the DM.

Encrypted password support is now enabled for your database.

Encrypting the Data

By default, the Oracle pin.conf file is in the BRM_Home/sys/dm_oracle directory.

To encrypt the data:

Generate an encrypted password and an encrypted AES key. See "Encrypting Passwords Manually" and "Generating an Encrypted AES Key".
Open the DM pin.conf file.
Set the crypt entry to enable AES encryption. Provide the encrypted AES key. Use the following syntax.
```
- crypt aes|Encryption_library "&aes|Encrypted_aes_key"
  
```
Note:
The encryption library is different depending on the platform you are using. You must include the pathname with the file.

For example, the following entry sets AES as the encryption method on the Oracle Solaris platform:
```
- crypt aes|BRM_Home/lib/libpin_crypt_aes4dm.so "&aes|11336997BDDFE1AC11336997BDDFE1AC117DE391888FE4203A4D21DB3751A2679F650487BD6BCEBB41A2D0D81C823490"
  
```

Set the decrypt entry to disable MD5 encryption:

- decrypt md5| "Abracadabra dabracaabrA"

Save the file.
Stop and restart the DM.

Migrating Data from MD5 to AES Encryption

Use the pin_crypt_upgrade utility to migrate MD5-encrypted data to the AES encryption scheme. This utility searches for all fields that are marked as encryptable and upgrades the data to AES encryption.

Note:

If the crypt entry in the pin.conf file is set to AES encryption and the table has both MD5-encrypted and AES-encrypted data, the data can be read. However, if the crypt entry in the pin.conf file is set to MD5 encryption and the table has both MD5-encrypted and AES-encrypted data, the data cannot be read.

Important:

After you migrate data to the AES scheme, you cannot revert to the MD5 scheme.

To migrate data from MD5 to AES encryption:

Configure the Oracle DM pin.conf file for AES encryption. See "Configuring the Data Manager for AES Encryption".
Open the BRM_Home/apps/pin_crypt/pin.conf file in a text editor and verify the following are set correctly:
- The cm pointers (for example, cm_ptr, login_type, login_name, and login_pw). For more information, see "Using Configuration Files to Connect and Configure Components" in BRM System Administrator's Guide.
- The MTA application entries (for example, per_batch, per_step, and fetch_size). For more information, see "Error Notifications".
Run the pin_crypt_upgrade utility from this directory.

Configuring the Data Manager for Oracle ZT PKI Encryption

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

Encrypting the Data

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

To encrypt the data:

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 to generate a root encryption key:
```
pin_crypt_app -genrootkey
  
```
A root encryption key is generated and is stored in the root key wallet.
Before enabling the Oracle ZT PKI encryption algorithm for dm_oracle, set the BRM_WALLET environment variable to wallet_location value.
Generate an encrypted password. See "Encrypting Passwords Manually".
Run the following command, which generates an encrypted Oracle ZT PKI key:
```
pin_crypt_app -useZT genkey -key AES_Key
  
```
where AES_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.

Important:
Include &ozt| because it is part of the encrypted Oracle ZT PKI key value.
Open the Oracle DM BRM_Home/sys/dm_oracle/pin.conf file in a text editor.
Enable the Oracle ZT PKI encryption algorithm by adding the following entry:
```
- crypt aes|Encryption_library "&ozt|Encrypted_key"
  
```
where:
- Encryption_library is the path and filename of the encryption library. The prefix for the library is lib for Solaris, HP-UX, Linux, and AIX, or null "" for Windows. The extension for the library is .so for Solaris, HP-UX, and Linux; .a for AIX; .dll for Windows.
- Encrypted_key is the key generated in step 6.
For example:
```
- crypt aes|BRM_Home/lib/libpin_crypt_aes4dm64.so "&ozt|767A144C814D633DBE49E59BF5BC6E18|DC4D6836B327875B7B200BAC6CD45C50A4850DDF3DC542FCFE57E134C4A6780A63E7445219ADC609779279B2C809C8EC"
  
```
Note:
The encryption library is different depending on the platform you are using. You must include the pathname with the file.
Set the decrypt entry, which disables MD5 encryption, by adding the following entry:
```
- decrypt md5| "Abracadabra dabracaabrA"
  
```
By default, the MD5 key is set to Abracadabra dabracaabrA.
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.

Important:

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.

Note:

The data keys in the CRYPTKEY_T table should be in synchronization for all the 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 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.

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/password@database_alias
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.

Enabling Password Restriction for /service Objects

In BRM, you can use password restriction to secure the creation, modification, and deletion of /service objects.

Password restriction forces passwords to adhere to the following rules:

Contain a minimum of 8 characters
Include at least one numeric character, one uppercase character, and one special character
Differ from the previous four passwords (not applicable for customer registration and service creation)
Not include any part of the user ID

By default, password restriction for /service objects is disabled in BRM.

To enable password restriction for /service objects:

Go to the BRM_Home/sys/data/config directory.
Run the following command, which creates an editable XML file from the customer instance of the /config/business_params object:
```
pin_bus_params -r BusParamsCustomer bus_params_customer.xml 
  
```
This command creates the XML file named bus_params_customer.xml.out in your working directory. To place this file in a different directory, specify the path as part of the file name.
Open the bus_params_customer. xml.out file.

Search the XML file for the following line:

<EnablePasswordRestriction>disabled</EnablePasswordRestriction>

Change disabled to enabled.
Save the file as bus_params_customer.xml.
Go to the BRM_Home/sys/data/config directory, which includes support files used by the pin_bus_params utility.
Run the following command, which loads the change into the /config/business_params object:
```
pin_bus_params PathToWorkingDirectory/bus_params_customer.xml
  
```
where PathToWorkingDirectory is the directory in which bus_params_customer.xml file resides.

Caution:
BRM uses the XML in this file to overwrite the existing customer instance of the /config/business_params object. If you delete or modify any other parameters in the file, these changes affect the associated aspects of the BRM customer configuration.

Note:
To run this command from a different directory, see "pin_bus_params".
Read the object with the testnap utility or Object Browser to verify that all fields are correct.

See "Using testnap" for general instructions on using the testnap utility. See "Reading Objects by Using Object Browser" for information on how to use Object Browser.
Stop and restart the CM.
(Multischema systems only) Run the pin_multidb script with the -R CONFIG parameter. For more information, see "pin_multidb" in BRM System Administrator's Guide.

About Storing Customer Profile Information

You can collect information about your customers and store them in the database in the /profile objects. In the profile object, you store marketing or other information relevant to your company, but not necessarily used for accounting. A /profile storable class is a top-level class in BRM, which you subclass to define /profile storable classes for your specific needs. It contains the standard top-level object fields and a field which is a pointer to the POID of the /account object with which it is associated.

The /account object is not used to store this marketing information because inheriting the /account object to store these fields would cause object-type collisions if a variety of enhanced services were installed on the same BRM installation.

Because /profile objects are linked to specific /account objects, any number of different /profile objects can be linked to the same /account object. However, each /profile object can be linked to only one /account object.

After you define a /profile storable class, you use the Customer FM standard opcodes and Customer FM policy opcodes to create, delete, modify, and validate profile objects.

Using Profile Objects to Collect Customer Profiles

This section describes how to use profile objects to collect customer profiles.

Defining a Profile Subclass

Use the Storable Class Editor to create /profile storable subclasses.

See "Creating Custom Fields and Storable Classes" for details on adding storable subclasses and fields to the database.

Creating a Profile Object

To create a profile object:

Create an flist with a PIN_FLD_INHERITED field containing your specific profile information.
Pass this flist into PCM_OP_CUST_CREATE_PROFILE.

Modifying a Profile Object

To modify a profile object:

Modify the /profile object flist.
Pass this flist into PCM_OP_CUST_MODIFY_PROFILE.

Deleting a Profile Object

To delete a /profile object, use PCM_OP_CUST_DELETE_PROFILE.

Validating Profile Objects

To validate /profile objects, you customize the following customer FM policy opcodes:

PCM_OP_CUST_POL_PREP_PROFILE
PCM_OP_CUST_POL_VALID_PROFILE

For more information on customizing policy opcodes, see "Adding and Modifying Policy Facilities Modules".