Chilkat.Dkim Class Overview

Chilkat.Dkim signs and verifies email MIME data using DKIM and DomainKey signatures. It can prepend DKIM-Signature or DomainKey-Signature headers, verify existing signatures, count signatures in MIME data, cache or prefetch public keys, and provide detailed verification information as JSON.

What the Class Is Used For

Use Chilkat.Dkim when an application needs to add DKIM signatures to outbound email or verify DKIM / DomainKey signatures on inbound MIME messages. The class works directly with MIME data held in BinData, uses RSA private keys for signing, and retrieves or caches RSA public keys for verification.

Sign Email with DKIM Configure the signing domain, selector, headers, canonicalization, algorithm, and private key, then call DkimSign.
Verify DKIM Signatures Count and verify DKIM-Signature headers and inspect VerifyInfo for details.
Support DomainKey Create and verify DomainKey-Signature headers using DomainKey-specific settings.
Cache Public Keys Load test public keys manually or prefetch public keys for repeated verification of messages from the same selector/domain.

Typical DKIM Signing Workflow

  1. Create a Dkim object.
  2. Load or create the email MIME content in a BinData object.
  3. Set DkimDomain to the signing domain.
  4. Set DkimSelector to the selector used for the DNS public-key lookup.
  5. Optionally configure DkimAlg, DkimCanon, DkimHeaders, and DkimBodyLengthCount.
  6. Call SetDkimPrivateKey with the RSA private key.
  7. Call DkimSign. Chilkat constructs and prepends the DKIM-Signature header to the MIME data.
  8. Check LastErrorText after failures or unexpected behavior.

Typical DKIM Verification Workflow

  1. Load the email MIME content into a BinData object.
  2. Call NumDkimSigs to determine how many DKIM-Signature headers are present.
  3. Optionally call PrefetchPublicKey, LoadPublicKey, or LoadPublicKeyFile when public keys should be cached instead of fetched during verification.
  4. Call DkimVerify for the signature index to verify. The first signature is index 0.
  5. Inspect VerifyInfo for JSON details such as domain, selector, algorithm, canonicalization, signed headers, public key, and verified status.
  6. Check LastErrorText if verification fails or behaves unexpectedly.

Core Concepts

Concept Meaning Important Members
DKIM Signature A DKIM-Signature header prepended to MIME data to prove that selected headers and body bytes were signed by the domain’s private key. DkimSign, DkimVerify, NumDkimSigs
DomainKey Signature A DomainKey-Signature header created and verified with DomainKey-specific settings. DomainKeySign, DomainKeyVerify, NumDomainKeySigs
Selector A DNS selector used with the signing domain to locate the public key. For example, selector reykjavik and domain example-code.com form the lookup name reykjavik._domainkey.example-code.com. DkimSelector, DomainKeySelector, PrefetchPublicKey
Signing Domain The domain that signs the message and publishes the public key used for verification. DkimDomain, DomainKeyDomain
Canonicalization Rules for normalizing headers and body before signing or verifying. DkimCanon, DomainKeyCanon
Public-Key Cache A cached public key for a selector/domain pair, used to avoid DNS lookup or to test before the public key is installed in DNS. LoadPublicKey, LoadPublicKeyFile, PrefetchPublicKey

DKIM Signing Properties

Property Purpose Default / Guidance
DkimDomain Signing domain used when creating the DKIM-Signature. Must be set before calling DkimSign.
DkimSelector Selector used to form the DNS public-key query. Must be set before calling DkimSign.
DkimAlg Signing algorithm for DKIM. Possible values are rsa-sha256 and rsa-sha1. Default is rsa-sha256.
DkimCanon Canonicalization algorithm used for both header and body when creating the DKIM signature. Possible values are simple and relaxed. Default is relaxed.
DkimHeaders Colon-separated list of header fields included in the DKIM signing algorithm. Default is mime-version:date:message-id:subject:from:to:content-type.
DkimBodyLengthCount Optional maximum number of body bytes to hash when creating the signature. Default is 0, meaning the entire body is hashed.

DomainKey Signing Properties

