Core Security Patterns: Best Practices and Strategies for J2EE, Web Services, and Identity Management

The OASIS WS-Security (also referred to as OASIS WSS-SOAP Message Security) is an industry-standard effort to secure Web services by supporting and integrating multiple security standards and technologies. The OASIS WS-Security 1.0 specification has been accepted and approved by OASIS as an official standard. WS-Security forms the basis for building interoperable Web services security infrastructure by defining end-to-end message-level security mechanisms for SOAP messages. With industry support, currently WS-Security is emerging as a de facto standard for securing Web services and promoting security interoperability in Web services.

Motivation of WS-Security

In Web-services communication, SOAP defines the structure of an XML document and the rules and mechanisms that can be used to enable communication between applications. SOAP does not define or address any specific security mechanisms. Using SOAP headers provides a way to define and add features, enabling application-specific security mechanisms like digital signature and encryption.

Incorporating security mechanisms in SOAP headers poses several complexities and challenges in an end-to-end Web-services security scenario that mandates message-level and transport-level security features such as security context propagation, support for multiple security technologies, maintaining message integrity, and confidentiality across participating intermediaries. More importantly, incorporating security mechanisms in SOAP headers limits interoperability in certain aspects of addressing support for a variety of supporting security infrastructures, such as PKI, binary security tokens, digital signature formats, encryption mechanisms, and so forth.

The WS-Security specification incorporates a standard set of SOAP extensions required for securing Web services and implementing message authentication, message integrity, message confidentiality, and security token propagation. It also defines mechanisms for supporting a variety of security tokens, signature and encryption mechanisms, and standards-based security technologies, including PKI and Kerberos. The goal of WS-Security is to provide secure SOAP messages that support multiple security token formats for authentication or authorization, multiple signature formats, multiple encryption technologies, and multiple trust domains.

WS-Security Definitions

To understand WS-Security, it is important to know the terms and definitions specified in the WS-Security 1.0 specification. Let's take a look at some of the key terms and definitions.

• Claim: A declaration made by an entity. The entity can be a name, identity, key, group, privilege, capability, and so forth.

• Claim Confirmation: The process of verifying a claim belonging to an entity.

• Security Token: A security token (examples include username, X.509 certificate, and Kerberos token) represents a collection of one or more claims.

• Signed Security Token: A security token that is asserted and cryptographically signed by an authority.

• Trust: A characteristic that one entity is willing to accept and rely upon for another entity to execute a set of actions and/or to make a set of assertions about a set of subjects and/or scopes.

Using Digital Signatures in WS-Security

Applying a signature is critically important to Web services for the purpose of establishing the authenticity of a message and its sender's identity. With a digital signature applied in WS-Security, a recipient of a SOAP message is assured of the message's integrity and that the signed message and its elements have not been tampered with during transit.

WS-Security adopts and builds on the W3C XML signature specifications defining usage of various elements and a processing model for signing messages. However, XML signature better ensures that the message recipients at intermediaries or endpoints can verify the signature and validate the signer's identity.

Using Encryption in WS-Security

In Web-services communication, applying encryption can be done using standard SSL/TLS mechanisms, and the message can be encrypted in its entirety and sent confidentially to one or more recipients. Using SSL/TLS satisfies transport-level confidentiality requirements, but it does not solve message-level requirements when parts of an XML message must be made confidential by using selective encryption and then signed by different users.

WS-Security adopts and builds on XML encryption specifications for encrypting and decrypting messages. This facilitates encryption of messages in their entirety or as selected parts intended for multiple recipients based on their signed identity and privileges for viewing and consuming them. WS-Security also allows support use of SOAP intermediaries.

Using Security Tokens in WS-Security

WS-Security defines ways for sending security information as security tokens to its message recipients in order to provide support for authentication and representing identity in a SOAP message. WS-Security defines mechanisms for defining security tokens that include representing username and password combination, binary security tokens (e.g., X.509 certificate, Kerberos v5 ticket) and XML security tokens (e.g., SAML, REL).

The Role of SAML and REL in WS-Security

WS-Security allows representing XML-based security tokens by providing support for Security Assertions Mark-Up Language (SAML) and Rights Expression Language (REL).

