TChilkatDkim

Set to 1 to request cancellation of a currently running operation. A synchronous operation can be cancelled from another thread by setting this property on the same object. Methods that complete quickly or do not periodically check for cancellation may finish before the request is observed.

If set to a file path, this property logs the LastErrorText of each Chilkat method or property call to the specified file. This logging helps identify the context and history of Chilkat calls leading up to any crash or hang, aiding in debugging.

Enabling the VerboseLogging property provides more detailed information. This property is mainly used for debugging rare instances where a Chilkat method call causes a hang or crash, which should generally not happen.

Possible causes of hangs include:

• A timeout property set to 0, indicating an infinite timeout.
• A hang occurring within an event callback in the application code.
• An internal bug in the Chilkat code causing the hang.

Specifies the signing algorithm written to the a= tag of a newly created DKIM-Signature header. The default is rsa-sha256.

The value is trimmed and compared case-insensitively. The recognized values are rsa-sha256 and rsa-sha1. An empty or unrecognized value is normalized to rsa-sha256 rather than rejected.

Controls the maximum number of bytes from the canonicalized message body used when computing the DKIM body hash. The default is 0.

When a generated signature contains l=, verification hashes only the indicated prefix of the canonicalized body. Content appended after that signed prefix does not invalidate the signature.

Specifies one DKIM canonicalization algorithm to use for both the signed header fields and the message body. The default is relaxed.

The value is trimmed and compared case-insensitively. This property does not accept a header/body pair such as relaxed/simple or simple/relaxed. Pair values, an empty string, and other unrecognized values are normalized to relaxed rather than rejected.

Specifies the signing domain written verbatim to the d= tag of the generated DKIM-Signature header. The corresponding public key is normally published beneath the DNS name formed from DkimSelector and this domain.

Set this property to a nonempty, syntactically valid domain before calling DkimSign. If this property is empty, DkimSign returns 0 without modifying the MIME data. A nonempty value is not otherwise validated or normalized during signing; uppercase letters, surrounding whitespace, a trailing dot, and Unicode characters are emitted as supplied.

A colon-separated list of header field names to include in the DKIM signature. The list is written to the signature's h= tag in the same order. The default is:

mime-version:date:message-id:subject:from:to:content-type

Header-name matching is case-insensitive. For each occurrence of a name in this list, Chilkat selects the next matching header field from the bottom of the message header block upward, as required by DKIM. For example, if the message contains two Subject fields, listing subject once signs the bottommost field, while listing it twice signs both fields.

If a listed occurrence has no corresponding field in the message, the absent field is still included in the signing calculation. Repeating a name more times than it occurs can therefore implement DKIM oversigning and prevent a matching field from being inserted later without invalidating the signature.

• Use colon-separated field names without surrounding spaces.
• Include from; DKIM requires the From field to be signed, but DkimSign does not enforce this requirement or add it automatically.
• An empty list and names of missing fields are accepted rather than rejected.
• Avoid transport-added or frequently modified fields such as Received and Return-Path.

Specifies the selector written verbatim to the s= tag of a generated DKIM signature. The selector and DkimDomain form the DNS name used to locate the public key:

selector._domainkey.signing-domain

Supply only the selector. Do not include ._domainkey. or the signing domain. If this property is empty, DkimSign returns 0 without modifying the MIME data. A nonempty value is not otherwise validated or normalized during signing; for example, a complete DNS name is emitted as supplied rather than reduced to a selector.

Specifies the interval, in milliseconds, between AbortCheck callbacks during methods that support periodic cancellation checks. Set to 0 to disable these callbacks. The default is 0.

PrefetchPublicKey invokes AbortCheck while performing its DNS lookup. Setting this property to 1 and requesting cancellation from the first callback causes PrefetchPublicKey to return 0.

This property is mainly used in SQL Server stored procedures to retrieve binary data from the last method call that returned binary data. It is only accessible if Chilkat.Global.KeepBinaryResult is set to 1. This feature allows for the retrieval of large varbinary results in an SQL Server environment, which has restrictions on returning large data via method calls, though temp tables can handle binary properties.

Provides HTML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.

Provides plain text information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.

Provides XML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.

Indicates the success or failure of the most recent method call: 1 means success, 0 means failure. This property remains unchanged by property setters or getters. This method is present to address challenges in checking for null or Nothing returns in certain programming languages. Note: This property does not apply to methods that return integer values or to boolean-returning methods where the boolean does not indicate success or failure.

In SQL Server stored procedures, this property holds the string return value of the most recent method call that returns a string. It is accessible only when Chilkat.Global.KeepStringResult is set to TRUE. SQL Server has limitations on string lengths returned from methods and properties, but temp tables can be used to access large strings.

The length, in characters, of the string contained in the LastStringResult property.

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

Contains JSON describing the most recent call to DkimVerify. The property is initially an empty string and is replaced or cleared by each verification attempt.

