408 lines
12 KiB
Groff
408 lines
12 KiB
Groff
.Dd February 16, 2003
|
|
.Dt KUVERT 1
|
|
.Os Unix
|
|
.Sh NAME
|
|
kuvert \- automatically sign and/or encrypt mail based on the recipients
|
|
.Sh SYNOPSIS
|
|
.Nm kuvert
|
|
.Op Fl d
|
|
.Op Fl b
|
|
.Op Fl r | Fl k | Fl n | Fl v
|
|
.Sh DESCRIPTION
|
|
.Nm kuvert
|
|
reads mails from its queue, analyzes the recipients, decides to whom
|
|
it should encrypt and/or sign the mail using the PGP-MIME framework
|
|
defined in RFC3156 and sends the mail using your real MTA. kuvert can use
|
|
both old-style 2.x
|
|
.Xr pgp 1
|
|
and modern
|
|
.Xr gpg 1
|
|
at the same time, or can
|
|
coerce gpg into producing pgp-2.x-compatible signatures/encrypted data.
|
|
.Pp
|
|
The mail submission into the queue is usually done by
|
|
.Xr kuvert_mta_wrapper "1".
|
|
.Pp
|
|
The option
|
|
.Fl r
|
|
causes an already running
|
|
.Nm kuvert
|
|
process to reload the configuration file and the keyring(s).
|
|
This is done by sending a SIGUSR1 to the running process.
|
|
.Pp
|
|
The option
|
|
.Fl d
|
|
activates debugging output to syslog.
|
|
.Nm kuvert
|
|
does not fork when in debugging mode and processes just the
|
|
first mail in the queue, after which it terminates.
|
|
.Pp
|
|
If the option
|
|
.Fl b
|
|
is given, then
|
|
.Nm kuvert
|
|
will send an error mail to the user whenever fatal errors are encountered.
|
|
.Pp
|
|
The option
|
|
.Fl k
|
|
makes
|
|
.Nm kuvert
|
|
kill an already running process.
|
|
.Pp
|
|
With the option
|
|
.Fl n
|
|
.Nm kuvert
|
|
does not
|
|
.Xr fork 2
|
|
but keeps running in the foreground.
|
|
.Pp
|
|
The option
|
|
.Fl v
|
|
makes
|
|
.Nm kuvert
|
|
output its version number and exit immediately.
|
|
.Pp
|
|
At startup
|
|
.Nm kuvert
|
|
reads the keyring(s) and the configuration file,
|
|
then usually forks and runs the queue once every 60 seconds.
|
|
Whenever there is a file with a name consisting of digits only in the
|
|
queue,
|
|
.Nm kuvert
|
|
will parse the mime structure into a temporary directory using
|
|
.Xr MIME::Parser "3pm".
|
|
.Pp
|
|
.Nm kuvert
|
|
then decides whether the mail shall be left as is, clear-text signed
|
|
or signed and encrypted according to RFC3156.
|
|
This decision is done independently for every recipient of the
|
|
mail and works as follows:
|
|
.Bl -bullet
|
|
.It
|
|
If a public key of the recipient is known, sign and encrypt.
|
|
.It
|
|
If no public key of the recipient is known, just sign.
|
|
.El
|
|
.Pp
|
|
There are some options governing or overriding this basic setup, see
|
|
the section
|
|
.Sx CONFIGURATION
|
|
for details.
|
|
.Pp
|
|
Please note that
|
|
.Nm kuvert uses the
|
|
.Ql To: ,
|
|
.Ql Cc:
|
|
and
|
|
.Ql Bcc:
|
|
headers to determine
|
|
the recipients.
|
|
Recipients listed in a
|
|
.Ql Bcc:
|
|
header are handled separately from all other recipients and do not affect
|
|
the choice of actions for other recipients (ie. handling of
|
|
.Ar -force
|
|
options).
|
|
Additionally, if there is a
|
|
.Ql Resend-To:
|
|
header,
|
|
.Nm kuvert
|
|
will do no signing/encryption and send the mail just as it
|
|
is to the recipients indicated in the
|
|
.Ql Resend-To:
|
|
header.
|
|
.Pp
|
|
Afterwards the parsed MIME entity is amended with the signature or
|
|
replaced with the encrypted data and is sent off using the MTA.
|
|
The temporary directory is cleaned and
|
|
.Nm kuvert
|
|
processes either the
|
|
next queued message or waits for new messages.
|
|
.Pp
|
|
If there are problems, kuvert disables further processing of the respective
|
|
queuefile (it adds a
|
|
.Ql \&.
|
|
at the beginning of the filename, thus making the file ignored for further
|
|
queue-runs)
|
|
and sends an error message back to the sender.
|
|
.Sh CONFIGURATION
|
|
.Nm kuvert
|
|
needs some configuration directives in its configuration file
|
|
.Pa ~/.kuvert .
|
|
This file is read at startup and whenever you have
|
|
.Nm kuvert
|
|
reread things using
|
|
.Fl r.
|
|
Empty lines and lines starting with
|
|
.Ql #
|
|
are ignored, as well as lines containing directives
|
|
.Nm kuvert
|
|
can not interpret.
|
|
.Pp
|
|
Directives can either be:
|
|
.Bl -bullet
|
|
.It
|
|
a directive name followed by whitespace and then a value,
|
|
.It
|
|
or a regular expression matching an email address, followed by whitespace and an action keyword.
|
|
.El
|
|
.Pp
|
|
The list of directives kuvert understands:
|
|
.Bl -tag
|
|
.It Ar PGPPATH Pa path
|
|
defines the old-style compatible pgp executable to be used.
|
|
Default:
|
|
.Pa /usr/bin/pgp
|
|
.It Ar GPGPATH Pa path
|
|
defines the gnupg-compatible new-style pgp executable to be used.
|
|
Default:
|
|
.Pa /usr/bin/gpg
|
|
.It Ar USEPGP number
|
|
if number is not 0, kuvert will use the old-style pgp executable to generate
|
|
old-style encryption/signatures. If it is 0,
|
|
.Nm kuvert
|
|
will use gpg in a
|
|
compatibility mode to produce the old-style stuff. Please note: gpg needs
|
|
the gnupg-extension gpg-idea for this compatibility mode. You also
|
|
have to setup gpg to automatically load this extension.
|
|
Default: 0
|
|
.It Ar MTA Pa path-and-args
|
|
defines the Mail Transfer Agent
|
|
.Nm kuvert
|
|
should use. The MTA must read the mail text from stdin, support the flag
|
|
.Fl t ,
|
|
and also support multiple recipients given in separate arguments.
|
|
Default: /usr/lib/sendmail -om -oi -oem
|
|
.It Ar SECRETONDEMAND number
|
|
If SECRETONDEMAND is 1,
|
|
.Nm kuvert
|
|
will ask for the
|
|
key passphrases on demand and just before signing. If SECRETONDEMAND is 0,
|
|
then
|
|
.Nm kuvert
|
|
will query for passphrases on startup and store them itself (which is not very secure).
|
|
SECRETONDEMAND is automatically set to 0 if GETSECRET or DELSECRET are not set.
|
|
Default: 0
|
|
.It Ar GETSECRET Pa path-and-args
|
|
.It Ar DELSECRET Pa path-and-args
|
|
define what program to run to deal with externally stored passphrases, if SECRETONDEMAND is set;
|
|
ignored otherwise.
|
|
The path-and-args must contain "%s" which will be replaced with the key id in question. The program
|
|
must print the passphrase on its standard output.
|
|
GETSECRET is executed to retrieve a passphrase, while DELSECRET is used to delete passphrases.
|
|
Default: none
|
|
.It Ar ALWAYSTRUST number
|
|
if 1, add the alwaystrust parameter to gpg's invocation. See
|
|
.Xr gpg "1" for details about this parameter. Default: 0
|
|
.It Ar LOGFILE Pa path
|
|
sets the file
|
|
.Nm kuvert
|
|
logs its actions to. The logs are appended to that
|
|
file. Default:
|
|
.Nm kuvert
|
|
usually logs to syslog.
|
|
.It Ar QUEUEDIR Pa path
|
|
sets the directory where kuvert_mta_wrapper and
|
|
.Nm kuvert
|
|
put the queue of
|
|
mails to be processed. Default:
|
|
.Pa ~/.kuvert_queue
|
|
.It Ar TEMPDIR Pa path
|
|
sets the directory
|
|
.Nm kuvert
|
|
uses for temporary storage of the parts of the
|
|
parsed MIME entity.
|
|
.Em Attention: This directory is cleaned after every mail handled and every file in there is removed!
|
|
Default:
|
|
.Pa /tmp/kuvert.<uid>.<pid>.
|
|
.It Ar INTERVAL number
|
|
sets the queue check interval. the unit of measurement is seconds.
|
|
Default: 60 seconds
|
|
.It Ar IDENTIFY number
|
|
if non-zero,
|
|
.Nm kuvert
|
|
adds a
|
|
.Ql X-mailer
|
|
header to all mails it processes. Default: 0
|
|
.It Ar NGKEY keyid
|
|
sets the owner's key id for new-style pgp/gpg. To disable new-style pgp/gpg
|
|
completely, set the keyid to "0". Default: the first private DSA key found is used.
|
|
.It Ar STDKEY keyid
|
|
sets the owner's key id for old-style pgp. To disable old-style pgp completely, set the keyid to 0. Default: the first private RSA key found is used.
|
|
.It Ar DEFAULT action
|
|
specifies the action to be taken for unspecified recipient addresses.
|
|
See the next paragraphs for an explanation of the
|
|
.Ar action
|
|
argument.
|
|
.El
|
|
.Pp
|
|
All lines not starting with the pound sign
|
|
.Ql #
|
|
or a recognized directive
|
|
are interpreted as a
|
|
.Xr perl 1
|
|
regular expression followed by whitespace and an
|
|
action keyword.
|
|
.Pp
|
|
The regular expressions are applied to the email address
|
|
of the recipients of the mail, and the action keyword describes how to
|
|
modify
|
|
.Nm kuvert Ns
|
|
\&'s behavious for a recipient.
|
|
.Pp
|
|
The regular expression has to be written without the bracketing
|
|
.Ql / Ns
|
|
-characters.
|
|
The regular expressions are evaluated case-insensitively,
|
|
and in the order given in the configuration file. The first matching regexp
|
|
ends the evaluation sequence.
|
|
.Pp
|
|
The default action is to do not encrypt or sign at all, so you should
|
|
set a default that is reasonable for you by using the
|
|
.Ql DEFAULT
|
|
directive.
|
|
.Pp
|
|
The known action keywords are:
|
|
.Bl -tag
|
|
.It Ar none
|
|
Send it as it is, do not sign or encrypt at all. The MIME structure of
|
|
the mail is not changed in whatever way before sending.
|
|
This is the default action.
|
|
.Pp
|
|
This option is
|
|
.Em slightly special:
|
|
An explicitly set action of
|
|
.Ql none
|
|
is
|
|
.Em not affected or overridden
|
|
by any of the
|
|
.Ar -force
|
|
options or by the override header.
|
|
.It Ar std
|
|
Use just old-style pgp. If there is an old-style key known, encrypt and sign
|
|
using this old-style key and the owner's old-style key, otherwise just sign
|
|
using the owner's old-style key.
|
|
.It Ar ng
|
|
Use just new-style pgp, similar to the above.
|
|
.It Ar stdsign
|
|
Never encrypt, just sign using the owner's old-style key.
|
|
.It Ar ngsign
|
|
Never encrypt, just sign using the owner's new-style key.
|
|
.It Ar fallback
|
|
Encrypt with new-style, old-style or sign with new-style (or std-style if no new-style private key is available).
|
|
If there is a new-style key of the recipient known, encrypt and sign with
|
|
this key, else if there is an old-style key, encrypt and sign with this
|
|
key. Otherwise just sign with the owner's new-style key or (as last resort) the old-style key.
|
|
.It Ar none-force
|
|
Force no encryption/signing for all recipients of this mail.
|
|
.It Ar fallback-force
|
|
Force a fallback-type action for the recipients of this mail:
|
|
encrypt and sign with new-style or old-style pgp if keys for
|
|
.Em all affected
|
|
recipients are available or sign with new-style pgp. Recipients with
|
|
an action set to
|
|
.Ql none
|
|
are
|
|
.Em not affected
|
|
by fallback-force. Also note that a mixture of
|
|
old-style and new-style encryption is possible with fallback-force.
|
|
.It Ar ngsign-force "," stdsign-force
|
|
Sign only for all affected recipients, with new-style or old style pgp respectively. Again recipients with action
|
|
.Ql none
|
|
are
|
|
.Em not affected.
|
|
.It Ar ng-force
|
|
Encrypt and sign for all recipients of this mail if there is a new-style key
|
|
available for all of them, otherwise just sign for all of them using
|
|
new-style pgp. The difference between this action
|
|
and
|
|
.Ar fallback-force
|
|
is that there's no mixing of old-style and new-style pgp possible here.
|
|
Again recipients with action
|
|
.Ql none
|
|
are
|
|
.Em not affected.
|
|
.It Ar std-force
|
|
like
|
|
.Ar ng-force ","
|
|
but with old-style pgp.
|
|
Again recipients with action
|
|
.Ql none
|
|
are
|
|
.Em not affected.
|
|
.El
|
|
.Pp
|
|
Additionally, you can specify an override for a single mail by
|
|
adding a header to the mail of the form
|
|
.Ql X-Kuvert: Ar action
|
|
where action is one of the action keywords just listed
|
|
above. This override will be applied to all recipients of the given
|
|
mail and will override all action specifications given in the configuration
|
|
file, except the explicit
|
|
.Ql none Ns
|
|
s. Before final sending an email
|
|
.Nm kuvert
|
|
will remove
|
|
any existing override header from the email.
|
|
.Pp
|
|
The various
|
|
.Ar -force
|
|
actions are intended for users who want to avoid sending cleartext (signed)
|
|
and encrypted variants of the same mail to different recipients: You can
|
|
either turn off encryption or signing completely, or use the maximum
|
|
amount of privacy that is possible for a given set of recipients by checking
|
|
for keys for everybody before deciding whether to encrypt or just sign.
|
|
.Pp
|
|
The special handling for
|
|
.Ql none
|
|
does break this paradigma a bit, but is
|
|
necessary to make any
|
|
.Ar -force
|
|
option a safe choice for your
|
|
.Ql DEFAULT
|
|
action: Otherwise
|
|
.Nm kuvert
|
|
would send stuff signed or encrypted to recipients you know to be
|
|
completely unable/unwilling to accept signed or encrypted mail
|
|
(like mail robots). Therefore these were made unaffected (and disregarded)
|
|
by the
|
|
.Ar -force
|
|
options.
|
|
.Pp
|
|
.Sy Please note: the first occurrence of a -force action overrides all possible other occurrences!
|
|
.Sh FILES
|
|
.Bl -tag
|
|
.It Pa ~/.kuvert
|
|
configuration file for
|
|
.Nm kuvert
|
|
and
|
|
.Xr kuvert_mta_wrapper "1".
|
|
.It Pa ~/.kuvert_queue
|
|
the default queue directory for
|
|
.Nm kuvert
|
|
if the configuration file does not specify an alternative.
|
|
.It Pa /tmp/kuvert.pid.<uid>
|
|
holds the pid of a running process.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr kuvert_mta_wrapper "1",
|
|
.Xr q-agent "1",
|
|
.BR gpg "1",
|
|
.BR pgp "1",
|
|
RFC3156, RFC2015, RFC2440
|
|
.Sh AUTHORS
|
|
.An Alexander Zangerl <az@snafu.priv.at>
|
|
.Sh BUGS
|
|
Currently
|
|
.Nm kuvert
|
|
needs something sendmail-like in
|
|
.Pa /usr/lib/sendmail
|
|
that understands
|
|
.Fl t,
|
|
.Fl om,
|
|
.Fl oi
|
|
and
|
|
.Fl "oem".
|
|
.Pp
|
|
Multiple -force actions won't work.
|