Summary

Resolution

To create and implement an encrypted database password , follow these steps:

1.  Run the runPega script using the PassGen class and cleartext password.
2. Copy the resulting encrypted version of the password.
3. Customize and save the configuration file with the encrypted password.
4. Create an Encrypted Password, using the PassGen Tool.

STEP 1:

Process Commander’s PassGen tool encrypts one or more cleartext passwords into the format expected by the miniboot process, when authenticating to the database.  This tool is introduced in Process Commander V6.1.

The PassGen class cannot be run from the command prompt window because the class resides in the database; instead the class is run using the runPega script which executes a standalone PegaRULES class, out of the database. 

The runPega script is run from a command prompt window with PassGen as one of its arguments. 
There is also Windows version of RunPega.bat and a Unix version of  runPega.ksh script.  For additional details, refer to the runPega Batch Script document. 

The following examples uses the Windows version of the script. 

To run the standalone class PassGen using the runPega script:
• Open a command prompt window.
• Change the directory to the directory in which runPega resides.
• Run the script, supplying the arguments
•  listed below.
To run the script, first collect the information needed for the arguments to the script.  The arguments for the runPega script, with an example of each, are:
 Location of the JDBC driver .jar file:
--driver=E:\EclipseDartmouth\prprivate\libnodist\sqljdbc4.jar
 Location of prweb, the web context root name for PegaRULES:
--prweb=E:\ApacheTomcat6\apache-tomcat-6.0.20\webapps\prweb
 Location of configuration file containing the properties which PegaRULES uses to access the database which holds the engine classes:
--propfile=E:\EclipseDartmouth\prwebj2ee\prxml\broub-prbootstrap.properties
 Standalone class to execute, in this case the PassGen class which generates encrypted passwords:
com.pega.pegarules.pub.PassGen
 Cleartext password to encrypt:
v0601User
Following is an example of running the script with the cleartext password v0601User:
C:\62SP1\scripts>runPega.bat --driver=C:\P2P\Tomcat\lib\ojdbc6.jar --prweb=C:\P2P\Tomcat\webapps\prweb --propfile=C:\P2P\Tomcat\webapps\prweb\WEB-INF\classes\prbootstrap.properties com.pega.pegarules.pub.PassGen p2pusr1

Following is an example of the output of the runPega script above:

'#check' is not recognized as an internal or external command,
operable program or batch file.
Feb 27, 2014 4:12:19 AM com.pega.pegarules.internal.bootstrap.PRBootstrapDataSou
rce
19830421: Loading bootstrap properties from file:///C:\P2P\Tomcat\webapps\prweb\
WEB-INF\classes\prbootstrap.properties
Feb 27, 2014 4:12:20 AM com.pega.pegarules.internal.bootstrap.PRBootstrap
19830421: prbootstrap.properties merged with prbootstrap entries in Data-Admin-S
ystem-Settings
Feb 27, 2014 4:12:20 AM com.pega.pegarules.internal.bootstrap.PRMiniLoader
19830421: Will load phase 2 bootstrap from Pega-EngineCode:06-02-10
Feb 27, 2014 4:12:22 AM com.pega.pegarules.internal.bootstrap.phase2.PRBootstrap
Impl
19830421: PegaRULES base classes will be loaded from the database
Feb 27, 2014 4:12:22 AM com.pega.pegarules.internal.bootstrap.phase2.PRBootstrap
Impl
19830421: PegaRULES signed jar files will be extracted to: C:\Users\ADMINI~1\App
Data\Local\Temp\1\\extractedFiles
Feb 27, 2014 4:12:22 AM com.pega.pegarules.internal.bootstrap.phase2.PRBootstrap
Impl
WARNING: Cannot delete directory: extractedFiles
Feb 27, 2014 4:12:24 AM com.pega.pegarules.internal.bootstrap.phase2.PRBootstrap
Impl
INFO: PRBaseLoader jar path entry = C:\Users\ADMINI~1\AppData\Local\Temp\1\extra
ctedFiles\baseloader\java6
Feb 27, 2014 4:12:24 AM com.pega.pegarules.internal.bootstrap.phase2.PRBootstrap
Impl
INFO: PRBaseLoader jar path entry = C:\Users\ADMINI~1\AppData\Local\Temp\1\extra
ctedFiles\baseloader\java5
Feb 27, 2014 4:12:24 AM com.pega.pegarules.internal.bootstrap.phase2.PRBootstrap
Impl
INFO: PRBaseLoader jar path entry = C:\Users\ADMINI~1\AppData\Local\Temp\1\extra
ctedFiles\baseloader
Feb 27, 2014 4:12:25 AM com.pega.pegarules.internal.bootstrap.phase2.PRBootstrap
Impl
19830421: PegaRULES classes will be loaded from the database
Feb 27, 2014 4:12:25 AM com.pega.pegarules.internal.bootstrap.phase2.PRBootstrap
Impl
INFO: PRAppLoader jar path entry = C:\Users\ADMINI~1\AppData\Local\Temp\1\extrac
tedFiles\apploader
Feb 27, 2014 4:12:25 AM com.pega.pegarules.internal.bootstrap.PRBootstrap
19830421:
============ PegaRULES Bootstrap Configuration ============
           Date: Thu Feb 27 04:12:25 PST 2014
   Java Version: Sun Microsystems Inc. 1.6.0_25
  Configuration: file:/C:/P2P/Tomcat/webapps/prweb/WEB-INF/classes/prbootstrap.p
