| 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 |
| Argument | Description |
|---|
| 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.
|