Talking To HailStorm

Copyright and Authorship Notice

This is an abridged chapter extract and was written by Dan Maharry. It is taken from "Early Adopter Hailstorm" by Dan Maharry, Robert Eisenberg, P.G. Muraleedharan and Jonathan Pinnock published by Wrox Press Limited in October 2001; ISBN 186100608x; copyright 
© Wrox Press Limited 2001; all rights reserved.

No part of this chapter may be reproduced, stored in a retrieval system or transmitted in any form or by any means -- electronic, electrostatic, mechanical, photocopying, recording or otherwise -- without the prior written permission of the publisher, except in the case of brief quotations embodied in critical articles or reviews.

Microsoft surprised a lot of people with the release of their initial white paper on HailStorm. It contained the frank proposal that HailStorm services would be completely accessible from any platform, and not just Windows. As the white paper put it:

"The HailStorm platform uses an open access model, which means it can be used with any device, application or services, regardless of the underlying platform, operating system, object model, programming language or network provider. All HailStorm services are XML Web SOAP; no Microsoft runtime or tool is required to call them."

Over the next three chapters, we'll look at the standards Microsoft has chosen to use and what we need to know to get HailStorm working for us.

In this chapter, we'll look at:

• The Kerberos Authentication Service, which Passport uses to validate users
• How to construct the SOAP packets that contain instructions for HailStorm web services.
• The transport protocols we can use to send our SOAP packets to the HailStorm server.

Bear in mind, that where possible we'll be looking at only the relevant pieces of each standard for use with HailStorm. There will be links and references outside of the book for those wishing to find out more as appropriate. We'll also flag up where things might not go so well in this quest for technology agnosticism.

Making Conversation

When HailStorm is finally released in the first half of 2002 it will sit behind the identity/security mechanism offered by Passport v3.0, which is due be released some time earlier. At the time of writing, Passport v2.0 had just been released and there were no more specifics on v3.0 beyond the knowledge that it will stop using its current proprietary authentication mechanism in favor of the industry standard Kerberos system. This would suggest that Passport might become the authentication mechanism in the next version of the Windows OS family; Kerberos is already the Windows 2000 security mechanism. If this happens, a user logged on to their computer would automatically be logged into all Passport-enabled web sites as well.

As we saw in Chapter 1, HailStorm offers a set of services in the form of a digital safe deposit box for which a user pays a small subscription fee. This sits behind Passport as an additional, decidedly useful feature which clients may make use of if they want. Users log on to a HailStorm endpoint (a web site, XBox game, Stinger smart phone, PocketPC etc.) in the usual way through Passport. If they already have a digital safe deposit box, the endpoint to should give the user the option or alter the information stored within the DSDB. They don't have a DSDB then they should be given the option to create one.

A Secure Future

So how will an endpoint perform a security handshake with and send a request to the Passport/HailStorm servers once HailStorm v1.0 has arrived? Let's look at the interaction with the Kerberos part of the Passport system first.

1.    Once a user has clicked on the Passport login icon, the endpoint sends a request to Passport (which acts as the Key Distribution Center or KDC) for a ticket-granting ticket (TGT) for the user.

2.    Passport returns a session key encrypted with the user's secret key and the TGT encrypted with its (Passport's) own secret key. The TGT also contains the session key.

3.    The endpoint asks the user for their password and generates their secret key. If the password was correct, the endpoint can now decrypt the session key.

4.    The endpoint now asks Passport for a ticket to access the HailStorm servers. Along with the request, it sends the still-encrypted TGT and some information that authenticates the user (UserID, PlatformID, and ApplicationID) encrypted with the session key.

5.    Passport decrypts the TGT, retrieves the session key from it, and decrypts the authentication information. All being well, it generates a new session key for the endpoint's talk with HailStorm and incorporates the key and the various IDs into a new ticket. The ticket is then encrypted with a secret key it can share with HailStorm on demand and is sent back to the endpoint along with the new session key again encrypted with the user's secret key.

The endpoint now has the information it needs to talk to HailStorm - the Kerberos ticket and the session key, which it decrypts with the user's secret key. It can now build a message to HailStorm, authenticate it, and expect a response.

6.    The header of the SOAP message holds the address of the server hosting the appropriate web service and the still-encrypted TGT and User PUID for identification.

7.    The body of the SOAP message to HailStorm contains an instruction to retrieve or amend information. This and the rest of the body are encrypted with the session key.

8.    Once completed, the endpoint sends the message to the named HailStorm server.

