1 .\"	$OpenBSD$
2 .\"
3 .\" Copyright (c) 2019 Martijn van Duren <martijn@openbsd.org>
4 .\"
5 .\" Permission to use, copy, modify, and distribute this software for any
6 .\" purpose with or without fee is hereby granted, provided that the above
7 .\" copyright notice and this permission notice appear in all copies.
8 .\"
9 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16 .\"
17 .Dd $Mdocdate$
18 .Dt FILTER-DKIMSIGN 8
19 .Os
20 .Sh NAME
21 .Nm filter-dkimsign
22 .Nd add dkim signature to messages
23 .Sh SYNOPSIS
24 .Nm
25 .Op Fl tz
26 .Op Fl a Ar algorithm
27 .Op Fl c Ar canonicalization
28 .Op Fl h Ar headers
29 .Op Fl x Ar seconds
30 .Fl d Ar domain
31 .Fl D Ar file
32 .Fl k Ar file
33 .Fl s Ar selector
34 .Sh DESCRIPTION
35 .Nm
36 adds a dkim signature to the message.
37 The following flags are supported:
38 .Bl -tag -width Ds
39 .It Fl a Ar algorithm
40 The
41 .Ar algorithm
42 to use.
43 Supported signing algorithms are
44 .Em rsa
45 and
46 .Em ed25519 Pq when enabled at compile time .
47 Only sha256 should be used for hashing, since other algorithms are most likely
48 not supported by verifiers.
49 Defaults to
50 .Cm rsa-sha256 .
51 .It Fl c Ar canonicalization
52 The canonicalization algorithm used to sign the message.
53 Defaults to
54 .Em simple/simple .
55 .It Fl D Ar file
56 .Ar file
57 should point to a file containing a list of domains.
58 Only one domain per line should be specified.
59 See
60 .Fl d
61 for more information.
62 .It Fl d Ar domain
63 The
64 .Ar domain
65 where the public key can be found.
66 This option can be specified multiple times to select the best
67 .Ar domain
68 during signing.
69 If specified multiple times it looks at the domain component of the first
70 mailbox in the from-header and tries to find a match.
71 If no exact match can be found it looks for the closest parent
72 .Ar domain .
73 If no matches can be the first
74 .Ar domain
75 specified will be used.
76 .It Fl h Ar headers
77 The email headers which are included in the mail signature.
78 Per RFC this option requires at least the from header to be included.
79 The headers are specified by separating them with a colon.
80 The default is
81 .Em from:reply-to:subject:date:to:cc:resent-date:resent-from:resent-to:resent-cc:in-reply-to:references:list-id:list-help:list-unsubscribe:list-subscribe:list-post:list-owner:list-archive .
82 .It Fl k Ar file
83 .Ar file
84 should point to a file containing the RSA private key to sign the messages.
85 .It Fl s Ar selector
86 The selector within the _domainkey subdomain of
87 .Ar domain
88 where the public key can be found.
89 .It Fl t
90 Add the time of signing to the dkim header.
91 .It Fl x Ar seconds
92 Add the amount of
93 .Ar seconds
94 the signature is valid to the dkim header.
95 .It Fl z
96 Add the mail headers used in the dkim signature to the dkim header.
97 If a second
98 .Fl z
99 is specified all headers will be included in the dkim header.
100 Useful for debugging purposes.
101 .El
102 .Sh SEE ALSO
103 .Xr smtpd 8
104 .Sh STANDARDS
105 .Rs
106 .%A D. Crocker, Ed.
107 .%Q Brandenburg InternetWorking
108 .%A T. Hansen, Ed.
109 .%Q AT&T Laboratories
110 .%A M. Kucherawy, Ed.
111 .%Q Cloudmark
112 .%D September 2011
113 .%R RFC 6376
114 .%T DomainKeys Identified Mail (DKIM) Signatures
115 .Re
116 .Pp
117 .Rs
118 .%A J. Levine
119 .%Q Taughannock Networks
120 .%D September 2018
121 .%R RFC 8463
122 .%T A New Cryptographic Signature Method for DomainKeys Identified Mail
123 .Re
124 .Sh AUTHORS
125 .An Martijn van Duren Aq Mt martijn@openbsd.org