WS-Security language basics

Note

Only element descriptions are provided in this section. Concepts relating to WS-Security are covered in Chapter 7.

The WS-Security framework provides extensions that can be used to implement message-level security measures. These protect message contents during transport and during processing by service intermediaries. Additional extensions implement authentication and authorization control, which protect service providers from malicious requestors. WS-Security is designed to work with any of the WS-* specifications we discuss in this chapter, as shown in Figure 17.5.

Figure 17.5. How WS-Security relates to the other WS-* specifications discussed in this chapter.

The WS-Security framework is comprised of numerous specifications, many in different stages of acceptance and maturation. In this book we've concentrated on some of the more established ones, namely:

• WS-Security
• XML-Encryption
• XML-Signature

Note that WS-Security represents a framework but also a specification that defines language elements. Because the language element descriptions provided in this chapter originate from three separate specifications, we qualify each element name with its origin.

Additionally, as part of our exploration of Web services security in Chapter 7, we discussed the features of the SAML specification, which enable centralized authentication and authorization. Because single sign-on languages are beyond the scope of this book, we don't discuss SAML language elements. (However, we do provide an example of a SAML SOAP header later on.)

17.5.1. The Security element (WS-Security)

This construct represents the fundamental header block provided by WS-Security. The Security element can have a variety of child elements, ranging from XML-Encryption and XML-Signature constructs to the token elements provided by the WS-Security specification itself.

Security elements can be outfitted with actor attributes that correspond to SOAP actor roles (explained at the end of Chapter 5). This allows you to add multiple Security blocks to a SOAP message, each intended for a different recipient.

17.5.2. The UsernameToken, Username, and Password elements (WS-Security)

The UsernameToken element provides a construct that can be used to host token information for authentication and authorization purposes. Typical children of this construct are the Username and Password child elements, but custom elements also can be added.

17.5.3. The BinarySecurityToken element (WS-Security)

Tokens stored as binary data, such as certificates, can be represented in an encoded format within the BinarySecurityToken element.

17.5.4. The SecurityTokenReference element (WS-Security)

This element allows you to provide a pointer to a token that exists outside of the SOAP message document.

Case Study

For each invoice generated by RailCo's Invoice Submission Service, it must provide a standard Username and Password token pair in the SOAP message header, as shown here:

Example 17.19. The Security SOAP header used by RailCo to provide user name and password values.

Security xmlns:wsse= "http://schemas.xmlsoap.org/ws/2002/12/secext"> UsernameToken> Username> rco-3342 Username> Password Type="wsse:PasswordDigest"> 93292348347 Password> UsernameToken> Security>

...

 

17.5.5. Composing Security element contents (WS-Security)

As previously mentioned, the WS-Security specification positions the Security element as a standardized container for header blocks originating from other security extensions. The following example illustrates this by showing how a SAML block is located within the Security construct. (As previously mentioned, single sign-on languages are beyond the scope of this book. The SAML-specific elements shown in this example therefore are not explained.)

Case Study

After RailCo's Invoice Submission Service has been authenticated by the TLS Accounts Payable Service (acting as the issuing authority), RailCo's service is automatically granted access to other TLS services.

Should RailCo want its Invoice Submission Service to then invoke any one of these TLS services, the TLS service would not need to re-authenticate or re-authorize the RailCo service requestor. Instead, the TLS service would request security information from the issuing authority, which would respond with assertion information, such as the authorization assertion shown here:

Example 17.20. The WS-Security SOAP header hosting a SAML authorization assertion.

Security xmlns:wsse= "http://schemas.xmlsoap.org/ws/2002/12/secext"> ... Execute ... Security>

...

 

17.5.6. The EncryptedData element (XML-Encryption)

This is the parent construct that hosts the encrypted portion of an XML document. If located at the root of an XML document, the entire document contents are encrypted.

