Dkim C++ Reference Documentation

CkDkim

Current Version: 11.5.0
Requires Chilkat Bundle License

Chilkat.Dkim

Sign and verify MIME email with DKIM and DomainKey signatures.

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

DKIM signing

Add DKIM signatures to MIME messages using a private key, selector, signing domain, canonicalization settings, and selected headers.

DomainKey support

Create or verify legacy DomainKey signatures when older mail systems or compatibility requirements depend on them.

Signature verification

Verify one or more signatures in a MIME message and determine whether the signed content, headers, and public key match.

Canonicalization control

Configure body and header canonicalization so signing and verification match the requirements of the sending domain and receiving systems.

DNS public keys

Retrieve DKIM public keys from DNS, prefetch keys when useful, and cache public keys to reduce repeated DNS lookups.

Verification diagnostics

Use VerifyInfo and related status information to understand which signatures were found, which were checked, and why verification succeeded or failed.

Common pattern: To sign, provide the MIME message, signing domain, selector, private key, canonicalization choices, and the headers to include in the signature. To verify, pass the received MIME message to Dkim, allow the class to locate the signature and public key, and inspect VerifyInfo for detailed results.

For an extended overview, see Dkim Class Overview.

Object Creation

// Local variable on the stack
CkDkim obj;

// Dynamically allocate/delete
CkDkim *pObj = new CkDkim();
// ...
delete pObj;

Properties

AbortCurrent
bool get_AbortCurrent(void);
void put_AbortCurrent(bool newVal);
Introduced in version 9.5.0.58

Set to true 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.

Cancellation behavior: Treat this as a cancellation request rather than a guarantee of immediate termination. After the method returns, use the method's normal return value and diagnostic properties to determine the outcome.

top
DebugLogFilePath
void get_DebugLogFilePath(CkString &str);
const char *debugLogFilePath(void);
void put_DebugLogFilePath(const char *newVal);

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.

More Information and Examples
Example showing how to use DebugLogFilePath.
top
DkimAlg
void get_DkimAlg(CkString &str);
const char *dkimAlg(void);
void put_DkimAlg(const char *newVal);

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

ValueMeaning
rsa-sha256RSA signing with a SHA-256 message digest. This is the recommended choice.
rsa-sha1Legacy RSA signing with SHA-1. Use only when compatibility with an older system requires it.
DKIM background: The algorithm identifies both the public-key algorithm and the digest algorithm used to create the signature. A verifier must support the selected algorithm and retrieve a matching public key from DNS or the local key cache.

top
DkimBodyLengthCount
int get_DkimBodyLengthCount(void);
void put_DkimBodyLengthCount(int newVal);

Specifies the optional DKIM body-length value written to the l= tag. The value is the maximum number of bytes from the canonicalized message body to include in the body hash. The default is 0, which omits the l= tag and hashes the entire canonicalized body.

Security note: A partial body signature does not protect content appended after the signed portion. Signing the complete body is normally preferred unless a specific interoperability requirement calls for the l= tag.

top
DkimCanon
void get_DkimCanon(CkString &str);
const char *dkimCanon(void);
void put_DkimCanon(const char *newVal);

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

ValueBehavior
simplePreserves header and body formatting closely. Small changes in whitespace or line folding can invalidate the signature.
relaxedNormalizes defined whitespace and header-name differences, making the signature more tolerant of harmless transport formatting changes.
Canonicalization background: DKIM signs a canonicalized representation of the message rather than the raw bytes exactly as stored. The signer and verifier must apply the same canonicalization rules.

top
DkimDomain
void get_DkimDomain(CkString &str);
const char *dkimDomain(void);
void put_DkimDomain(const char *newVal);

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

DKIM and DMARC: The DKIM signing domain does not have to be identical to the visible From domain for DKIM verification itself. DMARC separately evaluates whether the authenticated DKIM domain is aligned with the message's From domain.

top
DkimHeaders
void get_DkimHeaders(CkString &str);
const char *dkimHeaders(void);
void put_DkimHeaders(const char *newVal);

