Get tips on using enterprise Java technologies and APIs, such as those in Java Platform, Enterprise Edition (Java EE).

Secure Conversations for Web Services With Metro

Metro is a high performance, extensible, easy-to-use web services stack.
It combines the JAX-WS reference implementation with Project Tango. Project Tango, also called Web Services Interoperability Technology
or WSIT, implements numerous WS-\* standards to enable interoperability with other implementations and to provide Quality of
Service (QOS) features such as security, reliability, and transaction support. Metro is bundled as part of the open source application
server called GlassFish v2 and the
commercial offering, Sun Java System Application Server 9.1.
Metro also runs in other containers such as Tomcat.

An earlier Tech Tip, Securing
Web Services Using WSIT introduced Metro's support (through WSIT) for web services security. This support implements the following
web services security specifications published by the Organization for the Advancement of Structured Information Standards (OASIS)
consortium: WS-Security, WS-SecurityPolicy, WS-SecureConversation, and WS-Trust. The tip also showed examples of using the WS-Security
support in Metro. The following tip focuses on the support in Metro for WS-SecureConversation. You will learn the basics of
WS-SecureConversation and see examples of using the WS-SecureConversation support in Metro.

A sample application package accompanies the tip. The sample application
demonstrates how to enable secure conversations in Metro for a web service. You can enable secure conversations for a web service
manually by coding appropriate policy assertions in the Web Services Definition Language (WSDL) file for the service. However,
the NetBeans IDE offers an easier, more automated way to enable secure
conversations in Metro for a web service. Because of this, the sample in this tip uses NetBeans, specifically
NetBeans IDE 6.0.1. The sample also uses
GlassFish v2 UR1.

An Introduction to WS-SecureConversation

WS-SecureConversation is a web services specification designed to enable secure communication between web services.
The specification is built on top of two other web services specifications: WS-Security and WS-Trust. WS-Security provides the basic
framework for message level security in web services and WS-Trust specifies a framework for brokered trust across different security
domains. WS-Security and WS-Trust were covered in the tip
Securing Web Services Using WSIT.

The objective of WS-SecureConversation is to enable secure messaging between a client and a web service, especially in
situations where they exchange multiple messages. WS-Security is useful for securing simple one-way messages. However, to securely
exchange multiple messages, a client and a web service typically require a security context in which to exchange the messages.
WS-SecureConversation provides just such a context. It adds a "handshake&quot process, shown in Figure 1,
that allows a web service and its client to authenticate to each other and to establish a shared security context. The security
context is shared by the client and web service for the lifetime of a communication session. This context contains a shared secret
key that can be used to secure subsequent messages between the client and service, and can significantly improve performance by avoiding
repeated key exchanges in multi-message exchange scenarios.

Figure 1.WS-SecureConversation Handshake Process

In WS-SecureConversation, a SecurityContextToken, typically obtained from a Security Token Service (STS), is used to
describe the security context. An STS, introduced in the WS-Trust specification, is trusted by both the client and the web service to
provide interoperable security tokens.

The <SecurityContextToken> element describes the security context. The <Identifier> element
identifies the security context using an absolute Uniform Resource Identifier (URI). Notice too that the creation and expiration date
of the shared security token are also specified. The <Keys> element specifies the shared secret key of the security
context.

WS-SecureConversation also introduces key derivation mechanisms that enhance overall security. These mechanisms can use different
algorithms for deriving keys. Although a shared secret can be used to sign or encrypt messages, the WS-SecureConversation specification
recommends that messages be signed or encrypted using derived keys. Using a common secret, a client and a web service can define
different key derivations to use. It's possible, for example, to derive four keys so that a client and a web service can sign and
encrypt using separate keys. The key derivation mechanisms are not only used within the shared security context, that is, with a
SecurityContextToken, but can also be used with other security tokens such as those used in WS-Security.

WS-SecureConversation in Metro

Metro supports WS-SecureConversation within the general framework of WS-Security, WS-SecurityPolicy, and WS-Trust. Each web service
enabled for WS-SecureConversation has an associated STS that is used to issue and manage security contexts. Managing a security context
might include tasks such as renewing or canceling the security context. An extensible SessionManager on the server can
be used to persist the security contexts so that the contexts can be used in a "web farm" (a site that
uses multiple servers to deliver its content) in support of failover and high availability. By default,
the SessionManager stores the security contexts in memory, but you can extend the SessionManager to store
the session in a database.

Metro specifies a WS-SecureConversation through a <sp:SecureConversationToken> policy assertion.
Security requirements for the WS-SecureConversation messages are specified by the <sp:BootstrapPolicy> element
inside the <sp:SecureConversationToken> policy assertion. No run-time API is required.