SAML provides an XML-based framework for exchanging security-related information over networks, and thus over the Internet. SAML does not define newer mechanisms for authentication or authorization. Instead, it defines XML structures for representing information pertaining to authentication and authorization so that these structures can be marshaled across system boundaries and can be understood by the recipient's security systems. SAML is also designed to provide single sign-on for both automatic and manual interactions across security services. SAML is emerging as a de facto standard for securely exchanging XML-based security information regardless of the underlying security architectures and for promoting security interoperability. The OASIS WS-Security TC developed a SAML Token profile to define the rules for using SAML 1.1 assertions with WS-Security. OASIS endorsed SAML Token Profile 1.0 as a standard.

REL defines the rights, usage permissions, constraints, legal obligations, and license terms pertaining to an electronic document. Open Digital Rights Language (ODRL) and eXtensible Rights Markup Language (XrML) defines the XML vocabulary for representing REL. The OASIS WS-Security TC also developed a REL Token profile to define the rules and guidelines for using ISO/IEC 21000-5 Rights Expressions with WS-Security. OASIS ratified REL Token Profile 1.0 as a standard.

Refer to Chapter 7, "Identity Architecture and It's Technologies" for in-depth information about SAML and its applied scenarios.

WS-Security: The Anatomy of SOAP Message Security

WS-Security addresses the security of Web services by adopting existing standards and standards-based technologies in a platform-independent and transport-protocolneutral way. As we discussed earlier, it adopts XML signature and XML encryption for protecting messages by applying digital signature and encryption-decryption specifications. To address authentication and authorization requirements, it uses standard mechanisms, including username-password tokens, binary security tokens, and XML-based security tokens. The WS-Security specification works with all SOAP versions since SOAP 1.1.

Let's take a closer look at the structural details and characteristics of a WS-Security-enabled SOAP message and its core elements.

Message Structure and Its Core Elements

WS-Security defines a set of security-specific extensions that are to be embedded in a SOAP message. It defines the structure and its core elements, processing rules, and mechanisms that can be used to enable SOAP message security. WS-Securityspecific extensions are represented as child elements of the SOAP header element <soapenv:Header>. Figure 6-5 represents the structure of a SOAP message enabled with WS-Security elements representing security tokens, signature, and encryption.

Let's take a closer look at the WS-Security structural representation and its elements, illustrating the usage of security tokens, XML signature, and XML encryption.

Namespaces

The WS-Security 1.0 specification mandates the use of the following two XML namespaces in implementations. Using the following namespace URLs for obtaining the schema files is required. The prefix wsse identifies the namespace for WS-Security extensions, while wsu identifies the namespaces for global utility attributes. Table 6-1 shows the prefixes and namespaces for WS-Security extensions.

<wsse:Security>

The <wsse:Security> element is the parent element that represents a complete WS-Securityenabled SOAP message, including mechanisms for security tokens, applying signature, and encryption. A WS-Securityenabled SOAP message may contain one or more <wsse:Security> header elements.

Each <wsse:Security> element contains the security information applied to its intended message recipient or SOAP intermediaries. WS-Security headers representing multiple recipients should be specified with an optional role <S:role> attribute. It is optional to include a mustUnderstand="true" attribute, which forces the message recipient to generate a SOAP fault when the underlying implementation does not support WS-Security specifications. Example 6-36 shows how a <wsse:Security> element can be represented.

Example 6-36. Representation of <wsse:Security> element

<wsse:Security S:role="IntendedRecipentEndpoint" S:mustUnderstand="true"> . . . </wsse:Security>

<wsse:UsernameToken>

The WS-Security specification defines how to attach security tokens for sending and receiving security information between Web-services partners. The <wsse:Username> element provides a way to insert username information and additional username-specific information based on schemas. Example 6-37 shows how the <wsse:UserNameToken> element can be represented.

Example 6-37. Representation of <wsse:UserNameToken> element

<wsse:Security> <wsse:UsernameToken> <wsse:Username>Nagappan</wsse:Username> </wsse:UsernameToken>

<wsse:BinarySecurityToken>

