Implementing and using the TextEncrypted property type
Value List, and
properties can be encrypted by using the
TextEncrypted encryption types. 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. Another encryption type,
can be used for all properties when your implementation uses attribute-based access control.
PropertyEncrypt encryption type is preferred to the
TextEncrypted type described here, as it takes effect more broadly and
can be used for all property types.
If you have a legacy implementation that uses the
consider these factors:
Passwordtype requires no advanced configuration or Java skills to set up. Several standard properties implement this type; for example, the property Data-Admin-Operator-ID.pyPwdCurrent. Pega Platform applies the one-way MD5 algorithm to this value, which is never sent to any external system.
TextEncryptedtype requires one-time Java coding of encryption Java functions of your choice to implement a Public API Interface.
forms, the display of a value of a
Passwordproperty is a string of asterisks, for all users, in all situations. The Password value is never decrypted. In contrast, the value of a
TextEncryptedproperty can appear in clear text or as asterisks, depending on the runtime outcome of an access when rule ( Rule-Access-When rule type). Thus your application can make the clear-text value visible to specific users, or on certain reports, or during specified time periods.
Passwordproperties are initially added to the clipboard as unencrypted, clear text values. The system computes the hashed value only as the page is committed to the PegaRULES database. Thereafter, the hashed value appears in both the clipboard and the database row. Properties for passwords for the Operator IDs, rulesets, and ruleset versions are of mode
TextEncryptedvalues are always encrypted on the clipboard and in server-to-database network messages.
Implementing the TextEncrypted type
1. Choose and apply the type of cipher for your implementation of Pega Platform. Choose from platform cipher or custom cipher.
2. Create one or more properties that use the
Complete the General tab:
Set the Type to
- Set the Control field to ShowTextEncryptedPropertyValue.
In the Access When field, enter the second key part (When Name) of a Rule-Access-When
rule that determines whether the property value appears as decrypted cleartext or
asterisks. The Rule-Access-When rule can depend on any properties in the Applies To class,
plus properties on the
pxRequestorpage or other clipboard pages.
3. Reference the property normally in other rules.
TextEncryptedproperty for reporting, make the exposed column size greater than the number of characters of your longest cleartext value to avoid truncation of the exposed values. The required size of a
TextEncryptedproperty depends on your cipher. In most cases, for 64 characters of cleartext, 255 characters are adequate for the encrypted value.
You can use a
property in expressions, testing for equality
or inequality only. Call the standard function rule
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.
does not perform automatic type conversions for
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
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
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.
|.MyEncrypted||[email protected]("Hello World")|
To use a
property as a selection criteria on the Content
tab of a report definition rule:
TextEncryptedproperty a database column.
- Enter the clear text value (or a property reference for the comparison) in the Value field.
Is Equal Toor
Is Not Equal Tofor the comparisons.
- Enter EncryptTextPropertyValue in the Edit Input field.
Is Equal Toor
Is Not Equal To, the results are unpredictable.
Services and connectors
If an external system calls a service and sends to
(clear text) value for a field that is mapped to a
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.
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
Except as described here,
treats the value of a
property similar to a
Your application can place dates or numbers in the value, but validation does not occur.
Previous topic More about Properties Next topic JavaServer Pages tags