he Web Services Interoperability organization (WSI) has developed a whole stable of standards upon which Web services commerce and communication can be executed securely. These standards are in great demand and many developers have already gotten their feet wet with a few of them out of sheer necessity. But it’s not been particularly easy to figure out which standard one might need to apply in various circumstances. Hopefully, I’m about to change that.

This article provides a basic roadmap of the main WS-* standards, and some implementation guidelines for both Java and .NET. Many of the implementation libraries for the WS-* standards are found in the Java Web Services Development Pack 1.5 (JWSDP), available for download from Sun at http://java.sun.com/webservices/jwsdp/index.jsp, and in the Microsoft Web services enhancements add- on (WSE) for .NET.

Use this article as a pocket reference to help you get the basic info on each of these important standards so you can get your arms around all that WS-* has to offer and how you can make best use of it in your organization.

1: WS-Security

• What is it?
  A set of enhancements to SOAP that allows you to specify how a message can be secured when passing to and from a Web service.
• When would you use it?
  Any time you want to pass sensitive information into or get sensitive information out of a Web service.
• Tell me more!
  WS-Security ensures that a message isn’t tampered with en route from the client to the server and that sensitive information (such as passwords) is encrypted. It defines a set of enhancements to the SOAP specification of messaging to enable protection of the message through authentication, confidentiality, and assurance of integrity.

The original specification was drawn up by OASIS (Organization for the Advancement of Structured Information Standards), available at http://www.oasis-open.org/specs/index.php#wssv1.0. There are a number of toolkits in Java that implement it, including the open source axis-wsse, the IBM Web services toolkit, the Apache WSS4J project), and of course the aforementioned JWSDP.

When using .NET the WSE makes implementing WS-Security very simple. Full documentation on using the WSE to implement WS-Security may be found on MSDN, and the documentation contains a number of quickstart samples that you can use and adapt. For Java folks, the JWSDP comes with a number of worthwhile examples that include source code.

2. WS-Policy and WS-SecurityPolicy

• What is it?
  An XML Schema that allows the author to publish to the outside world what type of security or other policies they enforce.
• When would you use it?
  When your Web service has many diverse customers, and you want a consistent way to tell them how to access your service.
• Tell me more!
  You may be familiar with WSDL, which describes the protocol used to talk to a Web service. WS-Policy is an extension on this idea that describes the configuration of the Web service. So, if for example the Web service accepts only Kerberos tokens for security, then, the WS-Policy document associated with the service would document this. Clients calling the service can then make more intelligent decisions about how to call it.

WS-Policy is the baseline specification around which focused policy documents may be defined. An example of a policy type is a security policy (defined by the WS-SecurityPolicy specification) that uses WS-Policy as its basis. Some good documentation and its schema may be found at IBM developerWorks.

A simple example of a WS-SecurityPolicy document that specifies the security token types that a Web service will accept looks like this:

      wsse:Kerberosv5TGT      wsse:X509v3    

Using Java you would then write a handler that parses this XML using SAX or DOM to determine how you will talk to the Web service, using its stated security policy, which in this case would be to use a Kerberos or an x509 token. If your application has neither available, it will be aware that it cannot talk to the service prior to making an attempt at communication.

For.NET folks, if you are using WSE, there is a WS-Policy class that handles many of the details for you.

3. WS-Trust

• What is it?
  An extension to WS-Security that allows you to extend your security model across different domains or services.
• When would you use it?
  When your Web service and somebody else’s Web service want to share security information and credentials.
• Tell me more!
  This takes the concept of WS-Security a little further, extending it to allow trusted relationships across domains. It extends on WS-Security to request and issue security tokens and to manage trust relationships between domains.

A snippet of a WS-Trust document that makes a request for a security token is shown here:

...............http://example.org/mySpecialTokenhttp://schemas.xmlsoap.org/ws/2005/02/trust/Issue

MSDN offers a great resource for investigating WS-Trust at http://msdn.microsoft.com/library/en-us/dnglobspec/html/WS-trust.pdf. The specification itself and some background information are available at http://www-106.ibm.com/developerworks/library/specification/ws-trust/.

