Creating a custom cipher
Pega Platform provides encryption of sensitive data while the data is at rest. This encryption can be performed using a platform cipher or by using a custom cipher that you define.
Before you implement a custom cipher, ensure that you have completed the following requirements:
- Pega Platform is installed.
- The Pega Platform distribution image is extracted to a local hard drive where you have write permission, and prweb.jar has been expanded.
- You have update permission for the Pega rules database.
- The JAVA_HOME environment variable is set.
To implement a custom cipher, you create the cipher class, create a
.jar
file, and load the .jar
into the
database. Follow these steps to implement a custom cipher.
- On the hard drive where you extracted the distribution image, remove the build
name suffix from the jar file names in the
prweb\WEB-INF\lib
folder.Result: You should have files similar to the following: jsr94-1.0.jar
pradapter.jar
prbootstrap-api.jar
prbootstrap.jar
prdbcp.jar
- Update the
prconfig.xml
andprbootstrap.properties
files in your expanded image directory to include database login credentials, if they are not already present. - Perform the following steps to determine which cryptographic capabilities are supported in your environment and to select the algorithm for the custom cipher.
- From the scripts directory, run
runPega.bat
orrunPega.sh
with the following parameters:--driver<path to the database driver file>
--prweb<path to the archives/prweb folder>
--propfile<path to the bootstrap properties file>
com.pega.pegarules.exec.internal.util.crypto.JCECapabilities
For example: ./runPega.sh --driver /Users/yourname/Develop/apache-tomcat-8.0.33/lib/postgresql-9.4.1208.jar --prweb /Users/yourname/Develop/PegaPlatformDistro/archives/prweb --propfile /Users/yourname/yourname-prbootstrapX.properties com.pega.pegarules.exec.internal.util.crypto.JCECapabilities
- The output from step 3a is a list of supported capabilities. From that list, choose an algorithm, key length, and provider.The algorithm you select must have both a Cipher and KeyGenerator of the same name listed in the output. Depending on your algorithm, you might also specify a mode and padding for your transformation. Refer to the javadoc for javax.crypto.Cipher for more information on transformations.Consult your security administrator to ensure that your algorithm, key length, and provider satisfy your company's security policies.If the combinations available do not yield a key length of sufficient strength for your needs, you may need to update your Java Cryptography Extension (JCE) jurisdiction policy file to include unlimited key strength. For further details on the jurisdiction policy file, see the JCE documentation.If you update the jurisdiction policy file, run the JCECapabilities utility again to view the new combinations of algorithm, key length, and provider.
- From the scripts directory, run
- Use the PRCipherGenerator tool to generate Java source for your cipher class.
- From the scripts directory, run
runPega.bat
orrunPega.sh
with the following parameters:--driver<path to the database driver file>
--prweb<path to the archives/prweb folder>
--propfile<path to the bootstrap properties file>
com.pega.pegarules.exec.internal.util.crypto.JCECapabilities
<transformation>
<key length>
<provider> (optional)
For example: ./runPega.sh --driver /Users/yourname/Develop/apache-tomcat-8.0.33/lib/postgresql-9.4.1208.jar --prweb /Users/yourname/Develop/PegaPlatformDistro/archives/prweb --propfile /Users/yourname/yourname-prbootstrapX.properties com.pega.pegarules.exec.internal.util.crypto.PRCipherGenerator blowfish/cfb/pkcs5padding 128
Some examples of transformation, key length, and provider are shown below.
Transformation Key length Provider blowfish/cfb/pkcs5padding
128
blowfish
128
SKIPJACK/ECB/PKCS7Padding
128
BC
DESede/CBC/PKCS5Padding
168
Result: Java code is displayed. - Copy and save the generated code in a
.java
file for your custom cipher class and replace the placeholders with the package name and class name for your custom cipher. - You can create a test version of your cipher that contains logging statements that you can use to verify the implementation. To create a test version of your cipher, add the following two methods.
Note: You must remove the logging code prior to using the cipher in production, as described in step 11e. public byte[] encrypt(byte[] aInput) { System.out.println("encrypting"); return super.encrypt(aInput); } public byte[] decrypt(byte[] aInput) { System.out.println("decrypting"); return super.decrypt(aInput); }
- From the scripts directory, run
- Determine which codeset and version will hold your custom cipher.It is recommended that you use the customer codeset. However, you can choose to use a Pega Platform engine codeset.
Note: If you use a Pega Platform engine codeset and you later upgrade your engine version, you will have to migrate your cipher to the new version. - Compile the cipher class and create a jar file from the command line by using
compileAndLoad.bat
orcompileAndLoad.sh
with the following parameters:--basedir<path to your .java source folder>
--driver<path to the database driver file>
--jarfile<name of the jar file to output, without path>
--prweb<path to the archives/prweb folder>
--propfile<path to the bootstrap properties file>
--codeset
customer
orpega-enginecode
--codesetversion
06-01-01
for acustomer
codeset; otherwise, <relevant engine codeset version>--prprivate
<Package and class name in quotes for your cipher source code>
For example: ./compileAndLoad.sh --basedir /Users/yourname/Develop/Projects/SiteCipherProject/src --driver /Users/yourname/Develop/apache-tomcat-8.0.33/lib/postgresql-9.4.1208.jar --jarfile MyCustomCipher --prweb /Users/yourname/Develop/PegaPlatformDistro/archives/prweb --propfile /Users/yourname/yourname-prbootstrap.properties --codeset customer --codesetversion 06-01-01 -prprivate "com/yourname/CustomCipherBC.java"
Note: This command is very sensitive to spaces. Follow the example shown above. - Verify that the generated .jar file has been imported to the Pega Platform engine classes database table by entering the
following SQL query against the rules schema:
select pzjar, pzpackage, pzclass, pzlastmodified, pzcodeset, pzcodesetversion,pzpatchdate from <rules-schema>.pr_engineclasses where pzjar like '<jar file name>.jar'
- Log on to Pega Platform and add the Dynamic System
Setting with the following values:
Owning ruleset = Pega-Engine
Setting purpose = prconfig/crypto/sitecipherclass/default
Setting value = The qualified class name of your custom cipher.
For example: Pega-Engine prconfig/crypto/sitecipherclass/default com.yourname.CustomCipherBC
For more information, see Creating a Dynamic System Setting.
- Restart Pega Platform for your custom cipher to take effect.
- Log on to Pega Platform and perform the following steps
to activate your cipher:
- .
- Click Custom cipher.
- Click Activate.
- If you added logging statements to your cipher in step 4c, verify that
encryption is working for your instance of Pega Platform.If you did not add logging statements, skip this step.
- Create a case type.
- Open the Class definition for the case type and select Encrypt BLOB.
- From one of the Case portals, create an instance of the case type. Close and redisplay the instance.
- Review the console log.You should see messages that say
encrypting
anddecrypting
. These messages are generated from your custom cipher class. - Prior to going into production, remove any logging statements from your cipher code and repeat steps 5 through 8 so that your log does not grow excessively.
Previous topic Forcing data key rotation in the platform cipher Next topic Configuring a custom cipher