dkim_options()

[back to index]

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_CLOCKDRIFT data refers to a uint64_t that 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 uint64_t that contains a fixed time specification to use during signature generation. This follows the same form as a time_t but allows for larger integers.
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_MINKEYBITS data refers to a u_int that contains the minimum number of bits that are to be conisdered acceptable. The default is 1024.
DKIM_OPTS_MUSTBESIGNED data refers to an ordered, NULL-terminated array of header names which, when verifying a message, must be covered by a signature for the signature to be considered valid. The default is to make no such assertion. If data refers to a NULL pointer, the default is restored.
DKIM_OPTS_OVERSIGNHDRS data refers to an unordered, NULL-terminated array of pointers to NULL-terminated strings that name header fields which should be included in the header lists ("h=" tags) of signatures once more than the number of occurrences that were signed. This prevents later handlers from adding instances of those header fields without invalidating the signature. This list is empty by default.
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_REQUIREDHDRS data refers to an ordered, NULL-terminated array of header field names that should be considered mandatory when determining the validity of an input message for signing. The default is to require a From field only. 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 uint64_t that contains the time-to-live, in seconds, of signatures to be applied during signature generation.
DKIM_OPTS_SIGNHDRS data refers to an unordered, NULL-terminated array of header field names. Input header fields whose names match an entry in this list will be signed. Wildcarding using the asterisk ("*") character, meaning "match zero or more characters", is permitted. The From header field is mandatory and thus implicitly added to any list provided by the caller. The constant dkim_should_signhdrs may be specified as the data, which contains all of the header fields RFC6376 Section 5.4 says should be signed. The default is to sign all header fields. 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 internally 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 dkim_should_not_signhdrs may be specified as the data, which contains all of the headers RFC6376 Section 5.4 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 libopendkim 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 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. Usually one can simply use sizeof(data) here.
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_ACCEPTDK Allow references to key records formatted for DomainKeys (RFC4870). This means a key record retrieved from DNS that has no "v=" tag will be treated slightly differently; specifically, an empty "g=" tag in the key matches all senders (the DomainKeys way) rather than no senders (the DKIM way). This flag has no other effect.
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_BADSIGHANDLES Create DKIM_SIGINFO handles even for signatures that had syntax errors. This also means dkim_chunk() will not return a syntax error code when it encounters a DKIM signature with a syntax error in it.
DKIM_LIBFLAGS_CACHE Maintain a local cache of retrieved key 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 libopendkim 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_DROPSIGNER If a caller attempts to generate a signature for which a specific signer address is requested and the domain of the signer is not the same as or a subdomain of the signing domain, the default behaviour is to return an error from dkim_gensighdr() since a signature thus generated would violate the DKIM specification. If this flag is set, the signature will still be generated but the "i=" tag will be omitted so the signature is still compliant.
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_FIXCRLF Convert "naked" CR and LF characters into CRLFs when canonicalizing.
DKIM_LIBFLAGS_KEEPFILES Keep temporary files for manual debugging purposes. (Also requires that DKIM_LIBFLAGS_TMPFILES be set.)
DKIM_LIBFLAGS_REPORTBADADSP When doing the ADSP query, a response that is a syntax error will by default be ignored. Setting this flag causes an error to be returned. This can be common when, for example, wildcard TXT records are used to publish other data.
DKIM_LIBFLAGS_REQUESTREPORTS Includes an "r=y" tag in generated signatures, requesting participating verifiers send back forensic information about the verified message when validation fails. Useful for debugging signature validation issues.
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_STRICTHDRS Refuse to sign or verify a message that doesn't conform to the header field count rules specified in RFC5322 Section 3.6, and have a properly formed From field. Other checks may also be enforced in the future.
DKIM_LIBFLAGS_STRICTRESIGN Refuse to generate a signature from a signing handle bound to a verifying handle (see dkim_resign()) if the verifying handle yielded no valid signatures.
DKIM_LIBFLAGS_TMPFILES Make temporary files for debugging purposes. See dkim_sig_reportinfo() for an example of how this might be useful.
DKIM_LIBFLAGS_VERIFYONE When verifying, only process signatures until the first good one is found (by default, all of them will be attempted).
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-2008 Sendmail, Inc. and its suppliers. All rights reserved.
Copyright (c) 2009-2014, The Trusted Domain Project. All rights reserved.
By using this file, you agree to the terms and conditions set forth in the respective licenses.