Chilkat.XmlDSig Class Overview

Chilkat.XmlDSig loads and verifies XML Digital Signatures. It can inspect signatures, select among multiple signatures in one XML document, verify the overall SignatureValue, verify individual Reference digests, handle external references, extract KeyInfo, retrieve embedded certificates or public keys, canonicalize XML, and add an EncapsulatedTimeStamp to an existing signature.

What the Class Is Used For

Use Chilkat.XmlDSig when an application needs to validate or inspect XML signatures that already exist. It is the verification counterpart to XML signature generation: load signed XML, select a signature, provide any missing key or external reference data, then verify the signature and optionally each referenced object digest.

Verify XML Signatures Validate the selected XML Signature and optionally validate all Reference digests in the SignedInfo.
Inspect Signature Contents Get the number of signatures, number of references, reference URIs, KeyInfo, embedded certificates, and public key information.
Handle External References Provide external reference data from files, binary data, or text when the XML signature references content outside the XML document.
Canonicalize XML Canonicalize an entire XML document or a selected fragment using inclusive or exclusive canonicalization, with or without comments.

Typical Workflow

  1. Load the signed XML using LoadSignature, LoadSignatureSb, or LoadSignatureBd.
  2. Check NumSignatures to determine how many Signature elements were found.
  3. Set Selector when the XML contains more than one signature. The default is 0.
  4. Inspect references with NumReferences, ReferenceUri, and IsReferenceExternal.
  5. Provide external reference data when needed using SetRefDataFile, SetRefDataBd, or SetRefDataSb.
  6. Provide a public key when KeyInfo does not contain one, using SetPublicKey, or provide a certificate source with UseCertVault.
  7. For HMAC signatures, set the HMAC key with SetHmacKey.
  8. Call VerifySignature(true) to verify both the SignatureValue and Reference digests.
  9. If verification fails, use VerifyReferenceDigest for each reference and inspect RefFailReason.

Core Concepts

Concept Meaning Important Members
Loaded XML Signature The XML document loaded into the object. It may contain one or more Signature elements. LoadSignature, LoadSignatureSb, LoadSignatureBd, NumSignatures
Selector Chooses which signature is active when the XML contains multiple signatures. Selector
Reference A data object listed in SignedInfo. It may be internal to the XML document, contained within the signature, or external. NumReferences, ReferenceUri, IsReferenceExternal
Reference Digest The digest for one referenced object. Validating references helps locate which signed data failed to match. VerifyReferenceDigest, RefFailReason
KeyInfo The optional XML section that can contain or identify the key/certificate needed for signature verification. GetKeyInfo, GetPublicKey, GetCerts
External Reference Data Data not contained in the signed XML that must be supplied by the application before complete reference validation can succeed. SetRefDataFile, SetRefDataBd, SetRefDataSb, ExternalRefDirs

Loading Signed XML

Input Source Method Behavior
String containing XML LoadSignature Loads XML containing one or more XML digital signatures.
StringBuilder LoadSignatureSb Loads signed XML from a StringBuilder.
BinData LoadSignatureBd Loads signed XML from binary data.
Load behavior: When signed XML is loaded, Selector is automatically reset to 0, and NumSignatures is set to the number of XML Digital Signatures found.

Working with Multiple Signatures

A single XML document can contain multiple Signature elements. The Selector property determines which one is active for verification and inspection.

Member Purpose Usage
NumSignatures Number of Signature elements found in the loaded XML. Use this to loop through signatures.
Selector Selects which signature is active. Set to 0 for the first signature, 1 for the second, and so on.
Selected signature operations VerifySignature, GetKeyInfo, GetPublicKey, GetCerts, HasEncapsulatedTimeStamp These operate on the signature indicated by Selector.

Verifying Signatures

Verification Task Method What It Checks
Verify selected signature VerifySignature Verifies the SignatureValue for the selected signature. When verifyReferenceDigests is true, also verifies each Reference digest in SignedInfo.
Verify one reference digest VerifyReferenceDigest Computes and compares the digest for a single Reference. Useful for diagnosing which referenced object failed.
Set public key manually SetPublicKey Supplies the verification public key when it is not already available in KeyInfo.
Use an XML certificate vault UseCertVault Adds a certificate source to search for certificates containing public keys. Calling it again replaces the previous vault.
Verify HMAC signature SetHmacKey Supplies the HMAC key when the XML signature uses an HMAC signing algorithm.
Recommended verification call: Use VerifySignature(true) when complete validation is desired, because this verifies both the SignatureValue and the Reference digests.

Reference Inspection and External Data

Need Member Guidance
Count references NumReferences Number of referenced data objects in the selected XML signature.
Get reference URI ReferenceUri Returns the URI for a reference. URIs beginning with # are internal references.
Check whether a reference is external IsReferenceExternal Returns true if the reference is external and may require application-supplied data before validation.
Automatically search local directories ExternalRefDirs Semicolon-separated list of local directories to search for external files when the referenced external filename matches the local filename.
Ignore missing external references IgnoreExternalRefs Allows partial validation when external referenced files are unavailable. Default is false.

Providing External Reference Data

External references must often be supplied by the application before reference digest verification can succeed.

External Data Source Method How It Is Used
Local file SetRefDataFile Streams the file contents while computing the digest for the selected external reference.
Binary data SetRefDataBd Provides binary data for the external reference using a BinData object.
Text data SetRefDataSb Provides text data using a StringBuilder and a charset such as utf-8, utf-16, or windows-1252.
Charset matters: For text external references, the charset controls the byte representation used when computing the digest. When unsure, utf-8 is usually the first encoding to test.

