Commerce Secure Attributes
Overview
With Secure Attributes, a Commerce attribute type, data a user inputs is encrypted when it reaches the Oracle CPQ Server and remains encrypted while in memory. The encrypted value remains available to currently active Commerce actions. During this active request processing time, the customer can have the value sent to another application, such as for secure data storage.
In the Oracle CPQ database, the data for Secure Attribute fields will appear as the value “_mask_text” when viewed in XML from Web Services.
With a Secure Attribute field on a Commerce layout, Oracle CPQ can capture a value as it is being entered—while masking the entry as if it were a password—and use the Java RSS encryption standard to encrypt the data, without ever storing the original value in CPQ. Oracle CPQ only stores the masked data, which cannot be converted back to its original value.
While an Oracle CPQ action (such as Save) is active, the encrypted data is temporarily stored in memory. While it is in memory, it can be transferred it to the customer’s database, which will handle data storage, security, and any further encryption and decryption.
Oracle CPQ encryption uses standard Java libraries, including RSA standard and Optimal Asymmetric Encryption Padding. The public key, an SSL certificate with a minimum key length of 2048, must be uploaded to the Commerce Process.
You cannot use Secure Attributes without a Secure Attribute Encryption Key.
If you have a Secure Attribute on a layout, but no Secure Attribute Encryption Key, the following error message appears: “Unable to encrypt secure attribute. Please contact System Administrator.” when the user performs any action.
Public keys are validated and stored in a secure keystore. At runtime, public keys are retrieved from the keystore and used for encryption. The private key should be retained and used to decrypt Secure Attribute values.
Oracle CPQ does not hold the private key; it is retained by the customer’s system.
You cannot migrate public keys between Oracle CPQ environments. The keys can be the same for each environment, but they must be uploaded to each Commerce Process on each environment individually.
Administration
Creating a Secure Attribute for a Commerce Process
- Click Admin to go to the Admin Home Page.
-
Click Process Definition under the Commerce and Documents section.
The Processes page opens.
-
For the Commerce Process for which you want to add a secure attribute, ensure Documents is listed in the Navigation column and click List.
The Document List page opens.
-
For a main or sub-document, ensure Attributes is listed in the Navigation column and click List.
The Attribute List page opens.
-
Click Add.
The Attribute Editor page opens.
-
Enter values in the Label and Variable Name fields.
The Variable Name field populates automatically. Variable names can only contain alpha-numeric characters and underscores. The entry can be changed before saving, but after saving the value is read-only.
- In the Attribute Type drop-down, select Secure Text.
-
Click Add.
The Secure Text Attribute Editor page opens.
- Make any other desired changes and click Update to return to the Attribute List page.
Adding a Secure Attribute to a Commerce Layout
For a user to access and use a Secure Attribute, it must be added to a Commerce layout. For information about adding an attribute to a layout, see the topic Layout Editor Overview.
After changing the layout, deploy the changes to make them active.
Now that you have a Secure Attribute, enable the Commerce Process using that attribute to leverage your encryption software.
Uploading the Encryption Public Key
- Sign in as a FullAccess Host Company admin.
- Navigate to the Process Administration page.
- Click Admin to go to the Admin Home Page.
Click Process Definition under the Commerce and Documents section.
The Processes page opens.
Click the name of the Commerce Process, in the Name column, for which you want to enable secure attributes.
The Process Administration page opens.
-
Next to the Secure Attribute Encryption Key label, click Browse.
The File Upload dialog box appears.
-
Select the public key and click Open.
Last key upload time appears.
The public key must be in the .CER format and equal to 2048 or more bytes. Only one file can be uploaded per process.
After the contents of the public key are validated, the Key value is extracted and saved in the keystore.
Transferring Values from Memory
After a value has been entered into a Secure Attribute field, the encrypted value must be captured from memory before a subsequent action removes the value from memory. For example, the value could be captured and moved to a secure server.
There are several ways to capture the value, but no matter which way you choose, add the capture method to an action to ensure that the value can’t be lost from memory. For example, by adding the capture method to the Save action, you will always capture the value of the Secure Attribute when the Transaction is saved.
Strategies for transferring the captured value to a server include:
- BML function
- Advanced rules that call a BML function
When capturing the value from memory, BML refers to the value’s unique ID (based on the Secure Attribute’s name).
Functional Known Issues
Secure Attributes Lose Value in Mobile
In mobile Commerce, if a user enters a value into a Secure Attribute and then switches to a new tab on the mobile layout before saving the Transaction, the value of the Secure Attribute will be lost without the user being warned.
Workaround: After entering a value in a Secure Attribute while in Mobile Commerce, users should save the Transaction before switching to a new tab on the mobile layout. It is recommended that users save the Transaction immediately after entering a value in a Secure Attribute to avoid any chance of this issue occurring.
Secure Attributes Values Only Available to First Ajax Rules Execution or Save
On a cached Transaction, if a user edits a Secure Attribute and then multiple, separate AJAX rule executions take place before an action is invoked, the Secure Attribute’s encrypted value will only be available to the rules in the first AJAX rule execution to run. Additionally, when a Secure Attribute is edited and then the Transaction is saved, the Secure Attribute’s encrypted value will not be available to subsequent AJAX rule executions.
Workaround: It is recommended not to use a Secure Attribute’s encrypted value in AJAX rules. However, if a Secure Attribute’s encrypted value must be available to an AJAX rule, the AJAX rule should be configured so that it will be executed before another AJAX rule execution or a potential save (both invoked by rules or by the user).
Notes
- Each Commerce Process can have a Secure Attribute Encryption Key. The Keys can be the same for each Commerce Process, or unique to each Commerce Process.
- The Java framework used to support RSA standard and Optimal Asymmetric Encryption Padding is the Java Cryptography Extension (JCE) framework.
- Existing Secure Attributes are not impacted when uploading a public key, either for the first time or any subsequent time.
- Validation of the decrypted data can be performed on your server, but not as the value is entered into CPQ.
- Oracle CPQ is not PCI-compliant, but using one of the transfer strategies you can integrate Oracle CPQ with a PCI compliant system that you build and manage. See the section Transferring Values from Memory, above.
Related Topics
See Also