{
  "domain": "chilkatsoft.com",
  "selector": "brisbane",
  "canonicalization": "relaxed/relaxed",
  "algorithm": "rsa-sha256",
  "signedHeaders": "from:to:subject:date:message-id",
  "fromSigned": "yes",
  "expectedBodyHash": "...",
  "computedBodyHash": "...",
  "bodyHashVerified": "yes",
  "verified": "yes"
}

Not every member is present in every result. For malformed signatures, unsupported algorithms, missing signatures, DNS failures, or an out-of-range index, the value may be an empty string, {}, or a partial object without verified. Therefore, first check the return value of DkimVerify, and then treat individual JSON members as optional.

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

Creates a DKIM-Signature header and prepends it to the complete MIME message stored in mimeData. The BinData is modified in place.

Before calling this method:

• Construct the final MIME message, including all headers, transfer encodings, MIME boundaries, and body bytes.
• Use RFC 5322 line endings. The MIME header and body must use CRLF and be separated by . LF-only and CR-only MIME are not normalized and cause the method to fail.
• Set DkimDomain, DkimSelector, DkimAlg, DkimCanon, and DkimHeaders.
• Load the RSA private key by calling SetDkimPrivateKey.

On success, the generated header contains v=1, a=, c=, q=dns/txt, d=, s=, h=, bh=, and b=. When DkimBodyLengthCount is nonzero, the header also contains l=. The generated header does not include t=, x=, or i=. Signing the same bytes twice with the same settings and key produced identical output.

An empty body, a body without a final newline, and body data containing NUL or other binary bytes are accepted. An empty DkimDomain, an empty DkimSelector, missing or invalid private-key state, or malformed MIME causes the method to return 0 without changing mimeData.

Returns 1 for success, 0 for failure.

Verifies the DKIM-Signature header at zero-based sigIndex in the complete MIME message stored in mimeData. Signatures are indexed in top-to-bottom header order. Use NumDkimSigs to obtain the count.

Chilkat first looks for a public key cached under the exact selector/domain strings. If no exact match exists, it synchronously retrieves the TXT record at selector._domainkey.domain. The method does not modify mimeData.

Verification compares the signature's bh= value with the hash computed from the canonicalized body. When the signature contains l=, only the indicated number of canonicalized body bytes are included, so content appended after the signed prefix does not cause a body-hash failure.

After the call, inspect VerifyInfo. A completed verification failure normally contains "verified":"no". A body-hash mismatch also contains "bodyHashVerified":"no" with the expected and computed hashes. Operational and parsing failures may leave an empty string, {}, or a partial JSON object; use LastErrorText for the detailed reason.

Returns 1 for success, 0 for failure.

Loads and caches an RSA public key in this Dkim object for the exact selector and domain strings. A later DkimVerify uses the cached key when the signature contains the same selector and domain; otherwise verification falls back to DNS.

publicKey contains a textual key representation. Supported formats include:

• PEM X.509 SubjectPublicKeyInfo (-----BEGIN PUBLIC KEY-----)
• PEM PKCS#1 RSA public key (-----BEGIN RSA PUBLIC KEY-----)
• XML RSA key data
• RSA JWK JSON

The selector/domain cache key is case-sensitive. Loading a key for uppercase values does not satisfy a lowercase signature. A successful later load for the same pair replaces the earlier key. If a later load fails because the supplied key text is invalid, the previously cached key remains available.

Returns 1 for success, 0 for failure.

Loads an RSA public key from the local file at publicKeyFilepath and caches it in this Dkim object for the exact selector and domain strings. The file is read during this call.

Supported formats include PEM X.509 SubjectPublicKeyInfo, PEM PKCS#1 RSA public key, binary DER PKCS#1 RSA public key, XML RSA key data, and RSA JWK JSON. The selector/domain cache key is case-sensitive.

A later successful load for the same selector/domain pair replaces the earlier cached key. If no exact cached key is present when DkimVerify runs, Chilkat performs its normal DNS lookup.

Returns 1 for success, 0 for failure.

Loads the original caller object associated with the asynchronous task. This is an internal support method used by Chilkat's asynchronous task infrastructure and is not normally needed in application code.

Returns 1 for success, 0 for failure.

Returns the number of header fields named DKIM-Signature in mimeData. Header-name matching is case-insensitive. The method counts matching fields without validating the signature syntax; for example, a malformed DKIM-Signature: nonsense field is still counted.

The indexes used by DkimVerify are zero-based and follow top-to-bottom header order. The method returns 0 when no matching header is found, including for an empty message. It does not modify mimeData.

Retrieves the DKIM public key from DNS and caches it in this Dkim object for the exact selector and domain strings. The TXT lookup is made for:

selector._domainkey.domain

The method returns 1 when the DNS lookup and public-key loading succeed. Repeated calls for a cached pair can complete without another observable lookup. A successful prefetch replaces an existing manually loaded key for the same selector/domain pair.

DkimVerify also performs this DNS lookup automatically when no exact cached key is available. Prefetching is useful when several messages will be verified for the same selector and domain.

Returns 1 for success, 0 for failure.

Creates an asynchronous task to call the PrefetchPublicKey method with the arguments provided.

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 nil on failure

