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

Note: The platform cipher is tenant-qualified, and each tenant can have its own Platform cipher. If a platform cipher is activated in a shared tenant environment, all tenants have the same platform cipher.
  1. Create a keystore to reference the Customer Master Key that is stored in the Amazon Web Services Key Management Service (AWS KMS). For more information, see Creating a Keystore data instance, step 6, section Amazon Key Management Service (KMS).
  2. Click Designer Studio > System > Settings > Data Encryption.
  3. Select Platform cipher to encrypt data with the default cryptographic algorithm that is used by Pega Platform.
  4. 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.
  5. Click Activate to start using your keystore for encryption purposes.
  6. On the Warning dialog box that informs you about the changed encryption keystore, click Apply to confirm the keystore activation.
  7. In the Explorer panel, click Records > SysAdmin > Agents.
  8. In the RuleSet Name column, click Pega-IntegrationEngine.
  9. 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 they key is disabled or selected for deletion, the agent logs a security alert in the SECURITYALERT log file.
  10. 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.
  11. Optional: Create an Amazon Cloud Watch Alarm that informs you if the Customer Master Key that is being used is pending for deletion. For more information, see Creating an Amazon CloudWatch Alarm to Detect Usage of a Customer Master Key that is Pending Deletion.