Extending SOAP with Security

WS-Security defines a SOAP security header that provides a standard place for you to put security artifacts. The purpose of WS-Security is not to invent any new types of security, but instead to provide a common format for security in a SOAP message. Three major elements make up a SOAP security header: security tokens, XML Encryption, and/or XML Signatures. Security tokens are pieces of information used for authentication or authorization. Examples of security tokens are username/password and X.509 certificates. Many more token types are used, and we discuss them in detail later in this chapter. For XML Encryption, the security header may hold an EncryptedKey element containing a ReferenceList pointing to the specific parts of the message that have been encrypted. Similarly, if an XML Signature is within the security header, its Reference elements will point to the parts of the message that have been digitally signed.

Listing 7.1 shows what the basic WS-Security header structure looks like within a SOAP envelope (we have removed namespaces throughout this chapter to simplify).

Listing 7.1. Structure of a Basic WS-Security SOAP Header

 <S:Envelope>  <  S:Header  >   <wsse:Security>   <!-- Security Token -->   <wsse:UsernameToken>   ...   </wsse:UsernameToken>   <!-- XML Signature -->   <ds:Signature>   ...   <ds:Reference URI="#body">   ...   </ds:Signature>   <!-- XML Encryption Reference List -->   <xenc:ReferenceList>   <xenc:DataReference URI="#body"/>   </xenc:ReferenceList>   </wsse:Security>  </S:Header>     <S:Body>      <!-- XML Encrypted Body -->      <xenc:EncryptedData Id="body" Type="content">             ...      </xenc:EncryptedData>     </S:Body>  </S:Envelope> 

As you can see, Listing 7.1 contains a security header, commonly referred to with the namespace prefix wsse , which has three children: UsernameToken , which is an example of a security token; Signature , which represents an XML Signature; and an XML Encryption ReferenceList . In general, you see the following structure for the security header:

1. Security Tokens ” Zero, one, or more (but usually not more than one) security tokens. This example shows a UsernameToken .

2. Signatures ” Zero, one, or more XML Signatures. Usually, if an XML Signature is included, at a minimum it signs all or part of the soap body.

3. ReferenceList or EncryptedKey ” Zero, one, or more of these elements. As you learned about XML Encryption in Chapter 5, "Ensuring Confidentiality of XML Messages," the EncryptedData element can exist for each element encrypted. To consolidate these elements, you use a ReferenceList (from the XML Encryption namespace) or an EncryptedKey , which contains a reference list, to reference all the different EncryptedData elements. This way, a WS-Security processor can read the security header and then decrypt all the data to which EncryptedData refers. Often, the soap body is encrypted, as shown in the previous example.

In the following sections, we look in turn at each of the security artifacts that can be included in a WS-Security SOAP header.

WS-Security Namespaces

The different XML listings in this chapter sometimes contain prefixes for which the associated namespace has not been declared. The following list provides a quick synopsis of the different namespaces we refer to here.

Prefix	Short for	Namespace
ds	Digital signature	http://www.w3.org/2000/09/xmldsig#
wsse	WS-Security extension	http://www.docs.oasis- open .org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd
wsu	Web services utility	http://www.docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd
xenc	XML Encryption	http://www.w3.org/2001/04/xmlenc#