Differences between revisions 2 and 37 (spanning 35 versions)
Revision 2 as of 2016-02-22 15:00:43
Size: 1369
Comment: second step of russian translation
Revision 37 as of 2020-01-07 04:39:47
Size: 11656
Editor: PaulWise
Comment: jargon, linking
Deletions are marked like this. Additions are marked like this.
Line 4: Line 4:
Domain Keys Identified Mail (DKIM) combines several existing antiphishing and antispam methods to improve the quality of the classification and identification of legitimate e-mail. Instead of the traditional IP-address, to determine the message sender DKIM adds a digital signature associated with the domain name of the organization.

## If your page gets really long, uncomment this Table of Contents
## <<TableOfContents(2)>>

== dkim ==

=== Postfix and opendkim ===

Install the package: {{{
  apt-get install opendkim opendkim-tools
}}}

Add to the Postfix signature opendkim. For convenience, I keep all the settings in /etc/postfix/dkim/, you can choose a different directory. {{{
  mkdir /etc/postfix/dkim/
}}}

Generate a key for mail.example.com server {{{
  opendkim-genkey -D /etc/postfix/dkim/ -d example.com -s mail
}}}

resulting in the directory /etc/postfix/dkim/ 2 files : mail.private and mail.txt (private and public key, respectively). The key file is necessary to allow read access for the group, which employs OpenDKIM : {{{
  chgrp opendkim /etc/postfix/dkim/ *
  chmod g+r /etc/postfix/dkim/ *
}}}


== See also ==
The '''opendkim''' package is a full-featured DKIM milter implementation
suitable for use with MTAs (mail servers) such as [[Postfix]].

!DomainKeys Identified Mail (DKIM) combines several existing antiphishing and antispam methods to improve the quality of the classification and identification of legitimate e-mail. Instead of the traditional IP-address, to determine the message sender DKIM adds a digital signature associated with the domain name of the organization.

