Provided by: dkim-rotate_1.1_all bug

NAME

       dkim-rotate - Principles of Operation

INTRODUCTION

       dkim-rotate  is  a  tool  for  managing DKIM (email antispam) keys in a manner that avoids
       unnecessarily making emails nonrepudiable.

   Problem statement
       Using a static or nearly-static DKIM signing key enables anyone who obtains a copy  of  an
       email to verify its authenticity.

       This can be used to verify the authenticity of data from a data breach, for example.  This
       is not a desirable property, from the point of view of an email system’s users, and wasn’t
       an intended consequence of DKIM’s antispam function.

       For  fuller  discussion  of  the  nonrepudiability problem with DKIM, see the blog post Ok
       Google: please publish your DKIM secret keys, referenced in the SEE ALSO section.

   Solution - function of dkim-rotate
       We periodically generate a new key.  We deadvertise old keys (removing them from  the  set
       advertised in the DNS), We publish the private halves of old keys.

       The  overall result is that because old emails are forgeable (by anyone, since the private
       key has been published), emails become no longer nonrepudiable.

       We add appropriate warnings, and alter the DNS, to alert naive verifiers to the situation.

   Output and state files
       dkim-rotate will maintain and update the following output files and directories:

       /var/lib/dkim-rotate/instance/zone
              Zonefile in standard master file  syntax.   Created  by  taking  the  config  file,
              editing  the  serial number before ;!SERIAL, and appending TXT RR definitions.  The
              appended RRs have single-character alphabetic labels,  the  selectors.   See  dkim-
              rotate(5).

       /var/lib/dkim-rotate/instance/priv/keyname.pem
              Private key for use by the MTA.  See MTA CONFIGURATION.

       /var/lib/dkim-rotate/instance/exim
              File in format suitable for Exim ${lsearch }.  See MTA CONFIGURATION.

       /var/lib/dkim-rotate/instance/pub/
              Directory  where  private  keys  are  published  (deliberately  leaked).   See  KEY
              PUBLICATION.

       /var/lib/dkim-rotate/instance/state
              Principal state file.

       /var/lib/dkim-rotate/instance/...
              Other state and temporary files are stored here.

       (Each  dkim-rotate  instance  is  completely  separate;  they  do  not  share  state,   or
       configuration.)

SELECTORS

       dkim-rotate  maintains  a  collection  of DKIM keys.  The (currently advertised) keys each
       have a “selector”, dkim-rotate uses a small fixed set of  selectors,  in  rotation.   Each
       selector  is  an  (ASCII  lowercase)  letter,  so  dkim-rotate  supports  use  of up to 26
       selectors.  The default is 12.

   Current keys - selectors
       A DKIM signature found in an email indicates  where  to  find  the  key.   It  includes  a
       “selector”,  which  is a set of DNS labels to be prepended to the base DKIM domain for the
       mail domain which originated the email and by whose authority the message is being signed.

       A selector can be reused as soon as the key  which  was  previously  using  that  selector
       should  longer be advertised.  When creating keys, dkim-rotate will automatically choose a
       suitable available selector.

       The selector in DKIM terms is (usually)  the  dkim-rotate  selector  plus  a  fixed  label
       indicating  the signing authority (ie, the dkim-rotate instance).  dkim-rotate itself does
       not know the actual DKIM selectors; the suffix is added in the MTA and DNS configurations.

   DNS selector advertisement
       dkim-rotate outputs a  DNS  zonefile,  complete  with  serial  number,  as  /var/lib/dkim-
       rotate/instance/zone.

       Usually,  this  will  be  published directly by a nameserver, as a dedicated DNS zone, not
       used for other purposes.  This allows the management of the  mail  domains’  zones  to  be
       separated from the DKIM system.

       Let  us  imagine that the dkim-rotate output zone is dkim-rotate.example.net.  Within that
       zone, dkim-rotate will create DKIM TXT records, which look like this in  the  output  zone
       file:

              k IN TXT "v=DKIM1; h=sha256; s=email; n=...; p=..."

       This implies the following RRset:

              k.dkim-rotate.example.net. IN TXT "v=DKIM1; ..."

       A  mail domain (let us imagine, example.com), which wishes to indicate that this system is
       authorised to make DKIM signatures, will use a set of CNAMEs to delegate that authority:

              $ORIGIN example.com.
              a.example-net._domainkey     CNAME   a.dkim-rotate.example.net.
              b.example-net._domainkey     CNAME   b.dkim-rotate.example.net.
              c.example-net._domainkey     CNAME   c.dkim-rotate.example.net.
              d.example-net._domainkey     CNAME   d.dkim-rotate.example.net.
              e.example-net._domainkey     CNAME   e.dkim-rotate.example.net.
              f.example-net._domainkey     CNAME   f.dkim-rotate.example.net.
              g.example-net._domainkey     CNAME   g.dkim-rotate.example.net.
              h.example-net._domainkey     CNAME   h.dkim-rotate.example.net.
              i.example-net._domainkey     CNAME   i.dkim-rotate.example.net.
              j.example-net._domainkey     CNAME   j.dkim-rotate.example.net.
              k.example-net._domainkey     CNAME   k.dkim-rotate.example.net.
              l.example-net._domainkey     CNAME   l.dkim-rotate.example.net.

       So, overall, we have something like this:

              example.com.                           MX      mx0.example.com.

              k.example-net._domainkey.example.com.  CNAME   k.dkim-rotate.example.net.
              k.dkim-rotate.example.net.             TXT     "v=DKIM1; ..."

   DNS output file and nameserver configuration
       The zonefile is written to /var/lib/dkim-rotate/instance/zone.

       After it has been updated, dkim-rotate runs rndc  reload  (or  the  configured  dns_reload
       command).

       If  this  all  occurs  successfully,  dkim-rotate  assumes that dns_lag later, the new DNS
       records (and any deletions) are available everywhere.

       dkim-rotate does not use DNS Dynamic Update.