Reference Digest Failure Reasons

After VerifyReferenceDigest, inspect RefFailReason to understand why a reference digest failed.

RefFailReason Meaning Typical Next Step
0 No failure; the reference digest was valid. No action needed for this reference.
1 The computed digest differs from the digest stored in the XML. Check canonicalization, transforms, whitespace, referenced content, and whether the correct external data was supplied.
2 An external file is referenced but unavailable. Set ExternalRefDirs, call a SetRefData* method, or enable IgnoreExternalRefs for partial validation.
3 The reference index was out of range. Check NumReferences and use zero-based indexing.
4 Unable to find the Signature. Confirm that LoadSignature succeeded and that Selector identifies an existing signature.
5 A specified XML canonicalization transform is not supported. Review the transforms used by the Reference.
99 Unknown failure. Check LastErrorText for details.

KeyInfo, Certificates, and Public Keys

Task Method Result
Get KeyInfo XML GetKeyInfo Returns the KeyInfo XML for the selected signature, or null if no KeyInfo exists.
Get embedded public key GetPublicKey Returns the public key contained in KeyInfo, or null if no usable public key exists there.
Get embedded certificates GetCerts Returns the base64 representation of certificates found in the selected signature.
Supply public key manually SetPublicKey Use when KeyInfo does not contain the public key but identifies which key should be used.
Search certificate vault UseCertVault Provides an XmlCertVault to search for certificates containing public keys needed for verification.
KeyInfo is optional: Some XML signatures do not contain the public key. In those cases, the application must obtain the correct public key or certificate and provide it with SetPublicKey or UseCertVault.

Canonicalization Helpers

The class includes helper methods for canonicalizing XML outside of full signature verification. These are useful for diagnostics and interoperability testing.

Method Scope Options
CanonicalizeXml Canonicalizes the entire XML string passed to the method. Version can be C14N or EXCL_C14N. Comments are included only when withComments is true.
CanonicalizeFragment Canonicalizes a fragment starting at the XML element whose Id matches fragmentId. Supports C14N or EXCL_C14N. The prefix list applies only to exclusive canonicalization.
Exclusive canonicalization prefix list: The prefixList argument applies only when using EXCL_C14N. It contains namespace prefixes separated by spaces.

Encapsulated Timestamp Support

Task Method Purpose
Check for an EncapsulatedTimeStamp HasEncapsulatedTimeStamp Returns true when the selected signature contains an EncapsulatedTimeStamp.
Add an EncapsulatedTimeStamp AddEncapsulatedTimeStamp Adds an EncapsulatedTimeStamp to the selected signature and returns the updated signed XML in a StringBuilder.
Configure HTTP/TSA communication SetHttpObj Supplies an Http object used to communicate with OCSP responders, CRL distribution points, or timestamp authority servers when needed.

Diagnostics and Troubleshooting

Problem Area Member What to Check
General failure LastErrorText Provides detailed diagnostic information about the last method or property access. Check this after failures or unexpected results.
No signatures found LoadSignature, NumSignatures Confirm that the XML contains Signature elements and that the document was loaded successfully.
Wrong signature selected Selector For XML with multiple signatures, set the selector to the intended zero-based signature index.
Reference digest mismatch VerifyReferenceDigest, RefFailReason Verify references one at a time to identify which signed data object failed.
Missing external reference IsReferenceExternal, SetRefDataFile, SetRefDataBd, SetRefDataSb, ExternalRefDirs Provide the referenced content or configure directories where external files can be found.
Verifier cannot locate public key GetKeyInfo, GetPublicKey, GetCerts, SetPublicKey, UseCertVault Inspect KeyInfo and supply the public key or certificate source if it is not embedded in the signature.
TSA, OCSP, or CRL network configuration SetHttpObj Provide a configured Http object when proxies, timeouts, or connection settings are needed.

Best Practices

Recommendation Reason
Always check NumSignatures after loading XML. It confirms that signatures were found and helps determine whether Selector must be set.
Use Selector deliberately for multi-signature XML. Verification and inspection methods operate on the selected signature.
Use VerifySignature(true) for full validation. It verifies both the SignatureValue and the digests for all references.
Verify references individually when full validation fails. VerifyReferenceDigest and RefFailReason help locate the failed reference and explain why it failed.
Inspect each reference URI before validation. External references require either accessible files or application-supplied reference data.
Use SetRefDataFile for large external files. The file is streamed while computing the digest rather than requiring the entire file to be held in memory.
Do not ignore external references unless partial validation is acceptable. IgnoreExternalRefs allows validation to continue without unavailable external data, but the result is incomplete.
Use canonicalization helpers for difficult interoperability problems. CanonicalizeXml and CanonicalizeFragment can help diagnose whitespace, namespace, and transform issues.
Check LastErrorText after failures. It provides the most useful diagnostic detail for load, key, reference, canonicalization, timestamp, and verification problems.

Summary

Chilkat.XmlDSig is the XML Digital Signature verification and inspection class. It loads signed XML, selects among multiple signatures, validates SignatureValue and Reference digests, handles external reference data, extracts KeyInfo, embedded certificates, and public keys, canonicalizes XML or fragments, and can add an EncapsulatedTimeStamp to an existing signature.

The most reliable validation pattern is to load the XML, choose the correct signature with Selector, provide any missing external data or public key, call VerifySignature(true), and use VerifyReferenceDigest plus RefFailReason to diagnose failures.