Summary

In most deployments, you supply database connection settings for the PegaRULES database in a datasource defined in your application server. In Tomcat deployments and batch interface deployments that do not use an application server, you supply these settings in an XML configuration file, prconfig.xml. These settings include the database user name and password in plain text.

To avoid exposing the password, you can call a Process Commander Java class that encrypts the password in a keyring file, then removes the password element from prconfig.xml. When Process Commander does not find the password in the prconfig file, it will automatically find the keyring file, decrypt the password, and complete the database connection.

To implement database password encryption, complete the following steps:

1. Configure a JVM environment with access to Process Commander JAR files and the appropriate database driver files.
2. Configure database connections in prconfig.xml
3. Optionally, specify encryption options in prconfig.xml
4. Call the Process Commander Java class KeyringImpl to generate the pegarules.keyring file
5. Complete database connections using pegarules.keyring

Each of these steps is explained in detail below.

Understanding Process Commander Encryption

Process Commander database password encryption relies on the Java Cryptography Extension (JCE) which is bundled in the Java JDK.

JCE is part of the Java Cryptography Architecture (JCA), a framework that defines and supports cryptographic services. It includes a set of standard providers, such as Sun, SunRsaSign, and SunJCE, which contain the actual cryptographic implementations. Other custom or third-party providers may be added to the framework at your site. For more information on the JCE and JCA, go to Java SE Security on Sun's Java web site and follow the link to the Java SE Security Documentation for your JDK version.

By default, Process Commander uses the DESede (Triple-DES) algorithm with a 168-bit key. If you want to use another algorithm or key length, you can add elements to the prconfig file to specify other encryption options. See Specify encryption options in prconfig.xml.

Consult with your System Administration to see whether a particular encryption method is required for your deployment. You can list all the providers available in your environment by calling the Process Commander Java class JCECapabilities. See Determining Your Supported JCE Capabilities below.

Additional enhancements were made to PRPC 5.5 to incorporate the Bouncy Castle JCE provider.

Suggested Approach

1. Configure a JVM environment with access to Process Commander JAR files and the appropriate database driver files.

You must have a JRE distribution in place in the command-line system that allows you to make Java calls. JCE is bundled with JDK 1.4 and later. For more information, see the PRPC Platform Support Guide.

Make sure your classpath:

• Contains the JAR files in the libdirectory of your Process Commander deployment on the system. This directory contains the Process Commander libraries.

  • For example, in a typical Tomcat deployment, include the JAR files in

    C:\TC-6.0.16\webapps\prweb\WEB-INF\lib and lib\pega.

  • The Business Information Exchange (BIX) distribution includes a lib directory with the necessary JAR files.

  • Using a specific example, running KeyRingImpl in a Java 6 environment requires:

    • lib\pega\prprivate.jar

    • lib\pega\prpublic.jar

    • lib\pega\prlogging-1.2.14.jar

    • lib\pega\prlucene-1.4.3.jar

    • lib\base\java6\prjsr166java6-3.0.jar

    • lib\pega\pricu2jdk.jar

    • lib\prdbcp.jar

• Includes the location of the JDBC driver JAR files for your database.

  • For Tomcat, copy the drivers into the <Tomcat_HOME>/common/lib directory for Tomcat 5 installations, or <Tomcat_HOME>/lib for Tomcat 6 installations.

  • For more information on the appropriate driver for your database, see "Configuring database support on your application server" in the Installation Guide.

2. Configure database connections in prconfig.xml

Before generating the keyring file, complete the database connection settings in prconfig.xml to specify the source Process Commander database. See How to configure non-J2EE database connections in the prconfig.xml file.

The prconfig.xml file contains sample database connection settings for a SQL Server 2000 database:

<!--
<env name="database/drivers" value="com.microsoft.jdbc.sqlserver.SQLServerDriver;oracle.jdbc.OracleDriver" />
<env name="database/databases/PegaRULES/url" value="jdbc:microsoft:sqlserver://localhost:1433;SelectMethod=cursor;
SendStringParametersAsUnicode=false;ProgramName=PR ${SystemName}@${NodeName} ${DBName} #${ConnectionID}" />
<env name="database/databases/PegaRULES/userName" value="a_username" />
<env name="database/databases/PegaRULES/password" value="a_password" />
-->

Uncomment this example, and modify it as needed for your Process Commander database:

• In the database/drivers element, change the value to the appropriate driver for your database.
• In the database/databases/PegaRULES/url element, set the value to the connection URL for your database.
• Set the value of the database/databases/PegaRULES/userName element and the database/databases/PegaRULES/password to the user name and password of a user for the Process Commander database.

For example, the following elements specify the connections for a typical MS SQL 2005 database:

<!--
<env name="database/drivers" value="com.microsoft.sqlserver.jdbc.SQLServerDriver" />
<env name="database/databases/PegaRULES/url" value="jdbc:sqlserver://seprpc012k3;databaseName=pega-KP;SelectMethod=cursor;
SendStringParametersAsUnicode=false;" />
<env name="database/databases/PegaRULES/userName" value="pega-DBuser" />
<env name="database/databases/PegaRULES/password" value="pega" />
-->

