From 7164d02b8ac4481c068e5589593fbdbd9932dc82 Mon Sep 17 00:00:00 2001 From: Scott Kitterman Date: Mon, 12 Feb 2018 18:37:59 -0500 Subject: [PATCH] Add initial dkimpy-milter.conf.5 with initial target option set. --- dkimpy-milter.conf.5 | 374 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 374 insertions(+) create mode 100644 dkimpy-milter.conf.5 diff --git a/dkimpy-milter.conf.5 b/dkimpy-milter.conf.5 new file mode 100644 index 0000000..ac2cd4b --- /dev/null +++ b/dkimpy-milter.conf.5 @@ -0,0 +1,374 @@ +\" +.\" Standard preamble: +.\" ======================================================================== +.de Sh \" Subsection heading +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +'br\} +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.\" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.hy 0 +.if n .na +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "dkimpy-milter.conf 5" +.TH dkimpy-milter.conf 5 "2018-02-12" +.SH "NAME" +dkimpy-milter \- Python milter for DKIM signing and validation +.SH "VERSION" +.IX Header "VERSION" +0\. + +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +.I dkimpy-milter(8) +implements the +.B DKIM +specification for signing and verifying e-mail messages on a per-domain +basis. This file is its configuration file. + +Blank lines are ignored. Lines containing a hash ("#") character are +truncated at the hash character to allow for comments in the file. + +Other content should be the name of a parameter, followed by white space, +followed by the value of that parameter, each on a separate line. + +For parameters that are Boolean in nature, only the first byte of +the value is processed. For positive values, the following are accepted: +"T", "t", "Y", "y", "1". For negative values, the following are accepted: +"F", "f", "N", "n", "0". + +The provided setup.py installs this configuration file in /etc or +/usr/local/etc. + +Command line invocation of parameters as is done by OpenDKIM is not supported. + +.SH "USAGE" +.IX Header "USAGE" +Usage: + dkimpy-milter [/etc/dkimpy-milter.conf] + +.SH "OTHER DOCUMENTATION" +.IX Header "OTHER DOCUMENTATION" +This documentation assumes you have read Postfix's README_FILES/MILTER_README +(or Sendmail equivalent) and are generally familiar with Domain Keys Identified +Mail (DKIM). See RFC 6376 for details. + +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" + +dkimpy-milter operates with a default installed configuration file and +set of default configuration options that are used if the configuration file +cannot be found. These options can be changed by changing the installed +configuration files. For users transitioning from OpenDKIM, OpenDKIM config +files can be used directly. Not all OpenDKIM options are supported. If an +unsupported option from OpenDKIM is specified, an error will be raised. + +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" + +Configuration options are described here and in the configuration file +provided with the package. The provided setup.py installs this configuration +file in /etc or /usr/local/etc. + +.SH "OPTIONS" +.IX Header "OPTIONS" + +.TP +.I AuthservID (string) +Sets the "authserv-id" to use when generating the Authentication-Results: +header field after verifying a message. The default is to use the name of +the MTA processing the message. If the string "HOSTNAME" is provided, the +name of the host running the filter (as returned by the +.I gethostname(3) +function) will be used. + +.TP +.I Canonicalization (string) +Selects the canonicalization method(s) to be used when signing messages. +When verifying, the message's DKIM-Signature: header field specifies +the canonicalization method. The recognized values are +.I relaxed +and +.I simple +as defined by the DKIM specification. The default is +.I simple. +The value may include two different canonicalizations separated by a +slash ("/") character, in which case the first will be applied to the +header and the second to the body. + +.TP +.I Domain (dataset) +A set of domains whose mail should be signed by this filter. Mail from other +domains will be verified rather than being signed. + +This parameter is not required if a +.I SigningTable +is in use; in that case, the list of signed domains is implied by the +lines in that file. [NOT IMPLEMENTED] + +This parameter is ignored if a +.I KeyTable +is defined. [NOT IMPLEMENTED] + +.TP +.I KeyFile (string) +Gives the location of a PEM-formatted private key to be used for RSA signing +all messages. Ignored if a +.I KeyTable +is defined. [KeyTable NOT IMPLEMENTED] + +.TP +.I KeyFileEd25119 (string) +Gives the location of a Ed25519 private key to be used for Ed25519 signing +all messages. File is the Base64 encoded output of RFC 8032 Ed25519 private Key +generation (as used in dkimpy). Ignored if a +.I KeyTableEd25519 +is defined. [KeyTableEd25519 NOT IMPLEMENTED] + +.TP +.I Mode (string) +Selects operating modes. The string is a concatenation of characters that +indicate which mode(s) of operation are desired. Valid modes are +.I s +(signer) and +.I v +(verifier). The default is +.I sv +except in test mode (see the +.I opendkim(8) +man page) +in which case the default is +.I v. +When signing mode is enabled, one of the following combinations must also +be set: +(a) Domain, KeyFile, Selector, no KeyTable, no SigningTable; +(b) KeyTable, SigningTable, no Domain, no KeyFile, no Selector; +[fooTable options NOT IMPLEMENTED] + +.TP +.I PidFile (string) +Specifies the path to a file that should be created at process start +containing the process ID. + +.TP +.I Selector (string) +Defines the name of the selector to be used when signing messages. +See the +.B DKIM +specification for details. Used only when signing with a single key; +see the +.I SigningTable +parameter below for more information. + +This parameter is ignored if a +.I KeyTable +is defined. [KeyTable NOT IMPLEMENTED] + +.TP +.I Socket (string) +Specifies the socket that should be established by the filter to receive +connections from +.I postfix(1) +in order to provide service. +.I socketspec +is in one of two forms: +.I local:path, +which creates a UNIX domain socket at the specified +.I path, +or +.I inet:port[@host] +or +.I inet6:port[@host] +which creates a TCP socket on the specified +.I port +and in the specified protocol family. If the +.I host +is not given as either a hostname or an IP address, the socket will be +listening on all interfaces. A literal IP address must be enclosed in +square brackets. This option is mandatory in the configuration file. + +.TP +.I Syslog (Boolean) +Log via calls to +.I syslog(3) +any interesting activity. + +.TP +.I SyslogFacility (string) +Log via calls to +.I syslog(3) +using the named facility. The facility names are the same as the ones +allowed in +.I syslog.conf(5). +The default is "mail". + +.TP +.I SyslogSuccess (Boolean) +Log via calls to +.I syslog(3) +additional entries indicating successful signing or verification of +messages. + +.TP +.I UMask (integer) +Requests a specific permissions mask to be used for file creation. +This only really applies to creation of the socket when +.I Socket +specifies a UNIX domain socket, and to the +.I PidFile +(if any); temporary files are created by the +.I mkstemp(3) +function that enforces a specific file mode on creation regardless +of the process umask. See +.I umask(2) +for more information. + +.TP +.I UserID (string) +Attempts to become the specified userid before starting operations. +The value is of the form +.I userid[:group]. +The process will be assigned all of the groups and primary group ID of +the named +.I userid +unless an alternate +.I group +is specified. + +.SH "AUTHORS" +.IX Header "AUTHORS" +\ddkimpy-milter\fR was written by Scott Kitterman . +It is based on dkimpy-milter.py Copyright (c) 2001-2013 Business Management Systems, Inc. +Copyright (c) 2013-2015 Stuart D. Gathman +Copyright (c) 2018 Scott Kitterman . +.PP +This man-page was created by Scott Kitterman . + +.SH COPYRIGHT +Configuration items derived from OpenDKIM 2.11.0 opendkim.conf.5.in: +Copyright (c) 2007, 2008, Sendmail, Inc. and its suppliers. All rights +reserved. See LICENSE.Sendmail. + +Copyright (c) 2009-2015, The Trusted Domain Project. All rights reserved. +See LICENSE. + +Updated for dkimpy-milter. Updates licensed under the same terms as the rest +of the package. +Copyright (c) 2018, Scott Kitterman