XmlDSigGen Chilkat2 PHP 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

use Chilkat2\XmlDSigGen;

try {
    $xmlDSigGen = new XmlDSigGen();
    // ... use $xmlDSigGen ...
} catch (\Chilkat2\Exception $e) {
    echo $e->getClass(), '::', $e->getMethod(), " failed\n";
    echo $e->getMessage(), "\n";              // the LastErrorText of the failed call
}

public function __construct(array $properties = [])

Creates the object. The optional array sets properties in order, as if assigned one by one (new XmlDSigGen(['VerboseLogging' => true, 'RaiseError' => false])); an unknown or read-only name throws Error. The class is defined by the chilkat2 extension (extension=chilkat2 in php.ini): there is no PHP file to include.

There is no close(): PHP frees the object when its last reference goes (unset($xmlDSigGen), $xmlDSigGen = null, or the end of the function or request). Objects returned by methods are independent and freed the same way. The class may be extended (class MyXmlDSigGen extends \Chilkat2\XmlDSigGen); objects cannot be cloned or serialized.

public bool $RaiseError;

When true (the default), a method that fails throws Chilkat2\Exception. When false, it returns false (or null) instead, and the reason is in LastErrorText. Objects returned by a method inherit the value of the object that returned them.

Errors

Chilkat2\Exception extends RuntimeException: getMessage() is the failed call's full LastErrorText, getClass() its class ('Chilkat2\XmlDSigGen') and getMethod() the method name. The object remains usable. Methods that look something up and find nothing return null without throwing (each such method says so), methods that answer a question (HasMember, IsUnlocked, ...) return a plain bool, and property reads and writes do not throw for Chilkat reasons.

Misuse always throws, whatever RaiseError is: a wrong argument type is a TypeError (exact types under declare(strict_types=1)), a missing or extra argument an ArgumentCountError, a string containing a NUL byte or an out-of-range integer a ValueError, and an unknown property (properties are case-sensitive) or a write to a read-only one an Error. Named arguments work with the parameter names shown.

Strings are passed and returned as UTF-8; binary data is a PHP string of bytes. Unlocking: call (new \Chilkat2\GlobalSettings())->UnlockBundle('...') once at startup.

Properties

Behaviors

public string $Behaviors;

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 PHP 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