3. Optionally, specify encryption options in prconfig.xml

By default, the KeyringImpl class creates the encrypted keyring file, pegarules.keyring, using the DESede (Triple-DES) algorithm with a 168-bit key. In most environments, this algorithm will be adequate and no further configuration is necessary. If your site requires a different or stronger algorithm, you can add the following elements to prconfig.xml to set other options:

• Add the identification/KeyringPrefix element to specify different prefix for the keyring file name, for example:

  <env name="identification/KeyringPrefix" value="BIX-extract" />

  • With this setting, KeyringImpl generates a file named BIX-extract.keyring

  • In most cases, you only need to specify this option if more than one Process Commander system is deployed in the same application server and JVM.

• Add the identification/KeyringAlgorithm element to specify an encryption algorithm other than DESede.
  • For example:

    <env name="identification/KeyringAlgorithm" value="AES" />

  • You must add an algorithm supported by the JCE/JCA environment bundled in your JVM. See Determining Your Supported JCE Capabilities below.

• Add a identification/KeyringLength element to change the length of the key used to encrypt the file.
  • For example,

    <env name="identification/KeyringLength" value="256" />

4. Call the Process Commander Java class KeyringImpl to generate the pegarules.keyring file.

In a properly configured environment, from the command-line or in a script, make a Java call to com.pega.pegarules.crypto.KeyringImpl — for example:

Provide the following arguments:

1. JVM memory options: ensure that your JVM has allocated enough memory for the operation by setting:
   • The initial Java heap size to 512m (-Xms512m)
   • The maximum heap size to at least 768m (-Xmx768m)
2. System properties giving the location of the Process Commander configuration files prconfig.xml and prlogging.xml, for example:
   • -Dpegarules.config=.\config\prconfig.xml
   • -Dpegarules.logging.configuration=.\config\prlogging.xml
3. If the current classpath does not include the Process Commander libraries (see Configure a JVM environment above), add a -classpath option identifying the JAR files required by KeyringImpl.
   • Relative to the WEB-INF directory of a deployed prweb.war application, the classpath must at least include:
     • ..\lib\pega\prprivate.jar
     • ..\lib\pega\prpublic.jar
     • ..\lib\pega\prlogging-1.2.14.jar
     • ..\lib\pega\pricu2jdk.jar
     • ..\lib\prdbcp.jar
     • ..\lib\base\java6\prjsr166java6-3.0.jar
   • In a BIX distribution, these JAR files are provided in the lib directory without subdirectories.
4. Three parameters to KeyringImpl:
   • The full file specification (location and name) of the keyring file.

• The full file specification of the prconfig.xml file containing encryption options and connection settings for the databases whose passwords should be encrypted.
• The full path to the Process Commander deployment directory.
  • In Tomcat deployments, this is the directory in which the WEB-INF directory for prweb is located.
  • In BIX distributions, this is the top level directory containing the lib directory.

Complete KeyringImpl as follows:

1. Call KeyringImpl.

   The program displays configuration information and prompts you for an update password:

   

   You will need this password to change or remove the database password stored in the keyring file.

   The update password is saved in a one-way encryption; it cannot be read or retrieved from the keyring file. If you misplace the update password, you must delete the keyring file and recreate it.
2. Enter the update password.

   KeyringImpl displays connection information for the database being configured and prompts for the keyring password:

   

3. Enter the database password for the database user specified in the connection settings.

   KeyringImpl creates the keyring file in the location specified by the parameter you provided:

   

5. Using pegarules.keyring

Remove the password element, <env name="database/databases/PegaRULES/password" value="a_password" /> from the prconfig.xml file.

When Process Commander creates a database connection and does not find a password in prconfig.xml or a Data-Admin-DB-Name instance, it uses the keyring file as the source for the database password. There is no difference in Process Commander database processing.

Determining Your Supported JCE Capabilities

You can use the utility JCECapabilities to determine the cryptography providers and policy files available in your JVM environment. To display these resources, you make a Java call of the class com.pega.pegarules.crypto.JCECapabilities, for example:

As described for calling KeyringImpl above, provide arguments for the:

• JVM memory settings
• System properties providing the location of prconfig.xml and prlogging.xml
• Classpath to the Process Commander libraries (if necessary)

The example above shows a sample -classpath setting for a BIX distribution. Relative to the WEB-INF directory of a deployed prweb.war application, the classpath for JCECapabilities must at least include:

• ..\lib\pega\prprivate.jar
• ..\lib\pega\prpublic.jar
• ..\lib\pega\prlogging-1.2.14.jar
• ..\lib\pega\preventbus.jar
• ..\lib\base\java6\prjsr166java6-3.0.jar

Be sure to run JCECapabilities in the same JVM environment in which you will be using the keyring file.

JCECapabilities returns a display of the current system properties and then a listing of all the JCE providers and policy files supported in the current JVM. For example, the beginning of the listing will be similar to the following:

You can review this file to determine which encryption options are available to you. To specify the encryption options to be used when creating the keyring file, see 3. Optionally, specify encryption options in prconfig.xml above.