dkim_set_final()

[back to index]

SYNOPSIS
#include <dkim.h>
DKIM_STAT dkim_set_final(
	DKIM_LIB *libopendkim,
        DKIM_CBSTAT (*func)(DKIM *dkim, DKIM_SIGINFO **sigs, int nsigs));
);
Defines a callback function to be used for final scanning and sorting of the signatures discovered on a message.

From within dkim_eoh(), an array of DKIM_SIGINFO handles is allocated, and an array of pointers is created referring to them. During dkim_eoh(), a prescreen callback may be used to do initial sorting, analysis and disqualification of discovered signatures.

If this callback function is defined, it will be called by dkim_eom() to give the caller a final opportunity to review the signatures and possibly reorder or flag them for special treatment by the library now that the entire body has arrived and body hashes can be computed. sigs will refer to the array of discovered signatures and nsigs will indicate the length of this array.

From within this callback you can use dkim_sig_getcontext() on any of the DKIM_SIGINFO pointers to retrieve the user-allocated context specific to that signature as created earlier by the allocation callback set by dkim_set_signature_handle() and make use of the data found there. That context is not used by the library in any way.

Also available are dkim_sig_getflags() to retrieve current processing flags assigned to a signature, dkim_sig_getbh() to retrieve the results of the body hash comparison done (if any) on the signature, and dkim_sig_process() to retrieve the key named by the signature and attempt public key verification and body hash comparison.

The callback can also use the function dkim_sig_ignore() to indicate to the library that the signature should be ignored.

The callback should return one of the DKIM_CBSTAT return values. Any other value will cause dkim_eoh() to abort and return a status of DKIM_STAT_CBINVALID.

DESCRIPTION
Called When dkim_set_final() must be called before dkim_eom() has been called.
ARGUMENTS
ArgumentDescription
libopendkim The library instantiation handle, returned by dkim_init().
func A pointer to a function which takes a DKIM handle, a pointer to an array of DKIM_SIGINFO handles and an integer indicating the length of that array as parameters. If NULL, no callback will be used.
RETURN VALUES
  • DKIM_STAT_OK -- success
  • DKIM_STAT_INVALID -- dkim referred to a signing handle rather than a verifying handle
NOTES
  • None.

Copyright (c) 2007 Sendmail, Inc. and its suppliers. All rights reserved.
Copyright (c) 2009-2011, The Trusted Domain Project. All rights reserved.
By using this file, you agree to the terms and conditions set forth in the respective licenses.