In this fourth and final article of this series, I will put the pieces together to demonstrate the simultaneous use of all the four XML security standards, XML signature, XML encryption, WSS, and SAML, in one application. Here we will discuss two important and typical web services security application scenarios and learn two things: first, how the different web services security standards work together in an XML firewall to protect SOAP servers; second, what the different types of security tokens that you can use in WSS messages are and how they are related to digital signatures and encrypted data.

XML firewalls for Web Services Security

Have a look at Figure 1, which shows three actors engaged in an exchange of secure SOAP messages. You can see the following sequence of events in Figure 1.

Figure 1.

Step 1

A tour operator wants to book some rooms with a partner hotel at specially discounted rates. The tour operator and the hotel have existing business relationship. The tour operator's request for special discount should accompany some proof that the request is coming from a trusted business partner. For this purpose, the tour operator will include a security token in the GetSpecialDiscountedBookingForPartners request.

Listings 1 to 4 show the same GetSpecialDiscountedBookingForPartners request with different types of security tokens. Let's have a look at the security tokens one by one.

Have a look at the wsse:Security element within the SOAP Header of Listing 1. The first child element of the wsse:Security element is a wsse:UsernameToken element. The wsse:UsernameToken element wraps a username security token, very much like the username and password pairs that you use to check your e-mail.

The wsse:UsernameToken element contains three child elements, which together form the username token. The token is meant to prove the identity of the author of Listing 1.

The first child element of the wsse:UsernameToken element is a wsse:Username element, which wraps a username (ATrustedPartnerTourOperator) as its contents.

The second child element of the wsse:UsernameToken element is a wsse:Nonce element, which contains some binary data (a sequence of octets). The third child is a wsu:Created element. The Nonce and Created elements are used here in pair. In order to understand what Nonce and Created elements do, we need to understand the concept of keys generated form hashing (or message digest) functions.

Digest calculation

Let's suppose the tour operator and the hotel know a shared secret, just like your email account password, which is a shared secret between you and your email service provider. The tour operator can apply a digest algorithm to its password and arrive at a digest value. It can then use that digest as a symmetric key to encrypt or sign a message and send the message to the hotel. The hotel will use its knowledge of the shared secret to repeat the digest calculation and use the digest value (as a key) for decryption and signature verification.

What is the advantage of doing digest calculation? Why not use the password itself as a symmetric key for encryption and signing? In fact there's hardly an advantage if the tour operator is not using Nonce and Created elements.

The Nonce element wraps randomly generated sequence of bytes, while the Created element wraps a timestamp showing the time when the message was authored. The tour operator will combine the contents of these elements with his password to generate the digest value.

Combining these two elements in digest calculation has the advantage that it becomes difficult for hackers to guess the password from encrypted data or signatures. If the tour operator uses only its password for digest calculation, he will arrive at the same key every time he performs the digest calculation. Using the Nonce and Created elements in digest calculation will result in different keys, provided the tour operator doesn't re-use random numbers for Nonce element in a specified period of time.

Such keys derived by hashing a shared secret are known as HMAC (Hashed Message Authentication Code) keys.

Notice that the ds:Signature element in Listing 1 has a ds:KeyInfo element, which contains a wsse:SecurityTokenReference element. The wsse:SecurityTokenReference element has a child wsse:Reference element, whose URI attribute refers to the tour operator's username security token by means of a fragment identifier (#TourOperatorUsernameToken). We covered the use of wsse:SecurityTokenReference element in the last section of the second part of this series of articles.

This means that the tour operator used the key derived from the username token. The hotel's XML firewall will use its knowledge of the tour operator's password to repeat the digest calculation and arrive at the key that the tour operator used to sign the request of Listing 1.

Kerberos ticket

Now have a look at Listing 2, which contains a binary security token wrapped inside a wsse:BinarySecurityToken element. We introduced the use of binary security tokens in the last section of the second article of this series of articles. This time, we have wrapped a Kerberos ticket in Listing 2.

There are two types of Kerberos tickets, Ticket Granting Ticket (TGT) and a Service Ticket (ST). A Kerberos Server (also known as Key Distribution Center or KDC) hosts Kerberos ticket issuing services. It issues two types of Kerberos tickets, Ticket Granting Ticket (TGT) and a Service Ticket (ST). Let's discuss how the tour operator will use the two types of tickets to get authenticated with the hotel.

The tour operator will get a TGT from an Authentication Service (AS) hosted by the KDC. The tour operator will keep the TGT confidential and will never give it to anyone, as the TGT contains confidential information, such as a session key. If stolen, this information can be used to impersonate the tour operator.

