Configuring the platform cipher

Use the platform cipher to encrypt and decrypt sensitive data in your application without the need to create and code your own custom cipher. By using the platform cipher, you do not need to share knowledge about sensitive data in your application with Pega staff, because their assistance is not required to install a cipher.

1. Create a keystore to reference the Customer Master Key (CMK) that is stored in the Amazon Web Services Key Management Service (AWS KMS) or another key management service. For more information, see Creating a keystore.
2. In the header of Dev Studio, click Configure > System > Settings > Data Encryption.
3. To encrypt application data, in the Application data encryption section, do the following steps:
   1. Select Platform cipher to encrypt data with the default cryptographic algorithm that is used by Pega Platform.
   2. In the Keystore field, press the Down Arrow key, and then select the name of your keystore.
      CAUTION:

      • To change the Customer Master Key, you need to create a new Keystore instance, and then reference it on the Data Encryption landing page.
      • When changing the keystore, you must activate the new keystore before you delete or disable the currently active Customer Master Key. Otherwise, the data encrypted by the old keystore cannot be reencrypted by the new keystore.
   3. Click Activate to start using your keystore for encryption purposes.
4. To encrypt system data, in the System data encryption section, select the source of the master key.
   • Pega Platform
   • Keystore
   1. If you select Pega Platform, then also click Regenerate.
   2. If you select Keystore, then in the Select keystore field, press the Down Arrow key, select a keystore that is sourced from a data page, and click Activate.
5. On the Warning dialog box that informs you about the changed encryption keystore, click Apply to confirm the keystore activation.
6. In the navigation panel, click Records > SysAdmin > Agents.
7. In the RuleSet Name column, click Pega-IntegrationEngine.
8. In the Schedule Agents section, select the Enable check box for the pyValidateKMSMetadata agent. This agent checks whether the Customer Master Key that is stored in AWS is available. If the key is disabled or selected for deletion, the agent logs a security alert in the SECURITYALERT log file.
9. Optional: To receive an email notification about an inactive Customer Master Key, modify the pyHandleKMSValidationError activity.
   1. In the first step, in the Method field, press the Down Arrow key and select Property-Set.
   2. Click the Collapse method parameters icon and enter the following method parameters.
      • Param.To - Enter the email recipient.
      • Param.From - Enter the sender email.
      • Param.Subject - Enter the title of the email.
      • Param.Message - Enter the message that the email provides.
      • Param.Password - Enter the password to the sender email.
      • Param.smtpHost - Enter the sender email server address.
      • Param.HTMLmessage - Enter "true" to send the message as HTML. Enter "false" to send the message in plain text.
   3. Click Add a step.
   4. In the Method field, press the Down Arrow key and enter Call SendEmailNotification.
   5. Select the Pass current parameter page check box.
   6. Click Save.
10. Optional: If you are using an AWS KMS, you can create an Amazon CloudWatch Alarm that informs you if the Customer Master Key that is being used is pending for deletion. For more information, see the Amazon article Creating an Amazon CloudWatch Alarm to Detect Usage of a Customer Master Key that is Pending Deletion.