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

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. However, there are security requirements that need to be addressed if SOAP is to be completely embraced for B2B transactions. This article addresses these issues by providing step-by-step how-to instructions for application developers working in the Java programming language.

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 One | Part Two


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

Most of the commercial cryptographic toolkits provide APIs for generating an XML-Signature document, given the data to sign, the private key, and the public key/certificate. The following code3 shows how to sign achieve this, again assuming Apache Axis and Apache XML Security toolkits. For simplicity, the code retrieves the private key from a key store, however this is not recommended for deployment scenarios with high security needs since the key store provides minimal protection for the private key.

// Extract the private key & certificate from the key store 
KeyStore ks = KeyStore.getInstance("JKS");
FileInputStream fis = new FileInputStream("keyStoreFileName");
            ks.load(fis, "keyStorePassword".toCharArray());
        PrivateKey privateKey = (PrivateKey) ks.getKey("privateKeyAlias",
                    "privateKeyPass".toCharArray());
X509Certificate cert =
                    (X509Certificate) 
ks.getCertificate("certificateAlias");
 
// Add the digital certificate and public key to XML Signature document
 // Assumption is XMLSignature document was created earlier. See above code sample
       sig.addKeyInfo(cert);
       sig.addKeyInfo(cert.getPublicKey());
 // Sign the XML Signature document with our private key
       sig.sign(privateKey);

 // Transform XML Signature Document
       Canonicalizer c14n = 
         Canonicalizer.getInstance(Canonicalizer.ALGO_ID_C14N_WITH_COMMENTS);
 // Assumption is Document was extracted from SOAP Envelope 
earlier
byte[] canonicalMessage = c14n.canonicalizeDocument(doc);

 // Create a Deserializer for the XML Signature document
InputSource is = new InputSource(new 
java.io.ByteArrayInputStream(canonicalMessage)); 
AxisClient tmpEngine = new AxisClient(new NullProvider());
// env is SOAPEnvelope instance
DeserializationContextImpl dser = new DeserializationContextImpl(
is, new MessageContext(tmpEngine), Message.REQUEST, env);
dser.parse();

Now the SOAP document, a single XML document, is ready for transport to the server.

Server Signature Processing

Once the server receives the SOAP document, the logical first step is to verify that the document is from the correct user and that the document has not been altered, either accidentally or maliciously, in transit. Most SOAP engines are J2EE servlets and process all requests that arrive for a particular URL. If the SOAP Engine provides support for embedded XML-Signature documents, then the developer's work is pretty simple. Currently, there is one SOAP engine that provides automatic digital signature support, Systinet WASP Advanced Server. For all other cases, the application developer needs to intercept the SOAP document to extract the header element and verify the signature prior to processing the SOAP request. To do this, the SOAP toolkit, the cryptographic toolkit and the PKI vendor are required. The verification steps are outlined below followed by configuration instructions and sample code.

  • Extract the header element <SOAP-SEC:Signature> from the SOAP message. This should be done using the SOAP engine/toolkit.
  • Get the contents of the SOAP body element for use in verification. This is the original data that was signed.
  • Parse the XML-Signature document to extract the public key, algorithm details, and signed data. This requires the XML Parser and potentially the cryptographic toolkit, if the selected one provides an API for handling XML-Signature documents.
  • Verify the signature by creating the digest from the SOAP body element with the public key.
  • (Optional) Retrieve the certificate from the certificate repository managed by the PKI.
  • (Optional) Verify that the certificate is not on a Certificate Revocation List (CRL). This ensures that the associated key pair has not expired and the security of the private key has not been compromised.

