Previous      Contents      Next
Sun Java System Application Server Enterprise Edition 8 2004Q4 XML and Web Services Security Guide

---

What is WSS?

WSS defines the binding of XML digital signatures, XML encryption, and username/password tokens to secure SOAP messages. WSS in the Application Server defines how to use WSS to secure invocations of Web services, including Web services deployed on our Application Server.

The Web Services Security (WSS) specification is developed at OASIS. The WSS specification defines a SOAP extension providing quality of protection through message integrity, message confidentiality, and message authentication. WSS mechanisms can be used to accommodate a wide variety of security models and encryption technologies.

The WSS specification provides an extensible mechanism for associating security tokens with SOAP messages. The WSS specification itself does not define the format of the various types of security token. Instead, a series of security token profile documents have either been published or are in the process of being published. Each of these profile documents defines the use of a particular type of security token (e.g., X.509) to secure SOAP message using digital signatures or encryption.

Username token verification specifies a process for sending Username tokens along with the message. The receiver can validate the identity of the sender by validating the digital signature sent by the sender. A digital signature internally refers to a security token (for example, Username token or an X.509 Certificate token) to indicate the key used for signing. Sending these tokens with a message binds the identity of the tokens (and any other claims occurring in the security token) to the message. For more information about these security tokens, go to the URLs listed below:

Username Token Profile, based on OASIS WSS Username Token Profile 1.0, which can be read at the following URL:
http://docs.oasis-open.org/wss/2004/01/
oasis-200401-wss-username-token-profile-1.0.pdf
X.509 Certificate Token Profile, based on OASIS WSS X.509 Certificate Token Profile 1.0, which can be read at the following URL:
http://docs.oasis-open.org/wss/2004/01/
oasis-200401-wss-x509-token-profile-1.0.pdf

Support for message layer security is integrated into the Application Server and its client containers in the form of (pluggable) authentication modules. By default, message layer security is disabled on the Application Server. To enable message layer security, follow the steps outlined in Configuring The Application Server for Web Services Security.

This section contains the following topics:

Types of Message Level Security Tokens
Implementation-Specific Terminology

Types of Message Level Security Tokens

The following types of message-level security tokens are available in this release of the Application Server:

Username Token

The Application Server uses Username Tokens to deliver a user name and password and to authenticate the peer in the Web service invocation. Username tokens are typically used in lieu of digital signatures. Digital signatures are used to bind an authentication identity to the message content. Username tokens are used to bind an authentication identity to a message sender.

XML Digital Signature (DSig)

The Application Server uses XML Digital Signatures to authenticate the source of message content. Digital signatures is an authentication mechanism. Clients use digital signatures to establish their caller identity, analogous to the way basic authentication or SSL client certificate authentication have been used to do the same thing when transport layer security is being used. Digital signatures are used to enable the receiver to validate that the message has not be altered since it was signed, and as such can confirm that the signer defined the content (although they might not have sent it).

The XML Signature specification can be viewed at the following URL:
http://www.w3.org/TR/xmldsig-core/

XML digital signatures are designed for use in XML transactions. It is a standard that was jointly developed by W3C and the IETF (RFC 2807, RFC 3275). The standard defines a schema for capturing the result of a digital signature operation applied to arbitrary data and its processing. XML signatures add authentication, data integrity, and support for non-repudiation to the signed data.

XML Encryption (XML-Enc)

The purpose of encryption is to modify the data such that it can only be understood by its intended audience. This is accomplished by substituting an encrypted element for the original content. When predicated on public key cryptography, encryption can be used to establish the identity of the parties that can read a message.

The XML Encryption W3C standard can be viewed at the following URL:
http://www.w3.org/TR/xmlenc-core/

XML Encryption specifies a process for encrypting data and representing the result in XML. The data may be arbitrary data (including an XML document), an XML element, or XML element content. The result of encrypting data is an XML Encryption element which contains or references the cipher data.

Implementation-Specific Terminology

The Application Server conforms to the WSS Soap Message Security specification, which can be viewed from the URL http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0.pdf. This specification is used in the Application Server’s underlying implementation of Web Services Security.

Some of the terminology used in this document is described in the WSS specification, and is summarized here. The concepts are also discussed in Configuring The Application Server for Web Services Security.

Authentication Layer

The authentication layer is the message layer on which authentication processing must be performed.

Authentication Provider

