setDebugOutput Method
[This sample code uses features that were implemented in MSXML 5.0 for Microsoft Office Applications. XML digital signatures are not supported in MXSML 6.0 and later.]
Sets an IStream object on the IXMLDigitalSignature object to receive debug information generated by the IXMLDigitalSignature object.
C/C++ Syntax
HRESULT setDebugOutput (IStream* debugOutput);
Parameters
debugOutput
An IStream object to receive debugging information.
Return Values
S_OK
The debug output stream object was set without error.
E_FAIL
Failed to set the debug output.
Remarks
The IXMLDigitalSignature object generates debug information. This information consists of digest values and the signature value as the input to calculations. Such information can be helpful for debugging an application when the input data is invalid or improper. For example, if data referenced in the <ds:Reference> element must undergo an XLST transformation before it is digested, an improper style sheet or template will output an incorrect digest value. This scenario might also apply in other cases involving canonicalization and other transformations. The debug output could help you determine the source of such problems.
To catch the debug output, you need to create an IStream class that implements at least the Commit and Write methods. Other methods on the IStream interface can simply return E_NOTIMPL.
The IXMLDigitalSignature object invokes IStream::Commit with the grfCommitFlags parameter set to zero (0) before it begins to calculate a digest value. The object calls this method with the grfCommitFlags parameter set to one (1) after it finishes calculating the digest value. If you decide to direct the debug output to a file for each digest calculation, you can implement the IStream::Commit method in such a way that a new file is created if grfCommitFlags is 0 and the file is closed when grfCommitFlags is 1. If you want all the output to go to the standard output (stdout), you can use, for example, printf() to mark off the beginning of a digest calculation when grfCommitFlags is 0 and to mark off the end of the digest calculation when grfCommitFlags is 1. This is illustrated in the example below.
The IXMLDigitalSignature object invokes IStream::Write when it has the debug information ready. You can direct the output to a file if a file is opened, or you can print the debug output to stdout as shown in the example below. For each digest, the IXMLDigitalSignature object writes out the debug information in chunks. The maximum size of a chunk is 1024 bytes.
The IXMLDigitalSignature object also outputs debug information when calculating a signature value. In signature signing, the object writes out the <ds:SignedInfo> element to the debug output target after digesting all the data referred to in the <ds:Reference> elements. In signature verification, it writes out the <--ds:SignedInfo> element to the debug output target before calculating all the data digests. For an illustration, see the example below.
Example
The example below demonstrates how to catch the debug output from the IXMLDigitalSignature object and direct it to the standard output (stdout).
A DBStream class implementing the IStream interface is created (DBStream.cpp and DBStream.h). An instance of this class is passed to the IXMLDigitalSignature::setDebugOutput method call. All the debug data are displayed using printf(). You could also implement this class to save the output to one or more files, or to store the debug information in another XML DOM object. The same DBStream object is made available for both sign and verify in the main program.
The input signature template (signature.template.xml) contains an embedded reference (<ds:Reference URI="#obj" ...>) and an external one (<ds:Reference URI="http://www.example.com">). This means that two digests are encountered for each sign or verify, and the DBStream object records debug data for four digest values.
The example outputs a signed document persisted to signature.document.xml, as well as output displayed in the application's console.
Applies To
Versioning
MSXML 5.0 for Microsoft Office Applications and later