Web Services Security, Part 4
July 22, 2003
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.
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
coming from a trusted business partner. For this purpose, the tour operator will include
security token in the
Listings 1 to 4 show the same
with different types of security tokens. Let's have a look at the security tokens
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
check your e-mail.
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
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
elements are used here in pair. In order to understand what
Created elements do, we need to understand the concept of keys generated form
hashing (or message digest) functions.
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
symmetric key for encryption and signing? In fact there's hardly an advantage if the
operator is not using
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
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
operator uses only its password for digest calculation, he will arrive at the same
time he performs the digest calculation. Using the
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 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.
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
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.
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
element has a
wsse:SecurityTokenReference child element. The
wsse:SecurityTokenReference element contains a
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
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.
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
hotel can uniquely identify the key from the identifier and fetch the key as well.
means that the key identification mechanism is mutually agreed between the tour operator
the hotel. For example, the tour operator and the hotel may have already exchanged
through any mechanism and agreed on identifiers to identify the keys.
ValueType attribute of the
element, which identifies type of the key. In our case, the value of this attribute
"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.
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
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:
- 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.
- 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:
For SOAP server:
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.
Now the XML firewall sends the SOAP request of Listing 5 to the SOAP server.
The SOAP server invokes the web service and prepares the SOAP response that goes back to the SOAP server.
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.
Now the XML firewall has to prepare the
GetSpecialDiscountedBookingForPartnersResponse message for the tour operator.
This includes doing three things:
- Add a security token in the SOAP message of Listing 6, showing the response is coming from the hotel.
- Add an XML digital signature to Listing 6 as a proof of user authentication and message integrity.
- Encrypt the special discount being offered to the tour operator, as this discount is supposed to be confidential data.
UsernameTokenelement, 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.
xenc:ReferenceListelement in the
xenc:ReferenceListelement in Listing 7 contains an
xenc:ReferenceListelement may contain a number of
xenc:DataReferenceelements, where each
xenc:DataReferenceelement is supposed to refer to an
xenc:EncryptedDataelement. Notice from Listing 7 that the
xenc:ReferenceListelement contains just one
xenc:DataReferenceelement, whose URI attribute value (
#DiscountResponse) points to the
xenc:EncryptedDataelement inside the
GetSpecialDiscountedBookingForPartnersResponseelement in the SOAP Body.
- Now see what's inside the
xenc:EncryptedDataelement in Listing 7. The
xenc:EncryptedDataelement represents the contents of the
GetSpecialDiscountedBookingForPartnersResponseelement in encrypted form. We discussed
xenc:EncryptedDataelement in detail in the second part of this series of articles. We would like to draw your attention at the
ds:KeyInfoelement child of the
ds:KeyInfoelement contains a
wsse:SecurityTokenReferenceelement, 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.
Listing 7 also
ds:Signatureelement. Notice that the
ds:KeyInfochild of the
ds:Signatureelement 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
This means that the hotel first signed the complete SOAP Body and then encrypted contents
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
The tour operator, on receipt of Listing 7 will
follow the order in which the elements appear inside the
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
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
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
element appears before the
xenc:ReferenceList element. This means the hotel
encrypted the contents of the
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
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.
wsse:BinarySecurityTokenelement, which wraps an X509 certificate.
ds:KeyInfoelement inside the
ds:Signatureelement in Listing 9 refers to the
wsse:BinarySecurityTokenelement, which means the hotel produced the signature using its X509 certificate.
xenc:EncryptedKeyelement instead of the
xenc:ReferenceListelement of Listings 7 and 8.
xenc:EncryptedKeyelement wraps an encrypted key. You can compare the
xenc:EncryptedKeyelement of Listing 9 with the
xenc:EncryptedDataelement 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:EncryptedDataelement wraps data in encrypted form, while the
xenc:EncryptedKeyelement wraps cryptographic keys in encrypted form.
xenc:EncryptedKeyelement contains a child element named
CipherData, which in turn contains a child named
CipherValueelement 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.
xenc:EncryptedKeyelement contains a
ds:KeyInfoelement, which wraps a
ds:KeyNameelement, 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.
- Also have a look at the
xenc:ReferenceListelement inside the
xenc:EncryptedKeyelement. This element, as before, refers to the
xenc:EncryptedDataelement by means of a fragment identifier. The
xenc:EncryptedDataelement inside the
GetSpecialDiscountedBookingForPartnersResponseelement is the actual encrypted data that was encrypted using the secret key.
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.
The following sequence of message-exchanges occurs in Figure 2:
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.
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
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
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
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.
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.
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.
The hotel's XML firewall sends the SOAP request of Listing 14 to the SOAP server.
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).
The SOAP server sends the SOAP response of Listing 15 to the XML firewall.
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.
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.Resources
- 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
- 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.