Message-level security with JAX-WS on WebSphere Application Server v7

Page 4 of 12  Document options PDF - Fits A4 and Letter 2742 KB (58 pages) Get Adobe® Reader® Sample code My developerWorks needs you! Connect to your technical community Rate this tutorial Help us improve this content

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.

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 following keytool 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:

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 the keytool command that comes with Rational Application Developer v7.5.2 and not the WebSphere Application Server keytool as 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 the myclientKeys.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 the Authentication 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

   
   
   
   

   Note that since you use the private key of server1 for outgoing signatures, you must specify the password for the private key.

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

4. Click the OK button to save the callback handler changes.

5. Click the OK button to save the token changes. At this point, you should be back at the Authentication and protection page 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

   
   
   
   

   Notice that you have to enter the key’s password in addition to the key store password since you are accessing the private key.

   The results should look similar to Figure 29.

   
   
   Figure 29. Key store for consumer decryption
   
   
   

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

4. Click the OK button to save the callback handler changes.

5. Click the OK button to save the token changes. At this point, you should be back at the Authentication and protection page 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

   
   
   
   

   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.

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

4. Click the OK button to save the callback handler changes.

5. Click the OK button to save the token changes. At this point, you should be back at the Authentication and protection page 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
   
   
   

Back to top

	Page 4 of 12