zdkimsign(1)

NAME
zdkimsign - a wrapper around zdkimfilter

SYNOPSIS

zdkimsign [option [option-arg]] message-file ...
zdkimverify [option [option-arg]] message-file ...
zarcseal [option [option-arg]] message-file ...

DESCRIPTION
zdkimsign is a wrapper around the zdkimfilter executable. It provides for offline signing of messages, and a few other utilities. It searches for the zdkimfilter executable in the build-time configured path, and either in the directory used for calling it, if any, or in the PATH. That way it can work when the package is built but not yet installed.

Normally, zdkimsign uses the --no-db option of zdkimfilter, so as to avoid having the messages signed this way logged to the database. However, the --db-filter and --db options allow logging. The inode number for database keys, in those cases is either that of the ctlfile or fixed 99999999.

zdkimsign creates the ctlfile in the directory specified by the -t option, if any; otherwise, in the one specified by the tmp configuration option, if present; otherwise in /tmp. The filesystem of the temporary directory may happen to be relevant for the uniqness of the pid-mtime-ino key.

zdkimverify and zarcseal are symlinks. Using them switches the behavior as described under the corresponding options below.

OPTIONS

-f config-filename
    Override the default configuration file. That way it is possible to configure for signing different header fields, or using different keys. zdkimsign only reads the tmp and default_domain configuration options, but forwards this command line option to the invoked zdkimfilter.

    If config-filename is an empty string (""), the program will use default values only. Otherwise, config-filename will be opened in the current directory.

-o filename
    Save intermediate verification debug files. When retrying DKIM authentication by undoing a MLM transformation, the retried message or part of it is saved to the filename, if given.

    This option uses by zdkimfilter's --save-files option.

    If the executable is compiled with debugging support, this option dumps the canonicalization results to files named "dkim.*.*".

    All files are created in the /tmp directory, possibly overridden by the corresponding configuration parameter.

-t tmp-directory
    The directory used for temporary files.

--syslog
    Log to syslog (LOG_MAIL facility) rather than stderr.

--filter
    Use standard I/O, that is read a mail file on stdin and rewrite it to stdout. This option implies --syslog, but the filter response is echoed on stderr in case of error.

    I/O behavior is obtained by passing the --no-fork option to zdkimfilter. That way, the message-file arguments get silently ignored.

--db-filter
    This option implies --filter, and enables database logging. To do that, the ctlfile includes the full list of recipients and a Courier's style id with the inode number of the ctlfile itself.

    See the description above for the relationship between key uniqueness and the temporary directory.

--db
    This option enables just database logging.

--domain domain
    Use this as the signing domain. If the domain argument contains a "@", then the whole string is set as the authenticated user and, if not overridden by the next option, to the envelope sender. Otherwise, if no "@", the ctlfile will have postmaster@domain. This may or may not result in a signature by such domain, according to the other configuration options.

--sender sender
    This sets the envelope sender in the ctlfile. The value is only relevant for --db-filter, since the ctlfile is used for signing only. If this option is not specified, domain is used as envelope sender as well, if it contains a "@".

--config
    Have zdkimfilter check and print the configuration file.

--help
    Print usage and exit.

--version
    Have zdkimfilter print the version. zdkimsign just prints which executable it is about to run.

--verify
    Act as if invoked as zdkimverify. The latter is a symbolic link to zdkimsign. The behavior is similar, invoking zdkimfilter, but the temporary ctlfile is written so as to trigger verification.

    Unless --filter is also specified, zdkimverify passes the --no-write option to zdkimfilter, so as to not modify the target mail file. Authentication-Results are output on stdout, log lines to stderr.

--arcseal
    Act as if invoked as zarcseal. The latter is a symbolic link to zdkimsign.

    This writes an ARC set on the target file(s), signed by the specified --domain option, using DKIM keys. An ARC set consists of the three header fields ARC-Seal, ARC-Message-Signature and ARC-Authentication-Results. The latter one is transformed from existing Authentication-Results fields, which are removed from the header.

FILES

/usr/lib/filters/zdkimfilter
    The build-time configured path of the zdkimfilter executable.

/etc/courier/filters/zdkimfilter.conf
    Default configuration file.

ENVIRONMENT VARIABLES

REMOTE_ADDR
    If this variable is set, the zdkimfilter child uses it for storing the client's "ip" variable to the database.

AUTHOR
Alessandro Vesely <vesely@tana.it>

SEE ALSO

zdkimfilter(8)
    Explains how to set up private keys for signing, and choice of domain.

zdkimfilter.conf(5)
    Explains configuration options, including key_choice_header and default_domain.