Section 2.

Introduction to message-level security

Transport-level security (e.g. HTTPS) is a point-to-point security model where the channel is
protected between two parties. However, many times the service consumer and service
provider are separated by intermediaries (e.g. an Enterprise Service Bus). In situations like
these, message-level security can provide an end-to-end security solution. Figure 1 depicts
how message-level security can provide an end-to-end security solution even if
intermediaries are between the consumer and provider. The secret is that with message-
level security, you can encrypt the message using the public key of the final destination. In
this way, only the intended receiver can decrypt the message. Additionally, by encrypting the
message and storing the encrypted data into the message, you can store the message on
the file system for asynchronous communication and later decrypt it when the receiver is
available. These are just a few of the reasons that message level security is often being
applied to secure Web services.

Figure 1. Comparison of transport level security and message level security (see
enlarged Figure 1)

Web Services Security (WS-Security) is an OASIS standard to describe how to implement

message-level security with Web services. Specifically, WS-Security describes how you can
add confidentiality (e.g. encryption), integrity (e.g. digital signatures), and authentication (e.g.
username and password) to a SOAP message. In most cases, XML encryption and XML
signatures are the mechanisms for securing the message; WS-Security describes how to
use these technologies with Web services to provide message-level security as well as
providing a framework for propagating security identities. Figure 2 provides an example of
how message-level security looks in a SOAP message. In this tutorial, you learn how to build
SOAP messages that get encrypted and signed to provide messages like the one shown in
Figure 2.

Figure 2. Example of message-level security of a SOAP message (see enlarged Figure

2)

Section 3. Creating and consuming JAX-WS Web

services
In this section, you create a simple HelloWorld Web service using a JAX-WS annotation
and the Rational Application Developer tooling. Then you use the Rational Application
Developer tooling to generate a proxy client to invoke the Web service. Finally, you test your
service provider (i.e. Web service) running on the WebSphere Test Environment (WTE) that
comes packaged with Rational Application Developer. In your testing, you examine the
SOAP messages (i.e. request and response) as they appear on the network.
Creating a JAX-WS Service Provider
In this tutorial, you will use a dynamic Web project to contain the Web service. Start by
creating a dynamic Web project and a plain old Java object (POJO) for your service provider
as shown in the following steps:
1. Start Rational Application Developer 7.5.2. Click File > New > Dynamic Web
Project, then enter HelloWorldProject as the project name, as shown in Figure
3.
 Figure 3. Create a dynamic Web project

2. Accept the defaults for the other fields, then click the Finish button. Choose No if
prompted to change to the Web perspective. For this tutorial, you will use the Java
EE perspective.
3. Select the HelloWorldProject project in the project explorer view. Right-click and
select New > Class, which brings up a Java Class wizard as shown in Figure 4.
 Figure 4. Create new Java class wizard

4. Enter com.ibm.dwexample for the package name and HelloWorldProvider as

the class name , and click the Finishbutton.
5. Copy the code from Listing 1 into the HelloWorldProvider.java file and save the
file.

Listing 1. HelloWorldProvider.java
package com.ibm.dwexample;
import javax.jws.WebService;

@WebService
public class HelloWorldProvider {
public String sayHello(String msg) {
System.out.println("[helloworld provider] Hello " + msg);
return "Hello " + msg;
}
 }

That’s it! A simple POJO with the @WebService annotation is all that is necessary to create
a JAX-WS Web service.
Now that you have created a Web service, you can use Rational Application Developer to
deploy your service onto the WebSphere Test Environment (WTE).
To deploy your service:
1. Select the HelloWorldProvider.java file that contains the code from Listing 1. Right-
click and choose Run As > Run on Server, which displays the Run On Server
wizard in Figure 5.

Figure 5. Run On Server wizard

2. Select the Choose an existing server radio button, and then select WebSphere
Application Server V7.0 at localhost. If you do not have a WebSphere Application
Server V7 server defined, you can define a new one by selecting Manually define a
new server followed by expanding the IBM folder and selecting the WebSphere
Application Server v7.0 server.
3. Click the Finish button to deploy and start the Web service on WebSphere
Application Server.
At this point, you have created a simple JAX-WS Web service, deployed it to WTE, and
started the service. Next we’ll create a JAX-WS client that can invoke the running Web
service.
Back to top
Creating a JAX-WS service consumer
Rational Application Developer V7.5.2 provides a wizard for generating a client from a JAX-
WS Web service. In this tutorial, you use a standalone Java client as your service consumer.
Therefore, you begin by creating a simple Java project that will contain your JAX-WS client
proxy as well as your client code that uses the generated client proxy.
To create a Java project:
1. Using Rational Application Developer select File > New > Other. Locate the Java
Project wizard and click Next.
2. In the New Java Project wizard, enter HelloWorldConsumer as the project name
and click Finish as shown in Figure 6. If prompted to switch to the Java perspective,
choose No to stay in the Java EE perspective.
 Figure 6. New Java Project wizard

