ezmlm-web/ezmlm-web-modules
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

renamed gpgpy-ezmlm to crypto-ezmlm

Browse source
This commit is contained in:
lars 2007-04-04 23:29:03 +00:00
parent e4d82256e7
commit ee170fc7da
11 changed files with 1397 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

89
crypto-ezmlm/trunk/man/conf-gpgpy.5 Normal file
View file

@ -0,0 +1,89 @@
.TH conf-gpgpy 5 "March 02007" "gpgpy-ezmlm" "Manual of gpgpy-ezmlm"
.SH NAME
conf-gpgpy \- format and available configuration options of the mailing list
specific configuration file for encryption via gpgpy-ezmlm
.SH DESCRIPTION
The file \fBconf-gpgpy\fR is used by the encryption wrapper gpgpy-ezmlm that
can be integrated into the ezmlm-idx mailing list manager.
.PP
If a mailing list directory contains the file \fBconf-gpgpy\fR, then encryption
support is enabled for the list. The manual of \fIgpgpy-ezmlm-manage\fR(1)
tells you how to create this file.
.SH FORMAT
An entry in \fBconf-gpgpy\fR has the following format:
.RS
.sp
\fIOPTION\fP = \fIVALUE\fP
.sp
.RE
.PP
.IP \fIOPTION\fP
the name of a setting
.br
surrounding whitespaces are stripped
.br
case does not matter
.IP \fIVALUE\fP
the value of a setting
.br
may be enclosed in double or single quotes
.br
surrounding whitespaces are stripped
.br
case usually matters
.br
boolean values must be `no' or `yes' (case independent)
.PP
Lines are ignored if they start with `#', do not contain `=' or are empty.
.SH AVAILABLE OPTIONS
.IP \fBplain_without_key\fP
If there is no valid key available for a recipient, then she should receive the
message in plaintext. Otherwise a warning message is sent instead of the
encrypted part.
.br
.sp
Possible values are `no' or `yes'.
.br
.sp
The default value is `no'.
.IP \fBsign_messages\fP
Sign all outgoing mails with the key of the mailing list.
.br
.sp
Possible values are `no' or `yes'.
.br
.sp
The default value is `no'.
.IP \fBgnupg_dir\fP
The given directory contains the gnupg keyring for this mailing list.
Values starting with a slash (`/') are interpreted as absolute paths.
Values starting with a tilde (`~') are subject to user expansion.
All other paths are interpreted relative to the mailing list directory.
.br
.sp
The default value is `.gnupg', thus each mailing list uses its own keyring by
default.
.SH EXAMPLE
The following is the default content of a \fBconf-gpgpy\fP file, as it is
created by \fBgpgpy-ezmlm-manage\fP:
.RS
.sp
.nf
plain_without_key = no
sign_messages = no
gnupg_dir = .gnupg
.SH FILES
conf-gpgpy
.SH AUTHOR
Written by Lars Kruse
.SH REPORTING BUGS
Report bugs to <devel@sumpfralle.de>
.SH COPYRIGHT
Copyright \(co 02006-02007 Lars Kruse
.br
This is free software. You may redistribute copies of it under the terms of the
GNU General Public License <http://www.gnu.org/licenses/gpl.html>. There is NO
WARRANTY, to the extent permitted by law.
.SH SEE ALSO
gpgpy-ezmlm(5), gpgpy-ezmlm-manage(1), gpgpy-ezmlm-encrypt(1), gpgpy-ezmlm-queue(1)

61
crypto-ezmlm/trunk/man/gpgpy-ezmlm-encrypt.1 Normal file
View file

@ -0,0 +1,61 @@
.TH gpgpy-ezmlm-encrypt 1 "March 02007" "gpgpy-ezmlm" "Manual of gpgpy-ezmlm"
.SH NAME
gpgpy-ezmlm-encrypt \- the qmail-queue substitue \fIgpgpy-ezmlm-queue\fR
calls this script to decrypt and reencrypt outgoing mails of the
ezmlm-idx mailing list manager.
.SH SYNOPSIS
.B gpgpy-ezmlm-encrypt
check
.br
.B gpgpy-ezmlm-encrypt
[\fIMAILINGLIST_DIR\fR]
.SH DESCRIPTION
gpgpy-ezmlm-encrypt reads a mail from descriptor 0. It then reads the envelope
information from descriptor 1. It assumes that the given mailing list directory
is configured to be encrypted. It tries to decrypt the message and to encrypt
it then for every single recipient given by the envelope information.
Afterwards it hands the reencrypted mail and the respective envelope
information over to qmail-queue (or a similar substitute like ifspamh).
.PP
Read the manual of \fIqmail-queue\fR(8) to find out more details about the
interface of qmail-queue - except for the optional mailing list directory
argument it is identical to gpgpy-ezmlm-encrypt.
.PP
gpgpy-ezmlm-encrypt supports encrypted inline and multipart messages. Only
parts that had to be decrypted are also encrypted for the recipients. So
plaintext parts of a message will be delivered as plaintext, too.
.SH SELF-TESTS
If you call gpgpy-ezmlm-encrypt without an argument, then it only runs some
self-tests. This should ensure that the environment of gpgpy-ezmlm-encrypt
works in a sane way.
.PP
If no problems were encountered, then the resulting exit code will be zero.
A value of 81 indicates a serious problem.
.SH MAILING LIST DIRECTORY
Every ezmlm mailing list is stored in a separate directory. It contains all
subscribers, moderators, the configuration and the archive of sent messages.
Read the manual of ezmlm(5) for further details.
.PP
Encrypted mailing list directories differ from normal ones by the existence of
the file \fBconf-gpgpy\fR. See the manual of conf-gpgpy(5) for details.
.PP
The mailing list directory most likely also contains a gnupg directory for
storing the private and public keys available to the list. The location of this
directory is configured via conf-gpgpy(5).
.SH EXIT CODES
The exit codes of gpgpy-ezmlm-encrypt are similar to the ones defind in the
manual of qmail-queue(8). In contrast to qmail-queue, you may also expect some
error messages at STDERR.
.SH AUTHOR
Lars Kruse
.SH REPORTING BUGS
Report bugs to <devel@sumpfralle.de>
.SH COPYRIGHT
Copyright \(co 02007 Lars Kruse
.br
This is free software. You may redistribute copies of it under the terms of the
GNU General Public License <http://www.gnu.org/licenses/gpl.html>. There is NO
WARRANTY, to the extent permitted by law.
.SH SEE ALSO
gpgpy-ezmlm(5), gpgpy-ezmlm-queue(1), conf-gpgpy(5), qmail-queue(8), ezmlm(5)

99
crypto-ezmlm/trunk/man/gpgpy-ezmlm-manage.1 Normal file
View file

@ -0,0 +1,99 @@
.TH gpgpy-ezmlm-manage 1 "March 02007" "gpgpy-ezmlm" "Manual of gpgpy-ezmlm"
.SH NAME
gpgpy-ezmlm-manage \- manage encrypted ezmlm mailing lists
.SH SYNOPSIS
.B gpgpy-ezmlm-manage [\fIMAILINGLIST_DIR\fR] [\fIACTION\fR] [\fIPARAMETER\fR]
.SH DESCRIPTION
gpgpy-ezmlm-manage configures the encryption support of your \fBezmlm(5)\fR
mailing lists.
.PP
Call gpgpy-ezmlm-manage without any arguments to run some self-tests. An
exit code of zero indicate, that no problem was found. Any other exit code is
accompanied by a description of the detected problem.
.PP
Besides these self-tests, gpgpy-ezmlm-manage supports the following actions:
.IP \fBenable\fR
Enable encryption for a mailing list. Essentially this just creates the
file \fBconf-gpgpy\fR(5) in the mailing list directory with default values.
.br
Nothing happens, if the mailing list directory already contains this file.
.br
Afterwards you will probably want to create a private key for the list
by using the action \fBgenkey\fR described below.
.IP \fBdisable\fR
Disable encryption of a mailing list. This just removes the file
\fBconf-gpgpy\fR(5) from the mailing list directory.
.br
Nothing happens, if this file does not exist.
.br
Be aware, that the gnupg keyring of the mailing list
will not be deleted automatically. This makes it possible to enable encryption
later again without recreating and importing the previous keys. Remove the
gnupg directory manually if you know, what you are doing. Check the action
\fBget_gnupg_dir\fR below for this purpose.
.IP "\fBgenkey\fR [ NAME [ COMMENT [ MAIL ]]]"
Generate the private key of this list. Additional arguments may be used to
change the description of the key (see \fBgpg\fR(1) for details). Empty values
are guessed automatically - e.g. the mail address of the key is extracted from
the respective files of the ezmlm-idx mailing list directory.
.br
Key generation may take some time.
.br
The generated keys do (by default) never expire.
.br
Use gpg(1) directly, if you do not like the default assumptions of
gpgpy-ezmlm-manage. For this purpose you should retrieve the location of the
gnupg keyring directory by using the action \fBget_gnupg_dir\fR described
below.
.IP \fBis_encrypted\fR
Check if the specified mailing list is currently encrypted. This just checks
if the file \fBconf-gpgpy\fR(5) exists in the mailing list directory.
.br
An exit code of zero indicates an encrypted mailing list. The exit code 100
is returned for a plaintext mailing list. Any other exit code indicates a
configuration problem.
.br
The current encryption state of the mailing list is also written to STDOUT in
a humanly readable way.
.IP \fBget_gnupg_dir\fR
Return the directory of the gnupg keyring used by this mailinglist. The result
is written to STDOUT.
.br
The location of the directory can be configured in the file \fBconf-gpgpy\fR(5).
See its manpage for details.
.br
Use the gnupg directory to manage the keyring of the list. E.g. the following
command imports the public key of a recipient into the keyring:
.RS
.RS
.sp
.nf
gpg --homedir MAILINGLIST_KEYRING_DIR --import KEYFILE
.RE
.RE
.SH EXIT CODES
gpgpy-ezmlm-manage returns the following (non-zero) exit codes:
.IP \fB1\fR
gpgpy-ezmlm is not installed or configured properly.
.IP \fB2\fR
The specified arguments are invalid.
.IP \fB3\fR
The specified mailing list directory is invalid.
.IP \fB4\fR
The requested action failed.
.IP \fB100\fR
The action \fBis_encrypted\fR returns this value for non-encrypted mailing
lists.
.SH AUTHOR
Lars Kruse
.SH REPORTING BUGS
Report bugs to <devel@sumpfralle.de>
.SH COPYRIGHT
Copyright \(co 02007 Lars Kruse
.br
This is free software. You may redistribute copies of it under the terms of the
GNU General Public License <http://www.gnu.org/licenses/gpl.html>. There is NO
WARRANTY, to the extent permitted by law.
.SH SEE ALSO
gpgpy-ezmlm(5), conf-gpgpy(5), ezmlm(5), gpgpy-ezmlm-queue(1)

83
crypto-ezmlm/trunk/man/gpgpy-ezmlm-queue.1 Normal file
View file

@ -0,0 +1,83 @@
.TH gpgpy-ezmlm-queue 1 "March 02007" "gpgpy-ezmlm" "Manual of gpgpy-ezmlm"
.SH NAME
gpgpy-ezmlm-queue \- a wrapper around qmail-queue for handling gpg encrypted
ezmlm-idx mailing lists
.SH SYNOPSIS
.B gpgpy-ezmlm-queue
.sp
.B gpgpy-ezmlm-queue
test
.SH DESCRIPTION
gpgpy-ezmlm-queue expects a mail at descriptor 0 and envelope information
at descriptor 1. It uses the qmail specific environemnt variables (e.g. HOME
and EXT) to check if the mail was sent by an encrypted ezmlm mailing list.
Take a look at the manual of \fIqmail-command\fR(8) for more details about
these environment settings.
.PP
If the mail was queued by an encrypted ezmlm mailing list, then
\fIgpgpy-ezmlm-encrypt\fR(1) is used to process the mail before finally
queueing the mail. Otherwise \fiqmail-queue\fR(8) is called directly.
.PP
gpgpy-ezmlm-queue does not read anything from the file descriptors 0 and 1.
Instead it just hands over these descriptors to either qmail-queue or
gpgpy-ezmlm-encrypt.
.SH SELF-TESTS
If you call gpgpy-ezmlm-queue with the argument "\fBtest\fR", then it only runs
self-tests. This should ensure that the environment of gpgpy-ezmlm-queue
works in a sane way.
.PP
If no problems were encountered, then the resulting exit code will be zero.
A value of 81 indicates a serious problem. A description of the problems is
written to STDERR.
.SH INTEGRATION INTO QMAIL
It is required, that your qmail installation includes the qmailqueue patch.
It is part of many qmail patchsets - e.g. qmail-ldap or similar.
.PP
In order to use the gpgpy-ezmlm-queue wrapper in your mail delivery chain,
you have to set the QMAILQUEUE environment setting during the startup of
qmail to the location of gpgpy-ezmlm-queue. By default this should be
/usr/local/bin/gpgpy-ezmlm-queue.
.IP "Example for a \fI/var/qmail/rc\fR startup file:"
.sp
.nf
#!/bin/sh
exec env - PATH="/var/qmail/bin:$PATH" \\
QMAILQUEUE=/usr/local/bin/gpgpy-ezmlm-queue \\
qmail-start "`cat /var/qmail/control/defaultdelivery`"
.PP
If you used to override the QMAILQUEUE setting with another program location
(e.g. for spam filtering), then you should start to use the setting
\fBGPGPY_QMAILQUEUE\fR for this value. This tells gpgpy-ezmlm-encrypt to
run the specified program instead of qmail-queue for the final delivery.
.SH ENVIRONMENT VARIABLES
.IP \fBGPGPY_QMAILQUEUE\fR
Override the default location /var/qmail/bin/qmail-queue for the queueing
program. This may also be the path to a qmail-queue substitute, e.g.
\fIifspamh\fR or similar.
.IP \fBGPGPY_EZMLM_ENCRYPT\fR
Override the default location /usr/local/bin/gpgpy-ezmlm-encrypt for the
gpgpy-ezmlm encryption wrapper around qmail-queue.
.IP \fBGPGPY_RESTRICT_UID\fR
If all encrypted mailing lists are delivered by the same user account (e.g.
vlists, vpopmail, ...), then you should consider to set this environment
variable to the numerical value of its user id. This will skip the
detection of encrypted lists, if the UID setting given by qmail-command is
different.
.SH EXIT CODES
gpgpy-ezmlm-queue only returns specific exit codes during self-test. For normal
operations gpgpy-ezmlm-encrypt and qmail-queue are responsible for setting the
exit code.
.SH AUTHOR
Lars Kruse
.SH REPORTING BUGS
Report bugs to <devel@sumpfralle.de>
.SH COPYRIGHT
Copyright \(co 02007 Lars Kruse
.br
This is free software. You may redistribute copies of it under the terms of the
GNU General Public License <http://www.gnu.org/licenses/gpl.html>. There is NO
WARRANTY, to the extent permitted by law.
.SH SEE ALSO
gpgpy-ezmlm(5), gpgpy-ezmlm-encrypt(1), conf-gpgpy(5), qmail-queue(8), ezmlm(5)

102
crypto-ezmlm/trunk/man/gpgpy-ezmlm.5 Normal file
View file

@ -0,0 +1,102 @@
.TH gpgpy-ezmlm 1 "March 02007" "gpgpy-ezmlm" "Manual of gpgpy-ezmlm"
.SH NAME
gpgpy-ezmlm \- overview of the gpgpy-ezmlm encryption filter for ezmlm-idx
mailing lists
.SH OVERVIEW
.PP
The usual mail delivery of ezmlm-idx:
.sp
.nf
+---------------+ +------------+ +-------------+
| \fBincoming mail\fR | | \fBezmlm-send\fR | | \fB$QMAILQUEUE\fR |
| for the | ===> | processing | ===> | queueing |
| mailing list | | list setup | | all mails |
+---------------+ +------------+ +-------------+
.PP
Mail delivery for gpgpy-ezmlm encrypted lists:
.sp
.nf
+---------------+ +------------+ +-------------------+
| \fBincoming mail\fR | | \fBezmlm-send\fR | | \fBgpgpy-ezmlm-queue\fR |
| for the | ===> | processing | ===> | check if the list | =...
| mailing list | | list setup | | is encrypted |
+---------------+ +------------+ +-------------------+
.sp
+--------------------+
| \fB$GPGPY_QMAILQUEUE\fR |
/===================================> | |
|| | queueing all mails |
|| plaintext mailing list +--------------------+
||
...=+|
||
|| encrypted mailing list
||
|| +---------------------+ +-------------------+
|| | \fBgpgpy-ezmlm-encrypt\fR | | \fB$GPGPY_QMAILQUEUE\fR |
/====> | decrypt and encrypt | ==++==> | queue mail for |
| for each subscriber | || | 1st subscriber |
+---------------------+ || +-------------------+
||
|| +-------------------+
|| | \fB$GPGPY_QMAILQUEUE\fR |
|+==> | queue mail for |
|| | 2nd subscriber |
|| +-------------------+
||
||
\+==> ...
.IP \fINote:\fR
The environment variables \fB$QMAILQUEUE\fR and \fB$GPGPY_QMAILQUEUE\fR are not
set in a standard qmail installation. Thus they default to
/var/qmail/bin/qmail-queue.
.SH HOW DOES IT WORK
Since ezmlm-idx v0.431 \fBezmlm-send\fR(1) respects the QMAILQUEUE environment
setting when queueing a mail. If QMAILQUEUE is not set, then the original
qmail-queue program is used instead.
.PP
gpgpy-ezmlm relies on the QMAILQUEUE setting pointing to
\fBgpgpy-ezmlm-queue\fR(1). Read its manpage for how to do this easily.
.PP
If you used to override the QMAILQUEUE setting with another program location
(e.g. for spam filtering), then you should start to use the setting
\fBGPGPY_QMAILQUEUE\fR for this value. This tells gpgpy-ezmlm-encrypt to
run the specified program instead of qmail-queue for the final delivery.
.SH ENVIRONMENT VARIABLES
.IP \fBGPGPY_QMAILQUEUE\fR
Override the default location /var/qmail/bin/qmail-queue for the queueing
program. This may also be the path to a qmail-queue substitute, e.g.
\fIifspamh\fR or similar.
.IP \fBGPGPY_EZMLM_ENCRYPT\fR
Override the default location /usr/local/bin/gpgpy-ezmlm-encrypt for the
gpgpy-ezmlm encryption wrapper around qmail-queue.
.IP \fBGPGPY_RESTRICT_UID\fR
If all encrypted mailing lists are delivered by the same user account (e.g.
vlists, vpopmail, ...), then you should consider to set this environment
variable to the numerical value of its user id. This will skip the
detection of encrypted lists, if the UID setting given by qmail-command is
different.
.SH WHY DOES GPGPY-EZMLM NEED TWO SCRIPTS FOR QUEUEING?
The reason is simple: it is all about speed.
.PP
gpgpy-ezmlm-queue is a shell script and requires very little overhead for
execution. Thus it does not have a big impact on the time-critical delivery
performance of your mailserver.
.PP
gpgpy-ezmlm-encrypt is implemented in python, as this language offers the
\fIpyme\fR module for easy handling of gnupg encryption. It is only called for
messages that are sent by encrypted mailing lists, so the impact of the python
overhead on overall mail delivery should be acceptable.
.SH AUTHOR
Lars Kruse
.SH REPORTING BUGS
Report bugs to <devel@sumpfralle.de>
.SH COPYRIGHT
Copyright \(co 02007 Lars Kruse
.br
This is free software. You may redistribute copies of it under the terms of the
GNU General Public License <http://www.gnu.org/licenses/gpl.html>. There is NO
WARRANTY, to the extent permitted by law.
.SH SEE ALSO
gpgpy-ezmlm-queue(1), gpgpy-ezmlm-encrypt(1), qmail-queue(8), ezmlm(5), ezmlm-send(1)