s-dkim-sign.8

.\"@ s-dkim-sign - [postfix-only] DKIM-sign-only milter.
.\"
.\" Copyright (c) 2024 - 2025 Steffen Nurpmeso <steffen@sdaoden.eu>.
.\" SPDX-License-Identifier: ISC
.\"
.\" Permission to use, copy, modify, and/or distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.
.Dd Oct 10, 2024
.ds VV \\%v0.6.2
.ds XX \\%S-DKIM-SIGN
.ds Xx \\%S-dkim-sign
.ds xx \\%s-dkim-sign
.
.Dt \*(XX 8
.Os
.Mx -enable
.
.
.Sh NAME
.Nm \*(Xx \%[\*(VV]
.Nd DKIM sign-only milter
.
.
.Sh SYNOPSIS
.
.Nm \*(xx
.Op options
.Nm \*(xx
.Op options
.Fl Fl test-mode
.Op options
.Pp
.Nm \*(xx-key-create
.Op Ar ed25519 Ns | Ns Ar rsa Ns Op :bits
.Ar path-prefix
.
.
.Mx -toc -tree html pdf ps xhtml
.
.
.Sh DESCRIPTION
.
A
.Xr postfix 1 Ns
-only RFC 6376/[8301]/8463 D(omain)K(eys) I(dentified) M(ail)
sign-only milter.
DKIM permits a person, role, or organization to claim responsibility for
a message by associating a domain name (RFC 1034; rather: RFC 5321) with
the message (RFC 5322) through a cryptographically verifiable signature
stored in a
.Ql DKIM-Signature
mail header.
The signature can be validated by fetching the appropriate public key(s)
from the domain's DNS (RFC 8499) record.
.
.Pp
.Sy Note:
the program is intended to be started via the
.Xr postfix 1
.Xr spawn 8
daemon, which takes care of the correct user and group credentials,
timeouts and stale server garbage collection etc.;
efficient operation requires postfix versions which support the
milter operation
.Ql SMFIC_QUIT_NC
(not yet as of version 3.9), elder versions will start a new program
instance for every SMTP or local connection.
.
.Pp
The general operation of milters is that they see all messages passing
the mail server, without knowing whether they are
.Dq incoming
or
.Dq outgoing .
This milter will sign all messages from
.Ql localhost
or configured
.Fl Fl client Ns
s with all registered
.Fl Fl key Ns
s; with
.Fl Fl milter-macro
.Ql sign
only server connections announcing a match are considered.
It will perform configured
.Fl Fl remove Ns
s for messages not from
.Ql localhost
or configured
.Fl Fl client Ns
s; again, with
.Fl Fl milter-macro
.Ql verify
only dedicated connections are considered.
Decisions are only narrowed down: once
.Ql sign
or
.Ql verify
paths are taken only
.Ql pass
remains as an option.
(Administrative automatic removals are performed for any decision but
.Ql pass ,
for example
.Ql DKIM-Store . )
.
.Pp
Fine-grained control of signing activity is available via
.Fl Fl sign
relations that link specific
.Fl Fl key Ns
s to mail addresses, domain names, or domain name wildcards,
as are extracted from (the first address of)
.Ql From
headers of messages seen by the milter.
Receivers will search for the public key DNS record of either the domain
defined by the matching
.Fl Fl sign
relation, the specified
.Fl Fl domain-name ,
or the one from the extracted address; if, without
.Fl Fl sign
relations, that then is
.Ql @localhost ,
however, a
.Ql pass
decision is made.
.
.Pp
In the following example all messages from
.Ql localhost
via all deliveries
.Pf ( Ql milter_macro_daemon_name
global) of the user
.Ql joe
at domain
.Ql his.domain ,
including all subdomains, for example
.Ql at.home.his.domain ,
are signed with the key
.Ql adaedape ,
all messages from
.Ql my.domain
including all subdomains with the keys
.Ql adaedape
and
.Ql rsape ,
however, if messages come from the domain
.Ql bla.my.domain
only the key
.Ql adaedape
will be used.
Other messages will not be signed.
.
.Bd -literal -offset indent
#@ /etc/postfix/main.cf:

milter_default_action = accept
non_smtpd_milters = unix:private/dkim-sign
smtpd_milters = unix:private/dkim-sign
milter_macro_daemon_name = outwall

#@ /etc/postfix/master.cf:

smtp inet n - n - - smtpd
  -o smtpd_tls_security_level=may
  -o milter_macro_daemon_name=ingress
localhost:smtp inet n - n - - smtpd
  -o syslog_name=localsmtp
#localhost:421 inet n - n - - smtpd
# -o syslog_name=lhlist
# -o smtpd_milters=unix:private/dkim-sign-list
# (address via mailman:
# DELIVERY_MODULE = 'SMTPDirect'
# SMTPHOST = 'localhost'
# SMTPPORT = 421)
..
dkim-sign unix - n n - - spawn
  user=ANON-USR
  argv=/usr/libexec/s-dkim-sign -R /etc/dkim-sign.rc
#dkim-sign-list unix - n n - - spawn
#  user=ANON-USR
#  argv=/usr/libexec/s-dkim-sign -R /etc/dkim-sign.rc --header-seal=+

#@ /etc/dkim-sign.rc

milter-macro sign, {daemon_name}, outwall
milter-macro verify, {daemon_name}, ingress

key rsa-sha256, rsape, /etc/dkim-pri-rsa.pem
#key big_ed-sha256, edape, /etc/dkim-pri-ed25519.pem
key adaed25519-sha256, adaedape, /etc/dkim-pri-ed25519.pem

#client localhost

domain-name my.domain

sign .my.domain
sign bla.my.domain , ,  ::adaedape : :
sign joe@.his.domain,his.domain,adaedape

header-sign *
header-seal *
ttl 259200

remove a-r, !, .my.domain, .his.domain
remove dkim, !, .com
remove mo-dkim, .
remove aucy
remove ip
.Ed
.
.Pp
.Nm \*(xx-key-create
is a simple shell script which uses the
.St -p1003.2
standard tools and
.Xr openssl 1
found in the
.Ev PATH
to create the private/public key tuple to anticipate in DKIM, as well
as readily formatting the according DNS record.
In interactive usage it will print a result abstract.
.
.
.Sh OPTIONS
.
Options may be given in short or long form,
.Fl Fl resource-file Ns
s only support the long form, and only a (logical) option subset.
.Fl Fl test-mode
performs a dry-run configuration syntax test, and outputs a normalized
resource file.
.
.
.Bl -tag -width ".It Fl BaNg"
.Mx Fl client
.It Fl Fl client Oo Ar action, Oc Ns Ar spec , Fl C Ns ..
Define rules for connecting clients as announced by the milter macro
.Ql _
.Pf ( Xr postfix 1
passes only
.Dq validated client name and address Ns
).
The optional
.Ar action
is either
.Ql s[ign]
(default),
.Ql v[erify]
or
.Ql p[ass]
(no action),
.Ar spec
is either a domain name or an IPv4 or IPv6 internet address, optionally
in RFC 1519 CIDR notation with network mask.
Domain names (see
.Fl Fl domain-name )
are matched exactly unless starting with a period
.Ql \&.
to enforce wildcard matches for it and its subdomains; only period
.Ql \&.
is a
.Dq super-\:wildcard
matching all domains.
Dictionaries are used except for CIDR ranges, which are matched last and
in the given order.
Defining any rule replaces the built-in
.Ql sign,localhost
/
.Ql verify,\&.
pair, and establishes
a default action
.Ql pass,\&. .
.Bd -literal -offset indent
--client 127.0.0.1
--client=exact.match
# Match d.a.s but also a.b.c.d.a.s
-C \&.d.a.s
--client=pass,2a03:2880:20:6f06::/64
.Ed
.
.Mx Fl client-file
.It Fl Fl client-file Oo Ar action, Oc Ns Ar path , Fl c Ns ..
Load a file of entries in the syntax described for the
.Ar spec
argument of
.Fl Fl client ;
Lines are read as via
.Fl Fl resource-file .
An optional
.Ar action
applies to all entries.
.
.Mx Fl debug
.It Fl Fl debug
Dry-run sandbox: no real action is performed, but only logged.
All messages remain unmodified.
.
.Mx Fl domain-name
.It Fl Fl domain-name Ar domain , Fl d Ns ..
Define the
.Ql d=
domain name to be used in signatures unless overwritten by a
.Fl Fl sign
relation.
If unset, and without relation, the domain name of (the first address of)
.Ql From
will be announced in signatures.
.Ar domain
can start with RFC 20 ASCII letters and digits, followed by also
.Ql \&.
period and
.Ql -
hyphen-minus; no other verification is performed.
The DKIM standard requires a real
.Ar domain
name, literal( addresse)s are not allowed.
Receivers will try to locate the public key(s) identified by the chosen
.Fl Fl key Ns
s selectors as DNS TXT records in the form
.Ql Ar selector Ns ._domainkey. Ns Ar domain .
.
.Mx Fl header-sign
.It Fl Fl header-sign Ar list , Fl ~ Ns ..
Define (comma-separated)
.Ar list
of case-insensitive header fields (names) to sign.
Alternatively built-in defaults may be used and modified by starting
.Ar list
with a commercial at
.Ql @ ,
or the recommendet extended variant with asterisk
.Ql * ;
further entries may then be prefixed with exclamation mark
.Ql \&!
to denote desired list exclusion.
Attempts to exclude
.Ql From
are errors, no other rules apply (untested: name validity, duplicates).
An effectively empty list is not used.
.Bd -literal -offset indent
--header-sign=@!in-reply-to,,,!to,!cc,openpgp
--header-sign '* !message-id , !to ,, !cc,BlahBlahBlah'
.Ed
.
.Mx Fl header-sign-show
.It Fl Fl header-sign-show
Show the built-in
.Fl Fl header-sign
lists, then exit.
.
.Mx Fl header-seal
.It Fl Fl header-seal Ar list , Fl ! Ns ..
Like
.Fl Fl header-sign ,
but
.Dq oversign ,
meaning DKIM signatures include an (additional) empty instance of given
headers, as such preventing attempts to inject headers not covered by,
and therefore not verified through the signature (without causing errors).
Default lists are built-in, but sealing needs to be activated explicitly;
.Dq signing non-present fields
is described in RFC 6376 from 2011, however.
Sealing headers not included in
.Fl Fl header-sign
(can) result(s) in broken signatures:
.Fl Fl test-mode
will catch this.
.Pp
.Sy Remarks:
In order not to break mailing-list posts (handled by software which does
not recognize message signatures) the built-in defaults exclude
.Ql Reply-To
and all the mailing-list related fields of RFC 2369.
In order to ease DKIM signing for mailing-lists as such sealing provides
a recommendet additional built-in addressable via plus sign
.Ql + .
.
.Mx Fl header-seal-show
.It Fl Fl header-seal-show
Show the built-in
.Fl Fl header-seal
lists, then exit.
.
.Mx Fl key
.It Fl Fl key Ar algo-digest,selector,path , Fl k Ns ..
Add a key to be used.
Unless
.Fl Fl sign
relations have been established messages will be signed with all keys.
In a comma-separated list of three fields, the first defines
.Ar algo Ns
rithm and
.Ar digest ,
separated by
.Ql -
hyphen-minus,
for example
.Cm rsa-sha1 .
Dependent on the used crypto library
.Pf ( Cm adaed25519-sha256 ) ,
.Cm big_ed-\:sha256 ,
.Cm rsa-\:sha256 ,
and
.Cm rsa-sha1
(obsoleted by RFC 8301, causes a warning) can be supported; the output of
.Fl Fl long-help
shows what is built-in.
The first two are the very same key-wise, except that
.Cm big_ed-sha256
is what was standardized as RFC 8463 in 2018, whereas
.Cm adaed25519-sha256
is draft-nurpmeso-dkim-algo-adaed25519.
The second field specifies the (DNS)
.Ar selector
of the public key (please see
.Fl Fl sign ) ;
it must obey
.Fl Fl domain-name
syntax.
The third field is the
.Ar path
to the private key file in PEM format;
file accessibility is not tested, but recommendable is tight-most
(readable by only root and the user identity running
.Nm ) .
.
.Mx Fl long-help
.It Fl Fl long-help , H
A help listing that includes available signature algorithms.
.
.Mx Fl milter-macro
.It Fl Fl milter-macro Ar action,name Ns Oo Ar ,value.. Oc , Fl M Ns ..
Only apply
.Ar action
.Pf ( Ql sign
or
.Ql verify )
if servers announce
.Ar macro
(with any of the given
.Ar value Ns
(s)), or let the connection pass.
With
.Xr postfix 1
one should
.Xr postconf 5
.Ql milter_macro_daemon_name=VAL1 ,
seen by the milter as the
.Ql {daemon_name}
macro with
.Ql VAL1 ,
therefore
.Fl Fl \&\&milter-macro Ns Ar =sign,{daemon_name},VAL1,VAL2
would be needed.
The macro is expected to be received when clients connect.
.
.
.Mx Fl remove
.It Fl Fl remove Ar type Ns Oo Ar ,spec.. Oc , Fl r Ns ..
Remove the specified
.Ar type
of headers, dependent upon which the optional
.Ar spec
can be a (comma-separated list of) string(s) to match (in order)
that defaults to the milter macro
.Ql j
.Pf ( Xr postfix 1 Ns
-expanded to
.Ql $myhostname ) .
.Sy Note:
matching is performed as documented for
.Fl Fl client ,
syntax validity is however not verified.
As a special case a sole exclamation mark
.Ql \&!
matches invalid header instances; without further strings the macro
.Ql j
is still used.
The
.Dq super-\:wildcard
period
.Ql \&.
matches anything, including invalid headers.
.
.Pp
Supported
.Ar type Ns
s which support
.Ar spec
matching are
.Ql a-r
.Pf ( Ql Authentication-\:Results ) ,
.Ql mo-a-r
.Pf ( Ql X-Mailman-\:Original-\:Authentication-\:Results ) ,
.Ql a-a-r
.Pf ( Ql ARC-Authentication-\:Results ) .
Lesser quality parsers exist for
.Ql a-m-s
.Pf ( Ql ARC-Message-Signature ) ,
.Ql a-s
.Pf ( Ql ARC-Seal ) ,
.Ql dkim
.Pf ( Ql DKIM-Signature )
and
.Ql mo-dkim
.Pf ( Ql X-Mailman-\:Original-\:DKIM-Signature ) .
.Dq All or nothing
removal (without
.Ar spec )
support exists for
.Ql aucy
.Pf ( Ql Autocrypt )
and
.Ql ip
.Pf ( Ql IronPort ) .
.
.Pp
.Sy Remarks:
Regarding
.Ql Authentication-\:Results
RFC 7001 says
.Dq For simplicity and maximum security, a border MTA could remove all \
  instances of this header field on mail crossing into its trust \
  boundary
and
.Dq A more robust border MTA could allow a specific list of \
  authenticating MTAs whose information is to be admitted, \
  removing the header field originating from all others Ns
\&.
.
.
.Mx Fl resource-file
.It Fl Fl resource-file Ar path , Fl R Ns ..
A configuration file with long options (without
.Ql Fl Fl
double hyphen-minus).
Each line forms an entry, leading and trailing whitespace is removed.
If the first non-whitespace character is the
.Ql #
number-sign the line is a comment and discarded.
Empty lines are ignored, other lines can be folded over multiple input
lines with a reverse-solidus
.Ql \e
before the newline: all leading whitespace of the next line is ignored.
.Bd -literal -offset indent
# Comment \e
  line
milter-\e
  macro \e
    sign , {daemon_name}
.Ed
.
.
.Mx Fl sign
.It Fl Fl sign Ar spec Ns Oo , Ns Ar domain Ns Oo , Ns Ar selector.. Oc Oc , \
  Fl S Ns ..
Establish a relation in between
.Ar spec
and none to maximally five
.Ar selector Ns
(s), which (in the end) have to relate to
.Fl Fl key Ns
s; fields form a comma-separated, multiple selectors instead a
.Ql \&:
colon-separated list;
all keys are used if there are none.
If any sign relation is established only those messages which match
a relation will be signed.
.Ar selector
order does not matter.
A non-empty
.Ar domain
overrides
.Fl Fl domain-name .
.
.Pp
.Ar spec
is matched against the (first address of the)
.Ql From
header of processed messages;
It can be a mail address like
.Ql local-part@dom.ain ,
or only a domain without
.Ql local-part@ .
Domains with a leading
.Ql \&.
period, as in
.Ql .dom.ain ,
match all subdomains, for example
.Ql a.b.c.dom.ain ,
or
.Ql joe@c.dom.ain .
Only a period is a
.Dq super-wildcard
that matches all domains, for example
.Ql jack@.
matches jack's.
.
.Pp
.Sy Remarks:
Some
.Ql local-part Ns
s require quoting, for example
.Ql t\(dqi(%;)@\(dq@gh.t .
Since normalization is applied during actual processing,
.Ql \(dqti(%;)@\(dq@gh.t
will have to be written in order for this to match.
.Pf ( Fl Fl test-mode
will catch this.)
Remarks: commas cannot be used even in a quoted
.Ql local-part .
.
.
.Mx Fl sign-file
.It Fl Fl sign-file Ar path , Fl s Ns ..
Load a file of
.Fl Fl sign
relations; Lines are read as via
.Fl Fl resource-file .
.
.Mx Fl test-mode
.It Fl Fl test-mode , #
Enable test mode: all options are evaluated, thereafter the final
settings are shown in resource file format.
The exit status indicates error.
It is highly recommended to use this for configuration checks.
.Sy Remarks:
must be the first option.
.
.Mx Fl ttl
.It Fl Fl ttl Ar seconds , Fl t Ns ..
Impose a time-to-live expiration upon generated DKIM signatures after
which newly receiving parties shall see them as invalidated.
.Ar seconds
must not be smaller than 30 and greater than 86400000 (1000 days).
.
.Mx Fl verbose
.It Fl Fl verbose
Increase log verbosity (three levels).
.El
.
.
.Sh "SEE ALSO"
.
.Xr postfix 1 ,
.Xr postconf 5 ,
.Xr spawn 8
.
.
.Sh AUTHORS
.
.An "Steffen Nurpmeso" Aq steffen@sdaoden.eu .
.
.
.Sh BUGS
.
.Bl -bullet -compact
.It
Of the two DKIM canonicalization modes
.Ql simple
is unsupported.
.It
Internationalized UTF-8 email, that is RFC 6530
.Dq Overview and Framework for Internationalized Email ,
RFC 6531
.Dq SMTP Extension for Internationalized Email ,
and RFC 6532
.Dq Internationalized Email Headers ,
is not supported; the old content transfer encoding style however is.
This may affect address matching.
.It
Does not support stand-alone mode (usable by any MTA).
.It
Does not support verification.
.It
Some
.Fl Fl remove
header types are parsed with a low-quality (but likely satisfying) parser.
.It
The unit test is incomplete.
.El
.
.\" s-ts-mode