7.4. Message-Level Web Service Security
Message-level security, or securing Web services at the message level, addresses the same security requirements—identity, authentication, authorization, integrity, confidentiality, non-repudiation, and basic message exchange—as traditional Web security. Both traditional Web and message-level security share many of the same mechanisms for handling security, including digital certificates, encryption, and digital signatures. Today, new mechanisms and standards are emerging that make it not only possible but easier to implement message-level security.
Traditional Web security mechanisms, such as HTTPS, may be insufficient to manage the security requirements of all Web service scenarios. For example, when an application sends a document with JAX-RPC using HTTPS, the message is secured only for the HTTPS connection, that is, during the transport of the document between the service requester (the client) and the service. However, the application may require that the document data be secured beyond the HTTPS connection, or even beyond the transport layer. By securing Web services at the message level, message-level security is capable of meeting these expanded requirements.
7.4.1. Understanding Message-Level Security
Message-level security, which applies to XML documents sent as SOAP messages, makes security part of the message itself by embedding all required security information in a message's SOAP header. In addition, message-level security can apply security mechanisms, such as encryption and digital signature, to the data in the message itself.
With message-level security, the SOAP message itself either contains the information needed to secure the message or it contains information about where to get that information to handle security needs. The SOAP message also contains information relevant to the protocols and procedures for processing the specified message-level security. However, message-level security is not tied to any particular transport mechanism: Since they are part of the message, the security mechanisms are independent of a transport protocol such as HTTPS.
JAX-RPC hides the details of a SOAP message exchange, but, to understand message-level security, it's helpful to examine a SOAP message in more detail. (See “Simple Object Access Protocol” on page 33 for more details about SOAP.) A SOAP message is composed of three parts:
An envelope
A header that contains meta information
A body that contains the message contents
Figure 7.5 illustrates how security information can be embedded at the message level. The diagram expands a SOAP header to show the header's security information contents and artifacts related to the message. It also expands the body entry to show the particular set of elements being secured.
The client adds to the SOAP message header security information that applies to that particular message. When the message is received, the Web service endpoint, using the security information in the header, applies the appropriate security mechanisms to the message. For example, the service endpoint might verify the message signature and check that the message has not been tampered with. It is possible to add signature and encryption information to the SOAP message headers, as well as other information such as security tokens for identity—for example, an X.509 certificate—that are bound to the SOAP message content.
In summary, message-level security technology lets you embed into the message itself a range of security mechanisms, such as identity and security tokens and certificates, and message encryption and signature mechanisms. The technology associates this security information with the message and can process and apply the specified security mechanisms. Message-level security uses encryption and it uses a digital signature to bind the claims—the identity attributes—from a security token to message content. It is possible to layer additional functionality on top of these basic mechanisms.
7.4.2. Comparing Security Mechanisms
The JAX-RPC over SSL (discussed in “Security for Web Service Interactions” on page 308) primarily concerns securing peer-to-peer communication. It relies on HTTP over SSL to create a secure channel between two peers.
Message-level security takes a different approach, since it embeds the security information within each message. Message-level security has different characteristics from SSL security. Let's compare these two approaches.
7.4.2.1. Transport Layer Security and SOAP Messages
HTTP over SSL protocol is a transport layer security mechanism that applies security protection to messages only when they are “on the wire,” that is, during transport. A message is encrypted—and thus protected—while it is on the wire. However, the message data is decrypted at the transport layer boundary. At that point, the message is unprotected and vulnerable while it is passed to other system layers, whether operating system, application server, or J2EE application layers. Thus, the duration of protection using HTTP is the lifetime of the message on the wire at the transport layer.
Message-level security not only persists beyond the transport layer, it lasts for as long as the XML content is perceived as a SOAP message. Since the security is applied to the SOAP message, the protection remains and the security information is available to the application server container and to applications that have access to SOAP messages through mechanisms and APIs such as JAX-RPC handlers and SAAJ. The duration of protection for message-level security is the lifetime of the SOAP message, and this can span the transport boundary.
Message-level security has other advantages in addition to providing a longer duration of protection. Because security is part of the SOAP message, applications can support Web service interactions that require maintaining protection through out the entire system or into the application layer. Having security as part of the message also makes it possible to persist both the message data and its security information. For example, perhaps to prove that a message was sent, an application may need to persist the message data and the digital signature bound to the message. Or, to protect against internal threats, an application may need to keep data in a SOAP message confidential, even to the application layer. HTTPS, since it only protects a message during transport, cannot give the application layer this encryption protection for the data.
7.4.2.2. Peer Entity and Data Origin Authentication
Two kinds of authentication in a network are: peer entity authentication and data origin authentication. With peer entity authentication, the security service verifies that the identity of a peer—in an association such as a session between a sender and receiver—is the identity claimed. Note that there must be an association between the two parties.
Data origin authentication verifies that the original source of a received message is as claimed, but, unlike peer entity authentication, no association between the sender and receiver is required. With data origin authentication, a target receiver can verify the identity of a message as belonging to the original message creator even if the message passes from its initial source through multiple participants before arriving at the target receiver.
A Web service interaction that uses HTTPS supports peer entity authentication, because the interaction covers just the connection between two peers. Message-level security supports data origin authentication, since its security is tied to the SOAP message itself rather than the transport mechanism.
Using HTTPS is disadvantageous in multi-hop scenarios where a message passes through numerous intermediate participants between the initial sender and target receiver, because each message exchange requires establishing a new association between the communicating participants. Furthermore, SSL requires that each participant decrypt each received message, then encrypt the same message before transmitting it to the next participant in the workflow. SSL, relying on peer entity authentication, does not support end-to-end multi-hop message exchange. (See Figure 7.6.)
Web service scenarios that pass messages to multiple participants lend themselves to using message-level security. Since message-level security is based on data origin authentication, an application that passes messages to numerous intermediary participants on the way to the target recipient can verify, at each intermediary point and at the final target recipient, that the initial message creator identity associated with the message is as claimed. In other words, the initial message content creator's identity moves with the message through the chain of recipients.
7.4.2.3. Levels of Granularity
In addition to handling end-to-end use cases, message-level security can provide security at a more granular level than HTTPS. The ability to apply security at different levels of granularity is important. Consider scenarios that handle XML documents, which are composed of a nested hierarchy of elements and subelements making them inherently granular. Message-level security, which is XML aware, can be more flexible in applying security mechanisms to a message than HTTPS.
For example, suppose you need to encrypt only certain elements or fragments of an XML document to be sent as a SOAP message. If you use HTTPS, you essentially encrypt the entire SOAP message since HTTPS encrypts everything passed on the wire. If you use message-level security, you can encrypt just a portion of the XML document, then send a SOAP message that is partially encrypted. Since encryption is computationally intensive, encrypting an entire document (particularly a large one) can impact performance.
Message-level security's finer-grained control in applying security protections is useful in common Web service interactions, such as end-to-end scenarios. You can apply different security to portions of a document so that participants in a workflow may only access those fragments applicable to their separate functions. For example, an application handling purchase orders may encrypt just credit card information. As the order passes among numerous workflow participants—customer relations, message brokers, supplier—only the appropriate participants, such as a financial department, can read the encrypted information. You could also apply different security mechanisms, such as different encryption algorithms, to various parts of a message, ensuring that only intended recipients can decrypt those parts of the message. Finer-grained control also supports intermediaries whose processing requires access to a small part of the message data, such as intermediaries that route messages to appropriate recipients.
7.4.2.4. Maturity of the Security Technologies
Message-level security is still an emerging technology, with relatively new specifications, some of which are not yet standardized. Moreover, these new specifications may not completely cover all security considerations.
HTTP over SSL is a mature, widely used and well understood standard technology. It is a technology that has been analyzed extensively and has held up against varied security threats. This technology supports both client and server authentication, data integrity, data confidentiality, and point-to-point secure sessions. The J2EE 1.4 platform relies on this technology to provide Web service interactions with standard portable and interoperable support.
Keep in mind that message-level security mechanisms are designed to integrate with existing security mechanisms, such as transport security, public key infrastructure (PKI), and X.509 certificates. You can also use both message-level security and transport layer security together to satisfy your security requirements. For example, you might use a message-level digital signature while at the same time exchanging the message using HTTP over SSL.
7.4.3. Emerging Message-Level Security Standards
Since it is a new technology, there are a number of emerging standards for message-level security. These new specifications, which are part of the Organization for the Advancement of Structured Information Standards (OASIS), the World Wide Web Consortium (W3C), the Internet Engineering Task Force (IETF), and other standards bodies, concentrate on message-level security for XML documents. New Java APIs are also emerging to support these industry Web service security standards. These APIS are developed as Java Specification Requests (JSRs) through the Java Community Process, and future versions of the Java platform may include them.
The emerging specifications address security issues—such as identity, security tokens and certificates, authentication, authorization, encryption, message signing, and so forth—as they apply at the message level. For those who want to explore these emerging standards on their own, here is a partial list of the more significant JSRs and specifications:
JSR 105— XML Digital Signatures for signing an XML document. It also includes procedures for computing and verifying signatures.
JSR 106— XML Digital Encryption for encrypting parts of an XML document.
JSR 155— Web Services Security Assertions, which is based on Security and Assertions Markup Language (SAML), is used for exchanging authentication and authorization information for XML documents.
JSR 183— Web Services Message Security Java APIs, which enable applications to construct secure SOAP message exchanges.
Let's look at how to apply message-level security mechanisms to build and send a SOAP message with some message-level security. For example, let's examine how message-level security APIs might put an XML digital signature on a purchase order document. A client first embeds the digital signature into the XML message, signing the message before sending it. The signature, which is an X.509 certificate, is embedded into the purchase order XML document along with other information. Code Example 7.14 shows the message header for this purchase order XML document with the embedded digital signature, per the XML Digital Signature specification. This code example is derived from the OASIS Web Service Security: SOAP Message Security, Working Draft 17 document. See http:www.oasis-open.org/committees/documents.php.
Code example 7.14. Embedding a Digital Signature in an SOAP Message
This XML document shows the SOAP envelope containing the message body for the purchase order details and the message header, with the digital signature for the message. The security portion of the header, which is part of the SOAP message itself, includes or references all the information necessary to describe and validate the signature details and artifacts, including:
Information specifying the security token, which is an X.509 certificate associated with the message. This information is enclosed within the wsse:BinarySecurityToken element.
A description of the signature algorithm and its details, enclosed within the ds:Signature element.
References to the signed message body elements. This is shown in the <ds:Reference URI="#myBody> element and associated attribute, which references the body of this message.
The signature value itself, which is inside the ds:SignatureValue element.
Information about the key or keys used for signing, enclosed with the ds:KeyInfo element. In this case the keys are from the associated X.509 certificate.
Since the message-level security specifications are still evolving, the details in this example may change. Regardless, the example does highlight how to associate security information with a particular SOAP message and include the security information as part of the message itself. As message-level security JSRs and specifications finalize and are incorporated in the J2EE platform, the corresponding Java APIs and the J2EE containers will hide many of these details from the application developer.
7.4.3.1. Using Message-Level Security Mechanisms
How can you make use of these emerging technologies and Java API implementations as they become available? There are two ways to approach this problem:
You can make the security code and any supporting framework for message-level security part of your application by placing it in the application's .ear file. Although this is the portable approach, it may require more work. You should consider this approach if your situation necessitates it.
You can use application server-specific extensions that explicitly provide message-level security. This is the preferred approach. Since vendors try to make new features available before standards are finalized, some application servers may offer nonstandard extensions that integrate some message-level security capabilities. Eventually these specifications may become part of the standard J2EE platform, but they may differ from the implementations offered by these early adopters. Although it may not be portable, it is the easier approach and more likely to provide the intended security.
Some of these technologies are more mature than others. For example, the Java Web Services Developer Pack (Java WSDP) toolkit has already incorporated some of the digital signature standards. Java WSDP is an integrated toolkit from Sun Microsystems that allows Java developers to build and test XML applications, Web services, and Web applications using the latest Web service technologies and standards implementations. The Java WSDP toolkit is available at http://java.sun.com/webservices/. In addition, some Apache Foundation projects include implementations of emerging message-level security capabilities.
Let's look at how you might implement a portable strategy to incorporate message-level security into your J2EE application. Note that while this is possible, it is not a task for every application developer since it is usually quite difficult to write truly secure code. You should attempt this only if you feel comfortable handling security code, since it involves writing a framework for security. However, it may be a useful strategy if you need to use message-level security today and cannot wait for it to be incorporated into the J2EE platform.
Suppose you want to add a digital signature to a message involved in a single exchange between two participants. First, try to leverage existing J2EE technologies and mechanisms. For example, because JAX-RPC is the primary message exchange technology for Web service interactions, try to plug in your security code to the SOAP messages that JAX-RPC exchanges. This may enable your Web services with message-level security. You can then leverage the JAX-RPC built-in mechanisms to manipulate the XML messages being exchanged.
Recall from Chapter 2 that JAX-RPC has handlers that provide a mechanism to intercept a SOAP message at various points during processing of request and response messages. You can use the JAX-RPC handler to interpose on the message exchange at the points in the interaction where handlers are invoked. These points are:
On the client side:
after parameters are marshalled into the request
before unmarshalling values returned in the response
On the server side:
before unmarshalling parameters for dispatch
after marshalling return values into the response
Handlers intercept all requests and responses that pass through a Web service endpoint, providing access to the actual SOAP message exchanged as part of the Web service request and response. Handlers let you apply different logic for service requests, responses, and faults. To do so, you add the appropriate code to the handler methods handleRequest, handleResponse, and handleFault. You can use handlers to apply message-level security to messages exchanged as part of your service. Since they are configurable on both the client and the endpoint, you can customize handlers to apply security services at both the client and service sides.
You use the SAAJ API to inspect and manipulate raw SOAP messages. SAAJ also gives you a compound message view capability that lets you examine MIME-based attachments. With SAAJ, you can also embed the digital signature information into the XML document and add the necessary security information to the header and message. Also consider using existing implementations of message-level security functionality, such as the digital signature capability.
For portability, you must include the message-level security implementations in the application's .ear file. At this early stage, it is also recommended that you create a library of actions that wrap security tasks and the functionality of existing implementations of message-level security. This library of actions should provide a higher level interface to these security functions. When providing a security library around existing message-level security implementations, it is also a good idea to provide multiple defaults for common use cases, such as for obtaining X.509 certificates, handling verification faults, and so forth. Once the library is in place, you can use the SAAJ API from within the handler logic to access the SOAP message. Then, apply the message-level security with your security library. Figure 7.7 shows the main participants in this process.
You may want to combine message-level security with other J2EE declarative and programmatic security mechanisms. For example, you may want to use HTTPS as the transport protocol even though the document is signed by a message-level mechanism. If you choose to use any of the J2EE declarative or programmatic security mechanisms along with JAX-RPC handlers, keep in mind the order in which the security constraints are enforced:
The container applies the declarative security mechanisms first.
The handlers run and apply their checks.
J2EE programmatic security mechanisms run after the handler checks.
You can also combine security mechanisms by adding some secure message-level functionality to an existing transport-level security solution. For example, if you have an existing Web service that uses SSL, you may want to add message-level integrity or confidentiality. Adding this security at the message level ensures that integrity or confidentiality persist beyond the transport layer.