Skip to content

Commit ae007d8

Browse files
flowerysongflowerysong
committed
docs: Improve man pages
1 parent 1987780 commit ae007d8

8 files changed

+366
-300
lines changed

‎configure.ac

+3
Original file line numberDiff line numberDiff line change
@@ -375,6 +375,9 @@ test "x$prefix" = xNONE && prefix=$ac_default_prefix
375375
SYSCONFDIR=`eval echo "$sysconfdir"`
376376
AC_SUBST([SYSCONFDIR])
377377

378+
BUILDDATE=`date +%F`
379+
AC_SUBST([BUILDDATE])
380+
378381
#
379382
# Finish up
380383
#

‎contrib/.gitignore

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
openarc-keygen.1

‎contrib/openarc-keygen.1.in

+4-4
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
.\" Copyright 2024 OpenARC contributors.
22
.\" See LICENSE.
3-
.Dd 2024-10-30
3+
.Dd @BUILDDATE@
44
.Dt OPENARC-KEYGEN 1
55
.Os OpenARC @VERSION@
66

@@ -9,13 +9,13 @@
99
.Nd DKIM (and ARC) key generation tool
1010

1111
.Sh SYNOPSIS
12-
.Nm openarc-keygen
12+
.Nm
1313
.Fl d Ar domain
1414
.Fl s Ar selector
1515
.Op options
1616

1717
.Sh DESCRIPTION
18-
.Nm openarc-keygen
18+
.Nm
1919
outputs a private key suitable for signing messages using
2020
.Xr openarc 8
2121
and also outputs one of several representations of the associated
@@ -105,7 +105,7 @@ it does not affect the handling of messages or signatures.
105105

106106
.Sh NOTES
107107
A suitable
108-
.Nm openssl
108+
.Em openssl
109109
executable must be available in the executing user's
110110
.Ev PATH .
111111

‎openarc/openarc-config.h