9.    On receipt of the message, HailStorm sends Passport the PUID and asks for the appropriate secret key to decrypt the ticket, which Passport delivers.

10.HailStorm decrypts the ticket and attempts to decrypt the body of the message with the session key.

11.All being well, the instruction is carried out and either the appropriate results or an error message are returned in the body of the SOAP response message encrypted by the session key.

In overview, it's apparent that only encrypted information is ever sent across the wire to ensure that the request, response, and user information remain as secure as possible.

At this point, it may not be too surprising if you find yourselves questioning the wisdom of Microsoft's choice of Passport as HailStorm's authentication mechanism. It is after all a Windows-only technology in the main. The key thing to remember is that Kerberos is an industry standard and not originally from Redmond. By adopting this, HailStorm can be accessed by any endpoint that can produce the right ticket and session key - not just Passport. Should other community-based sites like Yahoo or AOL decide to adopt Kerberos as their login mechanism; their users will have access to their own digital safe-deposit boxes as well. Likewise, Passport users will be able to access the facilities available to AOL and Yahoo.

It's not just the major players on the net either that can take advantage of this step. If you can implement a Kerberos-based login system, regardless of platform or operating system, you will be able to log in to HailStorm with it. Have a look at http://www.microsoft.com/windows2000/techinfo/howitworks/security/kerberos.asp for more information.

An Insecure Present

As we have already said, the Kerberos-based interchange is naturally still a while off. Therefore, the initial release of HailStorm in a Box skirts entirely over the issue of security, replacing the Kerberos ticket with a simple ID number generated when a first provisioning a HailStorm service for the user. If you've already installed the SDK, you can discover your identity and your temporary ID using the hspost executable in the Bin directory of the installation:

Similarly, the bodies of the SOAP packets sent between endpoint and service are not currently encrypted either. We'll see when we construct an example query inside a SOAP packet where this current shortcut fits in and the final solution that will replace it.

The Simple Object Access Protocol is described in its specification as "a lightweight protocol for the exchange of [structured and typed] information [between peers] in a decentralized, distributed environment". As this is the sort of environment we be using when programming against HailStorm SOAP is ideal. Intended as a simple alternative to other over-the-wire protocols (like DCOM, CORBA/IIOP and RMI) that could work within the generic Internet infrastructure with no other assistance, its sole function is to define the format of the message sent between clients and servers. Other internet protocols - in this case, HTTP, TCP, and SMTP - define the (synchronous and asynchronous) transport mechanisms used to send the messages.

Each SOAP message is an XML document with three main elements: the SOAP envelope, the SOAP header, and the SOAP body.

q        The <Envelope> element is the mandatory top-level element of a SOAP message, wrapping up both the message itself and any information about the message that might be necessary for its successful delivery and processing.

q        The optional <Header> element lets you specify extra information about the message that is not the message itself. For example, authentication, transaction management, and delivery routes.

q        The mandatory <Body> element contains the actual payload of the SOAP message, be it a request from an endpoint or a response from a server. The latter might contain a <Fault> element indicating an error or glitch occurred in the processing of the request.

SOAP also defines a namespace for the envelope at http://schemas.xmlsoap.org/soap/envelope/. This takes the attribute encodingStyle that allows you to set the serialization rules used in the SOAP message.

This schema is actually stricter than XML in an effort to keep things simple (which is the aim of SOAP after all), preventing the use of DTDs and processing instructions in a message for example.

For further information on SOAP, check out the W3C specification at http://www.w3c.org/TR/SOAP/.

SOAP

The choice of SOAP as the communication protocol between HailStorm endpoints and servers is not a surprise. Microsoft's open access strategy and HailStorm's web service‑centric nature matches SOAP's language and platform neutrality. However, SOAP never figures in HailStorm as an RPC medium (its original function), carrying objects and serialized structured data across the web. Instead, it uses SOAP's ability to route XML messages over the web to a server - via zero or more intermediaries, synchronously or asynchronously - and receive them back the same way. Indeed, a lot more information goes into the header of a SOAP envelope than in its message payload.

Deconstructing a HailStorm Request Message

Let's take an example and briefly look at each part of a request message before we go into the real detail. Say a friend has just got married and might need to update her last name in the contacts list stored in your digital safe deposit box by the myContacts service. The message you'd need to send HailStorm would look like this:

First, we have the definition of the namespaces at work inside this SOAP envelope/message. These are all pretty standard except number three which changes depending on the service you're addressing.

