XmlDSigGen C# Reference Documentation

XmlDSigGen

Current Version: 10.0.0
Requires Chilkat Bundle License

An API for generating/creating XML Digital Signatures. Use the XmlDSig class for verifying XML Digital Signatures.

Object Creation

Chilkat.XmlDSigGen obj = new Chilkat.XmlDSigGen();

Properties

Behaviors
public string Behaviors {get; set; }
Introduced in version 9.5.0.70

A comma-separated list of keywords to specify special behaviors to work around potential oddities or special requirements needed for providing signatures to particular systems. This is an open-ended property where new behaviors can be implemented depending on the needs encountered by Chilkat customers. The possible behaviors are listed below.

  • AttributeSortingBug (introduced in v9.5.0.79) Tells Chilkat to produce a signature that duplicates a common XML canonicalization attribute sorting bug found in some XML signature implementations (such as JPK VAT signed XML documents for Polish government, i.e. mf.gov.pl, csioz.gov.pl, crd.gov.pl, etc). See XML Signature Canonicalization Bug for details.
  • Base64CrEntity Produce multi-line base64 for XML elements such as SignatureValue and X509Certificate, with each line ending in a CR hex entity, except for the last line. For example: 
    <ds:X509Certificate>MIIFNTCCBB2gAwIBAgIQHozVnBl1lTsusAh26u6WZTANBgkqhkiG9w0BAQsFADCBlzELMAkGA1UE&#xD;
BhMCR0IxGzAZBgNVBAgTEkdyZWF0ZXIgTWFuY2hlc3RlcjEQMA4GA1UEBxMHU2FsZm9yZDEaMBgG&#xD;
A1UEChMRQ09NT0RPIENBIExpbWl0ZWQxPTA7BgNVBAMTNENPTU9ETyBSU0EgQ2xpZW50IEF1dGhl&#xD;
...
sp3FRlACVeb1Qlytr4vgc5FlCqn0rMtjlF4=
</ds:X509Certificate>
  • Base64Cr13Entity Produce multi-line base64 for XML elements such as SignatureValue and X509Certificate, with each line ending in a CR decimal entity, except for the last line. For example: 
    <ds:X509Certificate>MIIFNTCCBB2gAwIBAgIQHozVnBl1lTsusAh26u6WZTANBgkqhkiG9w0BAQsFADCBlzELMAkGA1UE&#13;
BhMCR0IxGzAZBgNVBAgTEkdyZWF0ZXIgTWFuY2hlc3RlcjEQMA4GA1UEBxMHU2FsZm9yZDEaMBgG&#13;
A1UEChMRQ09NT0RPIENBIExpbWl0ZWQxPTA7BgNVBAMTNENPTU9ETyBSU0EgQ2xpZW50IEF1dGhl&#13;
...
sp3FRlACVeb1Qlytr4vgc5FlCqn0rMtjlF4=
</ds:X509Certificate>
  • Base64Multiline Produce multi-line base64 for XML elements such as SignatureValue and X509Certificate. For example: 
    <ds:X509Certificate>MIIFNTCCBB2gAwIBAgIQHozVnBl1lTsusAh26u6WZTANBgkqhkiG9w0BAQsFADCBlzELMAkGA1UE
BhMCR0IxGzAZBgNVBAgTEkdyZWF0ZXIgTWFuY2hlc3RlcjEQMA4GA1UEBxMHU2FsZm9yZDEaMBgG
A1UEChMRQ09NT0RPIENBIExpbWl0ZWQxPTA7BgNVBAMTNENPTU9ETyBSU0EgQ2xpZW50IEF1dGhl
...
sp3FRlACVeb1Qlytr4vgc5FlCqn0rMtjlF4=
</ds:X509Certificate>
  • ForceAddEnvelopedSignatureTransform The "<Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature" /> " is normally only added when the Signature is contained within the XML fragment that is signed. The meaning of this tranformation is to tell the verifier to remove the Signature from the data prior to canonicalizing. If the Signature is not contained within the XML fragment that was signed, then the signature was not enveloped. There would be no need to remove the Signature because the Signature is not contained in the XML fragment being verified. However.. some brain-dead verifiying systems require this Transform to be present regardless of whether it makes sense. This behavior will cause Chilkat to add the Transform regardless.
  • NoEnvelopedSignatureTransform (introduced in v9.5.0.82) Prevents the "<Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature" /> " from being added in all cases.
  • EnvelopedTransformFirst (introduced in v9.5.0.87) Forces the http://www.w3.org/2000/09/xmldsig#enveloped-signature to be listed first when there are multiple transforms for a reference.
  • ebXmlTransform (introduced in v9.5.0.73) Causes the following tranform to be added for ebXml messages:
    <Transform Algorithm="http://www.w3.org/TR/1999/REC-xpath-19991116">
    <XPath xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">not(ancestor-or-self::node()[@SOAP-ENV:actor="urn:oasis:names:tc:ebxml-msg:actor:nextMSH"]
         | ancestor-or-self::node()[@SOAP-ENV:actor="http://schemas.xmlsoap.org/soap/actor/next"])</XPath>
</Transform>
  • TransformSignatureXPath (introduced in v9.5.0.75) Causes the following tranform to be added:
    <ds:Transform Algorithm="http://www.w3.org/TR/1999/REC-xpath-19991116">
   <ds:XPath>not(ancestor-or-self::ds:Signature)</ds:XPath>
