You are here: Reference > Rule types > Properties > Property rules - Implementing and using the TextEncrypted type

Properties — Implementing and using the TextEncrypted type

Comparing the Password and TextEncrypted property types

The two types for sensitive Single Value, Value List and Value Group properties are Password and TextEncrypted. Both types produce encrypted (or hashed) values for the property value within the PegaRULES database, and both types offer some degree of security within the user interface.

When choosing which Type value to use, consider these factors:

Implementing the TextEncrypted type

Implementation of a site-specific encryption algorithm requires Java skills and familiarity with the Java Cryptography Extension (JCE) technology. This topic provides an overview for planning purposes. Needed scripts and more detailed instructions are available from Global Customer Support.

1. Create a site-specific cipher. See the instructions in Storage Stream encryption of selected classes.

2. Create one or more properties that use the TextEncrypted type. Complete the General tab:

3. Reference the property normally in other rules.

Comparisons

You can use a TextEncrypted property in expressions, testing for equality or inequality only. Call the standard function rule encryptPropertyValue() to encrypt the comparison value (a constant, a property value, or computed text value) before the comparison. For example:

@encryptPropertyValue("Virginia") == .myEncryptProperty

.myEncryptProperty != @encryptPropertyValue(.pyLabel)

The access when rule test and automatic encryption (or decryption) occur only as users interact with a form. In all other cases, your application must explicitly call the functions.

Caution: Pega 7 Platformallows comparisons other than equality or inequality, but the results are unpredictable.

Type conversions

Pega 7 Platform does not perform automatic type conversions for TextEncrypted properties during Property-Set operations. As a result, it is rarely useful to directly assign an encrypted value to another property, or assign another property value to a TextEncrypted property.

When a TextEncrypted property is set to a value, the system encrypts the value unless it is already encrypted. Consider the following example:

In an activity, a Property-Set method operates on two properties MyEncrypted of type TextEncrypted, and MyText of type Text.

After the first of these three lines executes, the value in property MyEncrypted is encrypted. After the second line, the value in property MyText matches the value of MyEncrypted. No encryption or decryption takes place. After the third line, MyEncrypted holds the encrypted value from "Rosebud." Encryption is implicit.

PropertiesName PropertiesValue
.MyEncrypted =@encryptedPropertyValue("Hello World")
.MyText .MyEncrypted
.MyEncrypted "Rosebud"

Reports

To use a TextEncrypted property as a selection criteria on the Content tab of a report definition rule:

  1. Expose the TextEncrypted property a database column.
  2. Enter the clear text value (or a property reference for the comparison) in the Value field.
  3. Select either Is Equal To or Is Not Equal To for the comparisons.
  4. Enter EncryptTextPropertyValue in the Edit Input field.

Caution: The rule form accepts comparisons other than Is Equal To or Is Not Equal To, but the results are unpredictable.

Services and connectors

If an external system calls a service and sends to Pega 7 Platform a (clear text) value for a field that is mapped to a TextEncrypted property, the value becomes encrypted as soon as it reaches the clipboard.

Responses to service calls and connector requests normally send only the encrypted value. Your application can call the standard function @decryptPropertyValue() to send the decrypted, clear text value, but only in a context when the access when rule is true.

Notes

Do not send an encrypted property value to an external system that expects the clear-text value.

On the Clipboard tool display, the value of a TextEncrypted property is blank.

Except as described here, Pega 7 Platform treats the value of a TextEncrypted property similar to a Text property. Your application can place dates or numbers in the value, but validation does not occur.

Definitions exposed property
Related topics About Access When rules

About Property rules