Skip to main content

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


Updated on June 30, 2021

Encryption is a way to protect sensitive data within your application, without affecting the functionality of Pega Platform. Examples of typically encrypted data include Social Security numbers, credit card numbers, account numbers, and addresses.

Note: This guidance is specifically for UI centric applications where all the data is dealt with wholly within the Pega Platform run-time. For example, it would not apply to Pega Marketing or Customer Decision Hub deployments that must perform many asynchronous background processing tasks on the data, including asking relational databases to run SQL queries that make comparisons against data that is stored encrypted by Pega Platform.

You can choose one of the following methods to encrypt case data:

  • Class-level (BLOB) encryption
  • Property-level encryption.

The best practice depends on the capabilities of your application and the amount of data that needs to be encrypted.

Class-level encryption

Class-level (BLOB) encryption occurs when Pega Platform retrieves and opens an instance. Decryption occurs when Pega Platform retrieves and opens an instance.

The difference between class-level (BLOB) and property-level encryption is performance and functionality. BLOB encryption and decryption are more straightforward and efficient than the individual encryption and decryption of a large number of properties that store sensitive case data. BLOB encryption does not, however, encrypt properties that have been exposed as columns for reporting, properties that are stored on the clipboard when you open a case, or properties that are stored in secondary data stores such as the Elasticsearch index.

Encryption of the pzPVStream (BLOB) column for one class does not affect the pzPVStream column of other classes, even those that occupy the same table in the Pega Platform database.

For more information, see Storage stream encryption of selected classes.

Property-level encryption

Note: Do not configure properties for encryption if they are used for data segmentation purposes in Pega Marketing or Customer Decision Hub. Segmentation cannot be accomplished on encrypted values.

By using access control policies, you can encrypt any property type by listing it in a PropertyEncrypt access control policy. You can define such policies on Work-, Data-, and Index- classes. The property is encrypted in the database, clipboard, logs, and search indexes. If there is no PropertyRead policy that obfuscates the property, then the decrypted property value is visible to the user in a UI control. Properties specified in a PropertyEncrypt policy are encrypted unconditionally. Define PropertyRead policies to obfuscate or mask these values depending on who is viewing them. To get the cleartext value outside of UI controls (for example, in the background processing of cases), call the appropriate decryption method. You can define PropertyEncrypt access control policies for properties that are optimized for reporting only if the property type is equal to Text. To define a report filter for an encrypted property that is not Text, convert the values to text and store them in a Text property that is encrypted and optimized.

For more information, see Creating an access control policy.

Data Encryption

Data encryption in Pega Platform provides the following benefits:

  • Gives sensitive data in your applications an additional layer of security while preserving critical Pega Platform functionality
  • Makes it easier to comply with privacy policies, regulatory requirements, and contractual obligations for handling private data

Encryption uses a cipher algorithm to turn readable text (plaintext) into an unreadable secret format (ciphertext). The ciphertext can be decrypted only through the use of the correct encryption key. Every time that Pega Platform commits changes to the Pega Platform database and Elasticsearch indexes, data encryption occurs. Encryption is unrelated to the encryption that your database software or encryption software provides.

Decide what data needs to be encrypted and which encryption method to use before your application goes into production. If you decide to encrypt certain properties or change the encryption method after your application is in production, you must write activities to encrypt or reencrypt the existing data.

To avoid loss of encrypted data, do not delete data from the pr_data_admin_sec* tables.

Custom Cipher

Using a custom cipher also makes it difficult to support best practices such as key rotation, which is a complex task that requires maintaining information about every key ever used to encrypt data. Mistakes can easily lead to loss of data.

Defining a custom cipher requires that you define the Java classes that need to be installed on your Pega cluster.

This process is complex and requires very careful testing and assistance from Global Customer Support staff. Custom ciphers are not supported for use by Pega Cloud customers. Using a custom cipher also makes it difficult to support best practices such as key rotation, because the encryption key is compiled into a .jar file. If the key changes after production data is encrypted, you might not be able to decrypt the data without making significant changes to the custom cipher.