A colon-separated list of header field names to include in the DKIM signature. These names are written to the signature's h= tag and determine which message headers are protected. The default is: 

mime-version:date:message-id:subject:from:to:content-type
Header field names are case-insensitive. A field name may be listed more than once when multiple instances of the same header are to be signed.
Signing guidance: A DKIM signature must cover the From header. Sign stable, meaningful headers such as Date, Subject, To, and Message-ID. Avoid signing transport-added or commonly modified fields such as Received and Return-Path.

top
DkimSelector
void get_DkimSelector(CkString &str);
const char *dkimSelector(void);
void put_DkimSelector(const char *newVal);

Specifies the selector written 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
For example, selector reykjavik and domain example-code.com produce the DNS name reykjavik._domainkey.example-code.com.
Selector background: Selectors allow a domain to publish multiple DKIM keys and rotate keys without changing the signing domain. The private key configured by SetDkimPrivateKey must match the public key published for this selector and domain.

top
HeartbeatMs
int get_HeartbeatMs(void);
void put_HeartbeatMs(int newVal);

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

A smaller interval makes cancellation checks more responsive but increases callback overhead.

More Information and Examples
Event Callback Examples
top
LastErrorHtml
void get_LastErrorHtml(CkString &str);
const char *lastErrorHtml(void);

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.

top
LastErrorText
void get_LastErrorText(CkString &str);
const char *lastErrorText(void);

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.

More Information and Examples
Concept of LastErrorTextLastErrorText Standard Information
top
LastErrorXml
void get_LastErrorXml(CkString &str);
const char *lastErrorXml(void);

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.

top
LastMethodSuccess
bool get_LastMethodSuccess(void);
void put_LastMethodSuccess(bool newVal);

Indicates the success or failure of the most recent method call: true means success, false 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.

top
Utf8
bool get_Utf8(void);
void put_Utf8(bool newVal);

When set to true, all const char * arguments and return values are interpreted as UTF-8 strings. When set to false, they are interpreted as ANSI strings.

In Chilkat v11.0.0 and later, the default value is true. Before v11.0.0, it was false.

top
VerboseLogging
bool get_VerboseLogging(void);
void put_VerboseLogging(bool newVal);

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

top
VerifyInfo
void get_VerifyInfo(CkString &str);
const char *verifyInfo(void);
Introduced in version 9.5.0.76

Contains JSON describing the most recent DKIM or DomainKeys verification attempt. The information may include the signing domain, selector, public key, canonicalization, algorithm, signed headers, and whether verification succeeded. 

{
  "domain": "amazonses.com",
  "selector": "7v7vs6w47njt4pimodk5mmttbegzsi6n",
  "publicKey": "MIGfMA0GCSq...z6uqeQIDAQAB",
  "canonicalization": "relaxed/simple",
  "algorithm": "rsa-sha256",
  "signedHeaders": "Subject:From:To:Date:Mime-Version:Content-Type:References:Message-Id:Feedback-ID",
  "verified": "yes"
}
This property is updated by DkimVerify and DomainKeyVerify.
Authentication scope: A valid DKIM signature proves that the signed content has not changed and that the signer possessed the private key for the authenticated domain. It does not by itself prove the identity of the human sender, authorize the message, or establish DMARC alignment.

More Information and Examples
Verify DKIM-Signature Headers in Downloaded Email
top
Version
void get_Version(CkString &str);
const char *version(void);

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

More Information and Examples
How to get the Chilkat version at runtime.
top

Methods

DkimSign
bool DkimSign(CkBinData &mimeData);
Introduced in version 9.5.0.71

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

Before calling this method:

  • Set DkimDomain and DkimSelector.
  • Load the matching private key by calling SetDkimPrivateKey.
  • Configure the algorithm, canonicalization, signed headers, and optional body-length setting as needed.
Sign the final MIME representation: DKIM protects the canonicalized message headers and body. Complete MIME generation, transfer-encoding selection, content changes, and other message edits before signing. Changes made after signing can invalidate the signature.

Returns true for success, false for failure.

