proposed API breaks with async DNS

From: Daniel Black <>
Date: Sat, 31 Oct 2009 16:02:18 +1100

Some are aware that I'm developing some libopendkim code to consolidate DNS
querying and make it asynchronous. The plan is for queries for ADSP, DKIM-
Signatures and reputation to occur as soon as the relevant header is passed in
for processing.


As this will make policy and signature information available earlier would you
like to set call back functions for these?


DKIM_STAT dkim_set_signature_callback
        DKIM_LIB *libopendkim,

will do a calllback as soon as something invalid is known about the signature
or DKIM_SIGERROR_OK - if all is finished and the signature validates.


DKIM_STAT dkim_policy(
        DKIM *dkim,
        bool *test,
        bool *susp,
        dkim_policy_t *pcode,
        dkim_handling_t *hcode,
        DKIM_PSTATE * pstate
DKIM_DNSSEC dkim_policy_getdnssec(
        DKIM *dkim

with a callback:

DKIM_STAT dkim_set_policy_callback(
        DKIM_LIB *libopendkim,
        DKIM_CBSTAT (*func)(DKIM *dkim, dkim_policy_t pcode, DKIM_DNSSEC res)
To get an earlier complete policy information to act upon.


The result of this is that DKIM-Signature header fields need to be parsed
earlier and, than unlike previous version, allocation of a continuous block of
signatures is not practical.

The proposed API changes effect the following functions that use a number of
sigs parameter:

DKIM_STAT dkim_getsiglist(
        DKIM *dkim,
        DKIM_SIGINFO **sigs,
        int *nsigs

DKIM_STAT dkim_set_prescreen(
        DKIM_LIB *libopendkim,
        DKIM_CBSTAT (*func)(DKIM *dkim, DKIM_SIGINFO **sigs, int nsigs));

The proposed new API is:

DKIM_STAT dkim_getsiglist(
        DKIM *dkim,
        DKIM_SIGINFO *sigs,

DKIM_STAT dkim_set_prescreen(
        DKIM_LIB *libopendkim,
        DKIM_CBSTAT (*func)(DKIM *dkim, DKIM_SIGINFO *sig)
Note: maybe the dkim_set_signature_callback above obsolete's these functions?

And to assist with iteration over signature linked lists:

DKIM_SIGINFO *dkim_signext(DKIM_SIGINFO *sig);

which returns the next signature in the list or NULL if now more signatures

So loops will change from:
dkimf_prescreen(DKIM *dkim, DKIM_SIGINFO *sigs, int nsigs)
        int c;
        DKIM_SIGINFO *sig;
        for (c = 0; c < nsigs; c++)
                sig = sigs[c];
dkimf_prescreen(DKIM *dkim, DKIM_SIGINFO *sig)
        for ( ; sigs != NULL ; sig = dkim_signext(sig) )


The current FFR_DKIM_REPUTATION uses the API:

DKIM_STAT dkim_get_reputation __P((DKIM *dkim, DKIM_SIGINFO *sig,
                                          char *qroot, int *rep));

Passing of the qroot value here make async DNS here impossible so here are
some options:
1. make qroot a DKIM option
2. make qroot a list of DKIM options (more that one reputation service
3. remove it and let the application fetch the domain with dkim_sig_getdomain
and do its own reputation service.
4. something else?

#5 Namespace consistency:

rfc2822_mailbox_split is the only function that doesn't have a dkim_ prefix.
So that we don't conflict with functions elsewhere that happen to be called
the same thing lets use dkim_rfc2822_mailbox_split instead.

#6 ASYNC DNS API exported

The async DNS may provide API for doing your own async DNS for things like
VBR, SPF, CSV (insert other three letter email acronym).

DKIM_STAT dkim_dns_callback(const char *query, int type, void (*f)(char
*result, DKIM_DNSSEC, DKIM_DNSERROR), unsigned timeoutms);

here you setup the query and receive a callback when its done. it follows
Received on Sat Oct 31 2009 - 05:02:55 PST

This archive was generated by hypermail 2.3.0 : Mon Oct 29 2012 - 23:16:46 PST