In this release of the Sun Java Systems Application Server, the Application Server invokes authentication providers to process SOAP message layer security. A client-side provider encrypts and authenticates (by signature or username/password) the outgoing messages such that they can only be viewed by their intended recipients, and such that the recipient can determine the caller or invocation identity to apply in the Web service invocation. A server-side provider would decrypt content and validate passwords or signatures in inbound messages to establish the authentication identity associated with the Web services invocation. Services act like clients and clients act like services when processing response messages.

Client-Side Provider

Client-side providers are invoked on the client side of a SOAP message layer interaction. When entering the information for the client-side provider, enter the Java implementation class of the provider. Client authentication providers must implement the com.sun.xml.wss.provider.ClientSecurityAuthModule interface.

Server-Side Provider

Server-side providers are invoked on the server side of a SOAP message layer interaction. When entering the information for the server-side provider, enter the Java implementation class of the provider. Server-side providers must implement the com.sun.xml.wss.provider.ServerSecurityAuthModule interface.

Default Server Provider

The default provider is used to identify the server provider to be invoked for any application for which a specific server provider has not been bound.

Default Client Provider

The default client provider is used to identify the client provider to be invoked for any application for which a specific client provider has not been bound.

Request Policy

The request policy defines the authentication policy requirements associated with request processing performed by the authentication provider. Policies are expressed in message sender order such that a requirement that encryption occur after content would mean that the message receiver would expect to decrypt the message before validating the signature.

A request policy includes an optional authenticate source and an authenticate recipient. When neither of these properties is specified, authentication of the recipient is not required. When before-content or after-content is specified, content authentication need not occur. If content authentication is also required, its relationship to recipient authentication is defined by the value of this property.

Authenticate Source – Defines a requirement for message-layer sender authentication (e.g. username password) or content authentication (e.g. digital signature). Valid choices include:
sender authentication
content authentication
Authenticate Recipient – Define a requirement for message-layer authentication of the receiver of the request message to its sender (e.g. by XML encryption). Valid choices include:
before-content authentication
after-content authentication

To achieve message security, the request and response policies must be enabled on both the server and client. These policies are configure based on the type of authentication policies to be used. When configuring the policies on the client and server, make sure that the client policy matches the server policy for request/response protection at application-level message binding.

Developers can define application-specific protection policy (as opposed to overriding the default) by defining a message security binding in the Sun-specific application deployment descriptors.

Read Actions of Security Policy Configurations for more information on how these configurations operate.

Response Policy

The response policy defines the authentication policy requirements associated with response processing performed by the authentication provider. Policies are expressed in message sender order such that a requirement that encryption occur after content would mean that the message receiver would expect to decrypt the message before validating the signature.

A response policy includes an optional authenticate source and an authenticate recipient. When neither of these properties is specified, authentication of the recipient is not required. When before-content or after-content is specified, content authentication need not occur. If content authentication is also required, its relationship to recipient authentication is defined by the value of this property.

Authenticate Source –Defines a requirement for message-layer sender authentication (e.g. username password) or content authentication (e.g. digital signature). Valid choices include:
sender authentication
content authentication -
Authenticate Recipient – Defines a requirement for message-layer authentication of the receiver of the response message to its sender (e.g. by XML encryption). Valid choices include:
before-content authentication
after-content authentication

To achieve message security, the request and response policies must be enabled on both the server and client. These policies are configure based on the type of authentication policies to be used. When configuring the policies on the client and server, make sure that the client policy matches the server policy for request/response protection at application-level message binding.

Developers can define application-specific protection policy (as opposed to overriding the default) by defining a message security binding in the Sun-specific application deployment descriptors.

Read Actions of Security Policy Configurations** for more information on how these configurations operate.

Actions of Security Policy Configurations

Table # shows possible security policy configurations and the resulting set and order of security operations performed by the WSS Provider auth modules for that configuration.

Table 1-1   Security policy configurations and the corresponding (basic) actions performed by the WSS Provider auth modules

