Working with the PegaRULES Database
How to encrypt the Storage Streams of selected classes

Basics

Optionally, you can enable configuration of the Storage Stream or BLOB (pzPVStream ) column for rows of the PegaRULES database corresponding to specific classes.

Encryption occurs when PRPC saves an instance of the class; decryption occurs when PRPC retrieves and opens an instance. This feature is unrelated to any encryption of the database provided through database software or software provided by others.

Implementation of a site-specific encryption algorithm requires Java skills and familiarity with Java Cryptography Extension (JCE) technology. This topic provides an overview for planning purposes. Needed scripts and more detailed instructions are available on request from Global Customer Support.

1. Build a site-specific encryption cypher

PRPC does not include encryption software. The sample Java class PRCipherSampleBF exposes the SunJCE Java Cryptography Extension provider (in your system's JDK) of the Blowfish algorithm. The sample is provided only to demonstrate the capability and assist in development. To ensure the security and uniqueness of your encryption implementation, do not implement this sample.

1. Obtain the runPega and compileAndLoad script from Global Customer support.
2. Determine the choices available for your site-specific cipher, by running the JCE Capabilities tool (part of the runPega script) from the command prompt.
3. The results depend on your application server and JVM version. Based on the results, choose a combination of cipher, key length, and provider. 
4. Run PRCipherGenerator to create a class skeleton. 
5. Complete the skeleton class using the Blowfish samples provided by Pegasystems. (Your final implementation should use the same signature as this sample, but a custom coding not disclosed to Pegasystems.)
6. Add the new class to the appropriate .jar file. Use the compileAndLoad script to upload the compiled class to the PegaRULES database. You can't use the Import gadget for this.
7. Update the prconfig.xml file (on each node) so that the sitecipher class entry matches your new class :

<env name="crypto/sitecipherclass" value="YYYY.ZZZZ.QQQQ" />

where YYYY.ZZZZ is the name of your package and QQQQ is the name of your class, using the same values as above in the step 1.5 Complete the skeleton class...

9. To make the prconfig.xml setting take effect, stop and restart (or redeploy) the system.

As an alternative to the prconfig.xml file, you can use Dynamic System Settings to configure your application.
See How to create or update a prconfig setting.

2. Update class forms

1. Open each Class form that is to hold instances with encrypted Storage Stream values. Select the Encrypt BLOB? checkbox on the Basic tab. Save the Class form. (This checkbox affects only the BLOB column for instances of one single class.)
2. Repeat, updating this checkbox for each class to be affected.
3. Encryption is enabled. Your application can create instances of the class normally.

Notes and limitations

If a ZIP archive contains instances of classes with encrypted Storage Stream values, the ZIP archive can only be imported to another system that uses the identical site-specific cipher.

CPU processing for encryption and decryption can affect overall system performance, depending on data volumes and algorithms. To help you assess the impact, six Decimal properties on the Full Details display of the Performance tool record times and counts. (Elapsed time and CPU times are components of other statistics that measure database times. CPU statistics are available only for Windows platforms. All times are in seconds.)

• pxEncryptCPU — CPU time required to encrypt Storage Stream contents
• pxDecryptCPU — CPU time required to decrypt Storage Stream contents
• pxEncryptElapsed — Elapsed time required to encrypt Storage Stream contents
• pxDecryptElapsed — Elapsed time required to decrypt Storage Stream contents
• pxEncryptCount — Number of Storage Streams encrypted
• pxDecryptCount — Number of Storage Streams decrypted

Encryption of the Storage Stream column for one class does not affect the Storage Stream of other classes, even those occupy the same table in the PegaRULES database.

	prconfig.xml file, Storage Stream
	About Class rules Performance tool — Full details display

Working with the PegaRULES database