8 Protecting Personally Identifiable Information

This chapter describes a solution for protecting Personally Identifiable Information (PII) when outside the control of a security policy. PII refers to Social Security numbers, addresses, bank account numbers, and other similar information that is typically associated with one specific user and must generally be protected.

This chapter includes the following sections:

"Protecting PII Information: Main Steps"
"Using WLST to Override the pii_security_policy Attributes"
"Using the API to Decrypt PII"

8.1 Protecting PII Information: Main Steps

This section describes how to protect PII with the oracle/pii_security_policy policy The following topics are described:

"Determine What PII Data to Protect"
"Compose the XPath Expressions to Protect the PII Data"
"Configure the PII Encryption Key"
"Attach the pii_security_policy Policy"
"Attach the pii_security_policy to SOA Composite"
"Attach the pii_security_policy to JCA Binding"

Configure the PII encryption key, then choose where you need to attach the oracle/pii_security_policy policy as appropriate for your environment.

8.1.1 Determine What PII Data to Protect

Examine the SOAP request and response messages, or the WSDL, and determine what PII data you want to protect. There are two approaches:

Deploy the SOA application and use JDeveloper (or another mechanism) to look at the SOAP messages and determine what you need to protect.

See the SOAP message example in "PII Policy XPath Expressions".
Deploy the SOA application and look at the WSDL of the deployed application to determine what you need to protect.

You can display the WSDL document for the web service endpoint as described in "Viewing the Web Service WSDL Document" in Administering Web Services with Oracle Fusion Middleware.

You need to look at what data is being passed during both the request and response phases. That is, you may need to protect different data during the request and response.

8.1.2 Compose the XPath Expressions to Protect the PII Data

Compose the XPath expressions to protect the PII data in both the request and response messages. See the SOAP message example in "PII Policy XPath Expressions" in Understanding Oracle Web Services Manager for guidance.

You later specify these XPath expressions in the oracle/pii_security_policy in the request.xpath and response.xpath attributes.

8.1.3 Configure the PII Encryption Key

Configure a password CSF key to be used for generating the PII encryption key, as described in "Adding Keys and User Credentials to the Credential Store". The PII encryption key is derived from this password credential.

By default, oracle/pii_security_policy expects a key value of pii-csf-key, but you can change this.

If the web service client and the web service do not share a single credential store, the PII encryption key must be present and identical in their respective credential stores.

8.1.4 Attach the pii_security_policy Policy

Make a copy of the preconfigured oracle/pii_security_policy and then attach the copy to your web service and client. Perform the following steps:

In the navigator pane, expand WebLogic Domain to show the domain for which you need to configure PII. Select the domain.
In the content pane, click WebLogic Domain, then Web Services, and then Policies.
Select the oracle/pii_security_policy policy and make a copy.
Examine the Salt, Iteration, and Key Size settings to make sure the defaults are acceptable, and change as needed. See Table 18-92 for a description of these settings.
Edit the request.xpaths, response.xpaths and other oracle/pii_security_policy configuration properties of the copy. See "Understanding the PII Security Policy" in Understanding Oracle Web Services Manager to specify the XPaths, namespaces, csf.key, and so forth.

Remember that you may need to protect different data during the request and response.

You may prefer to skip this step and instead override the attributes as described in Step 7.
Attach the policy at design time or post-deployment, as described in Chapter 4, "Attaching Policies".

In addition to the steps described in described in Chapter 4, "Attaching Policies", the following sections provided here include use case-specific information:
- "Attach the pii_security_policy to SOA Composite"
- "Attach the pii_security_policy to JCA Binding"
Optionally, use Fusion Middleware Control, WLST, or JDeveloper (or another mechanism) to override request.xpaths and other oracle/pii_security_policy attributes.

See "Understanding the PII Security Policy" to specify the XPaths, namespaces, csf.key, and so forth.

See Chapter 5, "Overriding Policy Configuration Properties" for information on overriding configuration properties.

8.1.5 Attach the pii_security_policy to SOA Composite

You must attach the policy only at the service/reference level, and then to both the client and web service.

Consider the SOA composite represented in JDeveloper shown in Figure 8-1. For this composite, you would attach the policy to both the bpelprocess_1client_ep client and the PartnerLink1 reference. You cannot attach the policy to a component.

Figure 8-1 Where to Attach the pii_security_policy for a SOA Composite

Description of "Figure 8-1 Where to Attach the pii_security_policy for a SOA Composite"

Perform the following steps to view the SOA composite and attach the oracle/pii_security_policy policy.

In the navigator, expand SOA deployments.
Select soa-infra, expand the SOA partition (for example, the default partition) and select the target SOA composite application.

The SOA composite home page displays.
Select the Dashboard tab if it is not already selected.

The Components section of this tab lists the SOA components being used in the composite application, and the Services and References section displays the web service and reference bindings, as shown in Figure 8-2.

Figure 8-2 SOA Composite Application Dashboard Page

Description of "Figure 8-2 SOA Composite Application Dashboard Page"

See "Viewing the Web Services and References in a SOA Composite" in Administering Web Services for additional SOA-specific information.
Attach a copy of the oracle/pii_security_policy policy to both the web service client and the reference binding.

