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.
   Result: 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 prbootstrap.properties 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 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.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.
   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.
      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);
      }

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.

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

   --codesetcustomer or pega-enginecode

   --codesetversion06-01-01 for a customer 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.
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.

   For example:

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