Server Configuration
The following instructions are for configuring Tomcat 4.04 Beta2 for use with the Apache Axis SOAP engine and the Apache XML Security package to enable the code samples to work. However, it is safe to assume that similar configuration is required for other SOAP engines and J2EE application servers.

  • Download the Axis distribution. This has several dependencies, as outlined below.
    • Download a JAXP 1.1 compatible XML parser. Try Xerces2 Java Parser from Apache (http://xml.apache.org/xerces2-j/index.html) or the JAXP RI from Sun (http://java.sun.com/xml/downloads/jaxp.html).
    • Download the Apache-XML-Security-J 1.0.2 toolkit (provides implementation for the "XML-Signature Syntax and Processing" recommendation, essentially ability to create XML Digital Signature documents as well as encryption algorithms). See http://xml.apache.org/security/index.html
    • Download a JCE provider implementation. See www.bouncycastle.org for an open-source implementation.
  • Configure Tomcat (Version 4.04)
    • Add the following jars to the webapps/axis/web-inf/lib directory
      • xmlsec.jar (XMLSecurity class files)
      • JCE jar file (Assuming you are using Bouncy Castle JCE provider, this requires you to actually create the JAR as the distribution comes with a directory of class files).
      • Logger jar file (bundled with XMLSecurity project) Replace the log4j-core.jar that is part of Axis with the jakarta-log4j-1.2beta2.jar from XMLSecurity
      • XML Parser jar files (bundled with XMLSecurity project)
        • xmlParserAPIs.jar
        • xercesImpl.jar
      • xalan.jar (bundled with XMLSecurity project)
      • xml-apis.jar (bundled with XMLSecurity project)
    • Add the above jar files to your client classpath environment variable

Code Sample
The following code4 shows the processing that takes place within the invoke() method of an Apache Axis handler. This handler is the first in the chain of handlers. Assuming the signature verification succeeds, the next handler in the chain (aka the user service handler) is invoked. On failure, the target service is not invoked. The chain of handlers to invoke is specified as part of the SOAP engine configuration. In the case of Axis, it is part of the WSDD (Web Services Deployment Descriptor).

Message inMsg = msgContext.getRequestMessage();
       Message outMsg = msgContext.getResponseMessage();
       
// Verify signed message
       Document doc = inMsg.getSOAPPart().getAsSOAPEnvelope().getAsDocument();
       String baseURI = "http://xml-security"; // must match baseURI
 in client code
       CachedXPathAPI xpathAPI = new CachedXPathAPI();
Element nsctx = doc.createElement("nsctx");
nsctx.setAttribute("xmlns:ds", Constants.SignatureSpecNS);

Element signatureElem = (Element) xpathAPI.selectSingleNode(doc,
         "//ds:Signature", nsctx);
// Check to make sure that the document claims to have been signed
       if (signatureElem == null) 
{
     // handle and log error
return;
}
       XMLSignature sig = new XMLSignature(signatureElem, baseURI);
       boolean verify = 
sig.checkSignatureValue(sig.getKeyInfo().getPublicKey());
 if (verify == false)
{
  // signature verification failed -- do not forward 
request to SOAP Service.
}

Server SOAP Processing

As mentioned earlier in the Server Signature Processing section, the SOAP Engine will handle all requests that adhere to a specific URL. All of the existing SOAP engines on the market today either come as part of a pre-bundled J2EE application server and/or interoperate with the leading vendors in this space. The SOAP Engine parses the SOAP document, extracting the target service, which it maps to the appropriate Java class and method based on configuration. The Java method is invoked.

Now, for the majority of the cases where the SOAP Engine does not process the Signature header element, the Java class providing the Web service needs to do this or delegate it to another component. However, this is undesirable, as it requires the service provider to know that the request came in as a SOAP request, muddying the waters. Alternatively, a general SOAP handler should be written by the application developer that intercepts all signed SOAP requests, extracting the Signature header element and SOAP body element for signature verification purposes. Once verification succeeds, it then forwards (using SOAP Engine forwarding if available or a proprietary forwarding mechanism) the request to the target endpoint for processing. For example, in the code sample above, the SOAP Engine (Apache Axis) is responsible for forwarding the request to the next handler in the chain based on deployment descriptor information. The only catch here is making sure that if the SOAP engine does have an interceptor for signature processing, it does this work rather than the developer's handler.

Once the appropriate method has been invoked and performs the requested action, it returns, unaware a SOAP client invoked it. The SOAP Engine is responsible for bundling and encoding the response for submission to the client. The assumption here is that the response is not digitally signed.

CONCLUDING REMARKS

In conclusion, the ability to digitally sign a SOAP document is definitely achievable and straightforward, given the right toolbox. The existing set of SOAP and Digital Signature toolkits, both open source and commercial, should be leveraged to save the developer valuable time and effort. The emerging industry standards for SOAP, digital signatures, and their intersection are an enormous asset to a business, enabling the developers to build a standards-compliant application that is interoperable with other toolkits. The piece of the puzzle that is still vague is the actual integration point between the SOAP processing and the digital signature processing, especially on the server-side. Should this functionality be provided by a SOAP or Digital Signature toolkit? Currently, a SOAP engine (WASP by Systinet) provides it, although it is likely that in the future other SOAP engines and/or digital signature toolkits will also offer this feature. With the rapidly changing industry landscape, it is important for developers to track the acceptance of the SOAP specification and in particular of the SOAP-DSIG note as well as the emerging XKMS standard to ensure their applications are interoperable and ready to ride the wave.

REFERENCES

The following sites were referenced during the writing of this article.


1The Apache code is copyrighted 2001 by The Apache Software Foundation. All rights reserved.

2The Apache code is copyrighted 2001 by The Apache Software Foundation. All rights reserved.

3The Apache code is copyrighted 2001 by The Apache Software Foundation. All rights reserved.

4The Apache code is copyrighted 2001 by The Apache Software Foundation. All rights reserved.

<<Previous 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.

Dig deeper on Simple Object Access Protocol (SOAP)

Pro+

Features

Enjoy the benefits of Pro+ membership, learn more and join.

0 comments

Oldest 

Forgot Password?

No problem! Submit your e-mail address below. We'll send you an email containing your password.

Your password has been sent to:

SearchSoftwareQuality

SearchCloudApplications

SearchAWS

TheServerSide

SearchWinDevelopment

Close