XmlDSigGen Chilkat2 Java Reference Documentation

XmlDSigGen

Current Version: 11.7.0

Markdown version of this page for AI tools (v 11.7.0) · all AI docs

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

import com.chilkatsoft.chilkat2.ChilkatException;
import com.chilkatsoft.chilkat2.XmlDSigGen;

try (XmlDSigGen xmlDSigGen = new XmlDSigGen()) {
    // ... use xmlDSigGen ...
} catch (ChilkatException e) {
    System.out.println(e.getMessage());          // "XmlDSigGen.someMethod failed: <reason>"
    System.out.println(e.getLastErrorText());    // the full log of the failed call
}

public XmlDSigGen()

Creates the underlying native Chilkat object. The native library (chilkat2java) is loaded the first time any Chilkat2 object is created; see the README in the download for where it is looked for (-Dchilkat2.library.path, a classpath resource, or java.library.path).

public void close()

Releases the native object (XmlDSigGen is AutoCloseable, so try-with-resources calls it). Calling it again does nothing; any other method or property accessor called afterwards throws IllegalStateException. An object that is never closed is freed by a background cleaner once it becomes unreachable, but the garbage collector does not see native memory, so closing is the normal path. Objects returned by methods are owned by the caller too.

public boolean isClosed()

Returns true once close() has been called.

Errors

A method that fails throws ChilkatException, an unchecked exception carrying getClassName(), getMethodName(), getReason() (one line, also in the message) and getLastErrorText() (the full log, captured at the moment of the failure). The object remains usable. Methods that look something up and find nothing return null instead of throwing (each such method says so), and methods that answer a question (hasMember, isUnlocked, ...) return a plain boolean. Property accessors do not throw for Chilkat reasons.

A null string or object argument throws NullPointerException naming the parameter (except where a method documents that null is accepted), and a string containing U+0000 throws IllegalArgumentException.

Use an object from one thread at a time; it may be handed from one thread to another. The one cross-thread operation is setting setAbortCurrent(true) on an object that is busy in another thread (on the classes that have AbortCurrent). Unlocking: call new Global().unlockBundle("...") once at startup.

Properties

Behaviors

// read/write
String getBehaviors()
void setBehaviors(String value)

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 Chilkat2 Java Reference Documentation

XmlDSigGen

Current Version: 11.7.0

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

CreateXmlDSigSb

SetHmacKey

SetHttpObj

SetPrivateKey

SetRefIdAttr

SetTsa

SetX509Cert

Events

AbortCheck

PercentDone

ProgressInfo