roperties
Pega-EngineCode: 06-02-10
    ASM Version: -1955653517
       Database: Oracle Oracle Database 11g Enterprise Edition Release 11.1.0.7.
0 - Production
With the Partitioning, OLAP, Data Mining and Real Application Testing options
         Driver: Oracle JDBC driver 11.2.0.1.0
Active CodeSets: customer:06-01-01 at (latest patch)
                 pega-enginecode:06-02-10 at (latest patch)

=============== End Bootstrap Configuration ===============

Pega password generator
1 '088b81b888378c4b2c'

NOTE: Just to be clear – while the PassGen utility is being run, the prbootstrap.properties must contain your clear text database password.  Once the script executes, the clear text database password is replaced with the result returned by the utility. 
When the script is initially run, the prbootstrap.properties file looks like:

com.pega.pegarules.bootstrap.allclasses.dbcpsource=example.oracle
example.oracle.url=jdbc:oracle:thin:@//host:1521/prpc
example.oracle.username=prpc62sp1
example.oracle.password=prpc62sp1
oracle.jdbc.class=oracle.jdbc.OracleDriver

After running the utility, it must be updated it to :

com.pega.pegarules.bootstrap.allclasses.dbcpsource=example.oracle
example.oracle.url=jdbc:oracle:thin:@//host:1521/prpc
example.oracle.username=prpc62sp1
example.oracle.password=088b81b888378c4b2c
oracle.jdbc.class=oracle.jdbc.OracleDriver

STEP 2 : Provide Keyring to prconfig.xml

All that the Step-1 accomplishes is that it allows bootstrap access to the engine classes – in order to start an engine, one needs to provide a key ring to prconfig.xml.  Following is the procedure:

Process Commander’s KeyringImpl tool encrypts a cleartext password into the format expected by the miniboot process when authenticating to the PRPC Rules database.  This tool has been available since Process Commander V4.2 but must be run in a different way as of V6.1.  The following section describes the new process for using KeyringImpl to encrypt the PRPC Rules database password in V6.1.
Step One: Populate the Configuration File
The first step is to populate the prconfig.xml configuration file with the PRPC database cleartext password.  Cleartext is unencrypted and human-readable.
As described in Section 2.1, the prconfig.xml file includes the following four items which are required to access the PRPC database:
• Driver Class: Path to the .jar file of the JDBC driver specific to the type of database used.
• Database URL: Location of the database.
• Database Login Username: Provided in cleartext.
• Database Password: Provided in cleartext or encrypted using the KeyringImpl tool.

To begin this process, the database password must first be stored in cleartext.  Following is an example of the syntax for these four items in the configuration file:

<env name="database/drivers" value="oracle.jdbc.OracleDriver" />
<env name="database/databases/PegaRULES/url"
value="jdbc:oracle:thin:@host:1521:prpc" />
<env name="database/databases/PegaRULES/userName" value="p2pusr1" />
<env name="database/databases/PegaRULES/password" value="p2pusr1" />

In this example the cleartext password is p2pusr1.

Step 3: Determine the Keyring Password

The Keyring password is the password that you enter the first time you run KeyringImpl to create a keyring file; it is also entered in the future to control subsequent changes to the encrypted keyring file. 
It is required to enter this update password in order to make changes to the PRPC database password contained in the keyring file.  Determine this password before you run the KeyringImpl tool.  In the following example, the updated password is p2pusr1.

Step 4: Collect the KeyringImpl Arguments

Collect the following information needed to populate the arguments to KeyringImpl.  The arguments for this tool, with an example of each, are:
1. Location in which to create the pegarules.keyring file which will contain the encrypted password:
C:\P2P\Tomcat\webapps\prweb\WEB-INF\classes\pegarules.keyring
Note:  As of V6.x, one may choose the location of the pegarules.keyring file.  However, the file name cannot be changed.

2. Location of the prconfig.xml configuration file which contains the cleartext PRPC database password:
C:\P2P\Tomcat\webapps\prweb\WEB-INF\classes\broub-prconfig.xml

3. URL of prweb :
C:\P2P\Tomcat\webapps\prweb

