SOAP security: digital signature
Submitted on October 4, 2004
There are lots of articles and other documents written about securing the SOAP messages: XML Signature, Web Services Security, SOAP-DSIG and SSL. SOAP is a standard protocol used to exchange any XML documents. Such XML document exchanging can be applied in many kinds of business starting from public SOAP services for obtaining the latitude/longitude coordinates of an address (provided by http://geocoder.us) and ending with the private booking of a hotel room. This leads to a necessity to protect the XML data being transmitted from unauthorized reading and modifying. A detailed explanation of the main purposes of securing SOAP messages can be found in the Web Services Security article, by Bilal Siddiqui.
This article introduces the working sample code in Borland Delphi which implements the digital singing of the SOAP messages using the SHA hash algorithm and the private key cryptography with X509 certificates.
As described in http://www.w3.org/TR/SOAP/, every SOAP message has a SOAP envelope with its body and an unnecessary header inside. The task of digitally signing a SOAP XML message content can be divided into two common tasks: calculating the digest hashes for each XML content part to be secured and the digital signing of composed digest hashes together with the references to the corresponding XML content parts.
As required the SOAP Security specification, before calculating hash values or digital signatures for a specified XML data part, we must apply the XML canonicalization process in order to obtain the logical equivalence between XML documents. The XML canonicalization specification can be read at Canonical XML and also the XML Canonicalization provides detailed descriptions of the XML canonicalization process steps. So, first, let us go ahead and consider the working Delphi class which implements a simple case of the XML document canonicalization process.
A simple case of the canonicalization process without having the references to external XML documents and also without CDATA inclusions can be performed using the following steps:
In order to simplify the description, we used the Microsoft XMLDom document object engine for manipulating with XML data. The listing below demonstrates an algorithm for combining the XML nodes in canonical form:
Next, we need to order both the node namespaces and attributes in the ascending lexicographic order. In other words, we can use the Delphi string list object for ordering the namespaces and attributes declared within the current XML node:
The full sample source code and also the NormalizeAttributeValue function can be downloaded at soapsecurity.zip.
Once the XML document part has been normalized and canonicalized, it is ready for applying the digital signature and digest hash calculation algorithms.
Calculating the digest value of data
In this step we need to combine the SignedInfo XML node containing references to the XML data being secured together with their digest hash values. The function below accepts the whole SOAP XML document and also the reference URI list, which will be used to locate to the required XML nodes. This CreateSignedInfo function returns a newly created the SignedInfo XML node according to the Canonical XML specification.
This sample uses the TclEncoder component of the Internet Components - Clever Internet Suite library for encoding binary values into the Base64 encoding format. But it is possible to use any other encoding library on your convenience.
There are different ways to obtain the digest hash value: you can use standard Microsoft shipped CryptoAPI library or use any third party library such as StreamSec tools. In this article we have used the MS CryptoAPI library for calculating SHA1 digest hash values:
Signing the SOAP message using the cryptography algorithm
In this step we need to digitally sign the SignedInfo XML node we built in the previous chapter using a cryptographic algorithm. In our case we use the private key cryptography with X509 certificates. At first, we need to obtain the required certificate within the certificate store in terms of using the MS CryptoAPI library. When the certificate context is defined, it is time to digitally sign data using the CryptSignMessage CryptoAPI function in detached signature mode:
The obtained digital signature value is also encoded using the TclEncoder component and substituted into the Signature XML node.
Source Code and working sample
The sample code introduced in the article listings is simplified and does not provide the error handling code when signing the XML data. Also the sample does not implement any XML transformations which can be applied to the XML document when canonicalizing it before digitally signing and encoding.
In the next article about SOAP security extensions we will expand the sample code with XML transformations feature and also with including digital certificates into the SOAP XML data.
A full source code of all classes described in this article can be downloaded at soapsecurity.zip
This code is constantly being refined and improved and your comments and suggestions are always welcome.
With best regards,