by Jiandong Guo

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.

Here is an example of a shared security token:

   <wsc:SecurityContextToken
    xmlns:wsu='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd'
    xmlns:wsc='http://schemas.xmlsoap.org/ws/2004/04/sc'>
     <wsu:Identifier>uuid:...</wsc:Identifier>
     <wsu:Created>2008-03-07T08:24:05</wsu:Created>
     <wsu:Expires>2008-03-08T09:24:06</wsu:Expires>
    <wsse:Keys>
     <xenc:EncryptedKeyId="...">...</EncryptedKeyId>
     <wsse:SecurityTokenReference>... </wsse:SecurityTokenReference>
     ...
    </wsse:Keys>
   </wsc:SecurityContextToken>

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:

   <ns3:SecureConversationToken ns3:IncludeToken="
    http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/IncludeToken/Always...
     <wsp:Policy>
       <wsp:ExactlyOne>
         <wsp:All
    <ns3:BootstrapPolicy>
     <wsp:Policy>
       <wsp:ExactlyOne>
       ...
       <ns3:AlgorithmSuite>
     <wsp:Policy>
       <wsp:ExactlyOne>
       ...
       </wsp:ExactlyOne>
     </wsp:Policy>
       </ns3:AlgorithmSuite
       <ns3:IncludeTimestamp/>
       ...
       <ns3:X509Token ns3:IncludeToken=
        "http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/IncludeToken/AlwaysToRecipient">
       ...
       <ns3:WssX509V3Token10/>
       ...
       <ns3:OnlySignEntireHeadersAndBody/>
       ...
       <ns3:WssX509V3Token10/
       ...
     </ns3:BootstrapPolicy>
     ...
       </wsp:Policy>
   </ns3:SecureConversationToken>

Here is an example of a SecurityContextToken and DerivedKeyToken:

   <wsc:SecurityContextToken>
     <wsc:Identifier>urn:uuid:4d651587-8443-4874-8e01-308a8b2fb8f8</wsc:Identifier>
   </wsc:SecurityContextToken>

   <wsc:DerivedKeyToken
     <wsse:SecurityTokenReference>
       <wsse:Reference
         ValueType="http://schemas.xmlsoap.org/ws/2005/02/sc/sct"
          URI="urn:uuid:4d651587-8443-4874-8e01-308a8b2fb8f8" />
     </wsse:SecurityTokenReference>
     <wsc:Offset>0</wsc:Offset>
     <wsc:Length>24</wsc:Length>
     <wsc:Nonce>uE/cm2f0wuq5C7e2sJTvY704</wsc:Nonce>
   </wsc:DerivedKeyToken>

Security Profiles

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:

• Username Authentication with Symmetric Keys
• Mutual Certificates Security
• Transport Security (SSL)
• Message Authentication over SSL
• SAML Authorization over SSL
• Endorsing Certificate
• SAML Sender Vouches with Certificates
• SAML Holder of Key
• STS Issued Token
• STS Issued Token with Service Certificate
• STS Issued Endorsing Token

You specify one of these mechanisms when you
configure security for a web service
using the NetBeans IDE as shown in Figure 2.

Figure 2. Specifying a Security Profile for a Web Service

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.

Running the Sample Code

A sample application package accompanies the tip. To install and run the sample do the following:

1. If you haven't already done so, download NetBeans
   IDE 6.0.1 and GlassFish v2 UR1.
2. Start the NetBeans IDE.
3. If GlassFish v2 is not one of the NetBeans application servers, add it as follows:
   • Right-click the Servers node in the Services window.
   • Select Add Server.
   • Select GlassFish v2.
   • Click the Next button.
   • Click the Browse button and browse to the location that you installed GlassFish v2.
   • Click the Choose button.
   • Click the Next button.
   • Set the Admin Password to the default, adminadmin, unless you chose a different password for GlassFish.
   • Click the Finish button.
4. Add testing certificates to GlassFish as follows:
   • Download the copyv3.zip file from the
     
     xwss : Document & files page and unzip the file. You should see a newly extracted directory
     copyv3.
   • Change to the copyv3 directory.
   • 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.
5. Download the sample package and extract its contents. You should now see a newly extracted directory sc_samples.
6. Change to the sc_samples\lib directory. Copy the hook.jar file to the
   GF_install_dir\lib directory.
7. 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

8. 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.

      <ns3:SecureConversationToken ns3:IncludeToken=
       "http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/IncludeToken/AlwaysToRecipient">
        <wsp:Policy>
         <wsp:ExactlyOne>
          <wsp:All>
           <ns3:BootstrapPolicy>
            <wsp:Policy>
             <wsp:ExactlyOne>
              <wsp:All>
      ...
   

   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.

9. 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.
   • Select CalculatorClientSC in the Open Project window.
   • Click the Open Project Folder button.

   CalculatorClientSC is the client for the CalculatorServiceSC service.

10. Run the CalculatorClientSC project as follows:
    • Right-click the CalculatorClientSC node in the Projects window.
    • Select Run.

    You should see the results similar to those shown in Figure 5.

    
    

    Figure 5. CalculatorClientSC Result

11. Open the CalculatorService 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.
    • 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.

12. 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.

13. 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.
    • Select CalculatorClient in the Open Project window.
    • Click the Open Project Folder button.

    CalculatorClient is the client for the CalculatorService service.

14. Run the CalculatorClient project as follows:
    • Right-click the CalculatorClient node in the Projects window.
    • Select Run.

    You should see the results similar to those shown in Figure 6.

    
    

    Figure 6. CalculatorClient Result

    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.

-----------------------------------------------------------------------------------------------------------------------------

Java EE SDKs Refreshed

Update 4 versions of the Java EE 5 SDKs and Java Application Platform SDKs now offer multilingual support.
The "+ JDK" bundles also include the latest Java SE 6 (JDK) Update 5. Download the SDKs now.

--------------------------------------------------------------------------------------

GlassFish With MySQL Cobundle Released

Sun Java System Application Server 9.1 Update 1 (GlassFish v2 UR1) is now available bundled with the
MySQL Community Server open-source database.
Read the Release Notes and this
blog for details.
Download it now.