Security contexts and derived keys are represented in Metro by their corresponding tokens, <SecurityContextToken>
and <DerivedKeyToken>, which are used in securing application messages within the general mechanisms introduced in WS-Security.

Here is part of a policy assertion in Metro that includes a WS-SecureConversation specification:

As mentioned earlier, the NetBeans IDE offers an easier, more automated way to enable secure conversations in Metro for a web
service. One of the ways it does this is by providing a set of security profiles that specify the mechanism to be used in securing
conversations. The profiles are:

You can enable a secure conversation with any of the security mechanisms simply by clicking the Configure button next to the security
mechanism selection. This opens a secondary window for that security mechanism. Then select the "Establish Secure Session (Secure
Conversation)" checkbox in the secondary window as shown in Figure 3.

Figure 3.Establishing a Secure Conversation for an Web Service

When you build and run the web service, the handshake process will be used to establish a secure session between the web service and
its client. In general, if you want to secure a web service for more than one message in a transaction, you should enable a secure
conversation.

Open the build.xml file and set the AS_HOME variable to the location where you installed GlassFish v2.

Run the ant command. This copies the sample certificates to the GlassFish v2 application server
keystores for use with the sample. You can find ant in the <GF_install_dir>\\lib\\ant\\bin directory,
where <GF_install_dir> is the directory where you installed GlassFish v2.

Download the sample package and extract its contents. You should now see a newly extracted directory sc_samples.

Change to the sc_samples\\lib directory. Copy the hook.jar file to the
GF_install_dir\\lib directory.

Open the CalculatorServiceSC project in theNetBeans IDE as follows:

Select Open Project from the File menu.

Browse to the sc_samples directory from the sample application download.

Select CalculatorServiceSC in the Open Project window.

Click the Open Project Folder button.

CalculatorServiceSC is a simple calculator service that was created using the NetBeans IDE. It uses the Mutual
Certificates Security profile and is enabled for secure conversation. You can see the security configuration for
CalculatorServiceSC by expanding its Web Services node in the Projects window. Then right-click on CalculatorSC in the Web
Services node and select Edit Web Services Attributes as shown in Figure 4.

Figure 4.Viewing Web Service Attributes

Run the CalculatorServiceSC project as follows:

Right-click the CalculatorServiceSC node in the Projects window.

Select Run.

In response, the CalculatorServiceSC service is deployed to the GlassFish v2 application server and
the WSDL file for the web service is published to http://localhost:8080/CaculatorServiceSC/CaculatorSCService?wsdl.

If you examine the WSDL file, you'll notice that it includes a <sp:SecureConversationToken> policy assertion and
a <sp:BootstrapPolicy> element inside the policy assertion.

In other words, the NetBeans IDE generates the appropriate WSDL specifications for a secure conversation based on the security
profile and secure conversation selection that were made when the web service was created. You do not have to specify the
WSSecureConversation-related specifications in the WSDL file manually.

Open the CalculatorClientSC project with the NetBeans IDE as follows:

Select Open Project from the File menu.

Browse to the sc_samples directory from the sample application download.

Browse to the sc_samples directory from the sample application download.

Select CalculatorService in the Open Project window.

Click the Open Project Folder button.

CalculatorService is a simple calculator service that was created using the NetBeans IDE. It uses the Mutual
Certificates Security profile, but is not enabled for secure conversation. You can see the security configuration for
CalculatorService in the same way as you did for CalculatorServiceSC.

Run the CalculatorService project as follows:

Right-click the CalculatorService node in the Projects window.

Select Run.

In response, the CalculatorService service is deployed to the GlassFish v2 application server and the WSDL file
for the web service is published to http://localhost:8080/CaculatorService/CaculatorService?wsdl.

If you examine the WSDL file, you'll notice that it does not include any WSSecureConversation-related specifications. In
particular, there is no <sp:SecureConversationToken> policy assertion or
<sp:BootstrapPolicy> element in the WSDL file.

Open the CalculatorClient project with the NetBeans IDE as follows:

Select Open Project from the File menu.

Browse to the sc_samples directory from the sample application download.

Compare the running times for each project in the displayed Time value. Notice that it takes much less time to run
the calculator service with secure conversation enabled.

Currently the client accesses the calculator service five times. You can adjust the number of times that the
client calls the calculator service and see how it impacts the running times for each project.

About the Author

Jiandong Guo is a staff engineer and a senior member of the Application Server Web Services Security Group.
He has lead the development of implementations and solutions based on WS-SecureConversation and WS-Trust in the
Tango project.