MTA CONFIGURATION

       dkim-rotate provides the selector, and the private key, to the MTA.

       This is done by writing /var/lib/dkim-rotate/instance/exim.  This is in a  key-colon-value
       format, which is convenient for use by Exim’s lsearch lookup facility.

       After  this  file is updated, dkim-rotate runs the configured mta_reload command.  This is
       just true (a no-op) by default (and Exim doesn’t need it).

   MTA configuration output format
       The output file is lines of the form:

              key: value

       It may also contain #-comment lines.  The values are literal text, without any quotes (and
       therefore cannot contain newlines).

       The keys are;

       privkey
              The  filename  of  the private key to use.  This will be in the form /var/lib/dkim-
              rotate/instance/priv/hex.pem.

       selector
              The selector under which the corresponding public key is advertised.

       header_note
              Some text which it would be useful to put into the email headers.  It  starts  NOTE
              REGARDING DKIM KEY COMPROMISE.

              This could be put into a note= or warning= tag in the actual DKIM-Signature header.

              If  that  is not possible (e.g. Exim doesn’t support it) it could be put into DKIM-
              Signature-Warning, say.  It is probably a good idea to arrange that  it  is  itself
              covered  by the signature, to make it more complicated for an adversary to strip it
              out.

       url, readme_url
              URLs for the instance’s public WWW directory, the README.txt file, corresponding to
              this instance.

       key_reveal_url
              The  URL  at which the private key will be revealed to the world, after the key has
              been retired.  (Obviously, when this URL appears in the /exim file, the URL is  not
              yet valid.)

   Example Exim configuration
       DKIM  signing is done with additional options on the smtp transport.  The mailserver ought
       not to be a signing oracle for arbitrary incoming emails which are being relayed  (eg  via
       forward  files)  —  only  for  emails  generated locally, or from appropriately authorised
       places.  And we should choose, for the signing domain, the domain  which  appears  in  the
       From: header, and sign only if DKIM is enabled for that domain.

       The required config looks something like this:

              smtp:
                driver = smtp
                # ... other options ...
                # lookup fd caching ensures coherence of all of these, see exim 4.94 spec 9.8
                dkim_domain = ${if  and{                                  \
                  { match_domain {${domain:$h_from:}} {+dkim_domains} }   \
                  { !def:h_dkim-signature: }                              \
                  { !def:h_list-id: }                                     \
                  { or{                                                   \
                       { def:authenticated_id }                           \
                       { match_ip {$sender_host_address} {+relay_hosts} } \
               }}                                                         \
               } {${domain:$h_from:}} {} }
                dkim_selector = ${lookup {selector} lsearch {/var/lib/dkim-rotate/example-net/exim} }.example-net
                dkim_private_key = ${lookup {privkey} lsearch {/var/lib/dkim-rotate/example-net/exim} }
                dkim_sign_headers = _DKIM_SIGN_HEADERS : DKIM-Signature-Warning
                headers_add = ${if  and{                                  \
                  { match_domain {${domain:$h_from:}} {+dkim_domains} }   \
                  { !def:h_dkim-signature: }                              \
                  { !def:h_list-id: }                                     \
                  { or{                                                   \
                       { def:authenticated_id }                           \
                       { match_ip {$sender_host_address} {+relay_hosts} } \
               }}                                                         \
               } {DKIM-Signature-Warning: ${lookup {header_note} lsearch {/var/lib/dkim-rotate/example-net/exim} }} }

   Example Exim configuration (perl version)
       It  is  a  shame  that  Exim  doesn’t  seem  to have better and more cooked facilities for
       controlling dkim signing.  The required configuration is quite annoying repetitive.

       The following Perl can generate something like the config above:

              sub dkim_lookup { "\${lookup {$_[0]} lsearch {/var/lib/dkim-rotate/example-net/exim} }" }
              my $dkim_domain_expr = "\${domain:\$h_from:}";
              my $dkim_condition = <<END;
               and{                                                          \\
                  { match_domain {$dkim_domain_expr} {+dkim_domains} }       \\
                  { !def:h_dkim-signature: }                                 \\
                  { !def:h_list-id: }                                        \\
                  { or{                                                      \\
                       { def:authenticated_id }                              \\
                       { match_ip {\$sender_host_address} {+relay_hosts} }   \\
               }}                                                            \\
              END

              my $dkim_smtp_options = <<END;
                # lookup fd caching ensures coherence of all of these, see exim 4.94 spec 9.8
                dkim_domain = \${if $dkim_condition } {$dkim_domain_expr} {} }
                dkim_selector = ${\ dkim_lookup('selector')}.example-net
                dkim_private_key = ${\ dkim_lookup('privkey')}
                dkim_sign_headers = _DKIM_SIGN_HEADERS : DKIM-Signature-Warning
                headers_add = \${if $dkim_condition } {DKIM-Signature-Warning: ${\ dkim_lookup('header_note')}} }
              END
              $dkim_smtp_options =~ s{^(.*\S)\s*\\$}{ sprintf "%-70s\t\\", $1 }mge;