More Information and Examples
Send DKIM Signed Email
top
DkimVerify
bool DkimVerify(int sigIndex, CkBinData &mimeData);
Introduced in version 9.5.0.71

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

Chilkat uses a matching cached key when available; otherwise it retrieves the public key identified by the signature's selector and signing domain. After the call, inspect VerifyInfo for details about the signature and verification result.

Multiple signatures: A message can contain more than one DKIM signature, often because it passed through multiple signing systems. Verify each signature independently. One valid signature does not imply that every signature on the message is valid.

Returns true for success, false for failure.

More Information and Examples
Verify DKIM-Signature Headers in Downloaded Email
top
LoadPublicKey
bool LoadPublicKey(const char *selector, const char *domain, const char *publicKey);

Caches an RSA public key for the specified selector and domain. When a later DKIM or DomainKeys verification references the same selector and domain, Chilkat can use this cached key instead of retrieving the key from DNS.

The publicKey argument contains the key in a supported textual representation, such as PEM or XML. Chilkat detects the format automatically.

Typical use: This is useful for testing before a DNS record is published, for controlled verification environments, or when the application already obtained the authoritative public key by another trusted means. The cached key must correspond to the private key used by the signer.

Returns true for success, false for failure.

top
LoadPublicKeyFile
bool LoadPublicKeyFile(const char *selector, const char *domain, const char *publicKeyFilepath);

Loads and caches an RSA public key from the local file specified by publicKeyFilepath for the given selector and domain. Chilkat detects the supported key-file format automatically.

When a later DKIM or DomainKeys verification references the same selector and domain, the cached key can be used instead of performing a DNS lookup.

Path and trust: publicKeyFilepath is a path in the local filesystem. Only load keys from a trusted source because supplying an incorrect key changes which signatures can be accepted for that selector and domain.

Returns true for success, false for failure.

top
LoadTaskCaller
bool LoadTaskCaller(CkTask &task);
Introduced in version 9.5.0.80

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 true for success, false for failure.

top
NumDkimSigs
int NumDkimSigs(CkBinData &mimeData);
Introduced in version 9.5.0.76

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

More Information and Examples
Verify DKIM-Signature Headers in Downloaded Email
top
PrefetchPublicKey
bool PrefetchPublicKey(const char *selector, const char *domain);

Retrieves and caches the public key for the specified selector and domain. The DNS lookup is made for: 

selector._domainkey.domain
Call this method before verifying messages when the application expects many signatures from the same selector and domain. It may be called multiple times for different selector/domain pairs. DkimVerify and DomainKeyVerify use a matching cached key when available.
Key rotation: A selector identifies a particular published key. When a sender rotates to a new selector, prefetch that new selector as well. Do not assume that one cached key applies to every selector used by the domain.

Returns true for success, false for failure.

top
PrefetchPublicKeyAsync (1)
CkTask *PrefetchPublicKeyAsync(const char *selector, const char *domain);

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.

Note: The application is responsible for deleting (via the C++ delete operator) the object returned by this method.

Returns NULL on failure

top
SetDkimPrivateKey
bool SetDkimPrivateKey(CkPrivateKey &privateKey);
Introduced in version 9.5.0.71

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

Key matching: The private key must correspond to the public key published at selector._domainkey.domain, using the values in DkimSelector and DkimDomain. Protect the private key as a signing credential and rotate it if exposure is suspected.

Returns true for success, false for failure.

top

Events

To implement an event callback, your application would define and implement a class that inherits from CkBaseProgress. Your application can implement methods to override some or all of the default/empty method implementations of the CkBaseProgress base class.

For example:

  CkDkim dkim;

  MyDkimProgress callbackObj;

  dkim.put_EventCallbackObject(&callbackObj);

MyDkimProgress example:

#include "CkBaseProgress.h"

class MyDkimProgress : public CkBaseProgress {

  public:
    MyDkimProgress();
    virtual ~MyDkimProgress();

    void AbortCheck(bool  *abort);

    void PercentDone(int pctDone, bool  *abort);

    void ProgressInfo(const char *name, const char *value);