Note that, for these arguments, all pathnames are absolute.

Step 5: Collect the runPega Arguments

The KeyringImpl class now resides in the database as of PRPC V6.1, so the command line syntax used in prior versions does not longer work; to assist in running this class, the runPega script creates the correct syntax and runs the standalone class from the database. 

The runPega script is run from a command prompt with KeyringImpl as one of its arguments.  There is a Windows version of RunPega.bat and a Unix version runPega.ksh.  For additional details, see the runPega Batch Script document. 

The following examples uses the Windows version of the script.
The arguments for the runPega script, with an example of each, are:
1. Location of the JDBC driver .jar file:
--driver=C:\P2P\Tomcat\lib\ojdbc6.jar
2. Location of prweb, the web context root name for PegaRULES:
--prweb=C:\P2P\Tomcat\webapps\prweb
3. Location of prbootstrap.properties configuration file containing the properties which PegaRULES uses to access the database which holds the assembled classes:
--propfile=C:\P2P\Tomcat\webapps\prweb\WEB-INF\classes\prbootstrap.properties
4. Standalone class to execute, in this case the KeyringImpl class which generates encrypted passwords:
com.pega.pegarules.exec.internal.util.crypto.KeyringImpl

Step 6: Run the runPega Script Using KeyringImpl

The following examples uses the Windows version of the runPega script. 
To run the standalone class KeyringImpl using the runPega script, follow these instructions:
1. Open a command prompt window.
2. Navigate to the directory in which runPega resides.
3. Run the script, supplying the four arguments described above.

Following is an example of the script, using the example arguments:

c:\62SP1\scripts>runPega.bat --driver=C:\P2P\Tomcat\lib\ojdbc6.jar --prweb=C:\P2
P\Tomcat\webapps\prweb --propfile=C:\P2P\Tomcat\webapps\prweb\WEB-INF\classes\pr
bootstrap.properties com.pega.pegarules.exec.internal.util.crypto.KeyringImpl C:
\P2P\Tomcat\webapps\prweb\WEB-INF\classes\pegarules.keyring C:\P2P\Tomcat\webapp
s\prweb\WEB-INF\classes\broub-prconfig.xml C:\P2P\Tomcat\webapps\prweb

'#check' is not recognized as an internal or external command,
operable program or batch file.
Feb 28, 2014 6:46:58 AM com.pega.pegarules.internal.bootstrap.PRBootstrapDataSou
rce
19830421: Loading bootstrap properties from file:///C:\P2P\Tomcat\webapps\prweb\
WEB-INF\classes\prbootstrap.properties
Feb 28, 2014 6:46:59 AM com.pega.pegarules.internal.bootstrap.PRBootstrap
19830421: prbootstrap.properties merged with prbootstrap entries in Data-Admin-S
ystem-Settings
Feb 28, 2014 6:46:59 AM com.pega.pegarules.internal.bootstrap.PRMiniLoader
19830421: Will load phase 2 bootstrap from Pega-EngineCode:06-02-10
Feb 28, 2014 6:47:01 AM com.pega.pegarules.internal.bootstrap.phase2.PRBootstrap
Impl
19830421: PegaRULES base classes will be loaded from the database
Feb 28, 2014 6:47:01 AM com.pega.pegarules.internal.bootstrap.phase2.PRBootstrap
Impl
19830421: PegaRULES signed jar files will be extracted to: C:\Users\ADMINI~1\App
Data\Local\Temp\1\\extractedFiles
Feb 28, 2014 6:47:03 AM com.pega.pegarules.internal.bootstrap.phase2.PRBootstrap
Impl
INFO: PRBaseLoader jar path entry = C:\Users\ADMINI~1\AppData\Local\Temp\1\extra
ctedFiles\baseloader\java6
Feb 28, 2014 6:47:03 AM com.pega.pegarules.internal.bootstrap.phase2.PRBootstrap
Impl
INFO: PRBaseLoader jar path entry = C:\Users\ADMINI~1\AppData\Local\Temp\1\extra
ctedFiles\baseloader\java5
Feb 28, 2014 6:47:03 AM com.pega.pegarules.internal.bootstrap.phase2.PRBootstrap
Impl
INFO: PRBaseLoader jar path entry = C:\Users\ADMINI~1\AppData\Local\Temp\1\extra
ctedFiles\baseloader
Feb 28, 2014 6:47:03 AM com.pega.pegarules.internal.bootstrap.phase2.PRBootstrap
Impl
19830421: PegaRULES classes will be loaded from the database
Feb 28, 2014 6:47:03 AM com.pega.pegarules.internal.bootstrap.phase2.PRBootstrap
Impl
INFO: PRAppLoader jar path entry = C:\Users\ADMINI~1\AppData\Local\Temp\1\extrac
tedFiles\apploader
Feb 28, 2014 6:47:03 AM com.pega.pegarules.internal.bootstrap.PRBootstrap
19830421:
============ PegaRULES Bootstrap Configuration ============
           Date: Fri Feb 28 06:47:03 PST 2014
   Java Version: Sun Microsystems Inc. 1.6.0_25
  Configuration: file:/C:/P2P/Tomcat/webapps/prweb/WEB-INF/classes/prbootstrap.p