WS-Trust is a specification for a language, and a WS-Trust document is implemented in XML. The WSE has a WSTrust class (http://msdn.microsoft.com/library/default.asp?url=/library/en-us/wseref/html/T_Microsoft_Web_Services2_Security_WSTrust.asp) that abstracts many of the details of the SOAP message for WS-Trust, allowing you to develop WS-Trust enabled services in .NET.

4. WS-Privacy

• What is it?
  An XML Schema that defines your privacy policies regarding acceptance and use of personal information.
• When would you use it?
  If you need to collect a lot of information from your Web services clients, such as credit card information, you can publish a WS-Privacy document detailing how this information is handled.
• Tell me more
  You will be able to state how you conform to various privacy policies using the WS-Privacy specification. It encapsulates WS-Policy (it is a policy after all), WS-Security (to associate privacy claims with each message), and WS-Trust (to specify how claims around message privacy is met). It is a very ambitious effort, and to date hasn’t yet been formalized or released.

5. WS-SecureConversation

• What is it?
  A set of enhancements to SOAP that allow you to specify how a message can be secured throughout a long-running message exchange.
• When would you use it?
  If your Web service and your client interact over a long-running process with a lot of data going over and back between them.
• Tell me more!
  WS-Security provides mechanisms that allow you to build security for each message in a message exchange. However, in many cases you’ll require more complex interactions, with many messages being exchanged. You could secure each of these in isolation, but it would be much more efficient if you could establish a context that reduces the overall burden of securing each message. The WS-SecureConversation specification defines a Security Context Token that does just that.

An example of a context token is shown below:

  2004-05-07T21:24:06 2004-05-08T09:24:06

The specification itself is available at http://msdn.microsoft.com/library/en-us/dnglobspec/html/WS-secureconversation.pdf.

6. WS-Federation

• What is it?
  A set of enhancements to SOAP that allow you to federate trust credentials among a group of Web service partners.
• When would you use it?
  If you, and a number of other services share the same set of customers.
• Tell me more!
  This specification defines mechanisms to enable identity, account, attributes, authentication, and authorization federation across different trust realms. The specification is in the review stage. The WS-Security, WS-Trust, and WS-Policy models define the basis for federation. WS-Federation extends these by describing how they may combine to enable richer trust across and between domains and federated services.

Figure 1. Federated Trust: The image shows how the WS-Trust model can be applied to a federation scenario.

Where this would work is in a network that requires a degree of federation. For example, say you have a network of bulletin boards, some of which are public to all organizations that subscribe to your system, while others are private to specific companies. If the private boards are to be shared between company A and company B, but not company C, then you would use federation of credentials between companies A and B.

Figure 1 shows how the WS-Trust model can be applied to a federation scenario. In this case security tokens (1) are passed from the requestor’s trust realm and are used to acquire authentication on the respondent’s trust realm (2), in order to access the resource (3). So tokens from one domain are used on another, allowing for federation across the domains. The specification defines a schema for the various messages that would be used in this scenario.

WS-Authorization, WS-Reliability, and Four More
7. WS-Authorization

• What is it?
  A specification that allows you to specify how the users of your Web service will be authorized against various functionality.
• When would you use it?
  When you have a large user base and different users are permitted access to different aspects of your service.
• Tell me more!
  This specification (forthcoming) specifies the policy parameters for how Web services will authorize users. Authorization is different from authentication in that once a user is authenticated their authorization will determine which aspects of the service they may access. For example, one may need to authenticate against a service to use that service, but different users will have access to different sets of Web methods on the service. This is determined by their authorization profile, and this specification will provide a schema to uniformly describe that profile.

8. WS-Reliability

• What is it?
  A set of enhancements to SOAP that allows you to guarantee message reliability for your Web service.
• When would you use it?
  When it is vitally important that messages from your Web service have guaranteed delivery and/or duplicate elimination requirements.
• Tell me more!
  This specification is designed to ensure guaranteed delivery, to ensure that duplicate messages are eliminated, and to ensure message ordering, when necessary.

As the name says, its purpose is to enable reliable communication between Web services. Reliable message delivery means the ability to ensure that a message will be delivered with the desired and specified levels of quality of service. Some examples of this are:

• Message sent at least once (guaranteed delivery)
• Message sent at most once (guaranteed duplicate elimination)
• Message sent exactly once (guaranteed delivery and duplicate elimination)

An example of a WS-Reliability message is shown below:

      [email protected]    [email protected]    urn:services:ItemQuoteService    [email protected]    2002-09-07T10:19:07    Message    http://server1.anyuri.com/service/    2002-09-14T10:19:00            [email protected]    12          product12345    

You can see that in this case the SOAP envelope has headers attached to it for the Message, its reliability characteristics, and order. Applications that can manage documents with this schema will then encapsulate the reliability characteristics the specification is driving.

You can see the full schema for a WS-Reliability document at http://developers.sun.com/sw/platform/technologies/ws-reliability.schema.txt.

9. WS-ReliableMessaging

• What is it?
  A specification (proposed) that allows for reliable message delivery between applications. It isn’t limited to SOAP and Web services.
• When would you use it?
  When you have a system that requires reliable message delivery between varied software components.
• Tell me more!
  WS-ReliableMessaging is similar in concept to WS-Reliability in that it is designed to ensure reliability of message interchange between distributed applications. However, WS-Reliable messaging goes a step further in that it is designed to maintain reliability characteristics even in the presence of software component, system, or network failures. The protocol is transport-independent, allowing it to be implemented with network technologies other than SOAP, but a SOAP binding is also defined within the specification. The full specification is available at http://specs.xmlsoap.org/ws/2005/02/rm/ws-reliablemessaging.pdf.

10. WS-Routing

• What is it?
  A protocol that allows you to specify how SOAP messages get routed between software services.
• When would you use it?
  When you have a complex business process that requires a message to pass through many handlers and you want a guarantee of proper routing.
• Tell me more!
  This is a simple, stateless, SOAP-based protocol that is used to route SOAP messages asynchronously over transports such as TCP, UDP, or HTTP. When using it, the entire message path for a SOAP message, as well as its return path is described within the SOAP envelope. It supports one-way, two-way, and peer-to-peer messages as well as long-running transactions.

An example of a SOAP message that moves from point A to point D through points B and C, specified using WS-Routing would look like this:

                  http://www.im.org/chat         soap://D.com/some/endpoint                     soap://B.com            soap://C.com                  soap://A.com/some/endpoint         uuid:84b9f5d0-33fb-4a81-b02b-5b760641c1d6                  ...   

The full specification for WS-Routing can be found at http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnglobspec/html/ws-routing.asp.

11. XML-Encryption

• What is it?
  A specification that defines how to encrypt and decrypt part or all of an XML document.
• When would you use it?
  Any time you want information passing across the wire to be private. A classic example is transmitting a password up to a Web service.
• Tell me more!
  XML-Encryption is used to encrypt and decrypt digital content, including part or all of an XML document. It is particularly useful because of its ability to encrypt only part of a document. When full XML documents are encrypted it is easier for a hacker to attempt to decrypt them, as much of the document contents can be guessed at (for example or is present in many documents). It is generally used to encrypt a part of a document, for example, user name and password information, while leaving the rest of the document in clear text. The W3C has a great resource for learning more about XML-Encryption and how to use it.

12. XML-Signature

• What is it?
  A specification that defines how to ensure the validity of the sender of a document.
• When would you use it?
  Any time you want to send or receive information and need to know for sure that the service that you are sending to or receiving from is the one that you expect.
• Tell me more!
  XML-Signature is another encryption standard but this one uses a standard public key/private key algorithm to validate the authenticity of the originator of a document. The publisher of the information has a combination of a private and public key that is computationally infeasible to factorize and signs the document with this combination. The recipient of the document can then, based on this signature, derive that he isn’t being spoofed and that the document is from who he thinks it’s from. You can learn more about how it works and how to implement it at http://www.w3.org/TR/xmldsig-core/.

WS-Finished (for Now)
There are more standards for Web services and service-oriented architecture than you can shake a stick at and more are being added all the time. For this article, I picked 12 of the best-known (and most useful) standards and gave you a quick overview of what they are and when to apply them. Developers who make themselves familiar with the WS-* specs are learning very valuable skills for the near future, as the world is quickly becoming more and more service oriented. DevX will have more articles to describe the application of specific tricky specs and situations in the future. But for now, it’s up to you?go forth and standardize and secure with WS-*!