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 firstname.lastname@example.org.
A how-to guide for supporting digital signatures within SOAP messages (continued)
by Brenda Coulson
In order to generate keys and digitally sign documents, a toolkit is required, and there are plenty of cryptographic providers available (unless you want to provide your own implementation). The minimal security components are listed below:
- Support for a digital signature algorithm. Available algorithms are: DSA (Digital Signature Algorithm) or RSA algorithm (Rivest, Shamir, Adelman) or ECC (Elliptical Curve Cryptography). ECC is the latest algorithm licensed by Certicom, Inc. for which there is little support from other vendors.
- Support for a message digest/hash algorithm. Sampling of available algorithms are: MD2, MD5, SHA-0, SHA-1.
Although not required, API support for XML Signatures is a feature well worth having -- it saves the developer valuable time and effort. However, having said that, there is no standard API for achieving this, so use of such a toolkit does introduce a 3rd party dependency into your solution. Two such toolkits exist.
- Apache provides the XML Security project that provides an API for creating and verifying XML Signature documents. One of the dependencies is an underlying JCE provider such as described below.
- IBM provides a toolkit that sits on top of Apache SOAP 2.2 with SOAP header and XML Signature support. One of the dependencies is the XML Security Suite for Digital Signatures.
The JCE (Java Cryptography Extension) specification by Sun provides a reference implementation that contains support at a minimum for RSA and MD5. It has been integrated into Java 2 SDK version 1.4. For Java 2 SDK versions 1.2.x and 1.3.x, the JCE 1.2 (JCE 1.2.1 for export) is an optional package that needs to be downloaded and installed separately. It allows for 3rd party vendors to provide implementations that plug in to the architecture. These vendor implementations will often provide support for a larger selection of algorithms. The following companies provide open source JCE implementations:
- Cryptix compatible with JDK 1.1, 1.2, and 1.3.
- BouncyCastle JCE 1.2.1 implementation compatible with JDK 1.1, 1.2, and 1.3. They also have a version suitable for JDK 1.4 and the SUN JCE.
For systems with high security needs, a leading commercial security vendor is the best choice. These vendors provide security toolkits that come bundled with both JCE and XML Signature implementations.
In order to generate the final XML-Signature, an XML parser capable of generating XML documents is required. An XML parser is also a requirement for generating the final SOAP document. There are a number of publicly available ones that will suffice. The best one is Apache Xerces Parser. Combine this with the Sun JAXP API to provide an API that is independent of the underlying XML processor implementation.
The XML Signature is specified as a SOAP Header attribute. Through the SOAP toolkit, the application developer inserts the XML Signature document. An example of how this is done is shown later in Putting It All Together.
The amount of software required for the server is greater than that required for the client. Several of the categories are required for both client and server. In such cases, the server often requires a richer set of features.
The server requires a SOAP toolkit and also a SOAP engine that is capable of processing SOAP requests that contain the embedded digital signatures. Currently, only one such engine exists, the WASP Advanced Server by Systinet. If and when SOAP-DSIG receives support in the industry, more SOAP engines will provide support for this functionality. All SOAP engines should provides the following set of required features:
- Java to WSDL Generator (generate WSDL from Java services to be published)
- Java to UDDI Generator (generate UDDI from Java services to be published)
- Publish Java services to a public UDDI registry.
The requirements for a cryptographic toolkit on the server-side are equivalent to those for the client.
Web Server/Servlet Engine
In order to process requests, a Web server and servlet engine architecture are required. Any J2EE application server meets this requirement, though a minimal configuration requires only a Web server and a servlet engine. While there are several products that provide the necessary capabilities, a comparison of such is outside the scope of this article. The leading products in this space are generally considered to be:
As Web services are embraced, application servers are likely to provide more SOAP-related features currently offered by Web services vendors, potentially including the actual SOAP engine, which would need to include support for digital signatures in order to be a complete solution.
The requirements for a XML parser on the server-side are equivalent to those for the client.
Digital Signature technology is a small piece of a much larger picture; the Public Key Infrastructure (PKI) provides an objective 3rd party to ensure the non-repudiation and integrity of the data required for the digital signature(s) to be legally binding. Signers register themselves and subsequently their credentials (private/public key pair) with a Registration Authority (RA). Assuming the RA authenticates the user successfully, the Certificate Authority (CA) issues a digital certificate that represents the signer's public key, contains an expiration date, and is signed with the CA's own private key to prove that it was the CA and not an imposter. On the server, where verification is done in a typical PKI, a connection to the CA/RA (jointly called the PKI) is required. Usually, the certificates are stored in LDAP directory structures and are in the X.509 format. Depending upon the security and maintenance needs of the business, the business can choose to host the CA, RA, and LDAP directories locally or remotely at a site controlled and secured by the PKI vendor. There are a number of PKI vendors from which to choose. Depending on other requirements, it may make sense to choose the same vendor for the cryptographic libraries as for the PKI implementation. The leading vendors in this space are:
A full evaluation of PKI vendors is outside the scope of this article, but it is worth pointing out a few important features to consider when doing an evaluation of PKI vendors for use with a secure Web services solution.
- Adherence to PKCS (Public Key Cryptographic Standards). This is a set of standards created and maintained by RSA Security that defines standards to promote interoperability in the PKI industry.
- Cryptographic toolkits -- do they provide java toolkits that adhere to the JCE specification?
- Cryptographic toolkits -- do they provide an implementation for the XML-Signature specification? This could be a valuable development time-saver.
Now that all the required components have been identified, it is necessary to identify how the client submits a SOAP Request containing a Digital Signature to the server and receives the response. First, a high level diagram of both client and server side processing should serve as a reference for the remainder of this discussion, as shown in Figure 2.
Figure 2: SOAP Processing
Now let's start with an in-depth look at the client processing. For demonstration purposes, it is assumed that the developer is using the Apache Axis and Apache XML Security projects. If different toolkit(s) are used, the code samples will have to be modified accordingly, but the underlying functionality remains the same.
Client Signature Processing
The first step is to generate a private and public key pair and optionally a certificate. The cryptographic toolkit provides APIs for doing both. To generate the certificate, the client needs to specify their Distinguished Name (DN) that helps to uniquely identify their certificate in the certificate repository. Digital Certificates can be in a number of formats, the most common of which is the X.509 format, upon which LDAP is based. For this reason, most PKI vendors store their certificates in a LDAP repository. Details of directory structure attributes are outside the scope of this document - Refer to LDAP or X.509 documentation.
Once the keys are generated (on the client device for maximum security), the public key and optionally the certificate need to be submitted to a 3rd party CA. The CA can either be a publicly available repository or a dedicated CA repository. Either way, there is a fee for each certificate issued and the Registration Authority (RA) must authenticate the user submitting the certificate. Often, the PKI vendor provides proprietary authentication mechanisms as well as facilities for generating the key pairs and certificate on behalf of the user. In such a case, the PKI vendor needs to provide secure mechanisms for transporting the private key to the client. The chosen approach depends on the individual application needs. However, the submission of a certificate to a CA is highly proprietary and not provided for by the toolkits. There is an emerging standard developed by Verisign, Microsoft, and WebMethods to address this issue -- the XML Key Management Specification (XKMS). It is meant to simplify the ability to use a PKI by defining a protocol for distributing and registering public keys through an XML interface, thus opening up the currently complex and proprietary PKI world. There are two different specifications within this specification.
- X-KISS -- XML Key Information Service Specification. This defines a protocol for resolving public key information found in <ds:KeyInfo> elements. (<ds:KeyInfo> is defined by XML-SIG).
- X-KRSS -- XML Key Registration Service Specification. This defines a protocol for registration of public key information. This is targeted at Web browsers.
Until this specification is embraced and implemented by providers, the developer must use a proprietary mechanism for public key submission.
Once the keys and certificate have been generated and published, the client is ready to sign documents. First, the client must identify what document they need to sign. This is one of the missing pieces in the entire SOAP-Digital Signature puzzle. Traditionally, with XML Digital Signatures, the client provides the data to be signed which is input to a hash algorithm, but the entire XML Signature document is signed, not just the original data. But what is signed for a SOAP message that contains an embedded XML Signature? Following the XML-Signature paradigm, the SOAP body element is signed, which allows for the recipient to verify that the client message/request was not tampered with in transit. Thus, the SOAP processing must occur first. I'll come back to the signing.
Client SOAP Processing
The client needs to identify the Web service interface description to which it is submitting a request. This can be done either through a UDDI browser, which is part of the SOAP client-side toolkit or through verbal/written communication with the service provider, if it is an internal enterprise application. Once the service endpoint is identified, the client needs to generate the stub files through the use of the SOAP toolkit generator. The client writes the code to invoke the SOAP request, providing the necessary data, such as service endpoint URL and method argument values. The following code1 shows how to achieve this.
Service service = new Service(); Call call = (Call) service.createCall(); call.setTargetEndpointAddress(new java.net.URL("http://localhost:8080/axis/servlet/AxisServlet)); SOAPEnvelope env = new SOAPEnvelope(); // XMLUtils.StringToElement() creates an XML Element for the given // (namespace, elementName, textValue) combination SOAPBodyElement sbe = new SOAPBodyElement(XMLUtils.StringToElement("http://localhost:8080/MyService", "methodName", "")); env.addBodyElement(sbe); // Invoke service call.invoke(env); // Get response MessageContext mc = call.getMessageContext(); Message response = mc.getResponseMessage();
At this point, the developer needs to add the logic to sign the SOAP body element. The key is being able to gain access to the SOAP body element. Once the body element has been extracted from the SOAP document, it needs to be the input for the XML-Signature document processing. The following code sample2 shows how to achieve this with Apache Axis and XML Security packages.
// SOAPEnvelope has already been created and is stored in env // Actually add the SOAP signature header env.addMapping(new Mapping("http://schemas.xmlsoap.org/soap/security/2000-12", "SOAP-SEC")); env.addAttribute(Constants.URI_SOAP_ENV, "actor", "some-uri"); env.addAttribute(Constants.URI_SOAP_ENV, "mustUnderstand", "1"); SOAPHeader header = new SOAPHeader( XMLUtils.StringToElement(SOAPSECNS, "Signature", "")); env.addHeader(header); // Get the SOAPEnvelope as a XML Document so we can extract the SOAP // Signature element just added for use in creating the XML Signature. StringWriter writer = new StringWriter(); SerializationContext serializeContext = new SerializationContextImpl(writer, null); env.output(serializeContext); writer.close(); Reader reader = new StringReader(writer.getBuffer().toString()); Document doc = XMLUtils.newDocument(new InputSource(reader)); // Get the Signature Element from the Header Element soapHeaderElement = (Element) ((Element) doc.getFirstChild()).getElementsByTagNameNS("*", "Header").item(0); Element soapSignatureElement = (Element)soapHeaderElement.getElementsByTagNameNS("*", "Signature").item(0); // http://xml-security is the base-uri, which needs to be unique within document XMLSignature sig = new XMLSignature(doc, "http://xml-security", XMLSignature.ALGO_ID_SIGNATURE_DSA); // Add SOAP Body to XML Signature and sign. soapSignatureElement.appendChild(sig.getElement()); // Neat trick: since the XMLSignature is actually a part of the // SOAP XML document, the SOAP body is referenced as a URI fragment sig.addDocument("#Body");
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.
- 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.