Similar to username tokens, WS-Security allows representing binary security tokens such as X.509 certificates, Kerberos tickets, and non-XML format security information. For interpreting binary-formatted tokens, it uses two attributes, ValueType and EncodingType. The ValueType attribute indicates a security token, such as wsse:X509v3 or wsse:Kerberosv5ST. The EncodingType attribute specifies the encoding format of the binary data, such as Base64Binary. Example 6-38 shows how a wsse:BinarySecurityToken element indicating a X.509 certificate can be represented.

Example 6-38. Representation of <wsse:BinarySecurityToken> element

<wsse:BinarySecurityToken EncodingType="wsse:Base64Binary" ValueType="wsse:X509v3"/> JkFYGT9=...lhSE </wsse:BinarySecurityToken>

<saml:Assertion> and <r:license>

WS-Security allows representing XML-based security tokens that are represented using Security Assertion Markup Language (SAML) or Extensible Rights Markup language (XrML) as SAML assertions and REL security tokens, respectively. The SAML assertions and REL tokens are attached to WS-Security headers by placing them under the <wsse:Security> element.

Example 6-39 shows how a SAML 1.0 assertion can be represented using <saml:Assertion> element under <wsse:Security>.

Example 6-39. Representation of a SAML assertion in <wsse:Security>

<wsse:Security> <saml:Assertion Assertion IssueInstant="2004-02-11T00:36:02Z" Issuer="www.sun.com/identity" MajorVersion="1" MinorVersion="1" . . . </saml:Assertion> . . . </wsse:Security>

Example 6-40 show how a REL license can be represented using <r:license> element under <wsse:Security>.

Example 6-40. Representation of a REL license in <wsse:Security>

<wsse:Security xmlns:wsse="..."> <r:license xmlns:r="." license> <r:grant> <r:keyHolder> <r:info> <ds:KeyValue>...</ds:KeyValue> </r:info> </r:keyHolder> <r:possessProperty/> <sx:commonName ' xmlns:sx="...">Sun Microsystems</sx:commonName> </r:grant> <r:issuer> <ds:Signature>...</ds:Signature> </r:issuer> </r:license> . . . </wsse:Security>

<wsse:SecurityTokenReference>

The <wsse:SecurityTokenReference> element defines a URI that locates where a security token can be found. This provides the flexibility to obtain a security token from named external locations accessible via URI. This element can also be used to refer to a security token contained within the same SOAP message header.

<ds:Signature>

The WS-Security specification builds on the W3C XML signature specification for representing digital signatures in the WS-Security headers. The <ds:Signature> element can represent the digital signature and other related information, including how the signature was generated. A typical instance of <ds:Signature> contains a <ds:SignedInfo> element describing the information being signed, a <ds:SignatureValue> element containing the bytes that make up the digital signature, a <ds:Reference> element identifying the information being signed along with transformations, and a <ds:KeyInfo> element indicating the key used to validate the signature. A <ds:SignedInfo> element contains the identifiers for canonicalization and signature method algorithms. The <ds:KeyInfo> element may contain where to find the public key that can be referenced using a <wsse:SecurityTokenReference> element.

Example 6-41 shows how a <ds:Signature> element can represent a WS-Security-enabled SOAP message.

Example 6-41. Representation of an XML signature in <wsse:Security>

<SOAP:Envelope> <SOAP:Header> <wsse:Security> ... <wsse:BinarySecurityToken> ... </wsse:BinarySecurityToken> <ds:Signature> ... <ds:SignedInfo> <ds:Reference URI='#Body'> ... <ds:Transforms> ... </ds:Transforms> <ds:DigestMethod> . . . </ds:DigestMethod> ... </ds:Reference> <ds:CanonicalizationMethod ...> </ds:SignedInfo> <ds:SignatureValue> ... </ds:SignatureValue> <ds:KeyInfo> <wsse:SecurityTokenReference> ... </wsse:SecurityTokenReference> </ds:KeyInfo> </ds:Signature> ... </wsse:Security> </SOAP:Header> <SOAP:Body Id='Body'> ... </SOAP:Body> </SOAP:Envelope>

Refer to the "XML Signature" section earlier in this chapter for more information and details about generating and validating XML signatures.

<xenc:EncryptedData>