    void TaskCompleted(CkTask &task);

};
AbortCheck
void AbortCheck(bool *abort);

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.

More Information and Examples
Chilkat Event Callback Examples
top
PercentDone
void PercentDone(int pctDone, bool *abort);

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 true. This will cause the method to terminate and return a failure status or corresponding failure value.

More Information and Examples
Chilkat Event Callback Examples
top
ProgressInfo
void ProgressInfo(const char *name, const char *value);

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.

More Information and Examples
Chilkat Event Callback Examples
top
TaskCompleted
void TaskCompleted(CkTask &task);

Called from the background thread when an asynchronous task completes.

top

Deprecated

DomainKeyAlg
void get_DomainKeyAlg(CkString &str);
const char *domainKeyAlg(void);
void put_DomainKeyAlg(const char *newVal);
This property is deprecated. It will be removed in a future version.

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

Legacy protocol: DomainKeys is the predecessor to DKIM and is obsolete for modern email authentication. New implementations should use DKIM with rsa-sha256 unless compatibility with an older system specifically requires DomainKeys.

top
DomainKeyCanon
void get_DomainKeyCanon(CkString &str);
const char *domainKeyCanon(void);
void put_DomainKeyCanon(const char *newVal);
This property is deprecated. It will be removed in a future version.

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

ValueMeaning
simpleUses the message representation with minimal normalization.
nofwsApplies the DomainKeys no-folding-whitespace canonicalization rules.
Legacy protocol: These values apply to DomainKeys, not DKIM. For modern signing, use DkimCanon.

top
DomainKeyDomain
void get_DomainKeyDomain(CkString &str);
const char *domainKeyDomain(void);
void put_DomainKeyDomain(const char *newVal);
This property is deprecated. It will be removed in a future version.

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

Legacy protocol: DomainKeys is obsolete. Use DkimDomain for new DKIM implementations.

top
DomainKeyHeaders
void get_DomainKeyHeaders(CkString &str);
const char *domainKeyHeaders(void);
void put_DomainKeyHeaders(const char *newVal);
This property is deprecated. It will be removed in a future version.

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
Legacy protocol: This property applies only to DomainKeys. For modern DKIM signing, use DkimHeaders.

top
DomainKeySelector
void get_DomainKeySelector(CkString &str);
const char *domainKeySelector(void);
void put_DomainKeySelector(const char *newVal);
This property is deprecated. It will be removed in a future version.

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

selector._domainkey.signing-domain
For example, selector reykjavik and domain example-code.com produce reykjavik._domainkey.example-code.com.
Legacy protocol: This property applies only to DomainKeys. For modern DKIM signing, use DkimSelector.

top
DomainKeySign
bool DomainKeySign(CkBinData &mimeData);
Introduced in version 9.5.0.71
This method is deprecated.

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.

Legacy protocol: DomainKeys is obsolete and uses RSA with SHA-1. Use DkimSign for modern email authentication.

Returns true for success, false for failure.

top
DomainKeyVerify
bool DomainKeyVerify(int sigIndex, CkBinData &mimeData);
Introduced in version 9.5.0.71
This method is deprecated.

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.

Legacy protocol: DomainKeys verification is provided for compatibility with old messages and systems. Modern email authentication uses DKIM.

Returns true for success, false for failure.

More Information and Examples
Verify DomainKey-Signature Headers in Downloaded Email
top
NumDomainKeySigs
int NumDomainKeySigs(CkBinData &mimeData);
Introduced in version 9.5.0.76
This method is deprecated.

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.

Legacy protocol: This count does not include modern DKIM-Signature headers. Use NumDkimSigs for DKIM.

More Information and Examples
Verify DomainKey-Signature Headers in Downloaded Email
top
SetDomainKeyPrivateKey
bool SetDomainKeyPrivateKey(CkPrivateKey &privateKey);
Introduced in version 9.5.0.71
This method is deprecated.

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

Legacy protocol: This method is for obsolete DomainKeys signing. New applications should use SetDkimPrivateKey and DkimSign.

Returns true for success, false for failure.

top