qmail daned.8

NAME

qmail-daned - TLSA Record Checker for IndiMail

SYNOPSIS

qmail-daned [ -t timeout (days) ] [ -p port ] [ -h hash_size ] [ -v verbosity ] [ -f free_interval (min) ] [ -s save_interval (min) ] [ -w whitelist_file [.cdb] ] [ -T tlsadomains_file [.cdb] ] ipaddr contextFile

DESCRIPTION

qmail-daned is a qmail daemon for DANE protocol validation. ”DANE” defines the protocol for storing TLS certificates in the DNS for a variety of applications using them. DNS-based Authentication of Named Entities (DANE) is a great feature that uses the advantages of a DNSSEC signed zone in order to tell the client which TLS certificate one has to expect when connecting to a secure destination over HTTPS or SMTPS.

qmail-daned is a DANE verification daemon responding to UDP query packets, typically sent by a using tlsacheck(3) function in qmail-remote(8). The query packet consists of the sending the MX domain name. If the domain was previously successful for a tlsa check, and was last queried within timeout_days, the check succeeds. Otherwise the domain name supplied and the result of DANE verfication is added to a in memory TLSA database to check against future queries, and the check fails (meaning qmail-remote(8) will reject the message).

qmail-daned maintains its database in memory. Periodic backups of the database are made to contextFile on the disk, to enable qmail-daned to start with existing tlsa verification data, in case of restart. To keep the in-memory search as efficient as possible, entries older than timeout_days are expired during every request. To keep the in-memory database as small as possible, records older than timeout_days are periodically removed. The default interval is 5 minutes and can be changed by specifiying the -f option. You can force removal of expired records by issuing SIGUSR2 signal to qmail-daned. qmail-daned also backups the in-memory database to contextFile on receipt of SIGTERM or SIGUSR1 signal. The contextFile and its containing directory should be writeable by the user with which qmail-daned process runs. At start-up the file contextFile is read and all records older than timeout days are expired. qmail-daned can maintain an internal hash table for fast domain lookup using the hsearch(3) function.

A control file having the list of domains for which TLSA records needs to be verified, can be maintained in a control file, specified by the -T filename option. If this control file is present, TLSA verification will be skipped for all domains not in this file. If a file with the name filename.cdb exists, qmail-daned will use cdb(3) lookup, in addition to the normal in-memory search, in a table of tlsa verification enforced domains. qmail-daned re-reads this list of domains on receipt of signal SIGHUP. You can use the tlsadomains control file which is also used by qmail-remote(8).

A whitelist of domains not subject to tlsa checking can be specified to qmail-daned by the -w filename option. If a file with the name filename.cdb exists, qmail-daned will use cdb(3) lookup in addition to the normal in-memory search in a table of whitelisted domains. qmail-daned re-reads the whitelist on receipt of signal SIGHUP.

qmail-daned listens on IP address ipaddr, port 1998 for incoming UDP queries. 127.0.0.1 (the loopback address) is recommended for ipaddr if qmail-daned is to serve queries on the same machine. You can specify :: for qmail-daned to listen on wildcard IPV6 address. Specifiying * for ipaddr causes qmail-daned to listen on all addresses.

qmail-daned uses MSG_PEEK flag in recvfrom(2) to determine the length of the packet and then reads the entire packet in one operation.

OPTIONS

-v verbosity
Set verbosity. 0 - minimal, 1 - moderate, 2 - maximum, 3 - include debug messages

-h hash_size
specify the memory for creating a hash using hcreate(3)

-w filename
specify whitelist of IP ranges not subject to tlsa verification.

-t days
timeout for known IPs in days; defaults to 7.

-f minutes
periodic interval, in minutes, after which entries older than timeout days are expired; defaults to 5

-s minutes
save interval for context file, in minutes; defaults to 5

-p port
Alternate port to listen instead of the default 1998

QUERY FORMAT

Queries to qmail-daned are UDP packets containing the domain name(as a string) preceded by D, with the record terminated by an ASCII 0 character.

 Ddomain\0

qmail-remote(8) can delegate DANE validation to qmail-daned(8) if the DANE_VERIFICATION is set to host@port, where host@port represents the IP and port on which qmail-daned(8) is listening. qmail-remote(8) has the domain name (as a string) in UDP packets preceded by q, Sor F, with the record terminated by an ASCII 0 character. In the 'q' mode, qmail-daned(8) just returns if there is a record of DANE verification for domain. In the 'S' or 'F' mode, qmail-daned(8) does not do the actual DANE verification but simply updates its own in memory database with the result from qmail-remote. The character q is for verifying the existence of TLSA RR. The character S, F is for updating the DANE validation as success or failure respectively. By using these modes, qmail-remote and qmail-daned avoid duplicate DANE verification attempts between themselves.