The WS-Security specification builds on the W3C XML encryption specification for representing encrypted data in SOAP messages. The <xenc:EncryptedData> element can represent the encrypted data and other related information, including the encryption method and the key information. A typical instance of <xenc:EncryptedData> contains an <xenc:EncryptionMethod> element specifying the applied encryption method, an <xenc:CipherData> element containing the cipher value of the encrypted data, and a <ds:KeyInfo> element indicating the key used for encryption and decryption. A <xenc:ReferenceList> element can be used to create a manifest of encrypted parts of a message envelope expressed using the <xenc:EncryptedData> elements.

Example 6-42 shows how an <xenc:EncryptedData> element is represented in a WS-Security-enabled SOAP message.

Example 6-42. Representation of XML encryption in <wsse:Security>

<SOAP:Envelope> <SOAP:Header> <wsse:Security> ... <wsse:BinarySecurityToken> ... </wsse:BinarySecurityToken> <ds:Signature> ... </ds:Signature> ... </wsse:Security> </SOAP:Header> <SOAP:Body > ... <xenc:EncryptedData Type="http://www.w3.org/2001/04/xmlenc#Content"> <xenc:EncryptionMethod Algorithm="..." /> <ds:KeyInfo> <KeyName>...</KeyName> </ds:KeyInfo> <xenc:CipherData> <xenc:CipherValue ... </xenc:CipherValue> </xenc:CipherData> </xenc:EncryptedData> </SOAP:Body> </SOAP:Envelope>

Refer to the "XML Encryption" section earlier in this chapter for more information and details about encryption and decryption using XML encryption.

<xenc:EncryptedKey>

The <xenc:EncryptedKey> element is used to represent encrypted keys. In usage, a SOAP message carries both encrypted data and the encrypted symmetric key needed to read that data. The symmetric key is encrypted using the recipient's public key. When the message is received, the recipient can use its private key to decrypt the encrypted symmetric key and then use this symmetric key to decrypt the actual data.

The structure of an <xenc:EncryptedKey> element is quite similar to an <xenc:EncryptedData> element with three sub-elements: an <xenc:EncryptionMethod> element specifying how the key was encrypted, an <xenc:CipherData> element containing the cipher value of the encrypted key, and a <ds:KeyInfo> element specifying the information about the key used.

Example 6-43 shows how an <xenc:EncryptedKey> element is represented in a WS-Security-enabled SOAP message.

Example 6-43. Representing encrypted key in <wsse:Security>

<SOAP:Envelope> <SOAP:Header> <wsse:Security> <xenc:EncryptedKey> ... <ds:KeyInfo> <wsse:SecurityTokenReference> <ds:X509IssuerSerial> <ds:X509IssuerName> DC=CSPSecurity, DC=com </ds:X509IssuerName> <ds:X509SerialNumber>87070953</ds:X509SerialNumber> </ds:X509IssuerSerial> </wsse:SecurityTokenReference> </ds:KeyInfo> ... </xenc:EncryptedKey> ... </wsse:Security> </SOAP:Header> <SOAP:Body> <xenc:EncryptedData > <xenc:CipherData> </xenc:EncryptedData> </SOAP:Body> </SOAP:Envelope>

Again, refer to the "XML Encryption" section earlier in this chapter for more information and details about encryption and decryption using XML encryption.

<wsu:TimeStamp>

The WS-Security specification recommends the use of timestamps to determine the timelines and validity of security semantics. If a recipient receives two contradictory messages, the timestamps inserted in the message can be used to determine validity of one of them. The <wsu:TimeStamp> element allows you to define the message creation time and its expiration time.

Example 6-44 shows how a <wsu:Timestamp> element is represented in a WS-Security-enabled SOAP message.

Example 6-44. Representing time stamps in WS-Security

<SOAP:Envelope> <SOAP:Header> . . . <wsu:Timestamp wsu:> <wsu:Created>2002-08-22T00:26:15Z</wsu:Created> <wsu:Expires>2002-08-22T00:31:15Z</wsu:Expires> </wsu:Timestamp> <wsse:Security> . . . </wsse:Security> . . . </SOAP:Header> <SOAP:Body> . . . </SOAP:Body> </SOAP:Envelope>