Use a custom cipher only when your organization's security standards require the use of a cipher that is different from the Pega Platform cipher.

For more information, see Creating a custom cipher in Pega Platform.

Encryption key management

When you use BYOK, your master key is never directly accessed or stored by Pega Platform, using a two-tier encryption strategy.

Pega Platform creates an initial customer data key (CDK), and other CDKs based on the key rotation policy that you specify on the Data Encryption landing page. The CDKs are stored in encrypted format in the Pega database, and never appear in clear text on the clipboard or anywhere in memory that is accessible by you or your application.

On node start up, your KMS is called to decrypt the CDKs stored in the Pega database, using your master key. The CDKs are then reencrypted using a key generated by Pega Platform, which is not accessible to you or within your application. The reencrypted CDKs are only decrypted within Pega Platform as needed during operations to encrypt or decrypt your data.

Protection of other sensitive data

Pega creates and stores cookies on client browsers to assist in authenticating client requests. The cookie does not contain any operator-specific or case-specific data, only a randomly generated session ID. By default, this cookie is also encrypted using a Pega generated key. You can replace this key by configuring BYOK for the master key that is used to encrypt cookies on the Data Encryption landing page, in the section titled System data encryption.

For more information, see Configuring the platform cipher.

Passwords that are manually entered during development or application use (for example, login passwords and ruleset passwords) are not encrypted, but are stored as hashes, using the bcrypt hashing algorithm, in the Pega database.

Most other types of sensitive configuration data will be encrypted by using the BYOK feature if you configure it, otherwise these will be encrypted using the internal Pega Platform cipher and Pega Platform-generated master key, for example:

  • Authentication passwords for services, connectors, agents, and email.
  • Client secrets in keystores, authentication services, and authentication profiles.

However, user IDs and passwords for database connections or command-line utilities are not encrypted by using BYOK. Instead, they are encrypted by using an internal Pega Platform cipher and Pega Platform-generated master key that is not accessible by you or your application.

Encryption of Passwords and Other Secrets

Pega Platform stores and automatically encrypts a variety of passwords and other sensitive configuration data, such as:

Operator passwords

Operator passwords uses the Password property type. Automatically hashed, no developer actions are required.

Ruleset version passwords

Ruleset version passwords uses the Password property type. Automatically hashed, no developer actions are required.

Database connection passwords

When you run any of the command-line utilities, you must provide database credentials in the file and in the prconfig.xml file. By default, Pega Platform stores database connection passwords as clear text in these files. To secure these passwords, you can do the following:

  • Generate encrypted passwords for the file by using the PassGen tool.
  • Generate encrypted passwords for the prconfig.xml file in a pegarules.keyring file with the Keyring tool.

For more information, see How To Encrypt Database Passwords Using a JCE Keyring file.

Rule resolution passwords

Some command-line utilities require that you specify a Pega Platform user name and password for rule resolution. You can store these Pega Platform credentials in the same key ring file that stores the database connection password for the prconfig.xml file.

Passwords for external system authentication

Passwords for integration services and connectors, email and database connectivity, and agents require external authentication. Pega stores encrypted passwords using key information controlled by Pega and are decrypted as needed for authenticating with these external systems.

Sensitive information in configuration data

Pega encrypts certain configuration information, such as authentication profile data, keystore instances, by using key information also controlled by Pega Platform.

Note: By default, encryption uses key information that is controlled by Pega Platform. If your application data encryption is configured by using BYOK, then encryption of this data is also accomplished by using the BYOK configuration.
  • Encrypting application data

    Help secure your data by selecting the type of encryption to use in your application to encrypt and decrypt passwords, properties, and BLOBs. When you encrypt sensitive data at the application level, it inherently protects data stored in your application, and making it so only authorized parties can read it.

Have a question? Get answers now.

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

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best. is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us