At the top of the header is the routing information describing what type of message this is, its ultimate destination, and any intermediate points it will need to take on its trip there or on its trip back. Finally, there is the unique identifier for the message that the response will quote back for reference.

Second in the list is the Kerberos ticket used for talking with HailStorm. Later in the conversation, you may also include here the role the server has assigned to you as this expedites the carrying out of your instructions.

Last in the message header is information about the request itself; its destination, purpose, notes for the response, and so on.

We could have included two further elements in the header - <echoBack> and <adminRequest> - but the former is specific to sending SOAP message asynchronously which we can't at the moment and the latter, which replaces the standard request, wasn't working as we went to press. The XMI manual contains full details of what they should do.

As noted before, the body of the message contains the actual instructions to HailStorm - in this case, a request to replace your friend's maiden name with her married name.

In overview, the construction of the SOAP message remains simple, just as Don Box and company intended when they designed it (SOAP that is). The usually optional <Header> element has become mandatory, but that's about it as far as rudimentary SOAP is concerned. To grasp the HailStorm specific pieces, we'll need to start from the top again and look at each message segment in detail.

<Envelope> - Setting the Namespaces

One of the main reasons that SOAP will become at least the basis for XML web service communications (if it isn't already anyway) is its extensibility. In this particular case, we need to make use of four other namespaces in our message besides the standard one to cover the elements we need to get everything working.

In order of declaration, the schemas that define these namespaces represent:

srp - The SOAP Routing Protocol or SOAP-RP for short. This Microsoft protocol lets us define very precisely the route our message will take to and from the HailStorm server. You can find the SOAP-RP specification at http://www.gotdotnet.com/team/xml_wsspecs/soap-rp/default.html

m - The 'Content' document for the myContacts web service containing all the contacts information. Each my* service contains its own unique set of data elements as defined in a schema created specifically for that service. If you were querying the myAlerts service, you would specify the myAlerts schema here instead of that for myContacts. These schemas are covered in full in the XMI manual that accompanies the HailStorm SDK and to a lesser extent in Chapters 4 and 5 of this book.

hs - The core, non-service-specific elements that HailStorm needs to interject into the message.

ss - The security extensions to SOAP 1.1 ('SOAP-SEC') that allows a SOAP header entry to carry digital signatures - in this case the Kerberos ticket for talking with HailStorm. You can find the specification for SOAP-SEC at http://www.w3c.org/TR/SOAP-dsig/

The <envelope> element also omits the declaration of the SOAP serialization namespace that is usually present in SOAP messages. HailStorm messages will only ever be raw XML and won't need to hold any objects, so the reference is redundant.

Note that the URIs for these namespaces change quite often between releases of HailStorm and it's worth keeping an eye on them when a new one arrives. A change here will signify a change in the way the contents of the SOAP messages are structured.

<Header>/<path> - Defining A Target

The <path> header, as defined by the SOAP Routing Protocol, lets the creator of the message define its ultimate destination and the routes that message and replies will take to get there and back. It is a mandatory part of every HailStorm message, be it request or response.

The constituent sub-elements of <path> are described in the table below.

 

Element	Mandatory?	Description
<action>	Yes	Absolute URI of the form http://schemas.microsoft.com/hs/2001/10/core#####, where #### is the purpose of the message - request, response, notification, or fault. Note that if a request is transmitted by HTTP, the SOAPAction HTTP header field must contain this URI.
<to>	Yes in requests No in responses	Absolute URI of the form protocol://[cluster.]service.domain/[instance], which represents the ultimate destination of the message. It is mandatory for requests, optional for responses should there be a need to send it to an arbitrary URI, and must not be modified along the message path, once the message has been sent.
<fwd>	No	Holds as a list of <via> sub-elements that detail the route the request message should take to its ultimate destination
<rev>	No	Holds as a list of <via> sub-element that detail the route the reply to the message should take to its ultimate destination, the last element in the list. Omitting the <rev> element from the header indicates that no response is necessary.
<via>	Yes if <fwd> or <rev> elements are present, else no.	Contains one element of an ordered list of absolute URIs representing the intermediary endpoints that the message will pass through to get to its ultimate destination. An empty list would indicate that the message should return the way it came. Most commonly, this would mean on top of the HTTP response corresponding to the HTTP request that the message came in on.
vid	No	Attribute of <via>. A unique id that identifies a pre-defined route. Intermediate endpoints might not know the whole route but know where to send the message next based on the vid.
<id>	Yes	Universally unique identifier for a message generated by the sender. Cannot be shared by any two messages.
<relatesTo>	No in requests Yes in responses	Specifies the UUID of the request to which the message is a response.

 

The route from endpoint to server and back can involve several intermediaries that know how to receive and send on SOAP messages as required. It might also make use of several transport protocols as well. SOAP-RP currently allows us to define a path over the synchronous messaging protocols HTTP, UDP, and TCP only, but the need to support asynchronous messaging over SMTP as given in the SOAP specification should mean that SMTP will also be supported soon. Other messaging systems like Microsoft's MSMQ, IBM's MQSeries, .NET Remoting, and the Java Message Service (JMS) also have the capacity to send and receive SOAP messages as either intermediaries or endpoints.

Synchronous Messaging via HTTP

The HTTP request/response model mirrors that of SOAP almost perfectly and is the protocol of choice for synchronous messaging using SOAP. If a secure connection is required, HTTPS (HTTP + SSL) can be used in exactly the same fashion. It's generally recommended to use the HTTP POST request to send your SOAP message, as this will keep it hidden, as opposed to HTTP GET, which will attempt to append it to the destination URI. Indeed, the SOAP 1.1 specification provides details for binding SOAP to HTTP POST. It's all in the header.

The key lines of the HTTP header, specifying that the request contains an XML document using the utf-8 character set (HailStorm uses only utf-8 encoding) and that it is a HailStorm request are highlighted. In response, a SOAP message with the header:

is returned if the query worked and the SOAP message following the header contains a response indicating success. If, however, something went wrong on the server and an attempt to processing your query generated a SOAP Fault, the response header will always take this form:

There are several different scenarios using HTTP we can hypothesize now, which should be working when HailStorm becomes a reality next year.

Scenario 1: No Response Necessary

The first and simplest is the minimal case where the SOAP request is sent over HTTP and doesn't require a response (indicated by not including the <rev> element).

With all the optional elements taken out it's not too difficult to see how this all fits together.

Scenario 2: Response needed from sender

If we add in an empty <rev> element to this <path>, like so, we effectively add in that we would like a response and that it should be returned as an HTTP response to the original POST request.

This is the most common way to instigate a synchronous request/response from the HailStorm server.

Scenario 3: Response required somewhere else

If we needed to send the response to an endpoint other than the origin of the request, we would just add that as a value to the <via> element inside <rev>.

Scenario 4: Working through a proxy

For those behind firewalls, the fear that your SOAP messages won't go anywhere should be allayed with the knowledge that ports 80 and 443 (the defaults for HTTP and HTTPS respectively) are open on practically every firewall today. All that's required is for you to incorporate your firewall into your <fwd>/<via> and <rev>/<via> lists so the SOAP message knows how to find its way out and back in.

Of course, HTTP isn't the only transport protocol capable of synchronous messaging, but it is the simplest. It's also the only one whose binding with SOAP has been finalized. The TCP and UDP bindings in SOAP-RP are still in the preliminary stages.

Asynchronous Messaging via SMTP

Sending SOAP messages via email over SMTP or via some other asynchronous protocol is theoretically possible, in that the binding of SOAP to the SMTP protocol has been defined, but has yet to be implemented or documented. It should be only a matter of time before theory becomes practice though as SOAP-RP defines a binding to SMTP, allowing us to send our messages to HailStorm at least partly over email. We might perhaps see intelligent lyris-like servers as intermediary endpoints that know how to read and react to the contents of a HailStorm message, forwarding it to the next end point in the <via> list or storing it for your final consumption later. Theoretically then, we might one day be able to send messages that went via SMTP for some of the journey and not for the rest of it:

For the time being however, we must content ourselves with purposely embedding our SOAP message inside a MIME document and sending it on a one-leg journey to the server. MIME (Multipart Internet Mail Extensions) is a multipart mechanism for the bundling of several items within the same message. In this case, we would create a MIME document that held the SOAP message and any other files associated with it. For example, you could send a message to the myDocuments service saying 'Store the documents I have attached to this message', or perhaps send an electronic card to myContacts saying 'Read this card and store the information within.'

You can find the specification that describes how to bind SOAP 1.1 to MIME at http://www.w3c.org/TR/SOAP-attachments. In brief, it states that while the MIME envelope is aware of the SOAP message within (its content-type is set to text/xml), the SOAP message is unaware that it is being held inside a larger message. However, it does contain links to the other files attached in the MIME message within its <body> element. For example,

The actual insert request for the myDocuments service is left out because the schema for the content document of that service hasn't been released yet.

The top of the document declares the version of MIME the document conforms to and that it contains separate files which are related (Multipart/related) to a root document - our SOAP message, whose content type is given next (text/xml). The SOAP message follows in its usual form, the only difference is that the documents attached to the message are referred to in href links. In the message above then, we've included a reference to the Word document we want HailStorm to store for us. The document itself follows immediately after in the MIME message, an ASCII attachment with a content type of application/msword.

SOAP messages bound into a MIME document with or without any attachments they may have can be carried over any transport mechanisms - HTTP, messaging servers, etc - but the parsing of the MIME message itself is not very efficient. For this reason, Microsoft are developing an alternative to MIME encoding - DIME.

DIME, not MIME?

The reasoning behind the creation of DIME (Direct Internet Message Encapsulation) as MS sees it is twofold:

q        SOAP isn't very good at storing certain types of files (for instance binary image files or other XML files with different character encoding) within a message.

q        The speed of processing the SOAP message: SOAP message delimiters are only found once the whole message has been parsed. This adds to the overhead incurred in processing the message. Parsing a MIME multipart message can also take long time while trying to determine the various sub-parts of the MIME message.

DIME then is a 'leaner, meaner' binary encapsulation format for multipart documents with the media type 'application/dime'. Like MIME, it doesn't worry about how it will be transported from endpoint to endpoint - just how the components of the message are put together and taken apart. It's SOAP-RP that takes care of this; using DIME is mandatory over UDP and TCP. Unlike MIME, it's very new; Microsoft only released specification document on May 23, 2001. You can the DIME specification at http://www.gotdotnet.com/team/xml_wsspecs/dime/default.htm.

<Header>/<licenses> - Adding Some Authentication

Returning to our original SOAP message, the next part of the <Header> to look at is the <licenses> element. Like the <path>, this too is a mandatory element for a SOAP message targeting a HailStorm service.

The <licenses> element itself is defined by the SOAP-SEC schema extension to SOAP that caters for the embedding of digital signatures inside messages. In our particular case, we're using it to store two things:

• The Kerberos ticket that was generated for us when we logged into Passport. This ticket must be present inside a SOAP request to HailStorm for it to be valid, in a nested <hs:identity>/<hs:kerberos> element.
• The authorizedRole of the current client application with respect to the web service it's talking to - for example, owner, friend, or associate. Typically, this element is empty on first contact with the web service, which then grants it a role license to be used in any subsequent communication. Using this element allows the service to determine whether or not the user has the right privileges to process the request much faster than if the license was not available. Note that a role license is valid only for the duration of the session during which it was created. A new one must be created for each new session with the service.

Note that with the Kerberos authentication system not yet built into Passport, this version of HailStorm at least, must use the artificial ID generated when you provisioned the services for the user. Running the hspost -p at the command prompt, can retrieve this ID.

Two more elements you might find here in future releases of HailStorm are <ss:integrity> and <ss:confidentiality>. The former is used to hold any digital signatures that may need to be used and the latter to hold the <encryptedData> element specified by the XML Encryption initiative. Both also understand the SOAP mustUnderstand attribute that can be set to make sure that the recipient understands the whole message or else return an error message.

You can find out more about the SOAP Security Extension at http://www.w3c.org/TR/SOAP-dsig/.

<Header>/<request> - The Request Header

The <request> header element contains all the request information HailStorm requires bar the location of the information to be queried and the actual XMI instruction to be carried out.

There are four attributes for the <request> element itself:

• The service attribute contains the name of the HailStorm service you are querying.
• The document attribute specifies which of the three documents - content, roleList, or system - associated with the service you are trying to access.
• The method attribute contains the name of the HSDL method you are attempting to call against the web service. For example, insert, delete, or update. For more information on HSDL, see Chapter 5.
• The genResponse attribute tells the service whether to create a response to the query and send it back to the address given in or implied by the <rev>/<via> element. This can have three values - always, never, and faultOnly - indicating that a response should always be generated, never be generated, or generated only if an error occurred.

The <key> element meanwhile locates the exact XML document that is carrying the information you need to access. The cluster attribute states which server cluster the document is stored on while the instance attribute distinguishes which instance of the document owned by the entity with the given puid is being addressed. It is quite possible for one user/entity to have two sets of information stored within a service. For example, you could prefer to keep separate a list of business contacts from your personal contacts. In this case, the instance attribute could be all that differentiates the two sets of data from each other.

The puid attribute meanwhile is filled automatically with the Passport id of the entity that logged on and was authenticated by Kerberos. Like the Kerberos license however, while this is what will happen when HailStorm is finally released, for now it must be filled in with the artificial ID that you can retrieve by running hspost -p at the command prompt.

<Body>/<###########> - The Request Body

Last but by no means least, the body of the SOAP message contains the actual instructions to the service.

Each instruction is expressed in HailStorm's own data-manipulation language (HSDL), which we look at in Chapter 5. The top-level element represents the instruction given by the method attribute of the <request> element in the header, and its select attribute holds the route to the node in the XML document containing the data to be accessed, given as an XPath string (see Chapter 4 for more on forming these). Any XML nested inside the request is new information with which the user wishes to update or to insert into their DSDB.

Although it has taken a little while to work through it all, the individual elements of a HailStorm request message are pretty easy to take on board and as we'll see later, we won't even need to generate a great deal of the header when the HailStorm runtime libraries become available. For now though, let's take a look at the typical structure of SOAP response message we might get from HailStorm.

The Response from HailStorm

As you might expect, the format for a HailStorm response message doesn't differ greatly from that of a request. Of course, this time we need to know its construction in order to parse it rather than build it.

The namespace declarations for the response are the same as those for the request.

The path element however contains significantly less then before and the <relatesTo> element now contains the UUID for the request message to which this is the response.

As we noted earlier, the licenses element in the response also includes the authorizedRole element that we can include with subsequent messages - in this session only. Using this means that HailStorm doesn't need to re-evaluate the user's role and permissions before executing the request.

The <response> header returns the role assigned by HailStorm to the entity associated to the PUID given in the request header. Even if it can't do this for some reason, the response header will always be present in the message. In this case, "rt0" indicates that the client has full read-write access to myContacts. We'll take a more detailed look at roles in Chapter 5.

Last but not least, the body of the request message contains either a success message or a SOAP fault. If it's a success, the body may also contain:

• The results of the query, if one was made
• The reference IDs for any new information added to the safe-deposit box, if any was added

Interpreting SOAPFaults

Of course, it's unlikely that we won't create a few errors here and there, so it's useful to know what to look for when HailStorm returns a fault. SOAPFaults can look quite messy, especially if the lines wrap around to the next line. On reflection though, they can be quite easy to interpret. Like SOAP envelopes, there are two parts to a SOAP Fault:

• The overview, comprising the <faultcode> and <faultstring> elements
• The details of the errors generated, found in the <faultChain> element

Let's take an example. This is the error returned from the query above if we misspell myContacts, which is case-sensitive, with a lower case 'c'.

<faultcode> can return one of four values: Client and Server indicate that the client malformed the SOAP message or that the server was unable to process the message internally. The other two, VersionMismatch and MustUnderstand are SOAP-specific. The former indicates that HailStorm found the SOAP enveloper defined by an invalid namespace and the latter that HailStorm failed to fully understand the semantics of a message for which the SOAP mustUnderstandattribute was set.

The <faultstring> element meanwhile holds a short description of the error.

The most useful information is found inside the <faultChain> element, with a long and short description of each error. Sure enough, in the <longDescription> field, informs us that we have spelt the service name incorrectly.

This example is perhaps a bit too simple, generating as it does only one error. As we all know, one error often leads to another and another. The key is just to read what's in front of you. Misspelling a closing tag for example throws three errors back at you, the misspelling first and then two consequences of that.

Of course, there's only one mistake rather than three. I think it could be because 'The end tag found or its namespace does not match the last open tag'. Hmm.

It's never going to be as trivial as this all the time, but you should at least know now how to read a SOAP fault if that's all you have to go by. On the other hand, if you're using an XML IDE, or perhaps even the HailStorm extension for Visual Studio .NET that is in the works, the raw SOAP fault message will probably be parsed for you first - lucky you.

Summary

In this chapter, we have worked through a typical conversation between HailStorm endpoint and server. We have seen that

• Once a user is authenticated by the Kerberos system in Passport, the Passport ID and Kerberos ticket given the user are then embedded in the request sent to the server to continue the authentication process.
• Each piece of conversation between endpoint and server is encapsulated in a SOAP message.
• Each SOAP message includes routing information to the server and back, authentication info, and the request itself.
• The request is in two parts - an instruction in HSDL (HailStorm Data-manipulation Language) and an XPath expression to identify the part of document the instruction is to be carried out on. We'll cover the formulation of XPath expressions in the next chapter and a description of each HSDL instruction in Chapter 5.

In next chapter, we'll be taking at look at the structure of the XML documents that we've been querying and how to navigate about them using XPath.