A how-to guide for supporting digital signatures within SOAP messages

The following article is written by Brenda Coulson, Software Architect at Cysive, Inc. Brenda works in Product Development on the Cymbio Interaction Server. Brenda is a Sun Certified Java Programmer and Java Developer, and holds a BS degree from James Madison University. Brenda may be reached at bcoulson@cysive.com.

Part Two | Part Three

A how-to guide for supporting digital signatures within SOAP messages
by Brenda Coulson

Web services are the latest wave in distributed computing. Its ability to connect clients and servers independent of platform, programming language, and transport protocol gives it great promise. SOAP (Simple Object Access Protocol) is one of the many specifications contributing to the success of Web services. It defines the XML document structure for sending Web service requests and responses. From a security standpoint, it is possible to send SOAP messages over the HTTPS protocol, providing encryption of the data. However, there are other security requirements that need to be addressed if SOAP is to be completely embraced for B2B transactions, an area where SOAP is being positioned to replace EDI as the de-facto standard. Businesses will be conducting highly confidential and proprietary transactions and need to be assured of the integrity and authenticity of their data, that is, to guarantee that the person sending the document is who they say they are and that the data has not been tampered with. Historically, digital signatures address these requirements. There is an existing specification outside the Web service realm, XML-Signature that describes how to represent a document and its corresponding signature in XML format. Now there is a W3C Note, SOAP-DSIG that defines how to digitally sign SOAP messages. But how do all the pieces fit together to produce a complete solution that enables businesses to securely ride the Web services wave? In this article, I will address these issues by providing step-by-step how-to instructions for application developers working in the Java programming language.

TECHNOLOGIES

SOAP Overview

SOAP (Simple Object Access Protocol) specification defines the XML document structure, relying on XML Schema and XML Namespaces, for sending Web service requests and responses. It defines two basic message types. The first type (SOAP Message) contains a literal, potentially multi-node XML document in the SOAP body. The second type (SOAP RPC) contains a request/response method invocation in the SOAP body requiring the use of encoding rules. The RPC model is more common. The specification is a W3C recommendation based on input from a number of participating vendors. The appeal of SOAP is its independence from underlying protocols, programming languages and hardware platforms. It allows businesses to conduct business with each other without the need for tightly coupled point-to-point communication. There are two complementary specifications that need to be defined.

UDDI (Universal Description Discovery and Integration): UDDI is a standard developed by a community of vendors across a diverse set of industries. It defines interfaces for registering as well as finding businesses and services in a XML registry. The Publisher API enables a business to store or update data about themselves in the registry. This data includes name, description, classification(s), and available Web services. In order to publish data to a registry, the business must first establish credentials with the registry owner. There are a number of publicly available registries, including ones operated by Microsoft and IBM. It is also possible to setup a private registry for internal enterprise applications or secure B2B applications. The Inquiry API is defined in terms of SOAP over HTTP and allows users to discover services of interest. Although not defined by the UDDI specification, it is becoming the industry best practice to define the Web service interface in WSDL.
WSDL (Web Services Definition Language): This is analogous with the IDL (Interface Definition Language) from the CORBA/RMI distributed technologies. It defines the Web service, the operations it exposes (method name, parameter details), and most importantly, the service location. However, unlike CORBA and RMI, which by definition used IIOP for transport mechanism, WSDL needs to define the supported transport mechanism for the given service. The most common of these is SOAP over HTTP.

Digital Signatures

Digital Signature technology defines the mathematical algorithms for "signing" electronic data to create a legally binding transaction between the party that presents the data and the party that signs it. The signer generates a pair of cryptographic keys -- a private key (for use in signing) and a public key (for use in verifying). The signer must publish the public key (usually done by requesting a digital certificate issued by a 3rd party that vouches for the validity of the key pair). The private key must remain in the possession of the signer and must not be compromised. The signer generates a hash of the original data, signs it with their private key and sends it to the recipient for verification. The recipient can look up the corresponding digital certificate to ensure that the private key has not been compromised and then verify that the original message was not tampered with in transit. Digital Signatures provide the following guarantees.

