XmlDSigGen Zig 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

// Add the package once:
//     zig fetch --save https://chilkatdownload.com/11.6.1/chilkat-zig-11.6.1.tar.gz
// and in build.zig:
//     const chilkat = b.dependency("chilkat", .{ .target = target, .optimize = optimize });
//     exe.root_module.addImport("chilkat", chilkat.module("chilkat"));
const chilkat = @import("chilkat");

// Once per process, before any other Chilkat call:
try chilkat.unlockBundle("Anything for 30-day trial");

const xml_d_sig_gen = try chilkat.XmlDSigGen.init();
defer xml_d_sig_gen.deinit();

pub fn init() Allocator.Error!XmlDSigGen

Creates the underlying native Chilkat object. XmlDSigGen is a one-pointer struct passed by value; copying it copies the handle (two names for one object). Returns error.OutOfMemory if the library could not allocate the object. Use an object from one thread at a time; it may be handed from one thread to another.

pub fn deinit(self: XmlDSigGen) void

Releases the native object. Call it exactly once per object (usually with defer); the handle is invalid afterwards. Objects returned by methods are owned by the caller too and are released the same way.

pub fn fromHandle(h: *chilkat.c.CkXmlDSigGen.HCkXmlDSigGen) XmlDSigGen

Wraps a handle obtained from the C API (chilkat.c.CkXmlDSigGen), taking ownership of it. The struct's handle field goes the other way, for anything the Zig API does not cover.

Errors and memory

Methods that can fail return an error union: a method whose only outcome is success or failure returns Error!void; a method producing a string returns (Error || Allocator.Error)![:0]u8; a method producing an object returns Error!T. chilkat.Error is error{ChilkatFailed}; the reason for a failure is in getLastErrorText, and the object remains usable. Properties never fail, and methods that answer a question (hasMember, isUnlocked, ...) return a plain bool.

String arguments are [:0]const u8 (UTF-8; string literals can be passed as is). String results are copies allocated with the allocator argument and owned by the caller, so they stay valid across later calls on the same object.

const text = xml_d_sig_gen.someMethod(allocator, ...) catch |err| {
    const why = try xml_d_sig_gen.getLastErrorText(allocator);
    defer allocator.free(why);
    std.debug.print("{s}\n", .{why});
    return err;
};
defer allocator.free(text);

Properties

Behaviors

// read/write
pub fn getBehaviors(self: XmlDSigGen, allocator: Allocator) Allocator.Error![:0]u8
pub fn setBehaviors(self: XmlDSigGen, value: [:0]const u8) void

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 Zig 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 and memory

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