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.

To configure ciphers, you must have the pxCanManageDataEncryption privilege, which is included in the PegaRULES:SecurityAdministrator role.
  1. Create a keystore to reference the Customer Master Key (CMK) that is stored in the Amazon Web Services Key Management Service (AWS KMS). For more information, see Creating a keystore and Configuring an Amazon Key Management Service (KMS) keystore.
  2. Click Configure > System > Settings > Data Encryption.
  3. 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:
      • If you want 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. In the System data encryption section, select the source of the master key.
    • Pega Platform
    • Keystore
    1. If you selected Pega Platform, in the Encryption cipher field, press the Down Arrow key, select the encryption cipher, and click Regenerate.
    2. If you selected Keystore, in the Select keystore field, press the Down Arrow key, select the keystore, 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: 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.