Providing Integrity: XML Signature in WS-Security

Like XML Encryption, the XML Signature used in WS-Security is the same as discussed in Chapter 4. There are some special considerations for using XML Signature in a SOAP message, but mechanically it is just XML Signature put into the security header of a SOAP message.

XML Signature is used within WS-Security for two major reasons. One is to verify a security token credential such as an X.509 certificate or SAML assertion. Another is message integrity ”verifying that the message (or important parts of it) has not been modified in transit.

XML Signature for Validating a Security Token

Let's examine the first reason for XML Signature using an X.509 certificate “based security token ”to verify a security token credential. As we have mentioned previously, an X.509 certificate wraps metadata and a public key in an envelope that is digitally signed by a certificate authority. In addition to the public key, one of the most important pieces of metadata is the identity that is being represented by the certificate, which is attested to by the certificate authority. This identity is often the Subject or Common Name in the X.509 certificate but could also be a different attribute in the certificate, such as an attribute added for a partner identifier.

What makes the X.509 certificate valuable from an authentication perspective is the public key/private key relationship. If the presenter can prove that he has the private key that corresponds to the public key, then it is assumed that the presenter's identity is represented by the X.509 certificate. The presenter then proves possession of the corresponding private key by using a digital signature. If the presenter digitally signs a piece of known text with his private key, and you are able to validate the signature against this known text using the public key in the X.509 certificate, you can trust (to the extent you trust the certificate authority and to the extent you can trust that the private key has not been compromised) that the presenter has the identity represented.

XML Signature for Message Integrity

XML Signatures are also used to certify and maintain the integrity of the message itself. By signing the body of a message or some other part of a message, you can guarantee that the message arrives unaltered at the receiver's end as long as the receiver applies the signature validation process.

XML Signature in WS-Security Considerations

Chapter 4 described the different XML Signature models: Enveloped, Enveloping, and Detached Signatures. Because of the mutability of SOAP headers ”an intermediary can add or make changes to messages ”the Detached Signature model is the only one that makes sense for SOAP messages. This means that a WS-Security “signed message will always contain an explicit Reference element for what is being signed.

The possibility of legitimate changes in transit could conceivably cause problems with the XPath statements that are used in the Reference URI of the XML Signature. You must be careful when constructing XPath statements so that they remain valid at the point of signature validation.

The header can contain more than one XML Signature, and the signatures can potentially overlap. For example, imagine a scenario in which a message containing an order is traveling through intermediaries or processing stages within an enterprise. Say the message first goes to the order processing system that inserts a header containing the order-id and digitally signs it, putting an XML Signature into the security header that points to the order-id header. Then the message goes to the Shipping department, where someone inserts a shipping-id header and digitally signs both the order-id and shipping-id . When this message reaches the Billing department, these XML Signatures are validated prior to billing the customer.

WS-Security XML Signature Example

To illustrate this discussion of XML Signature in a SOAP message, Listing 7.20 shows a more complete example.

Listing 7.20. A Complete Example of XML Signature in a SOAP Message

 <S:Envelope>   <S:Header>     <wsse:Security>       <wsse:BinarySecurityToken         ValueType="wsse:X509v3"         EncodingType="wsse:Base64Binary"         wsu:Id="X509Token">         FIgEZzCRF1EgILBAgIQEmtJZc0rqrKh5i...       </wsse:BinarySecurityToken>  <ds:Signature>   <ds:SignedInfo>   <ds:CanonicalizationMethod   Algorithm="  http://www.w3.org/2001/10/xml-exc-c14n#  " />   <ds:SignatureMethod   Algorithm="  http://www.w3.org/2000/09/xmldsig#rsa-sha1  " />   <ds:Reference URI="#body">   <ds:Transforms>   <ds:Transform   Algorithm=" http://www.w3.org/2001/10/xml-exc-c14n#" />   </ds:Transforms>   <ds:DigestMethod   Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />   <ds:DigestValue>EULddytSo1...</ds:DigestValue>   </ds:Reference>   </ds:SignedInfo>   <ds:SignatureValue>   XLdER8=ErToEb1l/vXcMZNNjPOV...   </ds:SignatureValue>   <ds:KeyInfo>   <wsse:SecurityTokenReference>   <wsse:Reference URI="#X509Token"/>   </wsse:SecurityTokenReference>   </ds:KeyInfo>   </ds:Signature>  </wsse:Security>   </S:Header>   <S:Body wsu:Id="body">     <StatusRequest xmlns="http://www.myCompany.com/Order">        <OrderNumber>1234</OrderNumber>     </StatusRequest>   </S:Body> </S:Envelope> 

As you can see, using XML Signature in SOAP is reasonably natural. Listing 7.20 signs the body of the SOAP message by assigning an Id of body to the Soap Body element and then uses that as a target of the Reference URI in the signature. Notice the use of a SecurityTokenReference pointing up to the X.509 certificate wrapped in a BinarySecurityToken .

Signing a Security Token Reference

In many circumstances, signing security tokens themselves is necessary. As we mentioned earlier, there is a standard way to refer to security tokens using a strategy represented by the SecurityTokenReference element. Because this dereferencing strategy is different from URIs, the WS-Security specification introduces a new XML Signature-referencing strategy called the STR Dereference Transform . The idea is that what is being signed does not include the SecurityTokenReference itself; it signs what the SecurityTokenReference points to. This makes sense: You care about keeping integrity on the security token itself, not the reference. Listing 7.21 shows an example of a digital signature applied to a security token that is represented by a SecurityTokenReference .

Listing 7.21. A Signature Signing a Security Token to Maintain Its Integrity

 ...   <!-- This is the security token to be signed -->   <wsse:BinarySecurityToken Id="myX509Token"   ...   </wsse:BinarySecurityToken>   ...   <!-- This the security token reference -->   <wsse:SecurityTokenReference wsu:Id="mySecurityToken">  <wsse:Reference URI="#myX509Token"/>  </wsse:SecurityTokenReference>   ...   <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">     <SignedInfo>       ...       <Reference URI="#mySecurityToken">         <ds:Transforms>           <ds:Transform Algorithm="...#STR-Transform">             <wsse:TransformationParameters>               <ds:CanonicalizationMethod                Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315" />             </wsse:TransformationParameters>         </ds:Transform>       </Reference>     </SignedInfo>     <SignatureValue></SignatureValue>   </Signature> ... 

As you can see in this example, the Reference element in the XML Signature points back to #mySecurityToken , which is a SecurityTokenReference (rather than a security token). The STR Dereference Transform that is associated with the Signature Reference will follow the SecurityTokenReference back to the security token itself and validate the signature against that rather than the SecurityTokenReference .