Security Policy Configuration	Set and Order of Security Operations performed by the WSS Provider auth module
auth-source="sender"	[1.1] Client module sends a wsse:UsernameToken in the wsse:Security header of the SOAP request. The client security configuration file MUST have xwss:Authenticate element with nested xwss:UsernameAndPassword element containing the properties of the Token. The username and password are obtained by the ClientSecurityAuthModule during runtime via javax.security.auth.NameCallback and javax.security.auth.PasswordCallback; the values specified in the security configuration file are ignored. [1.2] Server module expects a wsse:UsernameToken in the request and the server security configuration file MUST have xwss:requireAuthentication element specifying the server requirements specific to the token. The values of all attributes (of xwss:requireAuthentication) MUST be false.
auth-source="content"	[2.1] Client module sends a digital signature along with the SOAP request and the client side security configuration file MUST have xwss:Sign element including in it the alias of the client certificate to be used for signing (specified using senderCertificateAlias). The SOAP Body of the request is signed. The key reference mechanism used is DirectReference. Please refer to security config. file schema for more. A single ds:Signature element is found in the wsse:Security header. [2.2] Server module expects a client signed request and the server security configuration file MUST have xwss:requireSignature element specifying the target (should be SOAP Body) of the signature via a nested Target element. It should also include attributes signTokenRequired (should be false) unless the key bearing token used by the client to sign the message is also included in the signature. The key reference mechanism must match the value specified in the client security configuration, which defaults to Direct (DirectReference). A single ds:Signature element is expected in the wsse:Security header.
auth-source="sender" auth-recipient= "before-content"	[3.1] Client module encrypts the SOAP Body of request (first) and sends a Username Token in the wsse:Security header. The effect of these operations is that the wsse:Security header contains an wsse:UsernameToken followed by an xenc:EncryptedKey. The content of the SOAP Body is replaced with xenc:EncryptedData. The client side security configuration file MUST have <xwss:Authenticate> element with nested xwss:UsernameAndPassword element containing the properties of the Token and xwss:Encrypt element containing the alias of the receiver’s certificate, specified using receiverCertificateAlias, with which it encrypts a symmetric key used for encrypting the body. Refer [1.1] [3.2] Server module expects a wsse:UsernameToken (authenticates source first) in the wsse:Security header and an encrypted message body (performs decryption later). The server security configuration file MUST have xwss:requireAuthentication element specifying the server requirements specific to the token and xwss:requireEncryption specifying the target of the encryption via a nested Target element (should be SOAP Body). The encryptContentRequired attribute should be true, implying the content of the SOAP Body has to be encrypted. The key reference type mechanism expected is Direct (DirectReference).
auth-source="sender" auth-recipient= "after-content"	Refer [3.1] & [3.2] The operations performed are reversed in order: the token is exported first and the body of the message is encrypted later. The server security module performs decryption first and then authenticates the sender of the message. The SOAP request should contain an xenc:EncryptedKey followed by an wsse:UsernameToken in the wsse:Security header. The content of the SOAP Body should be replaced with an xenc:EncryptedData element.
auth-source="content" auth-recipient= "before-content"	[5.1] Client module encrypts the SOAP Body of request (first) and signs it (encrypted body) later. The effect of this is that the wsse:Security header contains a ds:Signature element at the top followed by an xenc:EncryptedKey. The content of the SOAP Body is replaced with an xenc:EncryptedData element. [5.2] Server module expects a signed message (performs signature verification first) with an encrypted message body (performs decryption later).
auth-source="content" auth-recipient= "after-content"	Refer [5.1] & [5.2] The operations performed are reversed in order: the body of the message is signed first and is encrypted later. The server security module performs decryption (recipient authentication) first followed by source authentication. The SOAP request should contain xenc:EncryptedKey followed by an ds:Signature element in the wsse:Security header. The content of the SOAP Body should be replaced with an xenc:EncryptedData element.
auth-recipient= "before-content" OR auth-recipient= "after-content"	[7] The SOAP request (body of the message) is encrypted. An xenc:EncryptedKey is found in the wsse:Security header. The content of the SOAP Body is replaced with an xenc:EncryptedData element.
No policy specified.	No security operations are performed by the modules.

Rules for Performing Multiple Sign/Encrypt Operations

The WSS Provider modules can perform multiple sign/encrypt operations when a corresponding flag is set on the policies. The rules for mapping are as shown in Table #.

Table 1-2   Rules for Mapping

Security Policy	Security Operations that can be performed by the modules
auth-source="content"	Multiple sign operations can be performed. The operations are performed in the order the xwss:Sign elements appear in the configuration file.
auth-recipient= "before-content" OR auth-recipient= "after-content"	Multiple encrypt operations can be performed. The operations are performed in the order the xwss:Encrypt elements appear in the configuration file.
auth-source="sender" auth-recipient= "before-content" OR auth-recipient= "after-content"	Multiple encrypt operations can be performed before/after (depending upon auth-recipient flag) along with sending a UsernameToken. The encrypt operations are performed in the order the xwss:Encrypt elements appear in the config. file.
auth-source="content" auth-recipient= "before-content" OR auth-recipient= "after-content"	Multiple encrypt operations can be performed before/after (depending upon aJuth-recipient flag) along with a digital signature. Same order rules as above.

Previous      Contents      Next

---

Copyright 2004 Sun Microsystems, Inc. All rights reserved.