The EncryptedData element's Type attribute indicates what is included in the encrypted content. For example, a value of http://www.w3.org/2001/04/xmlenc#Element indicates that the element and its contents will be encrypted, whereas the value of http://www.w3.org/2001/04/xmlenc#Content states that encryption will only be applied to the content within the opening and closing tags.

17.5.7. The CipherData, CipherValue, and CipherReference elements (XML-Encryption)

The CipherData construct is required and must contain either a CipherValue element hosting the characters representing the encrypted text or a CipherReference element that provides a pointer to the encrypted values.

Case Study

In Chapter 15 RailCo designed a task-centric business service that uses an XSD schema to represent a small, custom invoice document as part of its transmission. This schema was imported and established a construct with a root InvoiceType element.

Following is an example of an XML document instance of this schema.

 
 2322
 
 
 $32,322.73
 
 
 07.16.05
 

 

To comply with TLS's security requirements, RailCo is required to apply encryption to any dollar amounts in business documents exchanged via the TLS B2B system. Shown in the following code example is the same XML fragment but with XML-Encryption elements representing the Total element and value.

Example 17.21. An XML document within a SOAP message containing an encrypted element.

 
 2322
 
 <EncryptedData
 xmlns="http://www.w3.org/2001/04/xmlenc#"
 Type="http://www.w3.org/2001/04/xmlenc#Element">
 <CipherData>
 <CipherValue>
 R5J7UUI78
 CipherValue>
 CipherData>
 EncryptedData>
 
 07.16.05
 

 

17.5.8. XML-Signature elements

A digital signature is a complex piece of information comprised of specific parts that each represent an aspect of the document being signed. Therefore, numerous elements can be involved when defining the construct that hosts the digital signature information. Table 17.5 provides brief descriptions of some of the main elements.

Table 17.5. XML-Signature elements

Element	Description
CanonicalizationMethod	This element identifies the type of "canonicalization algorithm" used to detect and represent subtle variances in the document content (such as the location of white space).
DigestMethod	Identifies the algorithm used to create the signature.
DigestValue	Contains a value that represents the document being signed. This value is generated by applying the DigestMethod algorithm to the XML document.
KeyInfo	This optional construct contains the public key information of the message sender.
Signature	The root element, housing all of the information for the digital signature.
SignatureMethod	The algorithm used to produce the digital signature. The digest and canonicalization algorithms are taken into account when creating the signature.
SignatureValue	The actual value of the digital signature.
SignedInfo	A construct that hosts elements with information relevant to the SignatureValue element, which resides outside of this construct.
Reference	Each document that is signed by the same digital signature is represented by a Reference construct that hosts digest and optional transformation details.

 

Case Study

TLS further requires that all invoices submitted with a total of over $30,000 must also be digitally signed. RailCo therefore inserts an XML-Signature compliant signature in the SOAP header of its invoice submission message, as shown here:

Example 17.22. A SOAP message header containing a digital signature.

<Signature xmlns= "http://www.w3.org/2000/09/xmldsig#"> <SignedInfo> <CanonicalizationMethod Algorithm= "http://www.w3.org/TR/2001/ REC-xml-c14n-20010315"/> <SignatureMethod Algorithm= "http://www.w3.org/2000/09/ xmldsig#dsa-sha1"/> <Reference URI= "http://www.w3.org/TR/2000/ REC-xhtml1-20000126/"> <DigestMethod Algorithm= "http://www.w3.org/2000/09/ xmldsig#sha1"/> <DigestValue> LLSFK032093548= DigestValue> Reference> SignedInfo> <SignatureValue> 9879DFSS3= SignatureValue> <KeyInfo> ... KeyInfo> Signature>

...invoice document with total exceeding $30,000...

 

SUMMARY OF KEY POINTS

• WS-Security establishes the standardized Security SOAP header block container that can be used for WS-Security defined token information or to host security blocks from other specifications.
• XML-Encryption provides a construct that replaces XML content with language-specific elements that represent encryption information.
• XML-Signature establishes the Signature block comprised of various algorithm pointers and parts from which the digital signature is derived.