# 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

Argument | Description
--- | ---
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 Name | Description
--- | ---
`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. </t>

`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.