Table of Contents

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.

  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 have files similar to the following:
    • jsr94-1.0.jar
    • pradapter.jar
    • prbootstrap-api.jar
    • prbootstrap.jar
    • prdbcp.jar
  2. Update the prconfig.xml and files in your expanded image directory to include database login credentials, if they are not already present.

  3. Perform 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 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>


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



      <key length>

      <provider> (optional)

      ./ --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/ 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
      Java code is displayed.
    2. 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.

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

      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); }
  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.

    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 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 or pega-enginecode

    --codesetversion 06-01-01 for a customer codeset; otherwise, <relevant engine codeset version>


    <Package and class name in quotes for your cipher source code>

    ./ --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/ --codeset customer --codesetversion 06-01-01 -prprivate "com/yourname/"
    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 values:

    Owning ruleset = Pega-Engine

    Setting purpose = prconfig/crypto/sitecipherclass/default

    Setting value = The qualified class name of your custom cipher.

    Pega-Engine prconfig/crypto/sitecipherclass/default com.yourname.CustomCipherBC

    For more information, see Creating a dynamic system setting.

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

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

    1. Dev 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. Review the console log.

      You should see messages that say encrypting and decrypting. These messages are generated from your custom cipher class.

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

Suggest Edit

Have a question? Get answers now.

Visit the Collaboration Center to ask questions, engage in discussions, share ideas, and help others.