-
Notifications
You must be signed in to change notification settings - Fork 2
/
signing-milter.8
256 lines (255 loc) · 7.77 KB
/
signing-milter.8
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
.\"
.\"signing-milter - signing-milter.8
.\"Copyright (C) 2010-2020 Andreas Schulze
.\"
.\"This program is free software; you can redistribute it and/or modify
.\"it under the terms of the GNU General Public License as published by
.\"the Free Software Foundation; only version 2 of the License is applicable.
.\"
.\"This program is distributed in the hope that it will be useful,
.\"but WITHOUT ANY WARRANTY; without even the implied warranty of
.\"MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
.\"GNU General Public License for more details.
.\"
.\"You should have received a copy of the GNU General Public License along
.\"with this program; if not, write to the Free Software Foundation, Inc.,
.\"51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
.\"
.\"Authors:
.\" Andreas Schulze <signing-milter at andreasschulze.de>
.\"
.\"
.TH signing-milter 8 "July, 2020"
.\"
.SH NAME
signing-milter \- sign email via milter protocol
.\"
.SH SYNOPSIS
.B signing-milter
.RI [ options ]
.\"
.SH DESCRIPTION
.B signing-milter
uses the
.I milter
interface, originally distributed as part of version 8.11 of
.B sendmail(8),
to provide signing service for mail transiting a milter-aware MTA.
.\"
.SH OPTIONS
.TP
.B \-h
Show summary of options and exit.
.TP
.B \-v
Show version of program and exit.
.TP
.B \-c clientgroup
If socket is
.I [unix|local]:path
.I signing-milter
will adjust
.I path
to be read/writeable by group
.I clientgroup.
The group must be any group other then root and the group
.I signing-milter
runs as. The parameter is required unless using an TCP socket.
.TP
.B \-d loglevel
Set the loglevel. The default level 3 logs all errors. Valid values are
effective syslog priorities as described in
.IR /usr/include/syslog.h
.TP
.B \-f
normally
.I signing-milter
uses the envelope sender as signeraddress to lookup in the signingtable.
If enabled,
.I signing-milter
uses also the value of a header named
.B X-Signer
to lookup the signeraddress. This is useful when using VERP
(Variable Envelope Return Path).
.TP
.B \-g group
Set the group
.I signing-milter
will run as if started as root. If omitted the groupname signing-milter is used.
.TP
.B \-k directory
for debugging purposes
.I signing-milter
can store data to files. They are created in the named directory which must be
readable, writeable an executable by the user
.I signing-milter
runs as. It must not have any rights for other.
.I signing-milter
creates two files containing unsigned and signed data. The files are named
plain-QUEUEID and signed-QUEUEID. If omitted no files are written.
.TP
.B \-l all Logs to STDOUT
Some environments work better if any logging is sent to STDOUT. This switch let
.I signing-milter
write any logmessage to STDOUT. Nothing will be send via SYSLOG, /dev/log is
not needed.
.TP
.B \-m signingtable
.I signing-milter
uses a table to lookup corresponding signingmaterial to a given sender address.
This table is a
.I cdb
compiled database. The signingtable lists mailaddresses on the left (key), one
ore more spaces or tabs and a full path to an associates file (value). These
file must contain a signer certificate and a signer private key in PEM format.
.sp
The files containing certificates and private keys are security sensitive.
Therefore they must only be readable and not writeable for the user
.I signing-milter
runs as. Also they must not be world readable.
.sp
Feature available since version 20120731:
.br
If you put cert and key in a file named /path/to/foo-cert+key.pem then
.I signing-milter
also try to load /path/to/foo-chain.pem. If it exist it should contain
intermediate and root certificates that will be included in the signature.
NOTE:
.br
There is not special error signaled if /path/to/foo-chain.pem exist
but is unreadable for the user
.I
signing-milter
run as.
When using chain certificates you should check the logs if it is really used.
.TP
.B \-n modetable
.I signing-milter
can use this optional table to lookup recipient addresses. If at least one
recipient of a message is found in modetable, the result is applied to the
whole message.
.sp
The value may contain any combination of the following words:
.RS
.TP
.B keep
for debugging purposes keep the plain and signed data unter /tmp/*-$queueid.
In contrast to the option
.I \-k
the directory is fix and saving occur not for all messages.
.TP
.B opaque
the signingmode is switched from detached to opaque. Opaque mode is intended
to preserve signatures for mail transiting broken MTAs.
.TP
.B skip
message will not be signed and simply pass unchanged.
.RE
.TP
.B \-s socket
Specifies the socket that should be established by the filter to receive
connections from
.I sendmail(8)
in order to provide service.
.I socket
is in one of three forms:
.I [unix|local]:path
which creates a UNIX domain socket at the specified path.
.I inet:port[@host]
which creates a TCP socket on the specified port.
.I inet6:port[@host]
which creates a TCPv6 socket on the specified port. If the host is not given as
either a hostname or an IP address, the socket will be listening on all
interfaces. If no socket is given at all, the milter listen on
.I inet6:30053@[::1].
Let's push IPv6, yeah!
.TP
.B \-t timeout
This is the number of seconds
.I signing-milter
will wait for an MTA communication (read or write) before timing out.
.TP
.B \-u user
Set the user
.I signing-milter
will run as if started under root. If omitted the username signing-milter is
used.
.TP
.B \-x
Causes
.I signing-milter
to add a header indicating the presence of this filter in the path of the
message from injection to delivery. The productname, version and hostname
are included in the headers contents.
.\"
.SH SECURITY
The
.I signing-milter
is security-sensitive. It talks to an MTA and has access to otherwise
unprotected private keys. It must run at fixed low privilege. The
.I signing-milter
refuses to run with root privileges.
.\"
.SH ACCOUNTS
You may start signing-milter as root. In this case
.I signing-milter
will switch to user/group signing-milter or the username given as \-u and \-g.
You may also switch to a unprivileged user and then start signing-milter.
.\"
.SH LOCAL SOCKET
If you want
.I signing-milter
run with a local unixsocket it is important the socket is accessible by
.I sendmail(8).
In this case start
.I signing-milter
under root, set \-u and \-g (or leave them default) and set \-c to a group
other then root and signing-milter.
.I signing-milter
will adjust the sockets owner, group and file mode to allow proper access by
.I sendmail(8).
.\"
.SH SIGNALS
.I signing-milter
dumps statistical data on SIGALARM. The data contains the number of signed
messages and the total signingtime in seconds.milliseconds separated by /. All
counters are set to zero after SIGALARM. Also on SIGTERM statistical data are
logged.
.\"
.SH STARTUP AND LOGGING
.I signing-milter
is designed to run by a supervisor like daemontools or runit. It does not fork
as daemon in background. So all logging goes to syslog using facility LOG_MAIL.
All messages except priority LOG_NOTICE and LOG_INFO are also sent to stdout.
.\"
.SH BUGS
The private signing keys must not be protected by password.
.I signing-milter
should also support GnuPG. A changed signingtable is noticed but not reloaded.
.I signing-milter
must currently restart when the signingtable has changed. Same applies to the
modetable.
.\"
.SH SEE ALSO
.BR cdb (1),
.BR syslog (3),
.BR cdb (5),
.BR sendmail (8)
.P
http://cr.yp.to/cdb.html, http://www.corpit.ru/mjt/tinycdb.html
.P
http://cr.yp.to/proto/verp.txt
.\"
.SH LICENSE
.I signing-milter
is licensed unter the terms of GNU General Public License as published by
the Free Software Foundation. Only version 2 of the License is applicable.
.\"
.SH AUTHOR
.I signing-milter
was written by Andreas Schulze. Portions of Code are inspired or copied from
postfix and opendkim.
.\"
.SH COPYRIGHT
Copyright (c) 2010-2015, Andreas Schulze. All rights reserved.
.\" _END_