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:
This section describes how to protect PII with the oracle/pii_security_policy
policy The following topics are described:
Note:
Configure the PII encryption key, then choose where you need to attach theoracle/pii_security_policy
policy as appropriate for your environment.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.
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.
Configure a password CSF key to be used for generating the PII encryption key, as described in Section 7.2.3, "Adding Keys and User Credentials to Configure 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, then the PII encryption key must be present and identical in their respective credential stores.
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-103 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 to Manage and Secure Web Services."
In addition to the steps described in described in Chapter 4, "Attaching Policies to Manage and Secure Web Services," the following sections provided here include use case-specific information:
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.
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
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
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 to Manage and Secure Web Services" 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-103 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
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.
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.
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.
This section describes how to override the oracle/pii_security_policy
attributes using WLST.
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 Section 4.4.3.2, "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 Section 4.4.3.1, "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 Section 4.4.3.2, "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.
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.