KEY PUBLICATION

       dkim-rotate  publishes  secret  keys  by  writing  them  to  a  directory   /var/lib/dkim-
       rotate/instance/pub/.   This  is  an ever-growing archive.  Nothing ahould be deleted from
       it.

       This directory  should  be  made  available  via  webserver,  and  the  corresponding  URL
       configured via the pub_url config directive.

       dkim-rotate  will  make  subdirectories 00 to ff here.  These are radix prefix directories
       which exist both to avoid the creation of a very large single directory of key files,  and
       to make it harder to enumerate the private keys.

       In particular, these subdirectories are not globally-readable, although they are globally-
       executable.  The webserver should run without privilege, so that the individual  keys  can
       be read, but the directories cannot be listed (and won’t be archived by any crawlers).

   README
       dkim-rotate will make a README.txt file in the pub/ directory.

       (Currently there is no way to configure the contents of this file.)

KEY LIFECYCLE

   Key statuses and lifecycle
        abbrev    meaning             time_t       (in   selector         how many
                                      statefile)
       ──────────────────────────────────────────────────────────────────────────────────
          -1      advertised;   not   first advertised   advertised       0/1
                  yet used                               (DNS)
          +0      signing             (first used; not   advertised       0/1; usually 1
                                      relevant)          (DNS)

         +N..     emails              last   used  for   advertised       [0          ..
                  percolating         signing            (DNS)            sel_limit]
         +X..     deadvertisment      last advertised    archival only    [0        ..];
                  propagating                                             usually 0/1
           R      revealed            (not  longer  in   archival only    many
                                      statefile)

   Example key lifecycle
             -0200 [0][1]     generate   and
                              advertise
                                               dns_lag (4h) + 2h slop
             +0400            start signing
                                               1d key rollover interval
             +0400 +1d        stop signing
                                               email_lag (3.5d timeout + 4h retry)  +
                                               2h slop
             -0200 +5d        deadvertise
                                               dns_lag (4h) + 2h slop
             +0400 +5d        reveal

       [0] -0200 means “2200 the previous day”

       [1]  If  a  free  selector is already available, this might be generated and advertised at
       +0400 -1d.

   Example cron configuration
                #mins hrs dom mon dow command
                26 22 * * *       dkim-rotate --minor
                26 4  * * *       dkim-rotate --major

       These jobs should be scheduled in a suitable local time  (in  the  timezone  of  the  mail
       server’s  users),  because  it  is good for all mails sent on a particular calendar day to
       become un-nonrepudiable (and un-deliverable) at once.

       To cope nicely with timezone changes the interval between --minor and the main run  should
       be  at  least  dns_lag  +  1h  +  an  allowance  for  processing  time etc.  The suggested
       configuration has a 6h interval, which suits the default dns_lag of 4h.

AUTHOR

       Copyright 2022 Ian Jackson and contributors to dkim-rotate.
       There is NO WARRANTY.
       SPDX-License-Identifier: GPL-3.0-or-later

SEE ALSO

       dkim-rotate(5)
              Configuration file

       dkim-rotate(1)
              Command line reference

       RFC6376
              DKIM Signatures

       Ok Google: please publish your DKIM secret keys
              article by Matthew Green

              <https://blog.cryptographyengineering.com/2020/11/16/ok-google-please-publish-your-
              dkim-secret-keys/>

                                                                                   dkim-rotate(7)