</ds:Transform>
  • CompactSignedXml (introduced in v9.5.0.73) The passed-in XML to be signed is first reformatted to a compact representation by removing all CR's, LF's, and unnecessary whitespace so that the XML to be signed is on a single line. The resulting XML (with signature) is also entirely contained on a single line. (If an XML declarator is present, then it will remain on it's own line.)
  • IndentedSignature (introduced in v9.5.0.73) Causes the XML Signature to be produced on multiple lines with indentation for easier human readability. The CompactSignedXml behavior takes precedence over this behavior.
  • FullLocalSigningTime (introduced in v9.5.0.76) Causes the signing time to be formatted like this: 2017-05-20T19:16:05.649+01:00.nnn, where the ".nnn" is added to indicate milliseconds.
  • LocalSigningTime (introduced in v9.5.0.76) Causes the signing time to be formatted using a local time (with a timezone offset such as "+01:00" rather than "Z" to signify GMT).
  • NoReplaceSigningTime Don't replace the <SigningTime> content with a timestamp of the current date/time. Instead keep the current value provided by the application.
  • NoTimestampBias Exclude the timestamp bias from the generated <SigningTime>
  • DnReverseOrder (introduced in v9.5.0.77) Causes DN's (certificate Distinguished Names) to be written in reverse order. Reverse order leads with "CN", such as "CN=..., O=..., OU=..., C=...", whereas normal order ends with "CN", such as "C=..., OU=..., O=..., CN=..."
  • IssuerSerialHex (introduced in v9.5.0.77) Causes the issuer serial number located in SignedProperties.SignedSignatureProperties.SigningCertificate to be emitted as uppercase hex instead of decimal. (Also, when signing XML for e-dokumenty.mf.gov.pl, Chilkat automatically recognizes it and uses IssuerSerialHex.)
  • IssuerSerialHexLower (introduced in v9.5.0.77) Causes the issuer serial number located in SignedProperties.SignedSignatureProperties.SigningCertificate to be emitted as lowercase hex instead of decimal.
  • SigningTimeAdjust-<numSeconds> (introduced in v9.5.0.80) When Chilkat automatically fills in the value for a SigningTime, it will use the current system date/time. This behavior can be used to adjust the generate time to numSeconds in the past. For example: "SigningTimeAdjust-60" will generate a signing time 60 seconds prior to the current time.
  • SigningTimeAdjust+<numSeconds> (introduced in v9.5.0.88) When Chilkat automatically fills in the value for a SigningTime, it will use the current system date/time. This behavior can be used to adjust the generate time to numSeconds in the future. For example: "SigningTimeAdjust+60" will generate a signing time 60 seconds past the current time.
  • UBLDocumentSignatures Causes an XPath "ancestor-or-self" Transform to be added for the 1st reference. See the example at UBL XAdES Enveloped Signature
  • SignExistingSignatures This keyword can be used when applying a 2nd or greater signature and the new signature will encompass one or more existing signatures. The default behavior is that existing signatures are not included in the canonicalization/digest before signing. Adding this keyword will cause existing signatures to be included in the canonicalization/digest.

top
CustomKeyInfoXml
public string CustomKeyInfoXml {get; set; }
Introduced in version 9.5.0.69

Specifies custom XML to be inserted in the KeyInfo element of the Signature. A common use is to provide a wsse:SecurityTokenReference fragment of XML.

More Information and Examples
(.NET Core C#) Sign SOAP XML using a wsse:SecurityTokenReference(C#) Sign SOAP XML using a wsse:SecurityTokenReference(Mono C#) Sign SOAP XML using a wsse:SecurityTokenReference(PowerShell) Sign SOAP XML using a wsse:SecurityTokenReference(.NET Core C#) Create XAdES with ec:InclusiveNamespaces within the Transforms(C#) Create XAdES with ec:InclusiveNamespaces within the Transforms(Mono C#) Create XAdES with ec:InclusiveNamespaces within the Transforms(PowerShell) Create XAdES with ec:InclusiveNamespaces within the Transforms
top
DebugLogFilePath
public string DebugLogFilePath {get; set; }

If set to a file path, causes each Chilkat method or property call to automatically append it's LastErrorText to the specified log file. The information is appended such that if a hang or crash occurs, it is possible to see the context in which the problem occurred, as well as a history of all Chilkat calls up to the point of the problem. The VerboseLogging property can be set to provide more detailed information.

This property is typically used for debugging the rare cases where a Chilkat method call hangs or generates an exception that halts program execution (i.e. crashes). A hang or crash should generally never happen. The typical causes of a hang are:

  1. a timeout related property was set to 0 to explicitly indicate that an infinite timeout is desired,
  2. the hang is actually a hang within an event callback (i.e. it is a hang within the application code), or
  3. there is an internal problem (bug) in the Chilkat code that causes the hang.

More Information and Examples
(.NET Core C#) Example showing how to use DebugLogFilePath.(C#) Example showing how to use DebugLogFilePath.(Mono C#) Example showing how to use DebugLogFilePath.(PowerShell) Example showing how to use DebugLogFilePath.
top
IncNamespacePrefix
public string IncNamespacePrefix {get; set; }
Introduced in version 9.5.0.70

The namespace prefix to use for InclusiveNamespaces elements. The default value is "ec". Set this property to the empty string to omit an InclusiveNamespaces prefix. For example, given the default values of IncNamespaceUri and IncNamespacePrefix, generated InclusiveNamespaces elements will appear like this: 

<ec:InclusiveNamespaces xmlns:ec="http://www.w3.org/2001/10/xml-exc-c14n#"> ... </ec:InclusiveNamespaces>

top
IncNamespaceUri
public string IncNamespaceUri {get; set; }
Introduced in version 9.5.0.70

The namespace URI for any InclusiveNamespaces elements that are created. The default value is "http://www.w3.org/2001/10/xml-exc-c14n#". For example, if the IncNamespacePrefix equals "ec" and this property remains at the default value, then the generated Signature element will be: 

<ec:InclusiveNamespaces xmlns:ec="http://www.w3.org/2001/10/xml-exc-c14n#"> ... </ec:InclusiveNamespaces>

top
KeyInfoId
public string KeyInfoId {get; set; }
Introduced in version 9.5.0.75

If set, causes the generated KeyInfo element to include an Id attribute with this value. For example: 

...
   <ds:KeyInfo Id="KeyInfo">
      <ds:X509Data>
         <ds:X509SubjectName>CERTIFICADO DE ABC</ds:X509SubjectName>
         <ds:X509Certificate>MIIITTCC....fIsIZeZOeQ=</ds:X509Certificate>
      </ds:X509Data>
   </ds:KeyInfo>
...

top
KeyInfoKeyName
public string KeyInfoKeyName {get; set; }
Introduced in version 9.5.0.69

Specifies the KeyName to be inserted in the KeyInfo element of the Signature if the KeyInfoType equals "KeyName".

More Information and Examples
(.NET Core C#) Create XML Digital Signature having KeyName(C#) Create XML Digital Signature having KeyName(Mono C#) Create XML Digital Signature having KeyName(PowerShell) Create XML Digital Signature having KeyName
top
KeyInfoType
public string KeyInfoType {get; set; }
Introduced in version 9.5.0.69

Specifies the type of information that will be included in the optional KeyInfo element of the Signature. Possible values are:

  • None
  • KeyName
  • KeyValue
  • X509Data
  • X509Data+KeyValue
  • Custom

The default value is "KeyValue". The "X509Data+KeyValue" option was added in Chilkat v9.5.0.73.

If None, then no KeyInfo element is added to the Signature when generated.

If KeyValue, then the KeyInfo will contain the public key (RSA, DSA, or ECDSA).

If X509Data, then the KeyInfo will contain information about an X.509 certificate as specified by the X509Type property.

If Custom, then the KeyInfo will contain the custom XML contained in the CustomKeyInfoXml property.

More Information and Examples
(.NET Core C#) Create XML Digital Signature having KeyName(C#) Create XML Digital Signature having KeyName(Mono C#) Create XML Digital Signature having KeyName(PowerShell) Create XML Digital Signature having KeyName(.NET Core C#) Sign SOAP XML using a wsse:SecurityTokenReference(C#) Sign SOAP XML using a wsse:SecurityTokenReference(Mono C#) Sign SOAP XML using a wsse:SecurityTokenReference(PowerShell) Sign SOAP XML using a wsse:SecurityTokenReference(.NET Core C#) Create XML Signature with KeyInfo / X509Data / X509Certificate(C#) Create XML Signature with KeyInfo / X509Data / X509Certificate(Mono C#) Create XML Signature with KeyInfo / X509Data / X509Certificate(PowerShell) Create XML Signature with KeyInfo / X509Data / X509Certificate(.NET Core C#) Create XML Signature with KeyInfo / X509Data / X509SKI(C#) Create XML Signature with KeyInfo / X509Data / X509SKI(Mono C#) Create XML Signature with KeyInfo / X509Data / X509SKI(PowerShell) Create XML Signature with KeyInfo / X509Data / X509SKI
top
LastErrorHtml
public string LastErrorHtml {get; }

Provides information in HTML format about the last method/property called. If a method call returns a value indicating failure, or behaves unexpectedly, examine this property to get more information.

top
LastErrorText
public string LastErrorText {get; }

Provides information in plain-text format about the last method/property called. If a method call returns a value indicating failure, or behaves unexpectedly, examine this property to get more information.

More Information and Examples
Concept of LastErrorTextLastErrorText Standard Information
top
LastErrorXml
public string LastErrorXml {get; }

Provides information in XML format about the last method/property called. If a method call returns a value indicating failure, or behaves unexpectedly, examine this property to get more information.

top
LastMethodSuccess
public bool LastMethodSuccess {get; set; }

Indicate whether the last method call succeeded or failed. A value of true indicates success, a value of false indicates failure. This property is automatically set for method calls. It is not modified by property accesses. The property is automatically set to indicate success for the following types of method calls:

  • Any method that returns a string.
  • Any method returning a Chilkat object, binary bytes, or a date/time.
  • Any method returning a standard boolean status value where success = true and failure = false.
  • Any method returning an integer where failure is defined by a return value less than zero.

Note: Methods that do not fit the above requirements will always set this property equal to true. For example, a method that returns no value (such as a "void" in C++) will technically always succeed.

top
SigId
public string SigId {get; set; }
Introduced in version 9.5.0.69

An option Id attribute value for the Signature element. The default value is the empty string, which generates a Signature element with no Id attribute. For example: 

<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
If this property is set to "abc123", then the Signature element would be generated like this: 
<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#" Id="abc123">

top
SigLocation
public string SigLocation {get; set; }
Introduced in version 9.5.0.69

Indicates where the Signature is to be located within the XML that is signed. This is a path to the position in the XML where the Signature will be inserted, using Chilkat path syntax (using vertical bar characters to delimit tag names. If the Signature element is to be the root of XML document, then set this property equal to the empty string.

For example, if we have the following SOAP XML and wish to insert the Signature at the indicated location, then the SigLocation property should be set to "SOAP-ENV:Envelope|SOAP-ENV:Header|wsse:Security". 

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header>
	<wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" SOAP-ENV:mustUnderstand="1">
		** The XML Signature is to be inserted here **
	</wsse:Security>
    </SOAP-ENV:Header>
...
</SOAP-ENV:Envelope>

More Information and Examples
Online Tool to Generate XML Signature Based on Sample Signed XML
top
SigLocationMod
public int SigLocationMod {get; set; }
Introduced in version 9.5.0.77

Modifies the placement of the signature at the location specified by SigLocation. Possible values are:

  • 0: Insert the Signature as the last child of the element at SigLocation. This is the default.
  • 1: Insert the Signature as a sibling directly after the element at SigLocation.
  • 2: Insert the Signature as a sibling directly before the element at SigLocation.

top
SigNamespacePrefix
public string SigNamespacePrefix {get; set; }
Introduced in version 9.5.0.69

The namespace prefix of the Signature that is to be created. The default value is "ds". Set this property to the empty string to omit a Signature namespace URI and prefix. For example, given the default values of SigNamespaceUri and SigNamespacePrefix, the generated Signature element will be: 

<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> ... </ds:Signature>

top
SigNamespaceUri
public string SigNamespaceUri {get; set; }
Introduced in version 9.5.0.69

The namespace URI of the Signature that is to be created. The default value is "http://www.w3.org/2000/09/xmldsig#". For example, if the SigNamespacePrefix equals "ds" and this property remains at the default value, then the generated Signature element will be: 

<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> ... </ds:Signature>

top
SignedInfoCanonAlg
public string SignedInfoCanonAlg {get; set; }
Introduced in version 9.5.0.69

The canonicalization method to be used for the SignedInfo when creating the XML signature.

  • "C14N" -- for Inclusive Canonical XML (without comments)
  • "C14N_11" -- for Inclusive Canonical XML 1.1 (without comments)
  • "EXCL_C14N" -- for Exclusive Canonical XML (without comments)
  • "C14N_WithComments" -- for Inclusive Canonical XML (with comments)
  • "C14N_11_WithComments" -- for Inclusive Canonical XML 1.1 (with comments)
  • "EXCL_C14N_WithComments" -- for Exclusive Canonical XML (with comments)
  • Note: The WithComments options are available in Chilkat v9.5.0.71 and later.

The default value is "EXCL_C14N".

top
SignedInfoDigestMethod
public string SignedInfoDigestMethod {get; set; }
Introduced in version 9.5.0.69

The digest method to be used for signing the SignedInfo part of the Signature. Possible values are "sha1", "sha256", "sha384", and "sha512". The default is "sha256".

top
SignedInfoId
public string SignedInfoId {get; set; }
Introduced in version 9.5.0.75

Optional Id attribute to be added to the SignedInfo element. The default value is the empty string, meaning that the SignedInfo is generated without an Id attribute.

top
SignedInfoPrefixList
public string SignedInfoPrefixList {get; set; }
Introduced in version 9.5.0.69

The inclusive namespace prefix list to be added, if any, when the SignedInfoCanonAlg is equal to "EXCL_C14N". The defautl value is the empty string. If namespaces are listed, they are separated by space characters.

If, for example, this property is set to "wsse SOAP-ENV", then the CanonicalizationMethod part of the SignedInfo that is generated would look like this: 

<ds:SignedInfo>
    <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">
      <InclusiveNamespaces xmlns="http://www.w3.org/2001/10/xml-exc-c14n#" PrefixList="wsse SOAP-ENV" />
    </ds:CanonicalizationMethod>
...
</ds:SignedInfo>

More Information and Examples
(.NET Core C#) Sign SOAP XML using a wsse:SecurityTokenReference(C#) Sign SOAP XML using a wsse:SecurityTokenReference(Mono C#) Sign SOAP XML using a wsse:SecurityTokenReference(PowerShell) Sign SOAP XML using a wsse:SecurityTokenReference
top
SigningAlg
public string SigningAlg {get; set; }
Introduced in version 9.5.0.69

Selects the signature algorithm to be used when using an RSA key to sign. The default value is "PKCS1-v1_5". This can be set to "RSASSA-PSS" (or simply "pss") to use the RSASSA-PSS signature scheme.

Note: This property only applies when signing with an RSA private key. It does not apply for ECC or DSA private keys.

top
SigValueId
public string SigValueId {get; set; }
Introduced in version 9.5.0.75

An option Id attribute value for the SignatureValue element. The default value is the empty string, which generates a SignatureValue element with no Id attribute. For example: 

<ds:SignatureValue>
If this property is set to "value-id-7d4a", then the Signature element would be generated like this: 
<ds:SignatureValue  Id="value-id-7d4a">

top
UncommonOptions
public string UncommonOptions {get; set; }
Introduced in version 9.5.0.87

This is a catch-all property to be used for uncommon needs. This property defaults to the empty string, and should typically remain empty.

top
VerboseLogging
public bool VerboseLogging {get; set; }

If set to true, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. The default value is false. Verbose logging should only be used for debugging. The potentially large quantity of logged information may adversely affect peformance.

top
Version
public string Version {get; }

Version of the component/library, such as "9.5.0.94"

More Information and Examples
(.NET Core C#) How to get the Chilkat version at runtime.(C#) How to get the Chilkat version at runtime.(Mono C#) How to get the Chilkat version at runtime.(PowerShell) How to get the Chilkat version at runtime.
top
X509Type
public string X509Type {get; set; }
Introduced in version 9.5.0.69

Specifies the kind of X.509 certificate information is provided in the KeyInfo element when the KeyInfoType equals "X509Data". Possible values are:

  • Certificate
  • CertChain
  • IssuerSerial
  • SubjectName
  • SKI

The default value is "Certificate".

Note: This property can be set to a comma-separated list of the keywords above. For example, If set to "SubjectName,Certificate", then both the X509SubjectName and X509Certificate parts will be added to the KeyInfo.

If Certificate, then the KeyInfo will contain the base64 encoded X.509v3 certificate.

If CertChain, then the KeyInfo will contain the base64 encoded X.509v3 certificate as well as any certificates available in the chain of authentication to the root cert.

If IssuerSerial, then the KeyInfo will contain the X.509 issuer's distinguished name and the signing certificate's serial number.

If SubjectName, then the KeyInfo will contain the X.509 subject distinguished name.

If SKI, then the KeyInfo will contain the base64 encoded value of the cert's X.509 SubjectKeyIdentifier extension.

More Information and Examples
(.NET Core C#) Create XML Signature with KeyInfo / X509Data / X509Certificate(C#) Create XML Signature with KeyInfo / X509Data / X509Certificate(Mono C#) Create XML Signature with KeyInfo / X509Data / X509Certificate(PowerShell) Create XML Signature with KeyInfo / X509Data / X509Certificate(.NET Core C#) Create XML Signature with KeyInfo / X509Data / X509SKI(C#) Create XML Signature with KeyInfo / X509Data / X509SKI(Mono C#) Create XML Signature with KeyInfo / X509Data / X509SKI(PowerShell) Create XML Signature with KeyInfo / X509Data / X509SKI
top

Methods

AddEnvelopedRef
public bool AddEnvelopedRef(string id, StringBuilder content, string digestMethod, string canonMethod, string refType);
Introduced in version 9.5.0.69

Specifies an enveloped Reference to be added to the Signature when generated. An enveloped Reference is for data contained within the Signature. (The Signature is to be an enveloping signature, and the data is enveloped by the Signature.)

The id is the value of the Id attribute of the Object element that is to be contained within the generated Signature. The content is the text content to be contained in the Object. Binary data can be signed by passing the bytes in content in an encoded format (such as base64 or hex).

The digestMethod is the digest method and can be one of the following: "sha1", "sha256", "sha384", "sha512", "ripemd160", or "md5".

The canonMethod is the canonicalization method, and can be one of the following.

  • "C14N" -- for Inclusive Canonical XML (without comments)
  • "C14N_11" -- for Inclusive Canonical XML 1.1 (without comments)
  • "EXCL_C14N" -- for Exclusive Canonical XML (without comments)
  • "C14N_WithComments" -- for Inclusive Canonical XML (with comments)
  • "C14N_11_WithComments" -- for Inclusive Canonical XML 1.1 (with comments)
  • "EXCL_C14N_WithComments" -- for Exclusive Canonical XML (with comments)
  • Note: The WithComments options are available in Chilkat v9.5.0.71 and later.

The refType is optional and is usually not needed. Set this to the empty string unless it is desired to add a Type attribute to the Reference that is advisory only.

Returns true for success, false for failure.

More Information and Examples
(.NET Core C#) Create Enveloping XML Digital Signature(C#) Create Enveloping XML Digital Signature(Mono C#) Create Enveloping XML Digital Signature(PowerShell) Create Enveloping XML Digital Signature(.NET Core C#) Create Enveloping XML Signature with Multiple References(C#) Create Enveloping XML Signature with Multiple References(Mono C#) Create Enveloping XML Signature with Multiple References(PowerShell) Create Enveloping XML Signature with Multiple References
top
AddExternalBinaryRef
public bool AddExternalBinaryRef(string uri, BinData content, string digestMethod, string refType);
Introduced in version 9.5.0.69

Specifies an external non-XML binary data Reference to be added to the Signature when generated.

The uri is the value of the URI attribute of the Reference.

The content contains the binary data to be digested according to the digestMethod.

The digestMethod is the digest method and can be one of the following: "sha1", "sha256", "sha384", "sha512", "ripemd160", or "md5".

The refType is optional and is usually not needed. Set this to the empty string unless it is desired to add a Type attribute to the Reference that is advisory only.

Returns true for success, false for failure.

More Information and Examples
(.NET Core C#) Create XML Signature with External Data Reference(C#) Create XML Signature with External Data Reference(Mono C#) Create XML Signature with External Data Reference(PowerShell) Create XML Signature with External Data Reference(.NET Core C#) XML Signature Multiple External References(C#) XML Signature Multiple External References(Mono C#) XML Signature Multiple External References(PowerShell) XML Signature Multiple External References
top
AddExternalFileRef
public bool AddExternalFileRef(string uri, string localFilePath, string digestMethod, string refType);
Introduced in version 9.5.0.69

Specifies an external file Reference to be added to the Signature when generated.

The uri is the value of the URI attribute of the Reference. It can (and likely will) be different than the localFilePath which is the path to the local file to be added. (The local file is not read until the XML digital signature is actually created.)

The digestMethod is the digest method and can be one of the following: "sha1", "sha256", "sha384", "sha512", "ripemd160", or "md5".

The refType is optional and is usually not needed. Set this to the empty string unless it is desired to add a Type attribute to the Reference that is advisory only.

Returns true for success, false for failure.

top
AddExternalTextRef
public bool AddExternalTextRef(string uri, StringBuilder content, string charset, bool includeBom, string digestMethod, string refType);
Introduced in version 9.5.0.69

Specifies an external non-XML text data Reference to be added to the Signature when generated.

The uri is the value of the URI attribute of the Reference.

The content contains the non-XML data to be digested according to the charset. The charset specifies the charset (such as "utf-8", "windows-1252", etc.) for the byte reprsentation of the text to be digested. The includeBom indicates whether the BOM (Byte Order Mark, also known as the preamble) is included in the byte representation that is digested.

The digestMethod is the digest method and can be one of the following: "sha1", "sha256", "sha384", "sha512", "ripemd160", or "md5".

The refType is optional and is usually not needed. Set this to the empty string unless it is desired to add a Type attribute to the Reference that is advisory only.

Returns true for success, false for failure.

More Information and Examples
(.NET Core C#) Create/Verify XML Signature with External Text Reference(C#) Create/Verify XML Signature with External Text Reference(Mono C#) Create/Verify XML Signature with External Text Reference(PowerShell) Create/Verify XML Signature with External Text Reference
top
AddExternalXmlRef
public bool AddExternalXmlRef(string uri, StringBuilder content, string digestMethod, string canonMethod, string refType);
Introduced in version 9.5.0.69

Specifies an external XML Reference to be added to the Signature when generated.

The uri is the value of the URI attribute of the Reference.

The content contains the XML document to be referenced.

The digestMethod is the digest method and can be one of the following: "sha1", "sha256", "sha384", "sha512", "ripemd160", or "md5".

The canonMethod is the canonicalization method, and can be one of the following.

  • "C14N" -- for Inclusive Canonical XML (without comments)
  • "C14N_11" -- for Inclusive Canonical XML 1.1 (without comments)
  • "EXCL_C14N" -- for Exclusive Canonical XML (without comments)
  • "C14N_WithComments" -- for Inclusive Canonical XML (with comments)
  • "C14N_11_WithComments" -- for Inclusive Canonical XML 1.1 (with comments)
  • "EXCL_C14N_WithComments" -- for Exclusive Canonical XML (with comments)
  • "" -- An empty string indicates that no transformation should be included / applied for this reference.
  • Note: The WithComments options are available in Chilkat v9.5.0.71 and later.
  • Note: The empty-string canonMethod is available in Chilkat v9.5.0.75 and later.

The refType is optional and is usually not needed. Set this to the empty string unless it is desired to add a Type attribute to the Reference that is advisory only.

Returns true for success, false for failure.

More Information and Examples
(.NET Core C#) Create XML Signature with External XML Reference(C#) Create XML Signature with External XML Reference(Mono C#) Create XML Signature with External XML Reference(PowerShell) Create XML Signature with External XML Reference
top
AddObject
public bool AddObject(string id, string content, string mimeType, string encoding);
Introduced in version 9.5.0.75

Specifies an Object to be added to the Signature.

  1. The id is the value of the Object element's Id attribute.
  2. The content contains the content of the Object element, which may be XML or plain text.
  3. The mimeType is the value of the Object element's MimeType attribute
  4. The encoding is the value of the Object element's Encoding attribute
In most cases, the mimeType and encoding are empty strings which cause the MimeType and Encoding attributes to be omitted.

Returns true for success, false for failure.

top
AddObjectRef
public bool AddObjectRef(string id, string digestMethod, string canonMethod, string prefixList, string refType);
Introduced in version 9.5.0.75

This is the same as the AddSameDocRef method, except the reference is to content within an Object previously added via the AddObject method. The id must be an Id equal to the Id attribute of an Object, or the Id attribute of an element within the Object.

Note: The canonMethod can be set to "Base64" to use the http://www.w3.org/2000/09/xmldsig#base64 transform.

Returns true for success, false for failure.

More Information and Examples
(.NET Core C#) Signed Zip as Base64 with XAdES-BES(C#) Signed Zip as Base64 with XAdES-BES(Mono C#) Signed Zip as Base64 with XAdES-BES(PowerShell) Signed Zip as Base64 with XAdES-BES
top
AddObjectRef2
public bool AddObjectRef2(string id, string digestMethod, Xml transforms, string refType);
Introduced in version 9.5.0.90

This method is the same as AddObjectRef, except it allows the Transforms to be specified exactly with a fragment of XML. See the example below.

Returns true for success, false for failure.

More Information and Examples
(.NET Core C#) XML-DSig Add Object Reference with Transforms Specified Explicitly(C#) XML-DSig Add Object Reference with Transforms Specified Explicitly(Mono C#) XML-DSig Add Object Reference with Transforms Specified Explicitly(PowerShell) XML-DSig Add Object Reference with Transforms Specified Explicitly
top
AddSameDocRef
public bool AddSameDocRef(string id, string digestMethod, string canonMethod, string prefixList, string refType);
Introduced in version 9.5.0.69

Specifies a same document Reference to be added to the Signature when generated. A same document Reference can be the entire XML document, or a fragment of the XML document.

The id can be the empty string to sign the entire XML document, or it can be the fragment identifier to sign a portion of the XML document.

The digestMethod is the digest method and can be one of the following: "sha1", "sha256", "sha384", "sha512", "ripemd160", or "md5".

The canonMethod is the canonicalization method, and can be one of the following:

  • "C14N" -- for Inclusive Canonical XML (without comments)
  • "C14N_11" -- for Inclusive Canonical XML 1.1 (without comments)
  • "EXCL_C14N" -- for Exclusive Canonical XML (without comments)
  • "C14N_WithComments" -- for Inclusive Canonical XML (with comments)
  • "C14N_11_WithComments" -- for Inclusive Canonical XML 1.1 (with comments)
  • "EXCL_C14N_WithComments" -- for Exclusive Canonical XML (with comments)
  • "" -- An empty string indicates that no transformation should be included / applied for this reference.
  • Note: The WithComments options are available in Chilkat v9.5.0.71 and later.
  • Note: The empty-string canonMethod is available in Chilkat v9.5.0.75 and later.

If exclusive canonicalization is selected, then the prefixList can contain a space separated list of inclusive namespace prefixes. For inclusive canonicalization, this argument is ignored. In general, pass an empty string for this argument unless you have specific knowledge of namespace prefixes that need to be treated as inclusive when EXCL_C14N is used.

Starting in Chilkat v9.5.0.70, the prefixList can be set to the keyword "_EMPTY_" to force the generation of an empty PrefixList under the Transform. For example: 

  <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">
	<ec:InclusiveNamespaces xmlns:ec="http://www.w3.org/2001/10/xml-exc-c14n#" PrefixList=""/>
  </ds:Transform>

The refType is optional and is usually not needed. Set this to the empty string unless it is desired to add a Type attribute to the Reference that is advisory only.

Returns true for success, false for failure.

More Information and Examples
(.NET Core C#) SOAP XML Digital Signature using RSA Key(C#) SOAP XML Digital Signature using RSA Key(Mono C#) SOAP XML Digital Signature using RSA Key(PowerShell) SOAP XML Digital Signature using RSA Key
top
AddSameDocRef2
public bool AddSameDocRef2(string id, string digestMethod, Xml transforms, string refType);
Introduced in version 9.5.0.90

This method is the same as AddSameDocRef, except it allows the Transforms to be specified exactly with a fragment of XML. See the example below.

Returns true for success, false for failure.

More Information and Examples
(.NET Core C#) XML-DSig Add Reference with Transforms Specified Explicitly(C#) XML-DSig Add Reference with Transforms Specified Explicitly(Mono C#) XML-DSig Add Reference with Transforms Specified Explicitly(PowerShell) XML-DSig Add Reference with Transforms Specified Explicitly
top
AddSignatureNamespace
public bool AddSignatureNamespace(string nsPrefix, string nsUri);
Introduced in version 9.5.0.75

Can be called one or more times to add additional namespaces to the Signature element.

Returns true for success, false for failure.

top
ConstructSignedInfo
public string ConstructSignedInfo(StringBuilder sbXml);
Introduced in version 9.5.0.74

This method will construct and return the canonicalized SignedInfo XML. The digests of each Reference are computed and included in the SignedInfo. This method is provided for certain special circumstances where one wants to get the exact canonicalized SignedInfo that would be signed using the private key.

Note: Properties such as SigLocation, SigningAlg, etc. and references must be set exactly as if an XML signature was to be actually generated because they determine the content of the SignedInfo.

Note, the sbXml is not signed by this method. It is not modified.

Returns null on failure

top
CreateXmlDSig
public string CreateXmlDSig(string inXml);
Introduced in version 9.5.0.69

Creates an XML Digital Signature. The application passes in the XML to be signed, and the signed XML is returned. If creating an enveloping signature where the Signature element is the root, then the inXml may be the empty string.

  • Chilkat v9.5.0.76 or greater is required for XML signatures for www.csioz.gov.pl

Returns null on failure

More Information and Examples
Online Tool to Generate XML Signature Based on Sample Signed XML
top
CreateXmlDSigAsync (.NET Core C#) (C#) (Mono C#) (PowerShell)
public Task CreateXmlDSigAsync(string inXml);
Introduced in version 9.5.0.69

Creates an asynchronous task to call the CreateXmlDSig method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns null on failure

top
CreateXmlDSigSb
public bool CreateXmlDSigSb(StringBuilder sbXml);
Introduced in version 9.5.0.69

Creates an XML Digital Signature. The application passes the XML to be signed in sbXml, and it is replaced with the signed XML if successful. (Thus, sbXml is both an input and output argument.) Note: If creating an enveloping signature where the Signature element is to be the root element, then the passed-in sbXml may be empty.

Returns true for success, false for failure.

More Information and Examples
(.NET Core C#) SOAP XML Digital Signature using RSA Key(C#) SOAP XML Digital Signature using RSA Key(Mono C#) SOAP XML Digital Signature using RSA Key(PowerShell) SOAP XML Digital Signature using RSA Key(.NET Core C#) Create XML Digital Signature using a ECDSA Key(C#) Create XML Digital Signature using a ECDSA Key(Mono C#) Create XML Digital Signature using a ECDSA Key(PowerShell) Create XML Digital Signature using a ECDSA KeyOnline Tool to Generate XML Signature Based on Sample Signed XML(.NET Core C#) Create AuthNRequest with embedded signature (HTTP-POST binding)(C#) Create AuthNRequest with embedded signature (HTTP-POST binding)(Mono C#) Create AuthNRequest with embedded signature (HTTP-POST binding)(PowerShell) Create AuthNRequest with embedded signature (HTTP-POST binding)(.NET Core C#) XML-DSig Add EncapsulatedTimestamp when Signing(C#) XML-DSig Add EncapsulatedTimestamp when Signing(Mono C#) XML-DSig Add EncapsulatedTimestamp when Signing(PowerShell) XML-DSig Add EncapsulatedTimestamp when Signing
top
CreateXmlDSigSbAsync (.NET Core C#) (C#) (Mono C#) (PowerShell)
public Task CreateXmlDSigSbAsync(StringBuilder sbXml);
Introduced in version 9.5.0.69

Creates an asynchronous task to call the CreateXmlDSigSb method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns null on failure

top
SetHmacKey
public bool SetHmacKey(string key, string encoding);
Introduced in version 9.5.0.69

Sets the HMAC key to be used if the Signature is to use an HMAC signing algorithm. The encoding specifies the encoding of key, and can be "hex", "base64", "ascii", or any of the binary encodings supported by Chilkat in the link below.

Returns true for success, false for failure.

More Information and Examples
Binary Encodings Supported by Chilkat(.NET Core C#) Create XML Digital Signature using HMAC Key(C#) Create XML Digital Signature using HMAC Key(Mono C#) Create XML Digital Signature using HMAC Key(PowerShell) Create XML Digital Signature using HMAC Key
top
SetHttpObj
public void SetHttpObj(Http http);
Introduced in version 9.5.0.90

Sets the HTTP object to be used to communicate with OCSP responders, CRL distribution points, or timestamp authority (TSA) servers if needed. The http is used to send the requests, and it allows for connection related settings and timeouts to be set. For example, if HTTP or SOCKS proxies are required, these features can be specified on the http.

More Information and Examples
(.NET Core C#) XAdES using TSA Requiring Client Certificate(C#) XAdES using TSA Requiring Client Certificate(Mono C#) XAdES using TSA Requiring Client Certificate(PowerShell) XAdES using TSA Requiring Client Certificate
top
SetPrivateKey
public bool SetPrivateKey(PrivateKey privKey);
Introduced in version 9.5.0.69

Sets the private key to be used for creating the XML signature. The private key may be an RSA key, a DSA key, or an ECDSA key.

Returns true for success, false for failure.

More Information and Examples
(.NET Core C#) Create XML Digital Signature using a DSA Key(C#) Create XML Digital Signature using a DSA Key(Mono C#) Create XML Digital Signature using a DSA Key(PowerShell) Create XML Digital Signature using a DSA Key(.NET Core C#) Create XML Digital Signature using a ECDSA Key(C#) Create XML Digital Signature using a ECDSA Key(Mono C#) Create XML Digital Signature using a ECDSA Key(PowerShell) Create XML Digital Signature using a ECDSA Key
top
SetRefIdAttr
public bool SetRefIdAttr(string uri_or_id, string value);
Introduced in version 9.5.0.75

Sets the "Id" attribute for a Reference.

Returns true for success, false for failure.

More Information and Examples
(.NET Core C#) Create JPK_VAT XaDES-BES Signed XML(C#) Create JPK_VAT XaDES-BES Signed XML(Mono C#) Create JPK_VAT XaDES-BES Signed XML(PowerShell) Create JPK_VAT XaDES-BES Signed XML
top
SetTsa
public bool SetTsa(JsonObject json);
Introduced in version 9.5.0.90

Sets the TSA (Timestamp Authority) URL and other related settings for automatically adding an EncapsulatedTimestamp.

Returns true for success, false for failure.

More Information and Examples
(.NET Core C#) XML-DSig Add EncapsulatedTimestamp when Signing(C#) XML-DSig Add EncapsulatedTimestamp when Signing(Mono C#) XML-DSig Add EncapsulatedTimestamp when Signing(PowerShell) XML-DSig Add EncapsulatedTimestamp when Signing
top
SetX509Cert
public bool SetX509Cert(Cert cert, bool usePrivateKey);
Introduced in version 9.5.0.69

Specifies the X.509 certificate to be used for the KeyInfo element when the KeyInfoType equals "X509Data". If usePrivateKey is true, then the private key will also be set using the certificate's private key. Thus, the SetPrivateKey method does not need to be called. If usePrivateKey is true, and the certificate does not have an associated private key available, then this method will return false.

Note: A certificate's private key is not stored within a certificate itself. If the certificate (cert) was obtained from a PFX, Java KeyStore, or other such source, which are containers for both certs and private keys, then Chilkat would have associated the cert with the private key when loading the PFX or JKS, and all is good. The same holds true if, on a Windows system, the certificate was obtained from a Windows-based registry certificate store where the private key was installed with the permission to export.

If, however, the certificate was loaded from a .cer file, or another type of file that contains only the certificate and not the private key, then the associated private key needs to be obtained by the application and provided by calling SetPrivateKey.

Returns true for success, false for failure.

More Information and Examples
More information about .pfx, .cer, .pem
top

Events

AbortCheck
public event AbortCheckEventHandler OnAbortCheck;

Provides the opportunity for a method call to be aborted. The AbortCheck event is fired periodically based on the value of the HeartbeatMs property. If HeartbeatMs is 0, then no AbortCheck events will fire. As an example, to fire 5 AbortCheck events per second, set the HeartbeatMs property equal to 200.

Chilkat .NET Event Implementation

Args are passed using Chilkat.AbortCheckEventArgs

Event callback implementation:

private void xmldsiggen_OnAbortCheck(object sender, Chilkat.AbortCheckEventArgs args)
	{
	    // application code goes here.
	}

To add an event handler:

Chilkat.XmlDSigGen xmldsiggen = new Chilkat.XmlDSigGen();
xmldsiggen.OnAbortCheck += xmldsiggen_OnAbortCheck;

Chilkat Mono/.NET Core Event Implementation

Event callback implementation:

public void handleAbortCheck(out bool abort)
	{
	    // application code goes here.
	}

To add an event handler:

Chilkat.XmlDSigGen xmldsiggen = new Chilkat.XmlDSigGen();
// ...
Chilkat.XmlDSigGen.AbortCheck abortCheck = new Chilkat.XmlDSigGen.AbortCheck(handleAbortCheck);
xmldsiggen.setAbortCheckCb(abortCheck);
top
PercentDone
public event PercentDoneEventHandler OnPercentDone;

Provides the percentage completed for any method that involves network communications or time-consuming processing (assuming it is a method where a percentage completion can be measured). This event is only fired when it is possible to know a percentage completion, and when it makes sense to express the operation as a percentage completed. The pctDone argument will have a value from 1 to 100. For operations (Chilkat method calls) that complete very quickly, the number of PercentDone callbacks will vary, but the final callback should have a value of 100. For long running operations, no more than one callback per percentage point will occur (for example: 1, 2, 3, ... 98, 99, 100).

The PercentDone callback counts as an AbortCheck event. For method calls that complete quickly such that PercentDone events fire, it may be that AbortCheck events don't fire because the opportunity to abort is already provided in the PercentDone callback. For time consuming operations, where the amount of time between PercentDone callbacks are long, AbortCheck callbacks may be used to allow for the operation to be aborted in a more responsive manner.

The abort output argument provides a means for aborting the operation. Setting it to true will cause the method to abort and return a failed status (or whatever return value indicates failure).

Chilkat .NET Event Implementation

Args are passed using Chilkat.PercentDoneEventArgs

Event callback implementation:

private void xmldsiggen_OnPercentDone(object sender, Chilkat.PercentDoneEventArgs args)
	{
	    // application code goes here.
	}

To add an event handler:

Chilkat.XmlDSigGen xmldsiggen = new Chilkat.XmlDSigGen();
xmldsiggen.OnPercentDone += xmldsiggen_OnPercentDone;

Chilkat Mono/.NET Core Event Implementation

Event callback implementation:

public void handlePercentDone(int pctDone, out bool abort)
	{
	    // application code goes here.
	}

To add an event handler:

Chilkat.XmlDSigGen xmldsiggen = new Chilkat.XmlDSigGen();
// ...
Chilkat.XmlDSigGen.PercentDone percentDone = new Chilkat.XmlDSigGen.PercentDone(handlePercentDone);
xmldsiggen.setPercentDoneCb(percentDone);
top
ProgressInfo
public event ProgressInfoEventHandler OnProgressInfo;

A general name/value event that provides information about what is happening during a method call. To find out what information is available, write code to handle this event and log the name/value pairs. Most are self-explanatory.

Chilkat .NET Event Implementation

Args are passed using Chilkat.ProgressInfoEventArgs

Event callback implementation:

private void xmldsiggen_OnProgressInfo(object sender, Chilkat.ProgressInfoEventArgs args)
	{
	    // application code goes here.
	}

To add an event handler:

Chilkat.XmlDSigGen xmldsiggen = new Chilkat.XmlDSigGen();
xmldsiggen.OnProgressInfo += xmldsiggen_OnProgressInfo;

Chilkat Mono/.NET Core Event Implementation

Event callback implementation:

public void handleProgressInfo(string name, string value)
	{
	    // application code goes here.
	}

To add an event handler:

Chilkat.XmlDSigGen xmldsiggen = new Chilkat.XmlDSigGen();
// ...
Chilkat.XmlDSigGen.ProgressInfo progressInfo = new Chilkat.XmlDSigGen.ProgressInfo(handleProgressInfo);
xmldsiggen.setProgressInfoCb(progressInfo);
top
TaskCompleted
public event TaskCompletedEventHandler OnTaskCompleted;

Called in the background thread when an asynchronous task completes.

More Information and Examples
C# .NET Framework TaskCompleted Event Callback ExampleC# .NET Core TaskCompleted Event Callback Example

Chilkat .NET Event Implementation

Args are passed using Chilkat.TaskCompletedEventArgs

Event callback implementation:

private void xmldsiggen_OnTaskCompleted(object sender, Chilkat.TaskCompletedEventArgs args)
	{
	    // application code goes here.
	}

To add an event handler:

Chilkat.XmlDSigGen xmldsiggen = new Chilkat.XmlDSigGen();
xmldsiggen.OnTaskCompleted += xmldsiggen_OnTaskCompleted;

Chilkat Mono/.NET Core Event Implementation

Event callback implementation:

public void handleTaskIdCompleted(int taskId)
	{
	    // application code goes here.
	}

To add an event handler:

Chilkat.XmlDSigGen xmldsiggen = new Chilkat.XmlDSigGen();
// ...
Chilkat.XmlDSigGen.TaskIdCompleted taskIdCompleted = new Chilkat.XmlDSigGen.TaskIdCompleted(handleTaskIdCompleted);
xmldsiggen.setTaskIdCompletedCb(taskIdCompleted);
top