Property Purpose Default / Guidance
DomainKeyDomain Signing domain used when creating the DomainKey-Signature. Must be set before calling DomainKeySign.
DomainKeySelector Selector used to form the DNS public-key query. Must be set before calling DomainKeySign.
DomainKeyAlg Signing algorithm for DomainKey. Only possible value is rsa-sha1. Default is rsa-sha1.
DomainKeyCanon Canonicalization algorithm used when creating the DomainKey-Signature. Possible values are simple and nofws. Default is nofws.
DomainKeyHeaders Colon-separated list of header fields included in the DomainKey signing algorithm. Default is mime-version:date:message-id:subject:from:to:content-type.

General Properties

Property Purpose Guidance
VerifyInfo JSON information about the last DKIM or DomainKey signature verified, or about the verification failure. Inspect after DkimVerify or DomainKeyVerify. It can include domain, selector, public key, canonicalization, algorithm, signed headers, and verification status.
AbortCurrent Causes the currently running method to abort. Applies to methods that may involve longer file operations or network communication. Can abort synchronous or asynchronous calls.
HeartbeatMs Interval in milliseconds between AbortCheck callbacks. Default is 0, meaning no callbacks.
LastErrorText Diagnostic text for the last method or property access. Check after failures or unexpected behavior. Diagnostic information may be available regardless of success or failure.

Signing Methods

Method Signature Type Required Setup Result
DkimSign DKIM-Signature Set DkimDomain, DkimSelector, and call SetDkimPrivateKey. Constructs and prepends a DKIM-Signature header to the MIME in BinData.
DomainKeySign DomainKey-Signature Set DomainKeyDomain, DomainKeySelector, and call SetDomainKeyPrivateKey. Constructs and prepends a DomainKey-Signature header to the MIME in BinData.
SetDkimPrivateKey DKIM private key Supply a PrivateKey object. Sets the private key used for creating DKIM signatures.
SetDomainKeyPrivateKey DomainKey private key Supply a PrivateKey object. Sets the private key used for creating DomainKey signatures.

Verification Methods

Method Purpose Important Details
NumDkimSigs Counts DKIM-Signature headers in MIME data. Use before verifying when messages may contain more than one DKIM signature.
DkimVerify Verifies the Nth DKIM signature. The first signature is index 0. On return, VerifyInfo contains additional details.
NumDomainKeySigs Counts DomainKey-Signature headers in MIME data. Use before verifying when messages may contain more than one DomainKey signature.
DomainKeyVerify Verifies the Nth DomainKey signature. The first signature is index 0. On return, VerifyInfo contains additional details.
Signature index rule: Most messages have a single signature, so the signature index is usually 0. Use the count methods when multiple signatures may be present.

Public-Key Loading and Caching

Method Purpose When to Use
LoadPublicKey Caches a public key for a selector/domain pair. Useful for testing verification when the public key is not yet installed in DNS. The public key may be in a text format such as XML or PEM, and Chilkat auto-detects the format.
LoadPublicKeyFile Caches a public key from a file for a selector/domain pair. Useful for testing with a public key file before DNS is configured. Chilkat auto-detects the public key format.
PrefetchPublicKey Fetches and caches the public key for a selector/domain pair. Useful when verifying many emails from the same domain or a small set of domains, avoiding repeated DNS lookups.
Cache behavior: Verification methods use a cached or pre-fetched public key when the selector and domain match.

Canonicalization and Header Selection

Area DKIM DomainKey
Algorithm rsa-sha256 or rsa-sha1. Default: rsa-sha256. Only rsa-sha1. Default: rsa-sha1.
Canonicalization simple or relaxed. Default: relaxed. simple or nofws. Default: nofws.
Signed headers Controlled by DkimHeaders. Controlled by DomainKeyHeaders.
Default header list mime-version:date:message-id:subject:from:to:content-type

VerifyInfo JSON

After a DKIM or DomainKey verification attempt, VerifyInfo contains JSON describing the signature or verification failure.

JSON Field Meaning
domain The signing domain found in the signature.
selector The selector used for the public-key lookup.
publicKey The public key used or found for verification.
canonicalization The canonicalization mode used by the signature.
algorithm The signing algorithm, such as rsa-sha256.
signedHeaders The headers included in the signature verification calculation.
verified Whether verification succeeded, such as yes.

Method Summary by Category

