Skip to main content


         This documentation site is for previous versions. Visit our new documentation site for current releases.      
 

Configuring the platform cipher

Updated on March 15, 2022

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.

Before you begin: 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) or another key management service. For more information, see Creating a keystore.
  2. In the header of Dev Studio, click ConfigureSystemSettingsData 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. In the System data encryption section, encrypt system data by selecting the source of the master key:
    ChoicesActions
    Pega PlatformSelect Pega Platform, and then click Regenerate.
    Keystore
    1. Select Keystore,
    2. In the Select keystore field, press the down arrow key, select a keystore that is sourced from a data page, and then 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 RecordsSysAdminAgents.
  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.

Related articles

Viewing keystore usage history in the platform cipherForcing data key rotation in the platform cipherEncrypting application dataEncrypting application data by using a custom key management serviceEncrypting system data by using a custom key management service

Tags

Pega Platform 8.7 Security

Have a question? Get answers now.

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

Visit the Support Center

Did you find this content helpful?

Yes
No

Want to help us improve this content?
Suggest an edit

We'd prefer it if you saw us at our best.

Pega.com is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us