setDebugOutput Method
[This feature was first implemented for MSXML 5.0.]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.
- Resource File (signature.template.xml)
- C/C++ Code (setDebugOutput.cpp)
- Output for the getVerifyingCertificate Method Example
Applies To
Versioning
MSXML 5.0 and later
To view reference information for Visual Basic, C/C++, or Script only, click the Language Filter button in the upper-left corner of the page.