Encryption in Pega Platform
Data encryption in Pega Platform™ gives sensitive data in your applications an additional layer of security while preserving critical Pega Platform functionality. Data encryption 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 the Pega Platform engine commits changes to the Pega Platform database and Elasticsearch indexes, data encryption occurs. Pega Platform can encrypt two types of data: case data and passwords. The encryption methods for case data and passwords are different.
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.
Case data encryption
Pega Platform supports the following approaches to encrypting case data:
- Class-level encryption – Encryption of the pzPVStream (BLOB) column in the tables that store class instances.
Encryption of the pzPVStream 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. Encryption occurs when Pega Platform saves an instance of the class. Decryption occurs when Pega Platform retrieves and opens an instance. Class-level encryption is unrelated to the encryption that your database software or encryption software provides.
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.
For more information, see Storage stream encryption of selected classes.
- Property-level encryption by using access control policies – You can encrypt any property type by listing it in a PropertyEncrypt access control policy. 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), you need to 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. This feature is available beginning with Pega 7.4.
For more information, see Creating an access control policy.
You can configure the cryptographic algorithm that Pega Platform uses for encryption and decryption for any of these approaches. The following options are available on the Data Encryption landing page:
- A predefined platform cipher that uses the AES256-CBC with PKCS7 Padding cryptographic algorithm and requires no development effort to use.
To use the platform cipher, you need to use keys that are owned and securely managed by your organization, and not by Pega or Pega staff. The keys must employ standard techniques, such as key rotation, to protect your sensitive data. On the Data Encryption landing page, you specify the Keystore rule instance and key information that is used during encryption and decryption. The Keystore class allows you to implement a "bring your own key" (BYOK) approach to encryption of application and internal system data, where you control and manage the master key that is used by Pega Platform for encryption. Supported key management systems include Amazon Web Services Key Management Service (AWS KMS), HashiCorp Vault, Microsoft Azure Key Vault, and Google Cloud KMS. You can also use a data page to define custom access to any other external key management system.
For more information, see Configuring the platform cipher.
- A custom cipher that is a cryptographic algorithm that you define. 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 Pega Global Customer Support staff for 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.
Pega Platform stores and encrypts a variety of passwords. These include operator passwords, passwords for ruleset versions, user IDs and passwords for database connections or command-line utilities, and authentication passwords for services, connectors, agents, and email.
Pega Platform encrypts the following types of passwords:
- Operator passwords (uses the Password property type) – Automatically hashed, no developer actions are required.
- 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 prbootstrap.properties file and in the prconfig.xml file. By default, Pega Platform stores database connection passwords as cleartext in these files. To secure these passwords, you can do the following:
- Generate encrypted passwords for the prbootstrap.properties file by using the PassGen tool.
- Generate encrypted passwords for the prconfig.xml file in a pegarules.keyring file with the KeyringImpl 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.
- Services, connectors, email, and agents – Passwords for integration services and connectors, email, and agents require external authentication, and you must first decide which type of encryption is required.