CONTROL FILES

qmail-daned by default looks at /etc/indimail/control for all control files. This path can be changed by defining the CONTROLDIR environment variable.

timeoutconnect
Number of seconds qmail-daned will wait for the remote SMTP server to accept a connection. Default: 60. The kernel normally imposes a 75-second upper limit.

timeoutremote
Number of seconds qmail-daned will wait for each response from the remote SMTP server. Default: 1200.

helohost
Current host name, for use solely in saying hello to the remote SMTP server. Default: me, if that is supplied;

tlsclientmethod
The TLS protocol list. Accepted values are SSLv23, SSLv3, TLSv1, TLSv1_1, TLSv1_2, TLSv1_3. The default is TLSv1_2 for OpenSSL Version < 1.0.1. Without this control file OpenSSL Version >= 1.0.1 uses TLS_client_method(3ossl) where the actual protocol version used will be negotiated to the highest version mutually supported by the client and the server. The supported protocols are SSLv3, TLSv1, TLSv1.1, TLSv1.2 and TLSv1.3. The default location of /etc/indimail/control can be overridden by environment variable CONTROLDIR.

tlsclientciphers
A set of OpenSSL client cipher strings. Multiple ciphers contained in a string should be separated by a colon. The default location of /etc/indimail/control can be overridden by environment variable CONTROLDIR

notlhosts
domains for which qmail-daned will not initiate TLS sesson. This file in /etc/indimail/control or directory defined by the CONTROLDIR envirnoment variable, shouldn't be confused with /etc/indimail/certs/notlshosts directory in the directory or the directory defined by the CERTDIR environment variable.

For TLS sessions, the default location of /etc/indimail/certs can be overridden by environment variable CERTDIR. This affects the location of below files/directories clientcert.pem, servercert.pem, tlshosts/<FQDN>.pem, tlshosts/exhaustivelist, notlshosts/<FQDN>, notlshosts/host.

clientcert.pem
SSL certificate that is used to authenticate with the remote server during a TLS session. If clientcert.pem does not exist, qmail-daned will not negotiate TLS. The default location of /etc/indimail/certs can be overridden by environment variable CERTDIR. clientcert.pem can be overridden by environment variable CLIENTCERT.

tlshosts/<FQDN>.pem
qmail-daned requires TLS authentication from servers for which this file exists (<FQDN> is the fully-qualified domain name of the remote SMTP server). One of the dNSName or the CommonName attributes have to match. The file contains the trusted CA certificates. The default location of /etc/indimail/certs can be overridden by environment variable CERTDIR.

tlshosts/exhaustivelist
if this file exists no TLS will be tried on hosts other than those for which a file tlshosts/<FQDN>.pem exists. The default location of /etc/indimail/certs can be overridden by environment variable CERTDIR.

WARNING: this option may cause mail to be delayed, bounced, doublebounced, or lost.

notlshosts/<FQDN>
qmail-daned will not try TLS on servers for which this file exists (<FQDN> is the fully-qualified domain name of the remote SMTP server). (tlshosts/<FQDN>.pem takes precedence over this file however). The default location of /etc/indimail/certs can be overridden by environment variable CERTDIR.

notlshosts/host
qmail-daned will not try TLS on servers for which this file exists (host is the domain name of the recipient). (tlshosts/<FQDN>.pem takes precedence over this file however). The default location of /etc/indimail/certs can be overridden by environment variable CERTDIR.

tlsadomains
file having the list of MX hosts for which TLSA records needs to be verified. If this control file is present, TLSA verification will be skipped for all domains not in this file. If a file with the name tlsadomains.cdb exists, qmail-daned will use cdb(3) lookup in addition to the normal in-memory search in a table of tlsa verification enforced domains.

SEE ALSO

qmail-remote(8), qdane(1), tlsacheck(3), hcreate(3) hsearch(3) hdestroy(3) recvfrom(2).

AUTHORS qmail-daned is currenty being maintained by Manvendra Bhangui <mbhangui@gmail.com> and is part of the IndiMail package at http://www.indimail.org