dkim_diffheaders()

[back to index]

SYNOPSIS
#include <dkim.h>

DKIM_STAT dkim_diffheaders(
	DKIM *dkim,
	dkim_canon_t canon,
	int maxcost,
	char **ohdrs,
	int nohdrs,
	struct dkim_hdrdiff **out,
        int *nout);
);
Attempts to discern how signed header fields were changed in transit in order to debug verification problems.
DESCRIPTION
Called When dkim_diffheaders() can be called at any time after end-of-headers processing (i.e. dkim_eoh()) while verifying.
ARGUMENTS
ArgumentDescription
dkim Message-specific signing handle, returned by dkim_verify().
canon Canonicalization mode that was used to generate the signature from which ohdrs was extracted.
maxcost When comparing two header fields, a "cost" is computed for each difference observed. The library computes the cost of a match by computing the number of character insertions, removals or replacements that would be needed to transition from the first header field to the second; insertions and removals each have a cost of 1 and replacements a cost of 2. Two header fields are considered a match for the purposes of this function if the cost of a comparison is below the value of maxcost. Thus, larger values are more prone to mismatches, but smaller values might not detect serious munging of headers in transit. Insertions and removals are given lower costs because it is presumed most munging in transit changes spaces, but doesn't actually rewrite other content.
ohdrs An array of pointers to NULL-terminated strings containing copies of the original signed headers as extracted from a signature. This can be obtained from signatures that had "z=" tags by using the dkim_ohdrs() function.
nohdrs The number of elements in the ohdrs array.
out A pointer to an array of struct dkim_hdrdiff objects that will be allocated by this function. Each object contains a character pointer called hd_old that refers to the original signed header, and one called hd_new that refers to its corresponding value in the received message.
nout A pointer to an integer that will be updated to contain the number of elements that are placed in the out array.
RETURN VALUES
  • DKIM_STAT_OK -- success
  • DKIM_STAT_INVALID -- the message handle was not initialized for verifying, or a maxcost of 0 was specified
  • DKIM_STAT_INTERNAL -- a regular expression processing error occurred
  • DKIM_STAT_NORESOURCE -- memory exhaustion occurred
  • DKIM_STAT_NOTIMPLEMENT -- the required regular expression library was not available when the library was compiled
NOTES
  • The library must be compiled with an approximate regular expression library in order to provide this service.
  • The returned array of pairs of strings refer to header fields present in both the original header field set and the received header field set that were not the same, but close enough to be considered a match based on the maxcost parameter. This function does not currently detect header fields removed in transit.

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