roperties
Pega-EngineCode: 06-02-10
    ASM Version: -1955653517
       Database: Oracle Oracle Database 11g Enterprise Edition Release 11.1.0.7.
0 - Production
With the Partitioning, OLAP, Data Mining and Real Application Testing options
         Driver: Oracle JDBC driver 11.2.0.1.0
Active CodeSets: customer:06-01-01 at (latest patch)
                 pega-enginecode:06-02-10 at (latest patch)

=============== End Bootstrap Configuration ===============

Current "user.dir" (default directory) is: c:\62SP1\scripts
Located PegaRULES logging configuration: file:/C:/P2P/Tomcat/webapps/prweb/WEB-I
NF/classes/Administrator-prlogging.xml
Located PegaRULES (V5.x) configuration: file:/C:/P2P/Tomcat/webapps/prweb/WEB-IN
F/classes/Administrator-prconfig.xml
2014-02-28 06:47:04,725 [                main] [          ] [
 ] (     basic.config.SettingsImpl) INFO    - prconfig.xml merged with prconfig
entries in Data-Admin-System-Settings
2014-02-28 06:47:05,663 [                main] [          ] [
 ] (    internal.cache.RACacheImpl) INFO    - Using RACacheImpl for Rule impleme
ntations with keyBaseLock = true
Enter update password: 2014-02-28 06:47:05,663 [                main] [
 ] [                    ] (    internal.cache.RACacheImpl) INFO    - assembly av
oidance is enabled and will infer SIC entries.
2014-02-28 06:47:05,663 [                main] [          ] [
 ] (ion.internal.PRGenProviderImpl) INFO    - Assembly Version: -1955653517

Database 'pegarules' has url: jdbc:oracle:thin:@10.225.52.198:1521:prpc
pegarules.xml username: p2pusr1
pegarules.xml password: p2pusr1
supply value or blank to leave unchanged or REMOVE to remove value from keyring
Enter keyring password: p2pusr1
Updated keyring file saved to: C:\P2P\Tomcat\webapps\prweb\WEB-INF\classes\pegar
ules.keyring

KeyringImpl-Specific Prompts and Output
To clarify the two passwords you enter and use of the encrypted results, the output of KeyringImpl (bracketed above) is broken out below:
Enter the updated password to be used to control access to the encrypted keyring file.
Enter update password: p2pusr1

Step 7: Remove the Password from the Configuration File

Confirm that the pegarules.keyring file is created successfully in the location specified.  Then, delete the entire line from the prconfig.xml file which refers to the database password:
 <env name="database/databases/PegaRULES/password" value="p2pusr1" />

ENCRYPTING DB PASSWORD FOR PRPCUtils.properties

Step1: Configure prpcUtils.xml to point to the location where the pegarules.keyring is placed(in general the classpath of prpcUtils.properties).

In the below example the file is copied to C:/62SP1/scripts/config/

<!-- JAVA Path for PRPC Engine  -->
<path id="prpc.base.path">
<pathelement location="${load.temp.dir}/WEB-INF/classes/"/>
<pathelement location="C:/62SP1/scripts/config/"/>
<fileset dir="${load.temp.dir}/WEB-INF/lib/">
<include name="*.jar"/>
</fileset>
<pathelement path="${pega.jdbc.driver.jar}"/>
</path>
<path id="prpc.boot.path">
<fileset dir="${load.temp.dir}/lib/boot/">
<include name="*.jar"/>
</fileset>
</path>

Step 2: Then, configure prpcUtils.properties to point to the prconfig.xml and prbootstrap.properties:

Example:
pegarules.config=C:\P2P\Tomcat\webapps\prweb\WEB-INF\classes\prconfig.xml
prbootstrap.config=C:\P2P\Tomcat\webapps\prweb\WEB-INF\classes\prbootstrap.properties

Step 3: Configure the initialization/settingsource in prconfig.xml:
Example:
Add the following tag in prconfig.xml:
<env name="initialization/settingsource" value="merged" />

Step 4:
Delete the password from prpcUtils.properties and leave “pega.jdbc.password=”  property blank as it is configured from the keyring file specified.
Run the import command to import the RAPs configured.
Example:
prpcUtils.bat  import

By the end of this process, there is no password tag in prconfig.xml, the encrypted password is in prbootstrap.properties and blank value for the password property in prpcUtils.properties.