Chilkat.XmlDSigGen Class Overview
Chilkat.XmlDSigGen creates XML Digital Signatures. It supports same-document references, external XML/text/binary/file references, Object references, enveloping signatures, X.509 certificate KeyInfo, custom KeyInfo XML, RSA/DSA/ECDSA private keys, HMAC signatures, canonicalization options, transforms, signature placement, timestamp authority settings, and compatibility behaviors for systems with strict or unusual XML signature requirements.
What the Class Is Used For
Use Chilkat.XmlDSigGen when an application needs to generate an XML signature according to XMLDSig-style rules. The class is focused on signature creation: you configure what is referenced, how each reference is digested and transformed, what key or certificate signs the data, where the Signature element is inserted, and what KeyInfo or X.509 details are included.
Sign XML Documents or Fragments
Add same-document references for an entire XML document or for a specific
element identified by an Id.
Sign External Data
Add references to external XML, text, binary data, or local files while
controlling digest methods and transforms.
Control Signature Shape
Choose Signature location, namespace prefix, Signature Id, SignedInfo Id,
SignatureValue Id, KeyInfo Id, and output formatting behaviors.
Use Certificates and Private Keys
Sign with a private key directly, or use a certificate with an associated
private key and include X.509 information in KeyInfo.
Typical Workflow
- Decide the signature style: same-document, external/detached, object-based, enveloping, or a specialized XML/XAdES-style format.
- Configure signature placement using SigLocation, SigLocationIdx, and SigLocationMod.
- Configure signature namespaces and Id attributes with properties such as SigNamespacePrefix, SigNamespaceUri, SigId, SignedInfoId, SigValueId, and KeyInfoId.
- Add one or more references using methods such as AddSameDocRef, AddExternalXmlRef, AddExternalTextRef, AddExternalBinaryRef, AddExternalFileRef, or AddObjectRef.
- Set digest, canonicalization, and transform options for each reference.
- Configure KeyInfo output with KeyInfoType, X509Type, CustomKeyInfoXml, or KeyInfoKeyName.
- Set the signing key with SetPrivateKey, SetX509Cert, or SetHmacKey.
- Optionally configure TSA, HTTP, or compatibility behaviors with SetTsa, SetHttpObj, or Behaviors.
- Generate the signature with CreateXmlDSig or CreateXmlDSigSb.
Core Concepts
| Concept | Meaning | Important Members |
|---|---|---|
| Signature | The generated XML Signature element containing SignedInfo, SignatureValue, optional KeyInfo, and optional Object elements. | CreateXmlDSig, CreateXmlDSigSb, SigNamespacePrefix, SigNamespaceUri |
| Reference | A piece of data included in SignedInfo by URI, Id, object reference, or external content. Each reference is digested. | AddSameDocRef, AddExternalXmlRef, AddObjectRef |
| Canonicalization | The process of converting XML into a stable byte representation before digesting or signing. | SignedInfoCanonAlg, AddSameDocRef, AddExternalXmlRef |
| SignedInfo | The signed XML structure containing the canonicalization method, signature method, and all references. | SignedInfoCanonAlg, SignedInfoDigestMethod, ConstructSignedInfo |
| KeyInfo | Optional information that helps the verifier identify or obtain the key or certificate used for verification. | KeyInfoType, X509Type, CustomKeyInfoXml, KeyInfoKeyName |
| Signing Key | The private key, certificate/private-key pair, or HMAC key used to create the SignatureValue. | SetPrivateKey, SetX509Cert, SetHmacKey |
Signature Placement
The Signature element can be inserted into a specific location in the XML document or can be generated as the root element for an enveloping signature.
| Property | Purpose | Guidance |
|---|---|---|
| SigLocation | Chilkat path to the element where the Signature should be inserted. | Use vertical bars to separate element names, such as SOAP-ENV:Envelope|SOAP-ENV:Header|wsse:Security. Use an empty string when the Signature is to be the root element. |
| SigLocationIdx | Selects the Nth occurrence of SigLocation. | Default is 0, meaning the first matching location. |
| SigLocationMod | Controls whether the Signature is inserted as a child or sibling. | 0 = last child, 1 = sibling after, 2 = sibling before. |
Enveloping signature note:
When the generated Signature element is the root of the output XML,
SigLocation is empty, and the input XML passed to
CreateXmlDSig or
CreateXmlDSigSb may also be empty.
Reference Types
| Reference Type | Method | Use When |
|---|---|---|
| Same-document XML reference | AddSameDocRef, AddSameDocRef2 | Sign the entire XML document or a fragment of the same document. An empty Id signs the entire XML document. |
| Object reference | AddObject, AddObjectRef, AddObjectRef2 | Add an Object element inside the Signature and reference it by Id. |
| Enveloping/object-contained content | AddEnvelopedRef | Add text content inside an Object element contained within the generated Signature, then reference that object. |
| External XML reference | AddExternalXmlRef | Sign XML content that is external to the XML document being generated. |
| External text reference | AddExternalTextRef | Sign non-XML text using a specified charset and optional BOM. |
| External binary reference | AddExternalBinaryRef | Sign binary data held in a BinData object. |
| External file reference | AddExternalFileRef | Sign a local file. The URI in the Reference can differ from the local file path used to compute the digest. |
Reference Type attribute:
Many reference methods accept refType. It is optional
and advisory. Pass an empty string unless a target format specifically requires a
Type attribute on the Reference.
Digest Methods and Canonicalization
| Setting | Allowed Values | Where Used |
|---|---|---|
| Reference digest method | sha1, sha256, sha384, sha512, ripemd160, md5 | Reference methods such as AddSameDocRef, AddExternalXmlRef, AddObjectRef, and related methods. |
| SignedInfo digest method | sha1, sha256, sha384, sha512 | SignedInfoDigestMethod. Default is sha256. |
| SignedInfo canonicalization | C14N, C14N_11, EXCL_C14N, C14N_WithComments, C14N_11_WithComments, EXCL_C14N_WithComments | SignedInfoCanonAlg. Default is EXCL_C14N. |
| Reference canonicalization | Same canonicalization keywords, or empty string for no transform in methods that support it. | canonMethod arguments on XML reference methods. |
| Inclusive namespace prefix list | Space-separated namespace prefixes, or _EMPTY_ where supported. | prefixList arguments and SignedInfoPrefixList. |
Canonicalization is critical:
XML signature verification depends on both sides canonicalizing the exact same
XML bytes. Use the canonicalization method, transforms, namespace prefix lists,
and compatibility behaviors required by the receiving system.
KeyInfo Configuration
| Property | Purpose | Values / Notes |
|---|---|---|
| KeyInfoType | Selects what, if anything, is added to the KeyInfo element. | None, KeyName, KeyValue, X509Data, X509Data+KeyValue, Custom. Default is KeyValue. |
| KeyInfoKeyName | Supplies the KeyName value when KeyInfoType = "KeyName". | Used when the verifier expects a symbolic key name. |
| CustomKeyInfoXml | Custom XML inserted into KeyInfo. | Common for WS-Security fragments such as wsse:SecurityTokenReference. |
| KeyInfoId | Adds an Id attribute to the generated KeyInfo element. | Use when the signature profile references KeyInfo by Id. |
| X509Type | Controls which X.509 certificate details are included when KeyInfoType = "X509Data". | Certificate, CertChain, IssuerSerial, SubjectName, SKI. Can be a comma-separated list. |
Signing Key Options
| Need | Method / Property | Guidance |
|---|---|---|
| Sign with a private key | SetPrivateKey | Sets an RSA, DSA, or ECDSA private key for signature generation. |
| Sign with a certificate’s private key | SetX509Cert(cert, true) | Uses the certificate for X509Data and also sets the private key from the certificate when available. |
| Include certificate only in KeyInfo | SetX509Cert(cert, false) | Provides certificate information for KeyInfo without setting the signing private key. |
| Sign with HMAC | SetHmacKey | Sets an HMAC key. The key can be supplied in encodings such as hex, base64, or ascii. |
| Use RSA-PSS | SigningAlg | For RSA private keys, use RSASSA-PSS or pss. Default is PKCS1-v1_5. |
Certificate/private-key reminder:
A certificate file such as .cer usually contains only
the public certificate. To sign, the private key must be available separately, or
the certificate must have been loaded from a source such as PFX/P12, JKS, a
Windows certificate store, smart card, HSM, or another source that associates the
certificate with its private key.
Signature Namespace and Id Options
| Element / Namespace | Property / Method | Purpose |
|---|---|---|
| Signature namespace prefix | SigNamespacePrefix | Prefix for the generated Signature element. Default is ds. Set empty to omit the Signature namespace prefix and URI. |
| Signature namespace URI | SigNamespaceUri | Namespace URI for the generated Signature. Default is http://www.w3.org/2000/09/xmldsig#. |
| Additional Signature namespaces | AddSignatureNamespace | Adds one or more extra namespaces to the Signature element. |
| Signature Id | SigId | Adds an optional Id attribute to the Signature element. |
| SignedInfo Id | SignedInfoId | Adds an optional Id attribute to SignedInfo. |
| SignatureValue Id | SigValueId | Adds an optional Id attribute to SignatureValue. |
| InclusiveNamespaces prefix/URI | IncNamespacePrefix, IncNamespaceUri | Controls the prefix and namespace URI for generated InclusiveNamespaces elements. Defaults are ec and http://www.w3.org/2001/10/xml-exc-c14n#. |
Advanced Transform Control
| Need | Method / Property | Use When |
|---|---|---|
| Specify standard transform settings | AddSameDocRef, AddObjectRef, AddExternalXmlRef | Use digest method, canonicalization method, prefix list, and optional reference Type. |
| Specify exact transform XML | AddSameDocRef2, AddObjectRef2 | Use when the receiving system requires a transform sequence that must be expressed exactly as XML. |
| Set reference Id attribute mapping | SetRefIdAttr | Sets the Id attribute for a Reference, useful when an XML profile uses a non-default Id attribute convention. |
| Construct canonicalized SignedInfo only | ConstructSignedInfo | Special-purpose method for obtaining the exact canonicalized SignedInfo that would be signed. The input XML is not modified. |
Base64 transform note:
For AddObjectRef, setting the canonicalization method
to Base64 uses the XMLDSig base64 transform.
Timestamp Authority and HTTP Support
| Need | Method | Purpose |
|---|---|---|
| Add timestamp authority settings | SetTsa | Sets the TSA URL and related settings for automatically adding an EncapsulatedTimestamp. |
| Configure HTTP used by validation/time services | SetHttpObj | Supplies an Http object used to communicate with OCSP responders, CRL distribution points, or TSA servers. This allows HTTP timeouts, proxies, and other connection settings to be controlled. |
Compatibility Behaviors
The Behaviors property accepts comma-separated keywords for special output requirements or compatibility with systems that expect non-default XML signature details.
| Behavior Area | Keywords | Purpose |
|---|---|---|
| Canonicalization compatibility | AttributeSortingBug | Reproduces a known XML canonicalization attribute sorting bug required by some external systems. |
| Base64 formatting | Base64Multiline, Base64CrEntity, Base64Cr13Entity | Controls multiline base64 formatting for elements such as SignatureValue and X509Certificate. |
| Enveloped signature transform control | ForceAddEnvelopedSignatureTransform, NoEnvelopedSignatureTransform, EnvelopedTransformFirst | Forces, suppresses, or reorders the enveloped-signature transform. |
| SOAP / ebXML / UBL transforms | ebXmlTransform, TransformSignatureXPath, UBLDocumentSignatures | Adds specialized XPath transforms used by particular XML messaging or document-signature profiles. |
| Output formatting | CompactSignedXml, IndentedSignature | Controls whether the signed XML is compact or whether the Signature is formatted with indentation for readability. |
| Signing time formatting | FullLocalSigningTime, LocalSigningTime, NoReplaceSigningTime, NoTimestampBias, SigningTimeAdjust-<seconds>, SigningTimeAdjust+<seconds> | Controls generated SigningTime values and formatting, including local time, milliseconds, retaining an application-supplied value, or adjusting the timestamp. |
| Certificate distinguished names and serials | DnReverseOrder, IssuerSerialHex, IssuerSerialHexLower | Controls X.509 issuer/subject distinguished-name ordering and whether issuer serial numbers are emitted as decimal or hex. |
| Multiple signatures | SignExistingSignatures | Causes existing signatures to be included in canonicalization/digest when applying a second or later signature. |
Use behaviors only when needed:
Most signatures should not require special behaviors. Set these keywords only
when a target system or signature profile explicitly requires them.
Generating the Signature
| Method | Input / Output | Use When |
|---|---|---|
| CreateXmlDSig | Accepts the XML as a string and returns the signed XML as a string. | Convenient when the XML is already available as a string and the output is expected as a string. |
| CreateXmlDSigSb | Accepts a StringBuilder containing the input XML and replaces it with the signed XML on success. | Use when working with large or mutable XML content. |
| ConstructSignedInfo | Returns the canonicalized SignedInfo XML without modifying the input XML. | Special-purpose diagnostic or integration workflow where the application needs the exact bytes that would be signed. |
Diagnostics and Troubleshooting
| Problem Area | Member | What to Check |
|---|---|---|
| General failure | LastErrorText | Provides detailed information about the last method call or property access. Check this after failures or unexpected output. |
| Signature inserted in the wrong location | SigLocation, SigLocationIdx, SigLocationMod | Confirm the Chilkat path, occurrence index, and child/sibling placement. |
| Verifier reports digest mismatch | AddSameDocRef, canonMethod, prefixList, Behaviors | Check transforms, canonicalization method, inclusive namespace prefix lists, whitespace behavior, and whether special compatibility behaviors are needed. |
| Verifier cannot find the key | KeyInfoType, X509Type, CustomKeyInfoXml | Confirm that KeyInfo contains the required certificate, public key, key name, or custom security-token reference. |
| Signing fails due to missing private key | SetX509Cert, SetPrivateKey | If SetX509Cert(cert, true) fails, the certificate may not have an associated private key. Load a PFX/P12 or set the private key separately. |
| TSA, OCSP, or CRL network issues | SetHttpObj, SetTsa | Provide a configured Http object when proxy, timeout, or other HTTP communication settings are required. |
Best Practices
| Recommendation | Reason |
|---|---|
| Start by matching the receiving system’s required signature profile. | XMLDSig interoperability depends on exact Signature placement, references, transforms, canonicalization, namespace prefixes, and KeyInfo contents. |
| Use AddSameDocRef for normal enveloped XML signatures. | It signs the current document or a specific element by Id. |
| Use AddExternal* methods for detached references. | External references allow the Signature to refer to data outside the XML being signed. |
| Use AddObject and AddObjectRef for object-contained data. | Object references are useful for enveloping signatures where signed data is contained inside the Signature. |
| Prefer SHA-256 or stronger digest methods unless a profile requires otherwise. | The class supports older algorithms, but modern signature profiles usually prefer SHA-256 or better. |
| Use SetX509Cert(cert, true) when the certificate has an associated private key. | This configures both KeyInfo certificate data and the signing key in one step. |
| Use CustomKeyInfoXml for WS-Security and other profile-specific KeyInfo formats. | Some systems require a precise KeyInfo structure rather than generic KeyValue or X509Data. |
| Use ConstructSignedInfo for difficult interoperability debugging. | It shows the exact canonicalized SignedInfo that would be signed. |
| Check LastErrorText after failures. | It provides the most useful information for diagnosing reference, canonicalization, key, certificate, TSA, or XML placement problems. |
Summary
Chilkat.XmlDSigGen is the XML signature generation class for applications that need precise control over XMLDSig output. It supports same-document, external, object-based, and enveloping signature scenarios; RSA, DSA, ECDSA, and HMAC signing; X.509 certificate KeyInfo; custom KeyInfo XML; canonicalization and transform control; signature placement; TSA integration; and compatibility behaviors for specialized XML signature profiles.
XML signature interoperability is exacting. The receiving system’s required Signature location, Reference URI, transforms, canonicalization method, namespace prefixes, KeyInfo shape, and certificate details should guide the configuration.