# 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

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.

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.