opendkim for Debian
-------------------

Generating a key and publishing a TXT record
--------------------------------------------

Selection of key length and rotation of keys are important parts of securely
implementing DKIM.  See https://www.m3aawg.org/sites/maawg/files/news/M3AAWG_DKIM_Key_Rotation_BP-2013-12.pdf
for an extended discussion.

The DKIM spec requires an RSA key between 512 and 2048 bits in length, but
keys shorter than 1024 bits should no longer be used.  2048 bit keys require
a much longer DNS TXT record to publish, so it may not be feasible in all
cases to use the maximum key size.

A 1024 bit key is both the RFC recommended key size and the upstream default.

The easiest way to generate a key is with the opendkim-genkey(8) utility.
For example:

$ opendkim-genkey -b 1024 -d example.com -s selector1

for a 2048 bit key, it would be:

$ opendkim-genkey -b 2048 -d example.com -s selector1

This will create two files: selector1.private, containing the private
RSA key, and selector1.txt, containing the appropriate DNS record for
this key.

Alternately, keys may be generated by hand:

$ openssl genrsa -out selector1.private 1024

Note that this private key should be installed such that it's readable
only by the filter itself and any other software requiring access to
it. Anyone who is able to access it will be able to sign mail as your
domain.

The opendkim package now provides a /etc/dkimkeys for this with correct
permissions.  As discussed in the debian/README.PrivateKeys file installed
in that directory, the private key should be owned by the user that runs the
opendkim filter (opendkim by default) with 0600 permissions.

The public value may then be retrieved with:

$ openssl rsa -in selector1.private -pubout -outform pem

The public key will go into your DNS TXT record under the name
<selector>._domainkey. The TXT record contains a number of tag/value
pairs as described in the DKIM specification. The required p= tag
contains the PEM-formatted (that is, base64-encoded DER) public key,
no header, footer, newlines or spaces. This can be obtained using
a command line like this:

$ openssl rsa -in selector1.private -pubout -outform pem 2>/dev/null | \
grep -v "^-"  | tr -d '\n'

Other useful but optional flags include k= (the key type, "rsa"
by default) and t= (which can have any of the flags "t" and "s",
indicating, respectively, testing mode and scope). Testing mode
instructs recipients to treat signed and unsigned email the same,
allowing the generation and verification of signatures without
any action (yet) being taken.

For example: example.com wishes to sign all of their mail with DKIM.
They choose the selector "mail" and decide, for now, to indicate that
they are in testing mode", until they've verified their configuration.
They might put the following in their DNS:

mail._domainkey.example.com TXT "v=DKIM1; k=rsa; t=y; p=<public key>"

Note that this is not an exhaustive list of features or tags; see below
for a link to the DKIM specifications.

Notes for Postfix users
-----------------------

Postfix users who wish to access the opendkim service via UNIX socket
(the default) may need to add the postfix user to the opendkim
group and ensure that UMask is set to 007 in /etc/opendkim.conf, in
order to make the socket readable by Postfix.

Users may also need to move the socket into a directory accessible by the
Postfix chroot; this can be accomplished by setting the Socket parameter
in /etc/opendkim.conf.

As an alternative, you may opt to connect to the filter over TCP. The
filter can be bound to localhost to prevent other hosts from accessing it.
For example, to bind to port 8891, specify "inet:8891@localhost".

Postfix has no internal differentiation between incoming and outbound mail.
In order to differentiate between mail that should be signed and mail that
should only be verified, it is often better to specify the milter
requirements per-service in master.cf rather than globally in main.cf.  As an
example:

# inbound messages from internet
# will be authenticated by OpenDKIM milter on port 12301
smtp      inet  n       -       -       -       -       smtpd
 .......
  -o smtpd_milters=inet:localhost:12301


# outbound messages have been through amavis
# will be signed by OpenDKIM milter on port 12301
127.0.0.1:10025 inet    n       -       -       -       -       smtpd
 .......
  -o smtpd_milters=inet:localhost:12301

This prevents a message from passing through the filter more than once.

Changing group ownership of socket
----------------------------------

The group ID of the UNIX socket created by opendkim can be changed by
changing the primary GID of the opendkim user, e.g.:
$ usermod -g mail opendkim

Starting OpenDKIM after a database service
------------------------------------------

When using OpenDKIM with an SQL data set, it may be necessary to configure
OpenDKIM to start after the database server.  Otherwise, OpenDKIM might try to
query the database when it is not ready yet.  This will typically result in
failure to start the OpenDKIM service.

To start OpenDKIM after some database service, create drop-in configuration
describing this dependency relation.  For example, if you are using MariaDB, run
"systemctl edit opendkim.service" and add the following:

[Unit]
After=mariadb.service

The same approach can be used to adjust other properties of the opendkim
service.
