Administration Guide for Oracle Billing Insight > Administering the Database >

Running the Master Key Update

You must run the script to update the master key once a year as required to comply with the Payment Card Industry Data Security Standard (PCI DSS). This script updates the master key as well as related subkeys and validation code in the Oracle Billing Insight database.

You must also update the master key after installing Oracle Billing Insight and setting up the OLTP and OLAP databases, where the master key is used.

To run the master key update

1. Repackage the GNU Lesser Public License on your Oracle Billing Insight files. For instructions on the process of repackaging, see Installation Guide for Oracle Billing Insight.
2. Shut down the application server to ensure that all data is in a consistent status.
3. It is strongly recommended to back up the Oracle Billing Insight OLTP database.
4. Back up the master keystore folder, EDX_HOME\keystore.
5. Back up the persistence.xma.xml file, found in the EDX_HOME\xma\config\modules directory. You must modify the file, then restore it after you run the master key update script. Make a backup of the persistence.xma.xml file to use for the restore.

   Modify the persistence.xma.xml file for the myDataSource and TransactionManager beans, required to support OLTP database operation when the application server is shut down. It is suggested to use c3p0 to connect to myDataSource, and Spring Framework transaction support for the TransactionManager bean.

   Remove or comment out the existing configurations and uncomment the myDataSource and TransactionManager bean sections, using the code and settings shown here.

   Consult your database administrator for the appropriate database connection parameters to use in the jdbcUrl property, which points to the OLTP database.

   1. Modify the myDataSource bean section to use the following code:

   <bean id="myDataSource" class="com.mchange.v2.c3p0.ComboPooledDataSource"

   destroy-method="close">

   <property name="driverClass">

   <value>oracle.jdbc.OracleDriver</value>

   </property>

   <property name="jdbcUrl">

   <value>jdbc:oracle:thin:@ebillingsrv:1521:oltp

   </value>

   </property>

   <property name="user">

   <value>oltp</value>

   </property>

   <property name="password">

   <value>oltp</value>

   </property>

   </bean>

   2. Modify the TransactionManager bean section to use the following code:

   <bean id="TransactionManager"

   class="org.springframework.jdbc.datasource.DataSourceTransactionManager">

   <property name="dataSource" ref="myDataSource" />

   </bean>

6. Place the following JAR files in the EDX_HOME\bin\keymgmt\lib directory:
   • For Oracle Database 11g only, the ojdbc5.jar file, found on your database server in the $ORACLE_HOME\jdbc\lib directory.
   • For Oracle Database 10g only, the ojdbc14.jar file, found on your database server in the $ORACLE_HOME\jdbc\lib directory.
   • For all versions of Oracle Database, the jta.jar file, which can be found on your database server in the $ORACLE_HOME\jlib) directory.
7. Set the log file path. The master key update uses Log4j. The configuration file, log4j_keymgmt.xml, is located in the EDX_HOME\config directory. For instructions on how to use Log4j, see:

   http://logging.apache.org/log4j/1.2/index.html

   The master key update generates a default log file, keymgmt.log, in the working directory, EDX_HOME\bin\keymgmt. Make sure you have write permission in this directory before running the script.

8. Set the correct JAVA_HOME and PATH for Java and then run the master key update script, found in the EDX_HOME\bin\keymgmt directory. For example:
   • UNIX:

   export JAVA_HOME=/opt/java1.5

   export PATH=$JAVA_HOME/bin:$PATH

   ./update_master_key.sh

   • Windows:

   set JAVA_HOME=c:\java1.5

   set PATH=%JAVA_HOME%\bin;%PATH%

   update_master_key.bat

9. Determine whether the update was successful:
   1. Check the log file. If the script was successful, then the following message appears in the log: Master Key Update process is completed.
   2. Check the MasterKeyStore.properties file, located in either the AES128 or blowfish subdirectory under the following directory:
      • UNIX. EDX_HOME/keystore
      • Windows. EDX_HOME\keystore

        The script generates a new master key in the MasterKeyStore.properties file with a timestamp. The first record contains the timestamp, followed by the previous master key with the same timestamp, and the current master key. The script saves the old master key file calledMasterKeyStore.properties.timestamp.

   3. Distribute the new MasterKeyStore.properties file to all application servers to guarantee master key consistency.
   4. Verify that the following data has been updated:
      • The SECURE_SUBKEY column in the EDX_SECURE_SUBKEY table
      • The Code in the EDX_UMF_SEC_VALIDATIONCODE table
      • The KEY_UPDATE_FLAG column in the EDX_SECURE_SUBKEY table will be NULL
10. If the master key update script ran successfully, then restore the original persistence.xma.xml file to the following directory and restart application server, and log in with your ID and password:
    • UNIX. EDX_HOME/xma/config/modules
    • Windows.EDX_HOME\xma\config\modules
11. If the master key update script did not run successfully, then follow these steps to troubleshoot the problem:
    1. If the script did not generate the new master key in the MasterKeyStore.properties file, then verify the configuration of the persistence.xma.xml file and run the script again.
    2. If the script successfully generated the new master key in the MasterKeyStore.properties file, then check the sub key flag in the KEY_UPDATE_FLAG column in the EDX_SECURE_SUBKEY table. If the column contains all NULL values, then you must restore the master key. Replace the MasterKeyStore.properties file located in the either the AES128 or blowfish subdirectory under the following directory with the backup file:
       • UNIX. EDX_HOME/keystore
       • Windows. EDX_HOME\keystore

         If the column contains any value other than NULL, then you can run the script again.

    3. If it is not possible to run the master key update script successfully, then restore the contents of the EDX_HOME/keystore directory and perform a full restore of the OLTP database.