Now that you have a Java project to hold the JAX-WS proxy classes that are
generated by Rational Application Developer, you can use Rational Application
Developer to generate the client proxy classes.
3. Expand the Services folder of the HelloWorldProject Web project. Right-click
the{http://dwexample.ibm.com/}HelloWorldProviderService service and
choose Generate > Client as shown in Figure 7.
 Figure 7. Generate the Web service client

4. Ensure the Web service runtime value in the configuration section is set to IBM
WebSphere JAX-WS, and Java Proxyis selected as the client type.
5. Click the Client project: link to change the client project to use the standalone Java
project you created above, as shown in Figure 8.

Figure 8. Web Service Client wizard

6. Choose HelloWorldConsumer as the client project for the generated Java proxy,
and then click OK as shown in Figure 9.

Figure 9. Specify the Client project for proxy

7. Click the Next button and enter com.ibm.dwexample.clientproxy as the target

package of the Web service client. Ensure the Generate portable client checkbox is
selected, as shown in Figure 10. It is usually a good idea to segregate the generated
code from your client code by using a different package name for the proxy code as
shown in this step.
 Figure 10. Web Service Client Configuration wizard

8. Click the Finish button to generate the client proxy code, which will look like Figure
11.
 Figure 11. Generated client proxy classes

Rational Application Developer uses the WSDL of the service provider to auto-generate Java
classes that can invoke the service provider Web service. Figure 11 shows the classes that
get generated for you. Using the generated proxy classes, you do not have to worry about
SOAP message building, XML parsing, or any other low-level programming constructs – the
generated classes do this for you. All you need to do is instantiate the client proxy and
invoke methods you want to be sent to the Web service. Therefore, next you will create a
simple Java test client that instantiates the generated client proxy in order to invoke the
service provider.
To create a Java test client:
1. Right-click the HelloWorldConsumer project and choose New > Class.
2. Enter com.ibm.dwexample as the package for the client and ClientTest as the
Java class name as shown in Figure 12. Note that you segregate your client code
from the generated proxy client by using a different Java package name.
 Figure 12. New Java Class wizard

3. Click the Finish button. Copy the code from Listing 2 into the ClientTest.java file
and save the file.

Listing 2. ClientTest.java
1 package com.ibm.dwexample;
2 import com.ibm.dwexample.clientproxy.HelloWorldProvider;
3 import com.ibm.dwexample.clientproxy.HelloWorldProviderService;

4 public class ClientTest {

5 public static void main(String[] args) {

6 try {
7 HelloWorldProviderService srv = new HelloWorldProviderService();
8 HelloWorldProvider port = srv.getHelloWorldProviderPort();
 9 String resp = port.sayHello("World");
10 System.out.println("[response] " + resp);
11 } catch(Exception e) {
12 e.printStackTrace();
13 }
14 }
15 }

In Listing 2, line 7 demonstrates how you instantiate the client proxy service that Rational
Application Developer generated for you. Then in line 8, you use the generated interface
(i.e. HelloWorldProvider) to get a handle to the Web service port. Finally you use the port
object to invoke the sayHello() method which will make a remote call to the Web service
provider. The invocation of port.sayHello(“World”)sends a SOAP request message to
the listening Web service provider shown in Listing 1. The service provider then sends a
SOAP response message back to the client. Let’s examine what these SOAP request and
response messages look like via the built-in TCP/IP Monitor view provided by Rational
Application Developer.
Back to top
Test and verify the consumer and provider
TCPMON is also available with the WebSphere installation. You can use the following
command to invoke it:
java –cp com.ibm.ws.webservices.thinclient_7.0.0.jar
com.ibm.ws.webservices.engine.utils.tcpmon
After you have the server-side and client-side up and running, it is generally a good idea to
test and verify things. Rational Application Developer provides a TCP/IP Monitor view to
display the SOAP message as it is transferred from the client to the server and back. To use
this view, we need to configure the TCP/IP Monitor to listen on an unused TCP/IP port, and
then update your client proxy code to point to this TCP/IP port. The following section
demonstrates how to do this.
1. In Rational Application Developer, select Window > Show View > Other. Then
locate the TCP/IP Monitor view in theDebug folder and click OK.
2. Right-click in the first entry box and choose Properties as shown in Figure 13.

Figure 13. TCP/IP Monitor view

3. Click the Add button to configure a new monitor to intercept the Web service request
and response in order to display the SOAP message.
4. Enter an unused TCP port for the Local monitoring port field. (e.g. 9081)
5. Enter localhost for the Host Name field.
6. Enter the TCP port for the Web service provider (check the WSDL in
the HelloWorldConsumer project). (e.g. 9080). You should have values similar to
Figure 14:

Figure 14. New Monitor settings

7. Click the OK button.

8. Now select your newly defined TCP/IP Monitor and click the Start button as shown in
Figure 15:

Figure 15. Start TCP/IP Monitor

Now that the TCP/IP Monitor is running and listening for Web service calls, you need
to change your client proxy to connect to the listening port of the TCP/IP monitor
instead of connecting directly to the service provider. You can accomplish this by
 changing the port number in the WSDL that was saved locally to the client project as
a result of clicking the Generate portable client checkbox in Figure 10.
9. Right-click the HelloWorldProviderService.wsdl file located in
the HelloWorldConsumer project under the src > META-INF > wsdl folder path and
choose Open With > WSDL Editor.
10. Change the port number to match the TCP/IP Monitor listening port (e.g. 9081) as
shown in Figure 16, then save and close the WSDL file.

Figure 16. WSDL Editor (see enlarged Figure 16)

11. Right-click the ClientTest.java file and choose Run As > Java Application. The
results should appear in the TCP/IP Monitor view as shown in Figure 17.

Figure 17. ClientTest results (see enlarged Figure 71)

At this point, you have developed a JAX-WS Web service provider (i.e. server-side) and a
JAX-WS Web service consumer (i.e. client-side) and demonstrated the results of the
consumer invoking the provider. In the next section, you configure the policy sets to add
message-level security to your little HelloWorld example, and once again view the results
in the TCP/IP Monitor view to verify that the SOAP message is being passed securely.

Section 4. Policy sets

Policy sets provide a declarative way to define qualities of service (QoS) for Web services.
This simplifies the management of multiple Web services as policy sets can be reused
across them. Let’s discuss the differences in policy set terminology:
• Policy – A policy describes a configuration that defines qualities of service (QoS) for
Web services. Examples include WS-Security and WS-Addressing.
• Policy sets – A policy set is a collection of policies.
 • Policy set attachment – In order to apply policy sets to Web services, they need to
be attached.
• Bindings – Policy sets are meant to be reused across Web services and thus do not
contain environment specific settings such as key stores or passwords. Instead, a
binding contains these environment specific values.

Figure 18. Example of policy sets (see enlarged Figure 18)

WebSphere Application Server V7 comes prepackaged with 18 policy sets (see Figure 18) to
simplify getting started. They are production-level policy sets that you can begin using
immediately. WebSphere Application Server V7 also comes with 4 sample bindings, but
these are for demonstration purposes only. For production Web services, you should
customize the policy set bindings as shown in this tutorial.
Rational Application Developer 7.5.2 also comes prepackaged with a set of policy sets.
Rational Application Developer 7.5.2 fully supports configuration of the client-side bindings
required for policy sets. However, you must configure server-side policy set bindings from
the WebSphere Application Server V7 server. WebSphere Application Server V7 does
support exporting policy sets and policy set bindings such that you can import them into
Rational Application Developer 7.5.2. After importing into Rational Application Developer,
you can attach the policy sets and policy set bindings to the service provider (i.e. server), as
well as the service consumer (i.e. client), using the wizards in Rational Application
Developer.
Setting up asymmetric keys
“Public-key cryptography, also known as asymmetric cryptography, is a form
of cryptography in which the key used to encrypt a message differs from the key used to
decrypt it. In public key cryptography, a user has a pair of cryptographic keys—a public
key and a private key. The private key is kept secret, while the public key may be widely
distributed. Incoming messages would have been encrypted with the recipient's public key
and can only be decrypted with his corresponding private key. The keys are related
mathematically, but the private key cannot be practically derived from the public key.”
(http://en.wikipedia.org/wiki/Public-key_cryptography)
To secure your Web services, you can use asymmetric keys. In this section, you learn how
to create a set of cryptographic keys that you then use to secure your Web service. Before
you get started, it may be helpful to review the following terminology:
• Public key – The key that is used by others to encrypt data for you.
• Private key – The key that matches your public key and is used to decrypt data that
others have encrypted with your public key. This key should not be shared with
others.
• Certificate authority – For others to trust that your public key really belongs to you,
you normally request a CA (e.g. Verisign, GeoTrust, GoDaddy) to sign your key.
Since others do the same thing, you can trust others by the CA vouching for you and
them.
• Digital certificate – To share your public key with others and for them to trust that
you are who you say you are, you create a digital certificate which contains your
public key along with your identity information (e.g. your name) and send this digital
document to a CA to sign for you.
• Key store – A place to store your keys. Also called a key ring.
• Signer certificate – After your digital certificate has been signed by a CA, it
becomes a signer certificate. Digital certificate, public key certificate, and signer
certificate are often used synonymously.
Back to top
Creating service provider keys
There are a number of tools for creating public key/private key pairs, but for this tutorial you
use the keytool command provided by the Java Development Kit (JDK), since it will be
available with standalone clients as well as with WebSphere Application Server.
First, you create the server-side keys that will be used by your service provider (i.e. server-
side) running on WebSphere Application Server V7. Then you create the client-side keys for
your service consumer running as a standalone client from Rational Application Developer
V7.5.2. We purposely separate the server-side keys from the client-side keys to delineate the
differences and to mimic the more likely production environment where the consumer and
provider are often distributed on different physical hardware. In other words, the private key
stays with the owner and should not be distributed.
The first thing you need to do is create a key store to hold your public and private keys. This
can be accomplished with the following keytool command:
1. In Microsoft Windows, select Start > Run…, then enter cmd in the Open field of the
dialog box and click OK.
2. In the Command Prompt window, change directories to where WebSphere
Application Server V7 is installed. (e.g. cd c:\Program
Files\IBM\SDP\runtimes\base_v7)
3. Now run the following keytool command:
java\bin\keytool.exe -genkey –v -alias server1 -keyalg RSA
-keystore helloServerKeys.jks -storepass f00bar
-dname "cn=server1,O=IBM,C=US" -keypass passw0rd

This command generates a public key and private key pair that will be accessed via
the server1 alias. Additionally, this command self signs the public key. Both private
and public keys are stored in the helloServerKeys.jks file, which is password
protected.
4. Next, you need to export your server1 certificate to be imported into your client-side
key ring later on, with the followingkeytool command:
java\bin\keytool.exe –export -v -alias server1 –file c:\temp\server1.cert –rfc
-keystore helloServerKeys.jks –storepass f00bar
For someone (or some computer) to encrypt messages for you, they need your public key.
Then you can decrypt the message using your private key. However, you must somehow
extract your public key from your key ring into some format and send it to the party with
which you wish to securely communicate. The export argument of the keytool does just
that, and in the above command saves the public key into an X509 digital certificate format
and stores it in the text file c:\temp\server1.cert. This public key certificate will then be
imported into the service consumer’s (i.e. client-side) key store such that the service
consumer will know how to encrypt messages for the service provider.
Figure 19 shows the commands used for creating the service provider keys:

Figure 19. Service Provider Key setup

Back to top
Creating service consumer keys
Now that you have created the server-side keys, next you create a client-side key store. Note
that this is a completely different set of keys and has no relationship to the server-side keys.
Only when you exchange public keys with each key store is a trust relationship established.
In fact, our keys use a different organization name
(i.e. server1 at IBM and myclient at ACME) to demonstrate that your keys can be from
completely different organizations and that the client and server need not have keys created
by one certificate authority.
As with the server-side keys, you can use the keytool command to create the client-side
key ring. Note that you will use thekeytool command that comes with Rational Application
Developer V7.5.2 and not the WebSphere Application Server keytoolas evident by the
different directories from which you run this command:
1. In Microsoft Windows, select Start > Run…, then enter cmd in the Open field of the
dialog box and click OK.
2. In the Command Prompt window, change directories to where Rational Application
Developer 7.5.2 is installed. (e.g. cd c:\Program Files\IBM\SDP)
3. Now run the following keytool command:
jdk\bin\keytool.exe -genkey –v -alias myclient -keyalg RSA
-keystore myclientKeys.jks -storepass g00ber
-dname "cn=myclient,O=ACME,C=US" -keypass p@ssword

Just as the service provider used this command to generate a public key and private
key pair, we now use the same command to create the service consumer’s key ring
with a corresponding set of public key/private key that is accessed via
 the myclient alias. Likewise with the service provider keys, this command creates a
self-signed public certificate that contains the public key. However, note that the
service consumer (i.e. client-side) keys are stored in themyclientKeys.jks file.
4. To build that trust level between the service provider and service consumer, you
need to export the client certificate to be imported into the service provider’s key
store. This is done with the following keytool command:
jdk\bin\keytool.exe –export -v -alias myclient –file c:\temp\myclient.cert
–rfc -keystore myclientKeys.jks –storepass g00ber

This command imports the public key certificate into the service provider’s (i.e.
server-side) key store so that the service provider will know how to encrypt
messages for the consumer.
5. Next you import the server-side public key into the client-side keys using the
following keytool command:
jdk\bin\keytool.exe –import -v –noprompt -alias server1 –file c:\temp\server1.cert
-keystore myclientKeys.jks –storepass g00ber

Recall above that you exported the public key of the server1 alias, which is the key
pair that is associated with your service provider. Therefore, you need to import this
public key into the client-side key store (i.e myclientKeys.jks). Then, when the
service consumer (i.e. client-side) wants to encrypt a message for the service
provider, the WS-Security configuration associated with the client will specify
the server1 alias public key in the client’s key store.
Figure 20 shows all of the commands listed above required to create the client-side
keys:

Figure 20. Creating client-side keys with keytool

Back to top
Importing service consumer keys
Recall during the service provider key creation, you had not yet created the service
consumer keys with which to export and import into the service provider’s key ring. Now that
you have created the client-side keys and certificates and exported the public key to be used
by the service consumer, you can now import this key into the service provider key ring.
1. The following keytool command lets you import the public key into the key ring:
 java\bin\keytool.exe –import -v –noprompt -alias myclient
–file c:\temp\myclient.cert -keystore helloServerKeys.jks
–storepass f00bar

Make sure you run this command from the WebSphere Application Server V7
directory (i.e. c:\Program Files\IBM\SDP\runtimes\base_v7)
Now that the service provider’s key ring is ready, you copy it to the cell configuration
directory of the WebSphere Application Server V7 runtime so that your keys will be
available on all nodes of a cluster for a clustered environment. This location will also
work for a standalone server configuration. In your policy set bindings configuration
below, you will point to this key store.
2. From the WebSphere Application Server V7 directory, copy the service provider’s
key ring to the following directory:
copy helloServerKeys.jks profiles\<profile name>\config\cells\<cell name>

On my machine the path is C:\Program

Files\IBM\SDP\runtimes\base_v7\profiles\was70profile1\
config\cells\griffith-t60pNode01Cell\MyKeys.
Now you have the client keys and the server keys both with an imported certificate from the
other. You will use these keys in the configuration of the WSSecurity policy set to provide
encryption and signing.
Back to top
Creating a policy set
WebSphere Application Server V7 allows creating policy sets from scratch to provide
maximum flexibility, but WebSphere Application Server V7 also comes with many
preconfigured policy sets to simplify their creation. Very often the preconfigured policy sets
are more than adequate for most needs and thus copying one of the built-in policy sets and
modifying it is often easier than starting from scratch – it is also the recommended approach.
In this tutorial, you will copy the Username WSSecurity default policy set.
The Username WSSecurity default policy set comes with a WSSecurity policy and a
WSAddressing policy. Within these policies, you specify message integrity by digitally
signing the message body, the timestamp, the addressing headers, and the username token.
Message confidentiality is achieved by encrypting the message body, the signature, and the
username token. Finally, these policies specify message authentication by using the
username token. All of the work of specifying what parts of the message to sign and encrypt
are already done for you by copying the Username WSSecurity default policy set.
Rational Application Developer 7.5.2 allows attaching policy sets and customization of client-
side bindings, but does not allow customization of policy sets.
To create and customize a policy set, you need to open the Administration Console of
WebSphere Application Server. In this tutorial, you use the WebSphere Application Server
that we installed inside of Rational Application Developer.
1. From Rational Application Developer, right-click your WebSphere Application Server
V7 runtime in the Servers view and choose Administration > Run administrative
console, as shown in Figure 21. Ensure your WebSphere Application Server V7
runtime is started or Run administrative console will be grayed out.

Figure 21. Launching Administration Console from Rational Application

 Developer

2. From the Administrative Console, select Services > Policy sets > Application
policy sets as shown in Figure 22.

Figure 22. Application policy sets (see enlarged Figure 22)

3. Click the checkbox next to the Username WSSecurity default, then click
the Copy… button.
The Username WSSecurity default policy set encrypts the SOAP body, the signature,
and the Username token. Additionally, the Username WSSecurity default policy set
signs the SOAP body, the timestamp, the addressing headers, and the Username
token. Message authentication is provided using the Username token. As this policy
set provides defaults that are likely to be used frequently in real-life scenarios, you
will use this policy set for this tutorial.
 Figure 23. Copy policy set (see enlarged Figure 23)

4. Enter HelloWorldPolicySet as the name for your new policy set and any
description you’d like in the description field. Click the OK button.
Back to top
Exporting a policy set
As discussed previously, Rational Application Developer does not allow customization of
policy sets and thus you used the Administration Console of WebSphere Application Server
to create the policy set. You can then export the policy set to allow the consumer to use the
same policy set. Additionally, you may attach the policy set to the service provider or service
consumer using Rational Application Developer such that the policy set will get attached
when deployed from Rational Application Developer.
1. From the Administration Console, select Services > Policy sets > Application
policy sets as shown in Figure 22.
2. Click the checkbox next to the HelloWorldPolicySet then click the Export… button.

Figure 24. Exporting policy sets (see enlarged Figure 24)

3. Click the HelloWorldPolicySet.zip link as shown in Figure 24 and save the file
to c:\temp. Click the OK button to save the file.
Back to top
Creating a policy set binding
The policy set defines the policies to attach to your service provider, but you need to assign
a binding to specify the service-specific settings to use, such as key stores. Rather than
starting from scratch, you copy the provider sample bindings and then customize it, as this is
usually easier and considered a best practice.
 1. In the Services menu, expand the Policy sets folder and select the General
provider policy set bindings link. This link displays the list of provider policy set
bindings.
2. Click the checkbox next to the Provider sample policy set bindings, then click
the Copy… button.
3. Enter HelloWorldProviderBindings as the name for the new bindings and any
desired text for the description field (optional), as shown in Figure 25.

Figure 25. Copy policy set bindings for customization (see enlarged Figure 25)

4. Click OK.
Back to top
Configuring service provider policy set binding
The provider sample that you started with is for demonstration purposes only, and you must
change the keys to provide production-level security. Therefore, you now need to customize
your new policy set binding by changing the sample keys to use the real keys that you
generated above.
To customize the policy set binding to specify which certificates you trust:
1. Navigate to the Keys and certificates policy bindings by
clicking HelloWorldProviderBindings > WS-Security > Keys and certificates.
2. Scroll down the page to the Trust anchor section and click the New… button.
3. Enter HelloServerTrustStore in the name field then click the External
keystore radio button.
4. Enter ${USER_INSTALL_ROOT}\config\cells\<yourCellName>
\helloServerKeys.jks for the full path to the external key store.
For simplicity in this tutorial, we use the hard-coded path to the key store. Normally,
you would create a new WebSphere variable (e.g. MY_KEY_STORE) that would point
to the absolute path so that you wouldn’t need to change your policy set bindings
when moving from one cell to another.
5. Select JKS as the key store type.
6. Enter f00bar as the key store password. Your screen should look something like
Figure 26.
 Figure 26. New trust anchor

On my machine the external key store path is C:\Program

Files\IBM\SDP\runtimes\base_v7\profiles\was70profile1\config
\cells\griffith-t60pNode01Cell\helloServerKeys.jks.
7. Click the OK button to save the changes.
In this step, you customized the policy set binding to specify which certificates you trust. This
step lets you verify that the public certificate that is used to encrypt messages is a trusted
certificate. In this tutorial, you use your server-side key store as your trust store to simplify
things. Normally, your trust store would contain trusted CAs (e.g. Verisign, GeoTrust) that
have signed the public keys.
Now that you have specified your trust store, you can customize the signing token for
inbound messages to use this trust store. This token essentially verifies that the key used to
sign the message is a trusted key.
To customize the signing token for inbound messages to use this trust store:
1. Navigate to the Authentication and protection bindings by
clicking HelloWorldProviderBindings > WS-Security > Authentication and
protection. This step displays a window like the one in Figure 27.
 Figure 27. Customizing policy set bindings (see enlarged Figure 27)

2. Select con_signx509token > Callback handler. Change the Certificate store to

be (none) instead of DigSigCertStore. Then choose HelloServerTrustStore next to
the Trusted anchor store label as shown in Figure 28.

Figure 28. Changing certificate store (see enlarged Figure 28)

3. Click the OK button to save the callback handler customizations.

4. Click the OK button again to save the consumer signature token customizations,
which should now bring you back to theAuthentication and protection page shown
in Figure 27.
Now that you have specified what trust store to use for verifying the signature for incoming
messages, you need to customize the token to be used for signing outgoing messages:
To customize the token for signing outgoing messages:
 1. Select gen_signx509token > Callback handler. Then choose Custom from the
drop-down in the Key store section and click the Custom keystore
configuration link.
2. Change the values to match this table:

Field Value

Keystore path ${USER_INSTALL_ROOT}\config

\cells\<yourCellName>
\helloServerKeys.jks

Keystore type JKS

Keystore password f00bar

Key name cn=server1,o=IBM,c=US

Key alias server1

Key password passw0rd

3.

4. Note that since you use the private key of server1 for outgoing signatures, you must
specify the password for the private key.
5. Click the OK button to save the key store configuration changes.
6. Click the OK button to save the callback handler changes.
7. Click the OK button to save the token changes. At this point, you should be back at
the Authentication and protectionpage shown in Figure 27.
Now that you have customized the binding for signatures, next you customize the binding for
encryption and decryption protection. You will begin with the con_encx509token token,
which is used to decrypt incoming messages.
To customize the binding for encryption and decryption protection:
1. Select con_encx509token > Callback handler. Then choose Custom from the
drop-down in the Key store section followed by clicking the Custom keystore
configuration link.
2. Change the values to match this table:

Field Value

Keystore path ${USER_INSTALL_ROOT}\config

\cells\<yourCellName>
\helloServerKeys.jks

Keystore type JKS

 Keystore password f00bar

Key name cn=server1,o=IBM,c=US

Key alias server1

Key password passw0rd

3.

4. Notice that you have to enter the key’s password in addition to the key store
password since you are accessing the private key.
5. The results should look similar to Figure 29.
6.
 Figure 29. Key store for consumer decryption

7. Click the OK button to save the key store configuration changes.

8. Click the OK button to save the callback handler changes.
9. Click the OK button to save the token changes. At this point, you should be back at
the Authentication and protectionpage as in Figure 27.
To customize the token used for encrypting outgoing messages:
1. Click gen_encx509token > Callback handler. Then choose Custom from the drop-
down in the Keystore section and click the Custom keystore configuration link.
2. Change the values to match this table:

Field Value

Keystore path ${USER_INSTALL_ROOT}\config

\cells\<yourCellName>
\helloServerKeys.jks
 Keystore type JKS

Keystore password f00bar

Key name cn=myclient,o=ACME,c=US

Key alias myclient

3.

4. Notice that in this case you do not need to provide a password for the key alias
because you are using the client’s public key to encrypt the outgoing response
message.
5. Click the OK button to save the key store configuration changes.
6. Click the OK button to save the callback handler changes.
7. Click the OK button to save the token changes. At this point, you should be back at
the Authentication and protectionpage as in Figure 27.
So far you have created a custom policy set and a custom policy set binding and customized
to use custom keys. While WebSphere Application Server V7 provides the ability to attach
policy sets and bindings to services in the Administrative console, for this tutorial, you will
use Rational Application Developer V7.5.2 to accomplish this task. Therefore, you now need
to export the policy set and bindings to import them into Rational Application Developer.
Back to top
Exporting a policy set binding
Just as you exported the copied policy set above, you can also export the policy set
bindings. Because this policy set binding is only for the service provider (i.e. server-side), it
isn’t necessary to export this policy set binding. However, doing so allows you to attach the
binding to the service provider in Rational Application Developer, which simplifies policy set
attachment during development.
1. In the Services menu, expand the Policy sets folder. Select the General provider
policy set bindings link to display the list of provider policy set bindings.
2. Click the checkbox next to the HelloWorldProviderBindings policy set bindings,
then click the Export… button.
3. Click the HelloWorldPolicySet.zip link as shown in Figure 30 and save the file
to c:\temp. Click the OK button to save the file.

Figure 30. Export policy set bindings

Section 5. Securing the service provider
Now that you have created a custom policy set and policy set binding (which you exported
to c:\temp) you need to import them into the HelloWorldProject to attach them to the
service provider. Recall that policy sets provide a declarative way to provide qualities of
service (QoS) for Web services. By attaching a policy set and binding to a Web service, you
are declaratively specifying what QoS to use.
1. From the main menu of Rational Application Developer choose File > Import > Web
services > WebSphere Policy Sets. Now click the Next button, which displays a
dialog box like the one in Figure 31.
2. Click the Browse… button and choose the HelloWorldPolicySet.zip file that you
exported to c:\temp above.
3. The wizard reads the zip file and lists the policy sets included in the file. Click the
checkbox next to HelloWorldPolicySet,then click the Finish button.

Figure 31. Import policy set

4. As in the steps above, right-click HelloWorldProject and choose Import > Import >
Web services > WebSphere Named Bindings. Now click the Next button, which
displays a dialog box like the one in Figure 32.
5. Click the Browse… button and choose the HelloWorldProviderBindings.zip file
that you exported to c:\temp above.
6. Again, the wizard reads the zip file and list the policy set bindings included in the file.
Click the checkbox next toHelloWorldProviderBindings, then click
the Finish button.
 Figure 32. Import policy set bindings

Once the policy set and bindings have been imported into Rational Application
Developer, you can attach them to the service provider.
7. In Rational Application Developer, drill into the HelloWorldProject > Services >
{http://dwexample.ibm.com}HelloWorldProviderService then right-click and
choose Manage policy set attachment…as shown in figure 33:

Figure 33. Attaching policy set and bindings

8. Click the Add button add a policy set and binding to an endpoint.
9. Leave the scope set to the entire service and choose HelloWorldPolicySet from the
drop-down for the policy set andHelloWorldProviderBindings from the drop-down
for the binding as shown in figure 34.
 Figure 34. Customizing policy set bindings

10. Click the OK button to save this association.

11. Click the Finish button to close the policy set attachment dialog box.
Now that you have attached the policy set and bindings to the service provider, you will
deploy the service provider onto the WebSphere Application Server runtime and verify that
our policy set and bindings have been attached.
There are a variety of ways to deploy the service provider onto the WebSphere Application
Server, but in this tutorial we will use the Add and Remove Projects… menu item available
in the Rational Application Developer Servers view.
To deploy the service provider:
1. Right-click WebSphere Application Server v7.0 at localhost (or whatever your
server is called if different) and chooseOpen. This will bring up the server
configuration settings page as shown in Figure 35.

Figure 35. WebSphere Application Server V7.0 server configuration (see

 enlarged Figure 35)

2. Ensure Run server with resources on Server is selected in the Publishing settings
for WebSphere Application Server section.
3. Save and close the server configuration file.
The Run server with resource on Server setting will ensure that the policy set and
bindings attachment show up in the WebSphere Application Server Administrative
Console.
In order to ensure a clean deploy, you will remove the HelloWorldProjectEAR from
the server, then re-add it.
4. Right-click the HelloWorldProjectEAR project under WebSphere Application
Server v7.0 at localhost in the Servers view and choose Remove as shown Figure
36.

Figure 36. Remove HelloWorldProjectEAR from server

 Now that the project has been removed, you will add it back, which will cause a fresh
deploy.
5. Right-click WebSphere Application Server v7.0 at localhost (or whatever your
server is called if different) and chooseAdd and Remove Projects… as shown in
Figure 37.
6. Click the HelloWorldProjectEAR project from the Available projects field and click
the Add > button to move it to the Configured projects field then click
the Finish button.

Figure 37. Deploy Service Provider to WebSphere Application Server

7. When the server finishes deploying and publishing, use the Administrative Console
to verify that the service provider was successfully deployed to WebSphere
Application Server and that the policy set and bindings have been attached. Once
again right-click WebSphere Application Server v7.0 at localhost, but this time
choose Administration > Run Administrative console.
8. Login to the admin console and select Services > Services providers. You should
see the HelloWorldProviderServicelisted in the service providers.
9. Click the HelloWorldProviderService to drill into this service.
10. You should now see the HelloWorldPolicySet attached as the policy set
and HelloWorldProviderBindings attached for the binding as shown in Figure 38.
 Figure 38. Verify policy set and bindings attached (see enlarged Figure 38)

If you do not see the HelloWorldProviderService in the service providers window, then logout
of the Adminstrative Console and then log back in to refresh the console such that you see
the policy set and bindings attached to the service provider as shown in Figure 38.
Since you copied the Username WSSecurity default policy set, this policy set defines
authentication through the username token. As a result, you need to enable security on the
WebSphere Application Server server such that authentication can occur.
To enable security on WebSphere Application Server:
1. In the Administrative Console, navigate to Security > Global security and verify
that Enable administrative security andEnable application security are selected
as shown in Figure 39.
 Figure 39. Enable application security (see enlarged Figure 39)

2. If security was not enabled before, you need to restart WebSphere Application
Server for the security settings to take effect.

Section 6. Consuming a secure service

At this point in the tutorial, you should have the service provider running on WebSphere
Application Server V7 with the customized HelloWorldPolicySet and bindings attached.
If you were to rerun the service consumer as developed above, the service provider would
reply with a SOAP fault indicating that the consumer does not adhere to the policy set
attached to this provider. Therefore, you need to attach a policy set to the consumer (i.e.
client-side) and customize the consumer bindings to match up with the expectations of
the service provider.

One way to ensure the consumer adheres to the policy of the service provider is to use the
same policy set, which is what we’ll do in this tutorial. Since you imported the
HelloWorldPolicySet into Rational Application Developer to attach it to the service
provider, it is also available to be attached to our service consumer.

Attaching a policy set

In a similar fashion to attaching the policy set to the service provider, you do the same
thing with the service consumer. The following sections describe this process.

To configure the consumer-side binding for signatures:

1. Drill down to HelloWorldConsumer > Services > Clients >
{http://dwexample.ibm.com}HelloWorldProviderService. Right-click and
choose Manage policy set attachment…
2. Click the Next button followed by the Add… button of the Application section,
which presents the dialog box shown in Figure 40.

Figure 40. Attaching policy set

3. Select HelloWorldPolicySet for the policy set drop-down.

4. Type HelloWorldConsumerBinding in the drop-down binding field and click
OK.
5. Select the WSSecurity policy type in the bindings configuration section. Click
the Configure… button, which presents the WSSecurity Binding Configuration
dialog as shown in Figure 41.
 Figure 41. WSSecurity Binding Configuration (see enlarged Figure 41)

6. Select the Digital Signature Configuration tab, and then click the Key Store
Settings… button of the Outbound Message Security Configuration section.
7. Enter the values in the following table for the Key Store Settings dialog shown in
Figure 42.

Field Value
Keystore path C:\Program Files\IBM\SDP
\myclientKeys.jks
Keystore passwordg00ber
Keystore type JKS
 Key alias myclient
Key Password p@ssword
8.

Figure 42. Outbound signature key settings

9. Notice that you are specifying that you want to sign the outbound (i.e. service
request) message using the private key of the myclient alias.
10. Click the OK button.
11. In the Inbound Message Security Configuration section, uncheck the Trust
Any Certificate, because we only want to trust the signature if the response is
from the server.
12. Click the Key Store Settings… button, then enter the values in the following
table:

Field Value
Keystore path C:\Program Files\IBM\SDP
\myclientKeys.jks
Keystore passwordg00ber
Keystore type JKS
13.

14. Click the OK button.

15. Enter C:\temp\server1.cert as the value for the Certificate Path field.

Now you have configured the consumer-side binding for signatures. Next, you will
configure the keys to use for encryption.

To configure the keys to use for encryption:

 1. Select the XML Encryption Configuration tab, and then click the Key Store
Settings… button of the Outbound Message Security Configuration section.
2. Enter the values from the following table for the Key Store Settings dialog shown
in Figure 43.

Field Value
Keystore path C:\Program Files\IBM\SDP
\myclientKeys.jks
Keystore passwordg00ber
Keystore type JKS
Key alias server1
3.

Figure 43. Outbound encryption key settings

4. Since you are encrypting the service request for the service provider, which is
associated with the server1 certificate, you specify the public key of server1 in
Figure 44.
5. Click the OK button.

To configure how to decrypt the inbound message (i.e. the response):

1. On the XML Encryption Configuration tab, click the Key Store Settings…
button in the Inbound Message Security Configuration section.
2. Enter the values from the following table for the Key Store Settings dialog shown
in Figure 44.

Field Value
Keystore path C:\Program Files\IBM\SDP
 \myclientKeys.jks
Keystore passwordg00ber
Keystore type JKS
Key alias myclient
Key password p@ssword
3.

Figure 44. Inbound encryption key settings

4. When the provider’s response comes back, it will be encrypted with the client’s
public key. Therefore, you need to decrypt the message using the client’s private
key, which is what we have specified in Figure 44.
5. Click the OK button.

Recall that the Username WSSecurity default policy set that you copied included
authentication using a username token. Somehow you need to get a valid
username token in the SOAP header for the server to verify that you are
authenticated before executing the service provider Web service. The Token
Authentication tab provides two such methods. You will choose the
UNTGenerateCallbackHandler.

6. Select the Token Authentication tab then choose the

com.ibm.websphere.wssecurity.callbackhandler.UNTGenerateCallbackHand
ler as the callback handler, as Figure 45 shows.
7. Enter a valid user name and password that matches the user repository of your
WebSphere Application Server (e.g. admin/admin).
8. Click the Add Timestamp checkbox.
9. Click the Add Nonce checkbox.
 10. Click the OK button, and then click the Finish button.

Figure 45. Token authentication (see enlarged Figure 45)

If the dialog box as shown in Figure 45 does not include checkboxes for Add
Timestamp and Add Nonce, you will need to ensure you are using Rational
Application Developer 7.5.2 .

Section 7. Testing secure JAX-WS

In section 3 of this tutorial, you tested the service provider and consumer and viewed the
SOAP messages as they traveled between the client and server. In section 3, you had not
yet enabled message-level security through the attachment of policy sets, and thus the
SOAP messages were sent in clear text (i.e. not encrypted) as shown in Figure 17. As one
of the goals with message- level security is to ensure confidentiality (i.e. only the
intended recipient can see the data inside the SOAP message), you now need to rerun the
test and verify that the SOAP messages contain encrypted data that isn’t visible to anyone
except the intended recipient (not even the TCP/IP Monitor that is acting as an
intermediary).

1. Ensure the TCP/IP Monitor is started as shown in Figure 15, then right-click the
ClientTest.java file of the HelloWorldConsumer project and choose Run As >
Run Configurations. This should present a Run Configurations dialog box as
shown in Figure 46.
 Figure 46. Setting ClientTest arguments (see enlarged Figure 46)

2. Since the consumer needs to use a Java Authentication and Authorization Service
(JAAS) to pass in the Username credentials, you need to specify the following
VM argument:

-Djava.security.auth.login.config=
”C:\Program Files\IBM\SDP\runtimes\base_v7
\profiles\was70profile1\properties\wsjaas_client.conf”

3. Next click the Run button and view the results in the TCP/IP Monitor view,
which looks something like Figure 47.

Figure 47. Viewing the SOAP messages with XML encryption (see enlarged
 Figure 47)

Notice that the Console shows the output from the consumer after unencrypting
the message. If you view the WebSphere Application Server console log, you see
a similar message, which demonstrates that the service provider received the
message.

Section 8. Conclusion

In this tutorial, we demonstrated how to create a Web service provider using JAX-WS
annotations. Then we showed you how to build a matching consumer and how to test the
client- to-server communications. Next, we demonstrated how to create a custom policy
set, which we showed you how to customize with personalized asymmetric keys, before
once again testing the client and server pair. Additionally, we showed you how to
monitor the data flowing between the client and the server, and verify that in fact the
SOAP messages are being encrypted and protected by the customized policy set you
created and associated with the service consumer and provider pair.

While this tutorial was designed to teach and instruct, the steps taken are valid
production-level configuration options that employ strong cryptography for encryption
and protection.

Acknowledgements

Special thanks to Zina Mostafa and Indran Naick for reviewing this tutorial.