Copies the RSA key from privateKey into this object for subsequent calls to DkimSign. The source PrivateKey object may be destroyed after this method returns successfully, and the configured key can be reused for multiple signatures.

A later successful call replaces the previously configured signing key. A failed call with an empty or unrecognized key clears the usable signing-key state; a subsequent DkimSign fails until a valid key is set again.

Returns 1 for success, 0 for failure.

Enables a method call to be aborted by triggering the AbortCheck event at intervals defined by the HeartbeatMs property. If HeartbeatMs is set to its default value of 0, no events will occur. For instance, set HeartbeatMs to 200 to trigger 5 AbortCheck events per second.

Delphi ActiveX Event callback implementation:

procedure TForm1.dkimAbortCheck(ASender: TObject;  out abort: Integer);
begin
    // Application code goes here...
end;


procedure TForm1.Button1Click(Sender: TObject);
var
  dkim: TChilkatDkim;

begin
  dkim := TChilkatDkim.Create(Self);
  dkim.OnAbortCheck := dkimAbortCheck;
  // ...

This provides the percentage completion for any method involving network communications or time-consuming processing, assuming the progress can be measured as a percentage. This event is triggered only when it's possible and logical to express the operation's progress as a percentage. The pctDone argument will range from 1 to 100. For methods that finish quickly, the number of PercentDone callbacks may vary, but the final callback will have pctDone equal to 100. For longer operations, callbacks will not exceed one per percentage point (e.g., 1, 2, 3, ..., 98, 99, 100).

The PercentDone callback also acts as an AbortCheck event. For fast methods where PercentDone fires, an AbortCheck event may not trigger since the PercentDone callback already provides an opportunity to abort. For longer operations, where time between PercentDone callbacks is extended, AbortCheck callbacks enable more responsive operation termination.

To abort the operation, set the abort output argument to 1. This will cause the method to terminate and return a failure status or corresponding failure value.

Delphi ActiveX Event callback implementation:

procedure TForm1.dkimPercentDone(ASender: TObject;  pctDone: Integer; out abort: Integer);
begin
    // Application code goes here...
end;


procedure TForm1.Button1Click(Sender: TObject);
var
  dkim: TChilkatDkim;

begin
  dkim := TChilkatDkim.Create(Self);
  dkim.OnPercentDone := dkimPercentDone;
  // ...

This event callback provides tag name/value pairs that detail what occurs during a method call. To discover existing tag names, create code to handle the event, emit the pairs, and review them. Most tag names are self-explanatory.

Note: Some Chilkat methods don't fire any ProgressInfo events.

Delphi ActiveX Event callback implementation:

procedure TForm1.dkimProgressInfo(ASender: TObject;  const name: WideString; const value: WideString);
begin
    // Application code goes here...
end;


procedure TForm1.Button1Click(Sender: TObject);
var
  dkim: TChilkatDkim;

begin
  dkim := TChilkatDkim.Create(Self);
  dkim.OnProgressInfo := dkimProgressInfo;
  // ...

Called from the background thread when an asynchronous task completes.

Delphi ActiveX Event callback implementation:

procedure TForm1.dkimTaskCompleted(ASender: TObject;  const task: IChilkatTask);
begin
    // Application code goes here...
end;


procedure TForm1.Button1Click(Sender: TObject);
var
  dkim: TChilkatDkim;

begin
  dkim := TChilkatDkim.Create(Self);
  dkim.OnTaskCompleted := dkimTaskCompleted;
  // ...

Specifies the algorithm used when creating a legacy DomainKey-Signature header. The only supported value, and the default, is rsa-sha1.

Specifies the canonicalization algorithm used when creating a legacy DomainKey-Signature header. The default is nofws.

Specifies the signing domain written to a legacy DomainKey-Signature header. Together with DomainKeySelector, it identifies the DNS location of the DomainKeys public key.

A colon-separated list of header field names to include in a legacy DomainKeys signature. The default is:

mime-version:date:message-id:subject:from:to:content-type

Specifies the selector used to locate the public key for a legacy DomainKeys signature. The DNS name is formed as:

selector._domainkey.signing-domain

Creates a legacy DomainKey-Signature header and prepends it to the MIME message stored in mimeData. The BinData is modified in place.

Before calling this method, set DomainKeyDomain and DomainKeySelector, and load the matching private key by calling SetDomainKeyPrivateKey.

Returns 1 for success, 0 for failure.

Verifies the legacy DomainKeys signature at zero-based index sigIndex in the MIME message stored in mimeData. Use NumDomainKeySigs to determine how many DomainKey-Signature headers are present.

After the call, inspect VerifyInfo for details about the signature and verification result.

Returns 1 for success, 0 for failure.

Returns the number of legacy DomainKey-Signature header fields found in the MIME message stored in mimeData. Signature indexes passed to DomainKeyVerify are zero-based and range from 0 through one less than this count.

Associates the RSA privateKey with this object for subsequent calls to DomainKeySign.

Returns 1 for success, 0 for failure.