Jump to [[#Quickstart]] for an overview and minimal setup, and refer to
[[#Configuration]] for the complete picture.

{{{#!wiki caution
Page is being revised. This work is now in progress, please try not to edit
much at this point.

(from the maintainer, January 2020)
}}}

<<TableOfContents(2)>>

= Quickstart =

The quickstart instructions in this section describe setting up a minimal, but
functional installation of opendkim for signing and verifying, integrated with
[[Postfix]]. This is the five-minute version of opendkim configuration for the
impatient. For a fuller discussion of the setup options available, please refer
to the subsequent sections.

Let’s go! First, install opendkim:

{{{
sudo apt install opendkim opendkim-tools
}}}

Next, generate the private key for your domain and selector pair:

{{{
sudo opendkim-genkey -D /etc/dkimkeys -d yourdomain.com -s 2020 -S
}}}

Now, edit /etc/opendkim.conf. At a minimum, four parameters need to be adapted:
the domain/selector/key file triple, and the socket. For the socket, the easiest
option is to use a TCP socket listening on a local port.

{{{
Domain yourdomain.com
Selector 2020
KeyFile /etc/dkimkeys/2020.private

Socket inet:8891@localhost
}}}

That’s it for opendkim. Restart the service with
{{{sudo systemctl restart opendkim}}}.

The final step is integrating the opendkim service with Postfix. Edit
/etc/postfix/main.cf to connect the two:

{{{
smtpd_milters = inet:localhost:8891
non_smtpd_milters = $smtpd_milters
}}}

And finally reload the Postfix configuration with
{{{sudo systemctl reload postfix}}}.

That’s it! Your mail is now being signed and verified. Don’t forget to publish
your public key as a TXT record in DNS at {{{2020._domainkey.yourdomain.com}}}.
The generated file /etc/dkimkeys/2020.txt contains that record for your
convenience.

= Configuration =

The following sections discuss opendkim configuration options in more detail.
See the manual page [[http://opendkim.org/opendkim.conf.5.html|opendkim.conf(5)]]
for reference.

These sections assume that you have installed the opendkim and opendkim-tools
packages.

{{{#!wiki note
The opendkim '''configuration file''' can be found at /etc/opendkim.conf. All
configuration parameters should be set in this file.

This needs to be stated, because there is a lot of older, now misleading
information on this online. Previously, one would edit the default settings at
'''/etc/default/opendkim''', and then execute
/lib/opendkim/opendkim.service.generate to generate systemd override files at
/etc/systemd/system/opendkim.service.d/override.conf and
/etc/tmpfiles.d/opendkim.conf. While this is still possible, it is now
recommended to adjust the settings directly in /etc/opendkim.conf.
}}}

== Generating keys ==

For key generation, the opendkim-tools package provides the
'''opendkim-genkey''' program. This program generates a private key named
{{{<selector>.private}}} in the specified directory.

{{{
sudo opendkim-genkey \
    --directory=/etc/dkimkeys \
    --domain=yourdomain.com \
    --selector=2020 \
    --nosubdomains
}}}

You will want to tweak some of these options. For example, you might not want to
forbid subdomain signing with {{{--nosubdomains}}}, or you might want to
restrict usage to email with {{{--restrict}}}. The cryptography has reasonably
strong default settings, so it is usually not necessary to specify {{{--bits}}}
(default: 2048) and {{{--hash-algorithms}}} (default: SHA-256).

The directory /etc/dkimkeys is created by the opendkim package as the
Debian-specific canonical key storage location. It is owned by user opendkim.
You could give it to root instead, but see the next section for a discussion of
key ownership and permissions.

Notice how we execute {{{opendkim-genkey}}} as root. That way,
{{{opendkim-genkey}}} produces key files with the correct, restricted
permissions, owned by root.

In the next section, an alternative scheme is described, where opendkim runs as
unprivileged user opendkim even when it reads the key file. In that case, it is
important that the key file be owned by user opendkim. So, if you plan to use
that scheme, be sure to execute {{{opendkim-genkey}}} as user opendkim instead:

{{{
sudo -u opendkim opendkim-genkey ...
}}}

== User and privileges ==

By default, the opendkim service runs as user opendkim. This is because the
default configuration contains a setting for parameter {{{UserID}}} in
/etc/opendkim.conf:

{{{
UserID opendkim
}}}

This setting instructs opendkim to ''become'' user opendkim.

So, more accurately, the opendkim service starts life as root, does everything
it needs to do as root – such as reading in keys –, and then, before beginning
normal operation, it drops the root privileges and becomes user opendkim. This
is a standard, secure procedure that should be appropriate for most users.

An alternative setup is possible where the opendkim service runs as an
unprivileged user from the very start, and this is described in the following
section.

=== Running as an unprivileged user ===

For setups that have additional security requirements, it is possible to run the
opendkim service as opendkim from the very beginning, with no root privileges
involved at any stage. Please note that most users will not need this.

Create a systemd override file at
/etc/systemd/system/opendkim.service.d/override.conf (you may need to create the
directory too), with the following contents:

{{{
[Service]
User=opendkim
Group=opendkim
}}}

The default {{{UserID opendkim}}} setting in /etc/opendkim.conf can now be
removed, as no privilege dropping is necessary.

Reload the systemd configuration with {{{sudo systemctl daemon-reload}}}, and
restart the opendkim service. It now runs as an unprivileged user.

Ensure that the unprivileged user can actually read the keys in /etc/dkimkeys,
see the discussion in the preceding section.

== Key selection ==

TODO Discuss KeyTable SigningTable

Setup the /etc/opendkim.conf:

{{{
# Specify the list of keys
KeyTable file:/etc/dkimkeys/keytable
# Match keys and domains. To use regular expressions in the file, use refile: instead of file:
SigningTable refile:/etc/dkimkeys/signingtable
# Match a list of hosts whose messages will be signed. By default, only localhost is considered as internal host.
InternalHosts refile:/etc/dkimkeys/trustedhosts
}}}

Now in the file /etc/dkimkeys/keytable, put information about the private key: {{{
mail._domainkey.example.com example.com:mail:/etc/dkimkeys/mail.private
}}}

In the file /etc/dkimkeys/signingtable, specify which key will sign a domain: {{{

# Domain example.com
*@example.com mail._domainkey.example.com
# You can specify multiple domains
# Example.net www._domainkey.example.net
}}}

In the file /etc/dkimkeys/trustedhosts, specify which hosts will have messages signed. If needed, include localhost as it is not implicit: {{{
127.0.0.1
10.1.0.0/16
1.2.3.4/24
}}}

== Socket ==

The opendkim service, being a ‘milter’, needs to provide a communication channel
for the MTA (Postfix). A TCP socket listening on a port only accessible locally
is a reasonable choice that is also easy to set up.

TODO

Some prefer setting up a UNIX domain socket instead, as a faster and more secure
channel (though opinion on this point is divided). This requires a little more
configuration work, and is described in the following section.

=== Using a local UNIX domain socket ===

The UNIX domain socket file must be accessible to clients. In Debian, Postfix
runs in a chroot jail in /var/spool/postfix by default, so the socket must be
below that path.

Postfix does not prescribe a standard location for UNIX sockets in its chroot.
You can mimic the /run directory hierarchy, and place the socket below
/var/spool/postfix/run/opendkim, or you can simply claim a top-level directory
like /var/spool/postfix/opendkim. Here we go with the latter.

First, create the directory, owned by opendkim and world-inaccessible:

{{{
sudo mkdir -m o-rwx /var/spool/postfix/opendkim
sudo chown opendkim: /var/spool/postfix/opendkim
}}}

Then configure the socket in /etc/opendkim.conf:

{{{
Socket local:/var/spool/postfix/opendkim/opendkim.sock
}}}

Add user postfix to group opendkim. Postfix can then rely on the group
permissions to actually access the socket:

{{{
sudo adduser postfix opendkim
}}}

Finally, adjust the Postfix configuration in /etc/postfix/main.cf:

{{{
smtpd_milters = unix:/opendkim/opendkim.sock
non_smtpd_milters = $smtpd_milters
}}}

== DNS resolution ==

TODO Discuss libunbound and local resolver setup

{{{
Nameservers 127.0.0.1
}}}

{{{
ResolverConfiguration /etc/opendkim/unbound.conf
}}}

== Postfix integration ==

TODO discuss bounce and default accept action

{{{
milter_default_action = accept
internal_mail_filter_classes = bounce
}}}

= Troubleshooting =

Try to send a mail. If you see in /var/log/mail.log something like {{{
Aug 13 13:18:00 yourhostname opendkim[15765]: OpenDKIM Filter: Unable to bind to port local:/var/spool/postfix/var/run/opendkim/opendkim.sock: No such file or directory
Aug 13 13:18:00 yourhostname opendkim[15765]: OpenDKIM Filter: Unable to create listening socket on conn local:/var/spool/postfix/var/run/opendkim/opendkim.sock
}}}
then that probably means that you did not create the directory for the socket (see above) or you gave it the wrong permissions. Double-check!

If you see {{{
Aug 13 13:46:19 yourhostname postfix/cleanup[17588]: warning: connect to Milter service unix:/var/run/opendkim/opendkim.sock: No such file or directory
}}}
then that means postfix could not read the socket. Did you put postfix in group opendkim? Are the permissions on /var/spool/postfix/var/run/opendkim/opendkim.sock correct?

If everything is correct, that does not mean your configuration of DKIM is complete: you must configure the DNS.

= DNS Configuration =

Add a TXT record for your example.com domain

||<#80FF80>'''Record Name'''||<#80FF80>'''Record Type'''||<#80FF80>'''Text'''||
|| mail._domainkey || TXT || v=DKIM1; k=rsa; p=MI.. (take it from /etc/dkimkeys/mail.txt file; remove the >"< and connect the lines after p= to one key.) ||

= Testing =

You can test your installation with opendkim-testkey: {{{
# opendkim-testkey -d example.com -s mail -vvv

opendkim-testkey: using default configfile /etc/opendkim.conf
opendkim-testkey: checking key 'mail._domainkey.example.com'
opendkim-testkey: key not secure
opendkim-testkey: key OK
}}}

= See also =
Line 33: Line 318:
 * [[http://opendkim.org/opendkim.conf.5.html|opendkim.conf(5)]]: Configuration parameters manual page
 * [[http://opendkim.org/opendkim-lua.3.html|opendkim-lua(3)]]: Lua scripting interface manual page

Translation(s): English - Русский


The opendkim package is a full-featured DKIM milter implementation suitable for use with MTAs (mail servers) such as Postfix.

DomainKeys Identified Mail (DKIM) combines several existing antiphishing and antispam methods to improve the quality of the classification and identification of legitimate e-mail. Instead of the traditional IP-address, to determine the message sender DKIM adds a digital signature associated with the domain name of the organization.

Jump to #Quickstart for an overview and minimal setup, and refer to #Configuration for the complete picture.

Page is being revised. This work is now in progress, please try not to edit much at this point.

(from the maintainer, January 2020)

Quickstart

The quickstart instructions in this section describe setting up a minimal, but functional installation of opendkim for signing and verifying, integrated with Postfix. This is the five-minute version of opendkim configuration for the impatient. For a fuller discussion of the setup options available, please refer to the subsequent sections.

Let’s go! First, install opendkim:

sudo apt install opendkim opendkim-tools

Next, generate the private key for your domain and selector pair:

sudo opendkim-genkey -D /etc/dkimkeys -d yourdomain.com -s 2020 -S

Now, edit /etc/opendkim.conf. At a minimum, four parameters need to be adapted: the domain/selector/key file triple, and the socket. For the socket, the easiest option is to use a TCP socket listening on a local port.

Domain   yourdomain.com
Selector 2020
KeyFile  /etc/dkimkeys/2020.private

Socket   inet:8891@localhost

That’s it for opendkim. Restart the service with sudo systemctl restart opendkim.

The final step is integrating the opendkim service with Postfix. Edit /etc/postfix/main.cf to connect the two:

smtpd_milters = inet:localhost:8891
non_smtpd_milters = $smtpd_milters

And finally reload the Postfix configuration with sudo systemctl reload postfix.

That’s it! Your mail is now being signed and verified. Don’t forget to publish your public key as a TXT record in DNS at 2020._domainkey.yourdomain.com. The generated file /etc/dkimkeys/2020.txt contains that record for your convenience.

Configuration

The following sections discuss opendkim configuration options in more detail. See the manual page opendkim.conf(5) for reference.

These sections assume that you have installed the opendkim and opendkim-tools packages.

The opendkim configuration file can be found at /etc/opendkim.conf. All configuration parameters should be set in this file.

This needs to be stated, because there is a lot of older, now misleading information on this online. Previously, one would edit the default settings at /etc/default/opendkim, and then execute /lib/opendkim/opendkim.service.generate to generate systemd override files at /etc/systemd/system/opendkim.service.d/override.conf and /etc/tmpfiles.d/opendkim.conf. While this is still possible, it is now recommended to adjust the settings directly in /etc/opendkim.conf.

Generating keys

For key generation, the opendkim-tools package provides the opendkim-genkey program. This program generates a private key named <selector>.private in the specified directory.

sudo opendkim-genkey \
    --directory=/etc/dkimkeys \
    --domain=yourdomain.com \
    --selector=2020 \
    --nosubdomains

You will want to tweak some of these options. For example, you might not want to forbid subdomain signing with --nosubdomains, or you might want to restrict usage to email with --restrict. The cryptography has reasonably strong default settings, so it is usually not necessary to specify --bits (default: 2048) and --hash-algorithms (default: SHA-256).

The directory /etc/dkimkeys is created by the opendkim package as the Debian-specific canonical key storage location. It is owned by user opendkim. You could give it to root instead, but see the next section for a discussion of key ownership and permissions.

Notice how we execute opendkim-genkey as root. That way, opendkim-genkey produces key files with the correct, restricted permissions, owned by root.

In the next section, an alternative scheme is described, where opendkim runs as unprivileged user opendkim even when it reads the key file. In that case, it is important that the key file be owned by user opendkim. So, if you plan to use that scheme, be sure to execute opendkim-genkey as user opendkim instead:

sudo -u opendkim opendkim-genkey ...

User and privileges

By default, the opendkim service runs as user opendkim. This is because the default configuration contains a setting for parameter UserID in /etc/opendkim.conf:

UserID opendkim

This setting instructs opendkim to become user opendkim.

So, more accurately, the opendkim service starts life as root, does everything it needs to do as root – such as reading in keys –, and then, before beginning normal operation, it drops the root privileges and becomes user opendkim. This is a standard, secure procedure that should be appropriate for most users.

An alternative setup is possible where the opendkim service runs as an unprivileged user from the very start, and this is described in the following section.

Running as an unprivileged user

For setups that have additional security requirements, it is possible to run the opendkim service as opendkim from the very beginning, with no root privileges involved at any stage. Please note that most users will not need this.

Create a systemd override file at /etc/systemd/system/opendkim.service.d/override.conf (you may need to create the directory too), with the following contents:

[Service]
User=opendkim
Group=opendkim

The default UserID opendkim setting in /etc/opendkim.conf can now be removed, as no privilege dropping is necessary.

Reload the systemd configuration with sudo systemctl daemon-reload, and restart the opendkim service. It now runs as an unprivileged user.

Ensure that the unprivileged user can actually read the keys in /etc/dkimkeys, see the discussion in the preceding section.

Key selection

TODO Discuss ?KeyTable ?SigningTable

Setup the /etc/opendkim.conf:

# Specify the list of keys
KeyTable file:/etc/dkimkeys/keytable
# Match keys and domains. To use regular expressions in the file, use refile: instead of file:
SigningTable refile:/etc/dkimkeys/signingtable 
# Match a list of hosts whose messages will be signed. By default, only localhost is considered as internal host.
InternalHosts refile:/etc/dkimkeys/trustedhosts

Now in the file /etc/dkimkeys/keytable, put information about the private key:

mail._domainkey.example.com example.com:mail:/etc/dkimkeys/mail.private 

In the file /etc/dkimkeys/signingtable, specify which key will sign a domain:

# Domain example.com
*@example.com mail._domainkey.example.com
# You can specify multiple domains
# Example.net www._domainkey.example.net 

In the file /etc/dkimkeys/trustedhosts, specify which hosts will have messages signed. If needed, include localhost as it is not implicit:

127.0.0.1
10.1.0.0/16
1.2.3.4/24

Socket

The opendkim service, being a ‘milter’, needs to provide a communication channel for the MTA (Postfix). A TCP socket listening on a port only accessible locally is a reasonable choice that is also easy to set up.

TODO

Some prefer setting up a UNIX domain socket instead, as a faster and more secure channel (though opinion on this point is divided). This requires a little more configuration work, and is described in the following section.

Using a local UNIX domain socket

The UNIX domain socket file must be accessible to clients. In Debian, Postfix runs in a chroot jail in /var/spool/postfix by default, so the socket must be below that path.

Postfix does not prescribe a standard location for UNIX sockets in its chroot. You can mimic the /run directory hierarchy, and place the socket below /var/spool/postfix/run/opendkim, or you can simply claim a top-level directory like /var/spool/postfix/opendkim. Here we go with the latter.

First, create the directory, owned by opendkim and world-inaccessible:

sudo mkdir -m o-rwx /var/spool/postfix/opendkim
sudo chown opendkim: /var/spool/postfix/opendkim

Then configure the socket in /etc/opendkim.conf:

Socket local:/var/spool/postfix/opendkim/opendkim.sock

Add user postfix to group opendkim. Postfix can then rely on the group permissions to actually access the socket:

sudo adduser postfix opendkim

Finally, adjust the Postfix configuration in /etc/postfix/main.cf:

smtpd_milters = unix:/opendkim/opendkim.sock
non_smtpd_milters = $smtpd_milters

DNS resolution

TODO Discuss libunbound and local resolver setup

Nameservers 127.0.0.1

ResolverConfiguration /etc/opendkim/unbound.conf

Postfix integration

TODO discuss bounce and default accept action

milter_default_action = accept
internal_mail_filter_classes = bounce

Troubleshooting

Try to send a mail. If you see in /var/log/mail.log something like

Aug 13 13:18:00 yourhostname opendkim[15765]: OpenDKIM Filter: Unable to bind to port local:/var/spool/postfix/var/run/opendkim/opendkim.sock: No such file or directory
Aug 13 13:18:00 yourhostname opendkim[15765]: OpenDKIM Filter: Unable to create listening socket on conn local:/var/spool/postfix/var/run/opendkim/opendkim.sock

then that probably means that you did not create the directory for the socket (see above) or you gave it the wrong permissions. Double-check!

If you see

Aug 13 13:46:19 yourhostname postfix/cleanup[17588]: warning: connect to Milter service unix:/var/run/opendkim/opendkim.sock: No such file or directory

then that means postfix could not read the socket. Did you put postfix in group opendkim? Are the permissions on /var/spool/postfix/var/run/opendkim/opendkim.sock correct?

If everything is correct, that does not mean your configuration of DKIM is complete: you must configure the DNS.

DNS Configuration

Add a TXT record for your example.com domain

Record Name

Record Type

Text

mail._domainkey

TXT

v=DKIM1; k=rsa; p=MI.. (take it from /etc/dkimkeys/mail.txt file; remove the >"< and connect the lines after p= to one key.)

Testing

You can test your installation with opendkim-testkey:

# opendkim-testkey -d example.com -s mail -vvv

opendkim-testkey: using default configfile /etc/opendkim.conf
opendkim-testkey: checking key 'mail._domainkey.example.com'
opendkim-testkey: key not secure
opendkim-testkey: key OK

See also


CategoryNetwork