+2-2
Original file line numberDiff line numberDiff line change
@@ -34,15 +34,15 @@ struct configdef arcf_config[] = {
3434
{"MilterDebug", CONFIG_TYPE_INTEGER, false},
3535
{"MinimumKeySizeRSA", CONFIG_TYPE_INTEGER, false},
3636
{"Mode", CONFIG_TYPE_STRING, false},
37+
{"OverSignHeaders", CONFIG_TYPE_STRING, false},
3738
{"PeerList", CONFIG_TYPE_STRING, false},
3839
{"PermitAuthenticationOverrides", CONFIG_TYPE_BOOLEAN, false},
3940
{"PidFile", CONFIG_TYPE_STRING, false},
4041
{"RequireSafeKeys", CONFIG_TYPE_BOOLEAN, false},
42+
{"SealHeaderChecks", CONFIG_TYPE_STRING, false},
4143
{"Selector", CONFIG_TYPE_STRING, false},
4244
{"SignatureAlgorithm", CONFIG_TYPE_STRING, false},
4345
{"SignHeaders", CONFIG_TYPE_STRING, false},
44-
{"OverSignHeaders", CONFIG_TYPE_STRING, false},
45-
{"SealHeaderChecks", CONFIG_TYPE_STRING, false},
4646
{"Socket", CONFIG_TYPE_STRING, false},
4747
{"SoftwareHeader", CONFIG_TYPE_BOOLEAN, false},
4848
{"Syslog", CONFIG_TYPE_BOOLEAN, false},

‎openarc/openarc.8.in

+101-83
Original file line numberDiff line numberDiff line change
@@ -1,114 +1,132 @@
1-
.TH openarc 8 "The Trusted Domain Project"
2-
.SH NAME
3-
.B openarc
4-
\- ARC signing and verifying filter for MTAs
5-
.SH SYNOPSIS
6-
.B openarc
7-
[\-c configfile]
8-
[\-f]
9-
[\-n]
10-
[\-p socketspec]
11-
[\-P pidfile]
12-
[\-u userid[:group]]
13-
[\-v]
14-
[\-V]
15-
.SH DESCRIPTION
16-
.B openarc
17-
implements the proposed
18-
.B ARC
19-
(Authenticated Received Chain) standard for confirming handling and
20-
authentication of a message as it is handled for delivery.
1+
.\" Copyright (c) 2005-2008, Sendmail, Inc. and its suppliers. All rights
2+
.\" reserved. See LICENSE.Sendmail.
3+
.\" Copyright (c) 2009-2013, 2015, 2016, The Trusted Domain Project. All
4+
.\" rights reserved. See LICENSE.
5+
.Dd @BUILDDATE@
6+
.Dt OPENARC 8
7+
.Os OpenARC @VERSION@
218

22-
.B openarc
9+
.Sh NAME
10+
.Nm openarc
11+
.Nd ARC signing and verifying filter for MTAs
12+
13+
.Sh SYNOPSIS
14+
.Nm openarc
15+
.Op Fl c Ar configfile
16+
.Op Fl f
17+
.Op Fl n
18+
.Op Fl p Ar socketspec
19+
.Op Fl P Ar pidfile
20+
.Op Fl u Ar userid Op : Ar group
21+
.Op Fl v
22+
.Op Fl V
23+
24+
.Sh DESCRIPTION
25+
.Nm
26+
implements the proposed ARC (Authenticated Received Chain) standard
27+
for confirming handling and authentication of a message as it is
28+
handled for delivery.
29+
30+
.Nm
2331
uses the
24-
.I milter
32+
.Em milter
2533
interface, originally distributed as part of version 8.11 of
26-
.B sendmail(8),
34+
.Xr sendmail 8 ,
2735
to provide ARC signing and/or verifying service for mail transiting
2836
a milter-aware MTA.
29-
.SH OPTIONS
30-
.TP
31-
.I \-c configfile
37+
38+
.Sh OPTIONS
39+
40+
.Bl -tag -width Ds
41+
.It Fl c Ar configfile
3242
Read the named configuration file. See the
33-
.I openarc.conf(5)
34-
man page for details. Values in the configuration file are overridden
35-
when their equivalents are provided on the command line until a configuration
36-
reload occurs. The default is to read a configuration file from
37-
.I @SYSCONFDIR@/openarc.conf
38-
if one exists, or otherwise to apply defaults to all values.
39-
.TP
40-
.I \-f
43+
.Xr openarc.conf 5
44+
man page for details.
45+
Values in the configuration file are overridden when their equivalents
46+
are provided on the command line (but only until a configuration reload
47+
occurs.)
48+
The default is to read a configuration file from
49+
.Pa @SYSCONFDIR@/openarc.conf
50+
if one exists.
51+
If no configuration file is found, default values are used.
52+
53+
.It Fl f
4154
Normally
42-
.I openarc
55+
.Nm
4356
forks and exits immediately, leaving the service running in the background.
4457
This flag suppresses that behaviour so that it runs in the foreground.
45-
.TP
46-
.I \-n
58+
59+
.It Fl n
4760
Parse the configuration file and command line arguments, reporting any
48-
errors found, and then exit. The exit value will be 0 if the filter would
49-
start up without complaint, or non-zero otherwise.
50-
.TP
51-
.I \-p socketspec
61+
errors found, and then exit.
62+
The exit value will be 0 if the filter would start up without complaint,
63+
and non-zero otherwise.
64+
65+
.It Fl p Ar socketspec
5266
Specifies the socket that should be established by the filter to receive
5367
connections from
54-
.I sendmail(8)
68+
.Xr sendmail 8
5569
in order to provide service.
56-
.I socketspec
70+
.Ar socketspec
5771
is in one of two forms:
58-
.I local:path
72+
.Ar local:path
5973
which creates a UNIX domain socket at the specified
60-
.I path,
74+
.Ar path,
6175
or
62-
.I inet:port[@host]
76+
.Ar inet:port Op @host
6377
or
64-
.I inet6:port[@host]
78+
.Ar inet6:port Op @host
6579
which creates a TCP socket on the specified
66-
.I port
80+
.Ar port
6781
using the requested protocol family. If the
68-
.I host
82+
.Ar host
6983
is not given as either a hostname or an IP address, the socket will be
70-
listening on all interfaces. A literal IP address must be enclosed in
71-
square brackets. If neither socket type is specified,
72-
.I local
84+
listening on all interfaces.
85+
A literal IP address must be enclosed in square brackets.
86+
If neither socket type is specified,
87+
.Cm local
7388
is assumed, meaning the parameter is interpreted as a path at which
74-
the socket should be created. This parameter is mandatory either here or
75-
in the configuration file.
76-
.TP
77-
.I \-P pidfile
89+
the socket should be created.
90+
This parameter is mandatory either here or in the configuration file.
91+
92+
.It Fl P Ar pidfile
7893
Specifies a file into which the filter should write its process ID at startup.
79-
.TP
80-
.I \-u userid[:group]
81-
Attempts to be come the specified
82-
.I userid
94+
95+
.It Fl u Ar userid Op Ar :group
96+
Attempts to become the specified
97+
.Ar userid
8398
before starting operations. The process will be assigned all of the groups
8499
and primary group ID of the named
85-
.I userid
100+
.Ar userid
86101
unless an alternate
87-
.I group
88-
is specified. See the FILE PERMISSIONS section for more information.
89-
.TP
90-
.I \-V
91-
Print the version number and build-time options, and then exit without
92-
doing anything else.
93-
.SH EXIT STATUS
102+
.Ar group
103+
is specified.
104+
105+
.It Fl V
106+
Print the version number and build-time options, then exit.
107+
108+
.Sh EXIT STATUS
94109
Filter exit status codes are selected according to
95-
.I sysexits(3).
96-
.SH VERSION
97-
This man page covers version @VERSION@ of
98-
.I openarc.
99-
.SH COPYRIGHT
100-
Copyright (c) 2005-2008, Sendmail, Inc. and its suppliers. All rights
101-
reserved.
110+
.Xr sysexits 3 .
102111

103-
Copyright (c) 2009-2013, 2015, 2016, The Trusted Domain Project.
104-
All rights reserved.
105-
.SH SEE ALSO
106-
.I openarc.conf(5), sendmail(8)
107-
.P
112+
.Sh SEE ALSO
113+
.Bl -item
114+
.It
115+
.Xr openarc.conf 5
116+
.It
117+
.Xr sendmail 8
118+
.It
108119
Sendmail Operations Guide
109-
.P
120+
.It
110121
RFC5321 - Simple Mail Transfer Protocol
111-
.P
122+
.It
112123
RFC5322 - Internet Messages
113-
.P
124+
.It
125+
RFC6376 - DomainKeys Identified Mail
126+
.It
114127
RFC8601 - Message Header Field for Indicating Message Authentication Status
128+
.It
129+
RFC8616 - Email Authentication for Internationalized Mail
130+
.It
131+
RFC8617 - The Authenticated Received Chain (ARC) Protocol
132+
.El

‎openarc/openarc.c

+3-6
Original file line numberDiff line numberDiff line change
@@ -2991,12 +2991,9 @@ mlfi_header(SMFICTX *ctx, char *headerf, char *headerv)
29912991
afc->mctx_hdrbytes + strlen(headerf) + strlen(headerv) + 2 >
29922992
conf->conf_maxhdrsz)
29932993
{
2994-
/*
2995-
** MSK: For now just accept these, but it's a security issue;
2996-
** OpenDKIM makes this tunable so I imagine people using this
2997-
** will ask for the same thing.
2998-
*/
2999-
2994+
/* FIXME: this should be configurable, and it might be better to
2995+
* default to rejecting the message.
2996+
*/
30002997
if (conf->conf_dolog)
30012998
{
30022999
syslog(LOG_NOTICE, "too much header data; accepting");

0 commit comments

Comments
 (0)