Strong authentication of the signer.
Integrity and authenticity of the signed data.
Protection against repudiation of the signature.

XML Signature Overview

Digital Signature does not define a document structure for sending signed data - this is where the XML Signature specification comes into play. It defines an XML document structure for representing both the digital signature data as well as the original message that is signed. It also includes elements for defining the algorithm(s), message digests, public key for verification purposes, and digital certificate. There are other optional elements that are not mentioned here for brevity.

SOAP-DSIG Overview

The SOAP-DSIG specification brings the pieces together. SOAP defines the XML structure for distributed computing. XML Signatures provides the XML structure for digital signatures. SOAP-DSIG note defines how to represent an XML Signature within a SOAP RPC-style message. Figure 1 shows the same SOAP document both with and without an XML Signature. Both versions are provided for demonstrative purposes.

Figure 1: Sample SOAP Documents

Here is a simple SOAP RPC-style document that invokes the method testMethod on a SOAP service located at http://localhost:8080/LogTestService.

Now the same document is shown below after it has been signed. Several elements have been highlighted for discussion purposes. Note that the Header element now includes a SOAP-SEC:Signature element whose body conforms to the XML-Signature specification. The ds:DigestValue element represents the digest of the SOAP-ENV:Body element as highlighted in the above document. It is the ds:Reference object that defines the content being signed through its URI attribute, the value of which is #Body, indicating the Body element of the current document. The ds:SignatureValue element represents the digital signature of the XML Signature document, as specified by the XML Signature specification. The ds:KeyInfo element provides the X.509 certificate and public key details for use by the server for signature verification.

REQUIRED SOFTWARE COMPONENTS

Client

A client application wishing to invoke SOAP requests that contain digital signatures requires several toolkits. This section details the required toolkits and how they interoperate. Although it is possible to write directly to the SOAP protocol from a Java application, it is much simpler and quicker to use a toolkit that hides the low-level details. This article assumes the user is using such a toolkit. It should be noted that at this time there are no SOAP toolkits for mobile or embedded devices; only standard desktop platforms are supported.

SOAP Toolkit
A SOAP toolkit should provide the following set of features (at a minimum):

WSDL to Java Generator (generates Java stubs for accessing a service defined in WSDL)
SOAP RPC API (provides an abstraction of underlying SOAP protocol)
UDDI Registry Browser

Toolkits that are available free for development purposes are listed below.

Apache Axis (follow-on to Apache SOAP project that has support for SOAP headers)
JWSDP (Java Web services Developer Pack) from Sun
GLUE by TheMindElectric
WASP Standard by Systinet

Next Page >>

Copyright 2002. Reprinted with permission. Cysive, Inc. builds mission-critical business systems for Global 2000 firms to help orchestrate interactions with customers, partners and employees across multiple channels such as web, wireless, voice and Web services.

For more information:

Looking for free research? Browse our comprehensive White Papers section by topic, author or keyword.

Are you tired of technospeak? The Web Services Advisor column uses plain talk and avoids the hype.

For insightful opinion and commentary from today's industry leaders, read our Guest Commentary columns.

Hey Codeheads! Start benefiting from these time-saving XML Developer Tips and .NET Developer Tips.
Visit our huge Best Web Links for Web Services collection for the freshest editor-selected resources.

Visit Ask the Experts for answers to your Web services, SOAP, WSDL, XML, .NET, Java and EAI questions.

Couldn't attend one of our Webcasts? Don't miss out. Visit our archive to watch at your own convenience.

Choking on the alphabet soup of industry acronyms? Visit our helpful Glossary for the latest lingo.

Discuss this article, voice your opinion or talk with your peers in the SearchWebServices Discussion Forums.


	Home > SOA News > A how-to guide for supporting digital signatures within SOAP messages