XmlDSigGen React Native Reference Documentation

XmlDSigGen

Current Version: 11.6.1

Chilkat.XmlDSigGen

Create XML Digital Signatures with precise control over references, transforms, keys, and placement.

Chilkat.XmlDSigGen creates XML Digital Signatures for same-document XML, external XML, text, binary, file, and Object-based references. It supports enveloped, enveloping, and detached-style signing workflows; X.509 certificate KeyInfo; custom KeyInfo XML; RSA, DSA, and ECDSA private keys; HMAC signatures; canonicalization options; reference transforms; signature insertion placement; timestamp authority settings; and compatibility options for systems with strict or unusual XML signature requirements.

Same-document signatures

Sign XML already present in the document, including enveloped signatures where the signature is inserted into the signed XML.

External references

Add references to external XML, text, binary data, files, or custom application-provided content.

Object and enveloping signatures

Build signatures that include signed data inside XML Object elements or produce enveloping signature structures.

Keys and KeyInfo

Sign with private keys or HMAC secrets and include certificate-based, public-key, or fully custom KeyInfo XML.

Canonicalization and transforms

Configure canonicalization, digest algorithms, signature algorithms, and reference transforms required by the receiving system.

Placement and compatibility

Control where the signature is inserted and enable compatibility behaviors for XML signature profiles with special formatting rules.

Common pattern: Configure the signature algorithm, canonicalization method, signing key or certificate, and KeyInfo style; add one or more references with the required transforms and digest methods; choose where the signature should be placed; then generate the signed XML. Use Chilkat.XmlDSigGen to create signatures and Chilkat.XmlDSig to inspect or verify them.

For an extended overview, see XmlDSigGen Class Overview.

Object Creation

// npm install @chilkat/react-native react-native-nitro-modules
// (React Native 0.76+ with the New Architecture; then `pod install` for iOS.  The Chilkat
//  native library is downloaded and verified during the native build -- see the package README.)

import { Chilkat, XmlDSigGen } from '@chilkat/react-native'

// Once per app start, before any other Chilkat call:
Chilkat.unlockBundle('Anything for 30-day trial')   // shorthand for new Global().unlockBundle(..)

const xmlDSigGen = new XmlDSigGen()
// ... the native object is released when `xmlDSigGen` is garbage collected, or now with xmlDSigGen.dispose()

new XmlDSigGen()

Creates the underlying native Chilkat object. XmlDSigGen is a Nitro Module HybridObject: use it from the JavaScript thread only (it cannot be passed to a Worklet or another runtime). Every member is synchronous and blocks the JavaScript thread until Chilkat returns; a method that can take a while also exists as a ...Async twin returning a Promise, which runs the same call on a native worker thread so the UI keeps rendering. While such a call is pending, every other call on this object throws, except abort() and assigning onPercentDone / onProgressInfo.

dispose(): void

Releases the native object immediately instead of waiting for garbage collection (useful for a large BinData or an open socket). Calling it more than once is harmless; any other use of the object afterwards throws. An object with a pending ...Async call cannot be disposed until the promise settles.

Errors

A method that can fail throws a plain Error: a method whose only outcome is success or failure returns void and throws on failure; a method producing a string or an object returns it and throws where Chilkat would have returned null. The error's message is "Class.method(...): reason", where the reason is the last informative line of the object's lastErrorText, which holds the full Chilkat log of the failed call. A ...Async twin rejects its promise with the same Error instead of throwing. Properties never throw, and methods that answer a question (has..., is..., ...) return a plain boolean.

try {
  xmlDSigGen.someMethod(...)
} catch (e) {
  console.log((e as Error).message)   // XmlDSigGen.someMethod(...): <reason>
  console.log(xmlDSigGen.lastErrorText)   // the full Chilkat log of the failed call
}

// The same call without blocking the JavaScript thread:
try {
  await xmlDSigGen.someMethodAsync(...)
} catch (e) {
  console.log((e as Error).message)   // XmlDSigGen.someMethodAsync: <reason>
}

Properties

Behaviors

// read/write
behaviors: string

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.

XmlDSigGen React Native Reference Documentation

XmlDSigGen

Current Version: 11.6.1

Create XML Digital Signatures with precise control over references, transforms, keys, and placement.

Same-document signatures

External references

Object and enveloping signatures

Keys and KeyInfo

Canonicalization and transforms

Placement and compatibility

Object Creation

Errors

Properties

Behaviors

CustomKeyInfoXml

DebugLogFilePath

IncNamespacePrefix

IncNamespaceUri

KeyInfoId

KeyInfoKeyName

KeyInfoType

LastErrorHtml

LastErrorText

LastErrorXml

LastMethodSuccess

SigId

SigLocation

SigLocationIdx

SigLocationMod

SigNamespacePrefix

SigNamespaceUri

SignedInfoCanonAlg

SignedInfoDigestMethod

SignedInfoId

SignedInfoPrefixList

SigningAlg

SigValueId

UncommonOptions

VerboseLogging

Version

X509Type

Methods

AddEnvelopedRef

AddExternalBinaryRef

AddExternalFileRef

AddExternalTextRef

AddExternalXmlRef

AddObject

AddObjectRef

AddObjectRef2

AddSameDocRef

AddSameDocRef2

AddSignatureNamespace

ConstructSignedInfo

CreateXmlDSig

CreateXmlDSigAsync

CreateXmlDSigSb

CreateXmlDSigSbAsync

SetHmacKey

SetHttpObj

SetPrivateKey

SetRefIdAttr

SetTsa

SetX509Cert

Events

PercentDone

ProgressInfo