Table of Contents

Article

Creating a custom cipher in Pega Platform

Pega® Platform provides encryption of sensitive data while the data is at rest. For more information, see Encryption in Pega Platform.

This encryption can be performed using a platform cipher or by using a custom cipher that you define. To implement a custom cipher, you create the cipher class, create a .jar file, and load the .jar into the database.

Prerequisites

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.

Implementing a custom cipher

Follow these steps to implement a custom cipher.

  1. 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. You should end up with jars like the following:

    jsr94-1.0.jar
    pradapter.jar
    prbootstrap-api.jar
    prbootstrap.jar
    prdbcp.jar

  2. Update the prconfig.xml and prbootstrap.properties files in your expanded image directory to include database login credentials, if they are not already present.

  3. Do the following steps to determine which cryptographic capabilities are supported in your environment and to select the algorithm for the custom cipher.
    1. From the scripts directory, run runPega.bat or runPega.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

    2. 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.

  4. Use the PRCipherGenerator tool to generate Java source for your cipher class.

    1. From the scripts directory, run runPega.bat or runPega.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.PRCipherGenerator
      <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.PRCipherGeneratorblowfish/cfb/pkcs5padding 128

      Some examples of transformation, key length, and provider are shown below.

      TransformationKey lengthProvider
      blowfish/cfb/pkcs5padding128 
      blowfish128 
      SKIPJACK/ECB/PKCS7Padding128BC
      DESede/CBC/PKCS5Padding168 

       

    2. Java code is displayed. Copy and save the generated code in a .java file for your custom cipher class. Replace the placeholders with the package name and class name for your custom cipher.
    3. Optional: 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. Caution: You must remove the logging code prior to using the cipher in production, as described in step 11e.


      public byte[] encrypt(byte[] aInput) {
      System.<em>out</em>.println("encrypting");
      return super.encrypt(aInput);
      }

      public byte[] decrypt(byte[] aInput) {
      System.<em>out</em>.println("decrypting");
      return super.decrypt(aInput);
      }

  5. 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.
    Caution: 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.

  6. Compile the cipher class and create a jar file from the command line by using compileAndLoad.bat or compileAndLoad.sh with the following parameters:

    --basedir <path to your .java source folder>
    --driver <database driver jar file>
    --jarfile <name of jar file to output, without path>
    --prweb <path to archives/prweb folder>
    --propfile <path to bootstrap properties file>
    --codeset < "customer" or "pega-enginecode">
    --codesetversion <"06-01-01" for customer codeset; otherwise, the 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.

  7. 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'

  8. Log on to Pega Platform and add the Dynamic System Setting with the following value:
    • 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 Dynamic System Settings.

  9. Restart Pega Platform for your custom cipher to take effect.

  10. Log on to Pega Platform and do the following steps to activate your cipher:

    1. Click Designer Studio > System > Settings > Data Encryption.
    2. Click Custom cipher.
    3. Click Activate.

     

  11. 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.

    1. Create a case type.
    2. Open the Class definition for the case type and select Encrypt BLOB.
    3. From one of the Case portals, create an instance of the case type. Close and redisplay the instance.
    4. Look at the console log. You should see messages that say "encrypting" and "decrypting." These messages are generated from your custom cipher class.
    5. Caution: 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.

     

 

Published March 18, 2014 — Updated March 29, 2019


81% found this useful

Related Content

Have a question? Get answers now.

Visit the Pega Support Community to ask questions, engage in discussions, and help others.