Note:
PII data requires that the composite have both entry and exit points: PII data is encrypted before entry and decrypted before exit.

For example, in Figure 8-2 you would attach the copy to both routePO service and to the WriteApprovalresults reference.

See Chapter 4, "Attaching Policies" for information on attaching policies. Also see "Attaching Policies to Binding Components and Service Components" in Developing SOA Applications with Oracle SOA Suite for additional SOA-specific information.
Examine the Salt, Iteration, and Key Size settings to make sure the defaults are acceptable, and change as needed. See Table 18-92 for a description of these settings.
Use Fusion Middleware Control, WLST, or JDeveloper (or another mechanism) to override request.xpaths, response.xpaths and other attributes.

The PII data for the request and response may be different.

Figure 8-3 shows a sample JDeveloper screen.

Figure 8-3 Overriding request.xpaths Attribute

Description of "Figure 8-3 Overriding request.xpaths Attribute"

Do this for both the web service and client, and ensure that they match.

See "Understanding the PII Security Policy" in Understanding Oracle Web Services Manager to specify the XPaths, namespaces, csf.key, and so forth.

See Chapter 5, "Overriding Policy Configuration Properties" for information on overriding configuration policies.

8.1.6 Attach the pii_security_policy to JCA Binding

You can attach the PII policy to JCA adapters for both SOA and Oracle Service Bus.

See "Managing Service and Reference Binding Components" in Administering Oracle SOA Suite and Oracle Business Process Management Suite for information on attaching the PII policy to JCA bindings.

See "Hiding Personally Identifiable Information in Messages" in Developing Services with Oracle Service Bus for information on how to attach oracle/pii_security_policy to Oracle Service Bus.

8.2 Using WLST to Override the pii_security_policy Attributes

Perform the following steps to override the oracle/pii_security_policy attributes using WLST:

Connect to the running instance of WebLogic Server, as described in "Accessing the Web Services Custom WLST Commands" in Administering Web Services with Oracle Fusion Middleware. Begin a session using the beginWSMSession command, as described in "Attaching Policies Directly Using WLST". For example:
```
wls:/wls_domain/serverConfig> beginWSMSession()

Session started for modification.
```
Select the policy subject that you want to work with. See "Identifying and Selecting the Policy Subject Using WLST".

Remember that you can attach oracle/pii_security_policy only in specific cases, as described in "When Can You Use the PII Policy" in Understanding Oracle Web Services Manager. If you attach the policy to a non-supported location, WLST generates validation errors.
Use the attachWSMPolicy command to attach a copy of the oracle/pii_security_policy to a web service port, as described in "Attaching Policies Directly Using WLST". For example:
```
wls:/base_domain/serverConfig> attachWSMPolicy('oracle/pii_security_policy')
 
Policy reference "oracle/pii_security_policy" added.
```
Override the oracle/pii_security_policy policy attributes. For example, the following command sets the request.xpaths attribute:
```
setWSMPolicyOverride('oracle/pii_security_policy','request.xpaths','//ns1:SSN'
 )
```
Similarly, the following command unsets the request.xpaths attribute:
```
setWSMPolicyOverride('oracle/pii_security_policy','request.xpaths'
 )
```
Write the contents of the current session to the repository using the commitWSMSession() command.

For more information about the WLST commands and their arguments, see "Web Services Custom WLST Commands" in WLST Command Reference for WebLogic Server.

8.3 Using the API to Decrypt PII

It is possible that the encrypted PII might be needed for making some decision. In this case, you must explicitly decrypt the PII with the provided API before it can be used.

For example, assume that a credit card number is marked as PII and is encrypted at the SOA service binding (entry point). If the credit card number is required inside a BPEL process to determine the type of credit card, then you must decrypt the credit card number using the API.

The oracle.security.xmlsec.pii.PIISecurity.java class is provided for this purpose. This class has the following method:

Class: oracle.security.xmlsec.pii.PIISecurity.java
 
/**
     * Converts cipher text string to plain text using password based key
     * derivation algorithm (PBKDF2).
     * 
     * @param ciphertext text to decrypt
     * @param password password for key derivation
     * @param pbkdfAlgo key derivation algorithm which should be PBKDF2
     * @param pbkdfSalt non-null and non-empty salt for key derivation
     * @param pbkdfIteration iteration count for key derivation
     * @param keySize size of key for key derivation
     * @param encAlg data encryption algorithm. it should be in the form:
     *                   "algorithm/mode/padding" for ex. AES/CBC/PKCS5Padding
     * @return plain text
     */
public static String decrypt(String ciphertext, char password[], String
 pbkdfAlgo, String pbkdfSalt, int bkdfIteration, int keySize, String encAlg);

The decrypt method returns the decrypted value of the encrypted PII, but does not update the actual value, which remains encrypted.

For SOA, you can invoke this API using the Java Embedding feature, which is described in "Using Java Embedding in a BPEL Process in Oracle JDeveloper" in Developing SOA Applications with Oracle SOA Suite.

Note:

Do not log the decrypted value of the PII unless you are completely aware of the security ramifications of doing so.