The session key inside the TGT has a limited life time and it proves that the holder is an authenticated party for the duration of a single session. The tour operator will present the TGT to a Ticket Granting Service (TGS) at the same KDC. The TGS will provide a service ticket to the tour operator, which the tour operator can send to anyone (such as the hotel). The same TGT can be used to get as many service tickets as needed from the same KDC.

Once the tour operator has the service ticket, he will wrap the service ticket inside the wsse:BinarySecurityToken element of Listing 2 and send Listing 2 to the hotel.

The service ticket contains all information needed to specify the address of the KDC who issued the ticket and the entity to whom the service ticket was issued (in our case, the tour operator). The hotel will extract the service ticket from Listing 2 and get it authenticated or validated form the KDC who issued the ticket. If the ticket is successfully validated (and the hotel trusts the KDC), the hotel can be sure that the sender was really the tour operator.

In order for this scheme of using Kerberos tickets, it is necessary that both the tour operator and the hotel trust the KDC.

Note that the process of issuing a TGT, getting a service ticket, and validating the service tickets is not part of WSS. WSS only defines how to wrap a Kerberos ticket in a BinarySecurityToken element. The rest of the details are covered by the Kerberos specification that IETF has defined. We have included some links in the resources section, where you can find more details about using Kerberos tickets.

Security token reference

