dkim_options()

SYNOPSIS
#include <dkim.h>
DKIM_STAT dkim_options(
	DKIM_LIB *lib,
        int op,
        int opt,
        void *data,
        size_t len
);
Sets or retrieves options to alter the behaviour of certain aspects of the library's operation.
DESCRIPTION
Called When dkim_options() can be called at any time after acquiring a library handle from dkim_init().
ARGUMENTS
ArgumentDescription
dkim Library instance handle, returned by dkim_init.
op Either DKIM_OP_SETOPT to set a current library option, or DKIM_OP_GETOPT to retrieve a current library option.
opt One of the following macros, to indicate which library option should be retrieved or changed. Possible values:
Option NameDescription
DKIM_OPTS_ALWAYSHDRS data refers to an array of pointers to strings which name headers that should be included in the header lists of signatures even if they were not present for signing. This list is empty by default.
DKIM_OPTS_CLOCKDRIFT data refers to a time_t which contains the number of seconds of clock drift that should be tolerated when determining whether or not a signature either has expired or was generated in the future. The default is 300 seconds (five minutes).
DKIM_OPTS_FIXEDTIME data refers to a time_t which contains a fixed time specification to use during signature generation.
DKIM_OPTS_FLAGS data refers to an unsigned integer which contains a bitwise-OR of desired flags. See below for the list of known flags.
DKIM_OPTS_QUERYINFO data refers to a string in which query information is stored. See dkim_query_t for more information.
DKIM_OPTS_QUERYMETHOD data refers to a dkim_query_t containing a value which should override any q= value in signatures during verifications.
DKIM_OPTS_SENDERHDRS data refers to an ordered, NULL-terminated array of header names which should be searched when trying to determine the ultimate sender of the message. The default is to check Resent-Sender, Resent-From, Sender and From. The caller's list completely replaces this list. If data refers to a NULL pointer, the default is restored.
DKIM_OPTS_SIGNATURETTL data refers to a time_t which contains the time-to-live of signatures to be applied during signature generation.
DKIM_OPTS_SIGNHDRS data refers to an unordered, NULL-terminated array of header names which are the ones that should be included when signing a message. Wildcarding using the asterisk ("*") character, meaning "match zero or more characters", is permitted. The From header is mandatory and thus implicitly added to any list provided by the caller. The constant should_signhdrs may be specified as the data, whicn contains all of the headers RFC4871 section 5.5 says should be signed. The default is to sign all headers. If data refers to a NULL pointer, the default is restored. Attempting DKIM_OP_GETOPT on this option returns an error as it is converted to regular expressions and not currently stored in a useable form.
DKIM_OPTS_SKIPHDRS data refers to an unordered, NULL-terminated array of header names which are the ones that should be skipped when processing a message for signing. The default is to skip no headers. The constant should_not_signhdrs may be specified as the data, whicn contains all of the headers RFC4871 section 5.5 says should not be signed. Wildcarding using the asterisk ("*") character, meaning "match zero or more characters", is permitted. If data refers to a NULL pointer, the default is restored. Attempting DKIM_OP_GETOPT on this option returns an error as it is converted to regular expressions and not currently stored in a useable form.
DKIM_OPTS_TMPDIR data refers to a string which is the directory libdkim should use for creating temporary files.
DKIM_OPTS_TIMEOUT data refers to an unsigned integer indicating the timeout, in seconds, to be used when doing DNS queries to retrieve key and policy records.
data If the operation is DKIM_OP_GETOPT, this specifies the address to which to write the retrieved value. If the operation is DKIM_OP_SETOPT, this specifies the address from which to copy the new option value.
len Number of bytes available for reading/writing at data.
FLAGS When setting or retreiving library flags, the method is to specify a bitwise-OR of flag bits in an unsigned integer. The recognized flags are:
DKIM_LIBFLAGS_ACCEPTV05 Accept signatures with version strings of "0.5", i.e. those which were based on some draft versions of the DKIM specification. Note that this does not change or relax the rules applied by this implementation, and thus these older signatures still may not verify due to evolutions of the specification that took place during the use of that version string.
DKIM_LIBFLAGS_CACHE Maintain a local cache of retrieved key and policy records, rather than relying on the DNS servers to do so. May improve performance if, for example, the DNS server is not local. Requires that libdkim be compiled with the QUERY_CACHE option since doing so adds a library dependency to the build.
DKIM_LIBFLAGS_DELAYSIGPROC Normally the key retrieval and public key validation takes place in the dkim_eoh() function, and the body hash verification takes place in dkim_eom() function. Setting this flag delays all processing of signatures until dkim_eom(). This means the caller will be unable to evaluate signature validity on completion of dkim_eoh() and will have to wait until after dkim_eom() (or the final processing callback if such is defined).
DKIM_LIBFLAGS_EOHCHECK Perform a signature check at the end of dkim_eoh(). This will cause dkim_eoh() to return an error code if no useable signatures were found in the message.
DKIM_LIBFLAGS_KEEPFILES Keep temporary files for manual debugging purposes. (Also requires that DKIM_LIBFLAGS_TMPFILES be set.)
DKIM_LIBFLAGS_SIGNLEN When signing messages, include in the signature the number of bytes that were canonicalized even when a length limit wasn't specified by the caller.
DKIM_LIBFLAGS_TMPFILES Make temporary files for debugging purposes. See dkim_reportinfo() for an example of how this might be useful.
DKIM_LIBFLAGS_ZTAGS Include the original header set encoded into a "z=" tag in the signature for diagnostic use by the receiver.
NOTES
  • None.

Copyright (c) 2005-2007 Sendmail, Inc. and its suppliers. All rights reserved.
By using this file, you agree to the terms and conditions set forth in the LICENSE.