Category Methods Purpose
DKIM signing SetDkimPrivateKey, DkimSign Provide the DKIM private key and prepend a DKIM-Signature header to MIME data.
DKIM verification NumDkimSigs, DkimVerify Count and verify DKIM signatures in MIME data.
DomainKey signing SetDomainKeyPrivateKey, DomainKeySign Provide the DomainKey private key and prepend a DomainKey-Signature header.
DomainKey verification NumDomainKeySigs, DomainKeyVerify Count and verify DomainKey signatures in MIME data.
Public-key cache LoadPublicKey, LoadPublicKeyFile, PrefetchPublicKey Cache or prefetch public keys for selector/domain pairs.
Async support LoadTaskCaller Loads the caller of an async method’s task.

Diagnostics and Troubleshooting

Problem Area Member What to Check
DKIM signing fails DkimDomain, DkimSelector, SetDkimPrivateKey, DkimSign Confirm the signing domain and selector are set, a private key has been supplied, and the MIME data is valid.
DomainKey signing fails DomainKeyDomain, DomainKeySelector, SetDomainKeyPrivateKey, DomainKeySign Confirm the DomainKey domain, selector, private key, and MIME data.
Verification fails because the key is not in DNS yet LoadPublicKey, LoadPublicKeyFile Cache the public key manually for the selector/domain pair while testing.
Verification is slow across many emails from the same domain PrefetchPublicKey Prefetch the public key once per selector/domain to avoid repeated DNS lookups.
Wrong signature index is verified NumDkimSigs, NumDomainKeySigs Count signatures first and verify the intended zero-based signature index.
Need details about why verification failed VerifyInfo, LastErrorText Inspect VerifyInfo for signature-specific JSON details, and LastErrorText for diagnostic text.
Long-running verification or DNS operation needs cancellation AbortCurrent, HeartbeatMs Configure heartbeat callbacks or set AbortCurrent from another thread to abort a running operation.

Common Pitfalls

Pitfall Better Approach
Calling DkimSign before setting the domain, selector, and private key. Set DkimDomain, DkimSelector, and call SetDkimPrivateKey first.
Assuming there is always only one signature. Use NumDkimSigs or NumDomainKeySigs when multiple signatures may exist.
Forgetting that signature indexes are zero-based. Use index 0 for the first signature.
Testing verification before the public key is published in DNS without loading it manually. Use LoadPublicKey or LoadPublicKeyFile to cache the key for testing.
Using DomainKey settings for DKIM signing, or DKIM settings for DomainKey signing. Use Dkim* properties for DKIM and DomainKey* properties for DomainKey.
Expecting DkimBodyLengthCount = 0 to limit body hashing. A value of 0 means the entire body is hashed.
Ignoring VerifyInfo after verification. Read VerifyInfo to see the domain, selector, canonicalization, algorithm, signed headers, and verification result.

Best Practices

Recommendation Reason
Use rsa-sha256 for DKIM unless compatibility requires otherwise. It is the default DKIM signing algorithm.
Set domain and selector explicitly before signing. They identify the signing domain and public-key DNS location used by verifiers.
Keep the public DNS selector/domain aligned with the private key used for signing. Verification succeeds only when the public key found for the selector/domain matches the private key used to sign.
Use PrefetchPublicKey for repeated verification workloads. It avoids repeated DNS public-key lookups for the same selector/domain.
Use LoadPublicKey or LoadPublicKeyFile during DNS setup/testing. These methods allow verification testing before the public key is installed in DNS.
Inspect VerifyInfo after verification. It provides structured details about the signature that was verified or why verification failed.
Check LastErrorText after failures. It provides the most useful diagnostic detail for signing, verifying, key-loading, DNS lookup, and MIME-processing problems.

Summary

Chilkat.Dkim is the Chilkat class for signing and verifying MIME email data with DKIM and DomainKey signatures. It supports DKIM signing with rsa-sha256 or rsa-sha1, DomainKey signing with rsa-sha1, configurable canonicalization and signed headers, signature counting, public-key caching, public-key prefetching, and detailed verification reporting through VerifyInfo.

The most important practical guidance is to set the correct domain, selector, and private key before signing; verify the intended zero-based signature index; cache or prefetch public keys when useful; and inspect VerifyInfo and LastErrorText for troubleshooting.