Now look at Listing 3, which does not contain any security token. Instead the wsse:Security element has a wsse:SecurityTokenReference child element. The wsse:SecurityTokenReference element contains a wsse:Reference element, which has a URI attribute whose value (http://www.myTourOperator.com/keys/Key1) points to an HTTP address.

This means that the key that the tour operator used for signature is the security token and it is available from the address that the URI attribute of the wsse:Reference element specifies. The hotel will dereference the URI to get the security token before being able to validate the signature.

Key identifier

Listing 4 shows another variety of using security tokens in a WSS message. Juts like Listing 3, Listing 4 also does not contain any security token. Instead it contains a wsse:SecurityTokenReference element, which in turn contains a wsse:KeyIdentifier element. The wsse:KeyIdentifier element wraps an identifier that identifies the key used to produce the signature. It is assumed that the hotel can uniquely identify the key from the identifier and fetch the key as well. This means that the key identification mechanism is mutually agreed between the tour operator and the hotel. For example, the tour operator and the hotel may have already exchanged keys through any mechanism and agreed on identifiers to identify the keys.

Notice the ValueType attribute of the wsse:KeyIdentifier element, which identifies type of the key. In our case, the value of this attribute is "wsse:X509v3", which means the key is actually an X509 certificate.

We have seen four alternate ways of wrapping or referencing security tokens using WSS. This covers step number 1 of Figure 1. The tour operator can send any of the messages shown in Listings 1 to 4 to the hotel's XML firewall.

Step 2

Notice from Figure 1 that step 2 occurs inside the XML firewall, which guards the hotel's SOAP server. The XML firewall receives the request, which contains a GetSpecialDiscountedBookingForPartners method invocation call. The XML firewall knows that before it can let the request make its way to the SOAP server, it has to check two things:

1. Authentication: In order to check the requester's identity, the XML firewall will extract the security token from the incoming request and process it to check who sent this message.
2. Message integrity: Making sure that the message received is exactly the one that was sent by the sender, and that no one has altered the message while on its way over the Internet. The XML firewall will validate the signature contained in the WSS message to check the integrity of the message. We have already discussed the details of this in part 2 of this series.

After successful authentication and message integrity check, the XML firewall will forward the SOAP request to the SOAP server. Listing 5 is the SOAP request that the XML firewall will send to the SOAP server. Notice that Listing 5 is the result of simply removing the SOAP Header from any of the Listings 1 to 4. This means that the SOAP server will receive only the SOAP Body without any security information, because it does not need any security information. The security information has already been utilized by the XML firewall for user authentication and message integrity.

At this point we would also like to clarify another point. We have shown the SOAP server and the XML firewall as two separate entities. This is because we are explaining web services security as a topic independent from SOAP. In real practice, an XML firewall may or may not be a separate entity i.e. some vendors may want to integrate their XML firewall and SOAP implementations. Let us consider both cases separately.

In case the XML firewall and the SOAP server are two separate entities, they will most likely be listening on two different addresses. For example, if we are considering HTTP communications between the tour operator and the hotel, the hotel may have used the following two HTTP addresses:

For XML firewall: http://www.myHotel.com/XMLfirewall
For SOAP server: http://localhost/SOAPServer

In order for the scheme shown in Figure 1 to work, the hotel will need to make sure that its web server does not allow any external client (e.g. web clients) to access the SOAP server. The security policy of the web server will allow only the XML firewall to reach the SOAP server and all other requests to the SOAP server will either be rejected or be routed to the XML firewall instead of the SOAP server.

On the other hand, the XML firewall and the SOAP server may also be integrated as one product. In this case, the XML firewall will listen to all incoming requests and the SOAP server will simply be a part of the over-all application (e.g. as a collection of Java classes), not capable of receiving requests from any client other than the XML firewall.

Step 3

Now the XML firewall sends the SOAP request of Listing 5 to the SOAP server.

Step 4

The SOAP server invokes the web service and prepares the SOAP response that goes back to the SOAP server.

Step 5

The SOAP server sends the response back to the XML firewall. The SOAP server's response back to the SOAP server is shown in Listing 6.

Step 6

Now the XML firewall has to prepare the GetSpecialDiscountedBookingForPartnersResponse message for the tour operator. This includes doing three things:

1. Add a security token in the SOAP message of Listing 6, showing the response is coming from the hotel.
2. Add an XML digital signature to Listing 6 as a proof of user authentication and message integrity.
3. Encrypt the special discount being offered to the tour operator, as this discount is supposed to be confidential data.

There can be various ways in which the hotel's firewall can perform these three tasks. Listings 7, 8, and 9 represent three different possibilities.

Have a look at Listing 7, which shows the GetSpecialDiscountedBookingForPartnersResponse message for the tour operator. Notice the following points in Listing 7:

1. Listing 7 contains a UsernameToken element, which we have already explained while discussing Listing 1. This means that the hotel and tour operator have an existing shared secret (e.g. password of the hotel that the tour operator knows), based on which the hotel has generated an HMAC key. The hotel has used the same key for signature and encryption. We'll see that shortly.
2. Listing 7 contains an xenc:ReferenceList element in the wsse:Security header. The xenc:ReferenceList element in Listing 7 contains an xenc:DataReference element.
3. The xenc:ReferenceList element may contain a number of xenc:DataReference elements, where each xenc:DataReference element is supposed to refer to an xenc:EncryptedData element. Notice from Listing 7 that the xenc:ReferenceList element contains just one xenc:DataReference element, whose URI attribute value (#DiscountResponse) points to the xenc:EncryptedData element inside the GetSpecialDiscountedBookingForPartnersResponse element in the SOAP Body.
4. Now see what's inside the xenc:EncryptedData element in Listing 7. The xenc:EncryptedData element represents the contents of the GetSpecialDiscountedBookingForPartnersResponse element in encrypted form. We discussed xenc:EncryptedData element in detail in the second part of this series of articles. We would like to draw your attention at the ds:KeyInfo element child of the xenc:EncryptedData element. The ds:KeyInfo element contains a wsse:SecurityTokenReference element, which refers to the security token contained inside the UsernameToken element of Listing 7. This means that the key used for encryption is the same as the HMAC key that the UsernameToken element specifies.
5. Listing 7 also contains a ds:Signature element. Notice that the ds:KeyInfo child of the ds:Signature element also refers to the HMAC key that the UsernameToken element contains. This means that the hotel used the same key for signature.

There is one very important point to be noticed in Listing 7. The ReferenceList element appears before the ds:Signature element. This means that the hotel first signed the complete SOAP Body and then encrypted contents of the GetSpecialDiscountedBookingForPartnersResponse element. As you perform a signature or encryption step, you prepend the corresponding element in the wsse:Security header. The net result of this prepending rule is that the security header contains elements in the reverse order of activities that you performed.

The tour operator, on receipt of Listing 7 will follow the order in which the elements appear inside the wsse:Security header i.e. it will decrypt the content of GetSpecialDiscountedBookingForPartnersResponse element first and then validate the signature.

If the tour operator does not follow the order in which the elements appear inside the wsse:Security header, the signature validation process will fail (although there will be no problem in decryption). This is because, the hotel signed the non-encrypted (plain text) contents. If the tour operator tries to validate the signature on encrypted contents, the hash value will not match and therefore the signature validation process will fail.

Now have a look at Listing 8, which is exactly the same as Listing 7, but the order of signature and encryption has been changed. This time the ds:Signature element appears before the xenc:ReferenceList element. This means the hotel encrypted the contents of the GetSpecialDiscountedBookingForPartnersResponse element and then signed the encrypted contents.

Naturally in order to process Listing 8, the tour operator will first validate the signature and then decrypt the GetSpecialDiscountedBookingForPartnersResponse element.

Listing 9 is another variation of the same response from the hotel. Listing 9 demonstrates the use of X509 certificates for signing and the use of symmetric keys for encryption. The hotel can use its X509 certificate for signing, but cannot use the same certificate for encryption. This is because the hotel cannot encrypt using its public key. It rather needs the tour operator's public key for encryption, so that the tour operator can decrypt the encrypted part using its private key. Let's see how this is accomplished in Listing 9.

1. Listing 9 contains a wsse:BinarySecurityToken element, which wraps an X509 certificate.
2. The ds:KeyInfo element inside the ds:Signature element in Listing 9 refers to the wsse:BinarySecurityToken element, which means the hotel produced the signature using its X509 certificate.
3. Listing 9 contains an xenc:EncryptedKey element instead of the xenc:ReferenceList element of Listings 7 and 8.
4. The xenc:EncryptedKey element wraps an encrypted key. You can compare the xenc:EncryptedKey element of Listing 9 with the xenc:EncryptedData element which we described in the second article of this series. You will see that there is no difference between their structures. The only difference is that the xenc:EncryptedData element wraps data in encrypted form, while the xenc:EncryptedKey element wraps cryptographic keys in encrypted form.
5. The xenc:EncryptedKey element contains a child element named CipherData, which in turn contains a child named CipherValue. The CipherValue element wraps a key in encrypted form. This key is actually a random number. The hotel generated the random number and then encrypted it using the tour operator's public key, so that the random number remains a shared secret between the two communicating parties. Such random numbers are normally referred to as secret keys.
6. The xenc:EncryptedKey element contains a ds:KeyInfo element, which wraps a ds:KeyName element, whose contents are "TourOperatorKey". This means that the hotel used the tour operator's public key to encrypt the secret key (the random number). When the tour operator receives this message, he can decrypt the secret key using his private key. Once he has the secret key in decrypted form, he can use it to decrypt the encrypted data.
7. Also have a look at the xenc:ReferenceList element inside the xenc:EncryptedKey element. This element, as before, refers to the xenc:EncryptedData element by means of a fragment identifier. The xenc:EncryptedData element inside the GetSpecialDiscountedBookingForPartnersResponse element is the actual encrypted data that was encrypted using the secret key.

Step 7

The hotel sends the completed response (Listing 7, 8, or 9) to the tour operator.

Step 8

The tour operator processes the hotel's response to read the special discount.

Sharing Authentication Data

The discussion in the previous sections assumes that the hotel and the tour operator have existing business relationship with each other. We will now depict a different scenario, in which the hotel and the tour operator do not have an existing relationship of trust with each other, and yet the tour operator wants to enjoy the special discount that the hotel offers.

Have a look at Figure 2, which shows all the actors of Figure 1, with an additional entity labeled "eMarketplace". Here we are assuming that the hotel and the tour operator do not know each other prior to the exchange of messages shown in Figure 2. However both the hotel and the tour operator have a relationship of trust with the eMarketplace. The use of SAML together with WSS, XML signatures, and XML encryption allows the hotel and the tour operator to share with each other their trust on the eMarketplace.

Figure 2

The following sequence of message-exchanges occurs in Figure 2:

Step 1

The tour operator wants to enjoy the special discount that the hotel offers. Therefore, it requests the eMarketplace to issue a SAML assertion. Listing 10 shows a request from the tour operator to the eMarketplace to issue an assertion. Notice that the request for a SAML assertion shown in Listing 10 is a normal WSS message that carries a username token and the tour operator's digital signature. The username token is the same as the one which we explained while discussing Listing 1. You can say that the tour operator can use WSS for authentication and message integrity while requesting for a SAML assertion.

Recall from the third article of this series that SAML defines the syntax to produce assertions and share authentication information. SAML does not impose any restriction on the actual process of authentication. Therefore, the username token element shown in Listing 10 is just one possible way of sending an authentication token and a request for assertion in a single message. The eMarketplace will first authenticate the tour operator using the username token and then issue the assertion based on the authentication.

Step 2

The eMarketplace sends an SAML assertion in response to the tour operator's request. The SAML assertion is shown in Listing 11. Note that Listing 11 wraps the Response in the SOAP Body. We explained the request-response mechanism for SAML assertions in the third article of this series, so we don't need to go into the details.

However, note that Listing 11 shows the signature within the Response element and not in the header. All the digital signatures that we have discussed so far reside inside the wsse:Security element. However, the SAML assertions specification dictates that while signing a SAML assertion, a SAML assertion issuing authority should use enveloped XML digital signature. This means that the signature should be enveloped (wrapped) inside the Response element. That's the reason we have shown the signature as a direct child element of the Response element.

Also notice that Listing 11 shows the assertion in plain text form. Listing 12 shows the same assertion in encrypted form. Just notice that we have replaced the contents of the SOAP Body with an xenc:EncryptedData element and included an xenc:EncryptedKey element in the wsse:Security element to indicate that we have encrypted the contents of the SOAP body.

Step 3

Now the tour operator wraps the SAML response in a WSS message and sends the WSS message to the hotel. This is shown in Listing 13, where we have used the SAML assertion as a security token. We have already explained the use of SAML assertions as security tokens in the last section of the third article of this series.

Notice that Listing 13 is similar to Listing 1, 2, 3, or 4, except the type of security token used. Listing 13 carries the same GetSpecialDiscountedBookingForPartners method call.

Step 4

The hotel's XML firewall processes the request of Listing 13, extracts the assertion from the security header, and checks the validity of the assertion. Upon successful validation of the authentication token and message integrity check, the hotel's XML firewall will discard the security information from Listing 13. The result will be Listing 14, which is the same as Listing 5, which the XML firewall sent to the SOAP server in step 3 of Figure 1.

Step 5

The hotel's XML firewall sends the SOAP request of Listing 14 to the SOAP server.

Step 6

The hotel's SOAP server invokes the web service and prepares the SOAP response, as shown in Listing 15 (same as Listing 6, which the SOAP server sent to the XML firewall in step 5).

Step 7

The SOAP server sends the SOAP response of Listing 15 to the XML firewall.

Step 8

The XML firewall authors the security information and wraps the information in the SAOP response. We explained three possibilities (Listings 7, 8, and 9) while discussing step 6 of Figure 1. All three possibilities are applicable here.

Step 9

The XML firewall sends the WSS message (Listing 7, 8, or 9) to the tour operator.

Step 10

The tour operator processes the WSS message received from the hotel's Firewall and extracts the discount information.

Future Directions and Applications

We have discussed four XML security standards (XML Signatures, XML Encryption, WSS, and SAML) and two application scenarios (direct authentication and sharing of authentication data) in this series of articles. Before we conclude this series, we would like to point at another important XML security standard being developed by W3C and two other application scenarios of web services security.

We have also discussed cryptographic keys in this series of articles. In fact the whole concept of security over the Internet is based on the use of cryptographic keys. The management of cryptographic keys is itself a whole topic, which is of paramount importance.

Keeping in mind the importance of key management, W3C is currently developing an XML-based key management standard known as XML Key Management Services or XKMS for short. Refer to the XKMS page at W3C for further details.

Transactions in web services is an important web service application. WS-Transaction is an attempt to standardize the transactional framework in web services. You can download the WS-Transaction specification and check the security considerations section of the specification to see that WS-Transaction uses WSS to secure transactional web services.

SOAP-based messaging is another important application of web services. The ebXML Messaging Services (ebMS) standard by OASIS defines the messaging framework for web services. You can download the ebMS specification from the ebXML Messaging page to see how it uses XML signatures.

• Read the official specifications of XML Signature, XML Encryption, WSS, and SAML.
• Following are some of the WSS, XML signatures, XML encryption, and SAML implementations currently available:
  • A web services development environment by IBM named Emerging Technologies Toolkit (ETTK) (formerly known as "Web Services Toolkit") supports XML encryption, XML signatures, and WSS along with other XML standards.
  • Baltimore's KeyTools XML for Java Toolkit supports XML signatures and XML encryption. An evaluation version is available for download.
  • This C-based Cryptlib Toolkit provides XML encryption and XML signatures support.
  • VisualSafe presents an evaluation version of its VisualSoft SecureDev 1.1 toolkit that supports XML signatures and XML encryption.

• Read this two part series of articles (Part 1 and Part 2) by the same author, which provides a simple implementation of XML encryption in Java.
• Read this article to learn more about Kerberos. Also check out Kerberos Home page at MIT site.
• We have discussed the concept of an eMarketplaces. This article by the same author discusses the eMarketplace model in detail.

XML.com Copyright © 1998-2006 O'Reilly Media, Inc.