X-Git-Url: https://git.deb.at/w?p=pkg%2Ft-prot.git;a=blobdiff_plain;f=t-prot.1;h=1474fccfbdd5b4afdcbf7042fc762c7614d4477a;hp=035f9b975cad773157ef0891848a9d5fb0bd6e73;hb=HEAD;hpb=eaaeebe9048266deff624831bf50ba847ae7f048 diff --git a/t-prot.1 b/t-prot.1 index 035f9b9..1474fcc 100644 --- a/t-prot.1 +++ b/t-prot.1 @@ -1,45 +1,88 @@ -.\" $Id: t-prot.1,v 1.148 2010/02/07 14:31:14 jochen Exp $ +.\" $Id: t-prot.1,v 1.192 2015/03/26 08:59:50 jochen Exp $ .\" -.TH T-PROT "1" "February 2010" "T-PROT" +.TH T-PROT "1" "March 2015" "T-PROT" .SH NAME t-prot \- TOFU Protection - Display Filter for RFC 5322 messages .SH SYNOPSIS .BI "t\-prot [" OPTIONS "]..." .SH DESCRIPTION .PP -This program is a filter to improve the readability of +This program is a filter to improve the readability of internet messages (emails and usenet posts) by *hiding* some annoying parts, e.g. mailing list footers, signatures, and TOFU (see definition below), as well as squeezing sequences of blank lines or punctuation. +The program also detects TOFU or a high quoting ratio in a message (so +you may take appropriate action, e.g. when submitting messages to a mailing +list or a news server). .br The filter is written in Perl and relies on input to be a single message conforming to RFC 822 or its successors, RFC 2822 and RFC 5322. -Messages conforming to RFCs 2045-2049 should be treated reasonably correct. +In messages conforming to MIME (RFCs 2045-2049) t\-prot handles text/plain +parts, others are not touched. .PP Already reformatted messages are handled well: the script was initially designed to cope with the output of the MUA mutt (which is the reason for not using standard CPAN modules for handling messages). .PP -For easy usage, you can include the file muttrc.t\-prot in your -~/.muttrc. Also coming with the t-prot package is the example S-Lang -macro t\-prot.sl for using t-prot from within slrn. +T\-prot offers example configuration files for mutt and its fork mutt\-kz, +Heirloom mailx and metamail. Also coming with the t-prot package is the +example S-Lang macro t\-prot.sl for using t-prot from within slrn. There +is a proof\-of\-concept filter for INN2, which you will have to adapt +to the needs of the news site you host. For use with sendmail's +alias(5) file, please see below (the option +.BR "\-p" " provides an example line)." .SH OPTIONS +.PP +If you do not specify any options, t\-prot does ... nothing. Every +feature you want must be turned on explicitly. +Admittedly, we have quite a number of options for t\-prot. To limit +confusion they are grouped into five sections: Input/Output Options, +Advertisement And Mailing List Footers, Filtering Options, Detection +Options, and Other Options. While the others should be quite clear, +filtering and detection might deserve a word (or two). +.PP +If you want to tune the appearance of your mail from within your MUA +(or news messages from within your NUA), then go for the Filtering +Options section. +.PP +If you want to use t\-prot to check on mails before they are submitted +to mailing lists, fed to your news server, or delivered by your MDA, +then have a peek at the Detection Options section. You may accept or +reject/bounce messages depending on t\-prot's result. +.SH INPUT/OUTPUT OPTIONS .TP -.BR "\-A" =DIRECTORY -"ad footer directory": -Defines the directory which contains the advertisement list footers (one -footer per file) which are to be tested when removing them with options -.B \-a -or -.BR \-\-ftr\-ad . -.br -This option is also needed if you do not want signature lengths to be -counted wrong or fullquotes get undetected when an ad footer is -appended at the bottom of the message (especially when using -.B "\-S" -or -.BR "\-t" ). +.BR "\-i" " FILE" +Defines an input file; default is '\-' i.e. STDIN. +.TP +.BR "\-o" " FILE" +Defines the output file; default is STDOUT. +.TP +.B "\-\-body" +Input consists just of the message's body. There are no RFC 5322 header +lines. +.IP +.IR NOTE : +This does not work with \-\-pgp\-short, and multipart messages will not +be detected due to missing headers. +.TP +.B "\-\-lax\-security" +Allow insecure writing method. DO NOT USE UNLESS YOU REALLY KNOW WHAT +YOU ARE DOING. (This ugly workaround is needed for some early mutt versions +and should NEVER be used as a default, otherwise it will probably turn into +a security issue.) +.sp +You can use this option safely to enable +.B "\-o" +/dev/null (or other files which cannot be changed with the user's +privileges). +.TP +.BR "\-\-max\-lines" =x +Maximum number of lines a message may count (with headers). If the message +is longer than x lines, the message will not be processed but printed +unmodified. Exit status will be EX_DATAERR except when called with \-Mmutt +or \-Mmutt\-kz. +.SH ADVERTISEMENT AND MAILING LIST FOOTERS .TP .B "\-a" "commercial signature": @@ -47,7 +90,7 @@ Hides "footers" (signatures) from commercial email providers. .br This option compares the last lines of the message body with any footer file found in the directory specified with -.BR "\-A" =DIRECTORY +.BR "\-A" " DIRECTORY" (which is mandatory for this option). The comparison is done by perl's .B index() function (please try @@ -59,57 +102,6 @@ This option is not needed if .B \-\-ftr\-ad is specified. .TP -.BR "\-\-bigq" [=n[,x]] -"shrink big quotes": -Blocks of quotes with more than n lines will be shrunk to x lines. -Defaults are 30 for n and 10 for x. -.TP -.B "\-\-body" -Input consists just of the message's body. There are no RFC 2822 header -lines. -.IP -.IR NOTE : -This does not work with \-\-pgp\-short, and multipart messages will not -be detected due to missing headers. -.TP -.B "\-c" -"compress": -Squeezes a sequence of blank lines to just two blank lines. -.TP -.BR "\-\-check" [=FLAGS] -Run checks. If successful, print an error message and quit with -an appropriate exit code. Useful e.g. for rejecting messages from -within INN2. -.IP -Flags are separated by commas (no whitespaces), and can be the -following (right now just one flag): -.IP -.IR ratio [=n] -.br -If the quoting ratio is n or more, the message is rejected. Must be -between 0 and 1, or else it is entirely disabled. Default is 0.75 -(i.e., 75% of the message lines are quotes). -.TP -.B "\-d, \-\-debug" -Print envelope info to syslog when bouncing TOFU contaminated email. -Default syslog facility is mail.debug. Requires -.BR \-p . -.TP -.B "\-\-diff" -"tolerate diff": -Tolerate unified diff (see -.BR diff (1) -and -.BR patch (1)) -appended *after* the signature (which usually makes the signature too long -to be valid). Not entirely consequent but sometimes useful, e.g. at the -Linux kernel mailing list. -.TP -.B "\-e" -"ellipsis": -Squeezes a sequence of four or more dots, exclamation marks, or question marks -to only three dots or marks, respectively. -.TP .B "\-\-ftr\-ad" "enable aggressive ad footer matching": With this option enabled, t-prot makes footer detection really greedy: We @@ -127,7 +119,36 @@ little *too* greedy. .sp .IR NOTE : This requires a directory with footer files to be given with option -.BR "\-A" =DIRECTORY. +.BR "\-A" " DIRECTORY". +.TP +.BR "\-A" " DIRECTORY" +"ad footer directory": +Defines the directory which contains the advertisement list footers (one +footer per file) which are to be tested when removing them with options +.B \-a +or +.BR \-\-ftr\-ad . +.br +This option is also needed if you do not want signature lengths to be +counted wrong or fullquotes get undetected when an ad footer is +appended at the bottom of the message (especially when using +.B "\-S" +or +.BR "\-t" ). +.TP +.B "\-l" +"list signature": +Hides "footers" (signatures) from mailing lists. Footer detection works like the +.B "\-a" +option. +.sp +.IR NOTE : +This requires a directory with footer files to be given with option +.BR "\-L" " DIRECTORY". +.B \-l +is not needed if +.B \-\-ftr\-ml +is specified. .TP .B "\-\-ftr\-ml" "enable aggressive mailing list footer matching": @@ -139,17 +160,60 @@ Works similar to \-\-ftr\-ad, just that it is intended for mailing list footers. .sp .IR NOTE : This requires a directory with footer files to be given with option -.BR "\-L" =DIRECTORY. +.BR "\-L" " DIRECTORY". .TP -.B "\-\-groupwise" -Hides TOFU as produced by Novell Groupwise. +.BR "\-L" " DIRECTORY" +"list footer directory": +Defines the directory which contains the mailing list footers (one footer +per file) which are to be tested when removing them with the options +.B \-l +or +.BR \-\-ftr\-ml . +.br +This option is also needed if you do not want signature lengths to be +counted wrong or fullquotes get undetected when a mailing list footer is +appended at the bottom of the message (especially when using +.B "\-S" +or +.BR "\-t" ). +.SH FILTER OPTIONS .TP -.B "\-h, \-\-help" -Displays a short help text with a summary on all options, and exits. +.BR "\-\-bigq" [=n[,x]] +"shrink big quotes": +Blocks of quotes with more than n lines will be shrunk to x lines. +Defaults are 30 for n and 10 for x. .TP -.BR "\-i" =FILE -"input file": -Defines a file for input; the default input is from '\-' i.e. STDIN. +.BR "\-c" "[n]" +"compress": +Squeezes a sequence of blank lines to just n blank lines. n defaults to 2. +.TP +.B "\-\-diff" +Tolerate unified diff (see +.BR diff (1) +and +.BR patch (1)) +appended after the signature (which usually makes the signature too long +to be valid). +.sp +Also, protect diff standard output from hiding (which would otherwise be easy +prey for +.BR "\-t" ). +.TP +.B "\-e" +"ellipsis": +Squeezes a sequence of four or more dots, exclamation marks, or question marks +to only three dots or marks, respectively. +.TP +.BR "\-\-fixind" +Fix broken quotes to adhere to RFC 3676 by removing spaces between quote +characters and adding a space after them. +.br +.IR NOTE : +This may produce false positives if spaces in between quote characters +are intended (thus changing the quoting level, see RFC 3676 for details). +.TP +.B "\-\-groupwise" +Hides TOFU as produced by Novell Groupwise. .TP .B "\-k" "anti Kammquote": @@ -164,12 +228,12 @@ section of this man page, that is). .IP Please also note that enabling this option is quite a performance hit. .TP -.BR "\-\-kminl" =n -Minimum line length for wrapped line detection on Kammquotes. For -details, please see the source code. +.BR "\-\-kdiff" =n +Minimum length difference between two lines for wrapped line detection on +Kammquotes. For details, please see the source code. .br Anyway, lower values make the algorithm more aggressive, higher values -make Kammquotes harder to detect. Default is 65. +make Kammquotes harder to detect. Default is 20. .sp Requires .BR "\-k" . @@ -184,63 +248,30 @@ make Kammquotes harder to detect. Default is 80. Requires .BR "\-k" . .TP -.BR "\-\-kdiff" =n -Minimum length difference between two lines for wrapped line detection on -Kammquotes. For details, please see the source code. +.BR "\-\-kminl" =n +Minimum line length for wrapped line detection on Kammquotes. For +details, please see the source code. .br Anyway, lower values make the algorithm more aggressive, higher values -make Kammquotes harder to detect. Default is 20. +make Kammquotes harder to detect. Default is 65. .sp Requires .BR "\-k" . .TP -.BR "\-L" =DIRECTORY -"list footer directory": -Defines the directory which contains the mailing list footers (one footer -per file) which are to be tested when removing them with the options -.B \-l -or -.BR \-\-ftr\-ml . -.br -This option is also needed if you do not want signature lengths to be -counted wrong or fullquotes get undetected when a mailing list footer is -appended at the bottom of the message (especially when using -.B "\-S" -or -.BR "\-t" ). -.TP -.B "\-l" -"list signature": -Hides "footers" (signatures) from mailing lists. Footer detection works like the -.B "\-a" -option. -.sp -.IR NOTE : -This requires a directory with footer files to be given with option -.BR "\-L" =DIRECTORY. -.B \-l -is not needed if -.B \-\-ftr\-ml -is specified. -.TP -.B "\-\-lax\-security" -Allow insecure writing method. DO NOT USE UNLESS YOU REALLY KNOW WHAT -YOU ARE DOING. (This ugly workaround is needed for some early mutt versions -and should NEVER be used as a default, otherwise it will probably turn into -a security issue.) -.TP .BR "\-\-locale" =LOCALE -"locale to use": -Here you can specify which locale to use. Right now this option is only -used when -.I "\-Mmutt" +Specify which locale to use for correct parsing of your MUA's formatting +of the displayed message (usually it is the locale your MUA uses). Right +now this option is only used when +.IR "\-Mmutt" " or" +.I "\-Mmutt\-kz" is specified, but this may change in future. You need the Perl module .I "Locale::gettext" for this feature. .sp .IR NOTE : If you use -.B mutt +.BR mutt , +.B mutt-kz or .B gnupg with locales, t-prot will only work correctly if you specify the corresponding @@ -256,24 +287,23 @@ You also have to make sure you are running t-prot with matching .B gnupg and -.B mutt +.BR mutt " /" +.B "mutt\-kz" versions. T-prot detects .B gnupg and -.B mutt +.BR mutt " /" +.B "mutt\-kz" locales of the recent stable versions of those programs, earlier versions -might not work well with a recent version of t-prot. There are patches available -to make t-prot fit into environments with some other -.B mutt -and -.B gnupg -versions. +might not work well with a recent version of t-prot. .TP -.BR "\-M, \-\-mua" =MUA +.BR "\-M, \-\-mua" MUA "mail user agent": Turn on special treatment for some mail user agents. (Right now only .BR mutt (1) -is supported, but more might be added in future.) +and +.BR "mutt\-kz" (1) +are supported, but more might be added in future.) .IR Caveat : If your MUA is supported by this feature you must ensure t-prot makes use of it when called from within your MUA to work as desired. @@ -288,7 +318,9 @@ fullquotes beginning with and some header lines...) .TP .B "\-\-ms\-smart" -Burn CPU cycles trying to be smart with MS style TOFU. +Burn CPU cycles trying to be smart with MS style TOFU: If there are PGP +signed parts inside the TOFU, the text still might conceal other message +parts and therefore should not be deleted. .sp Please note that this is probably just a waste of time because most MS Outlook users who do produce this kind of TOFU won't care about @@ -298,64 +330,22 @@ this option will probably just be interesting for mutt message hooks .BR know " the sender tries to write legible messages)." .sp Requires -.BR "\-Mmutt" " and" -.BR "\-m" . -.TP -.BR "\-\-max\-lines" =x -Maximum number of lines a message may count (with headers). If the message -is longer than x lines, the message will not be processed but printed -unmodified. Exit status will be EX_DATAERR except when called with -Mmutt. -.TP -.BR "\-o" =FILE -"output file": -Define the file to be written *to*; the default output is to STDOUT. -.sp -If "NONE" is specified as file name, there will be no output at all (useful -if all you need is t-prot's exit code). Use something like "./NONE" if you -really want to write to a file of this name. -.TP -.BR "\-p" [=ADDRESS] -"picky delivery": -If we really find some TOFU, abort with exit code -.IR EX_UNAVAILABLE . -Otherwise redirect the message to ADDRESS if given. -.sp -Intended for use from within mail delivery agents (MDAs) or mail transport -agents (MTAs), or even from with INN, so the message bounces if TOFU is -detected, and does not get on *your* nerves. :) -.sp -As an example for usage with -.BR sendmail , -put this line into your alias file and invoke -.BR newaliases : -.sp -notofu: |"/usr/local/bin/t\-prot \-mt \-p=user@mydomain" -.sp -This will bounce messages for if any TOFU is detected -inside the message, and deliver it to otherwise. -.I Note -that TOFU is only detected if you specify -.B "\-t" -respectively +.BR "\-Mmutt" " /" +.BR "\-Mmutt\-kz" " and" .BR "\-m" . -.sp -.B PLEASE be careful not to bounce messages to mailing lists! -.TP -.BR "\-P" =MESSAGE -"user defined bounce message for picky delivery": -You may specify your own bounce message to be returned when we try to deliver -an email and bounce it because there is TOFU inside. .TP .B \-\-pgp\-move -Move PGP verification output to bottom; requires -.BR "\-Mmutt" . +Move PGP and SSL verification output to bottom; requires +.BR "\-Mmutt" " /" +.BR "\-Mmutt\-kz" . .TP .B \-\-pgp\-move\-vrf -Move PGP verification outout to bottom only if verification shows a good signature -and the signature could be verified as authentic (using a trust path). If there is -any problem with the signature, the PGP output should not be moved so the user is -more likely to notice. Requires -.BR "\-Mmutt" . +Move PGP and SSL verification output to bottom only if verification shows a +good signature and the signature could be verified as authentic (using a +trust path). If there is any problem with the signature, the PGP output +should not be moved so the user is more likely to notice. Requires +.BR "\-Mmutt" " /" +.BR "\-Mmutt\-kz" . .sp .IR NOTE : If gpg is terminated before finished (e.g. hitting Ctrl-C, or using @@ -365,14 +355,19 @@ to be smart, there will be false positives. .TP .B \-\-pgp\-short Hide non-relevant PGP key uids; requires -.BR "\-Mmutt" . +.BR "\-Mmutt" " /" +.BR "\-Mmutt\-kz" . .TP .B "\-r" "rip header off": Hides all mail header lines. .TP -.BR "\-S" [=n] -"supression of overlong signatures": +.B "\-\-reply" +Subject lines with multiple reply prefixes (Re: and translations into other +languages) get squeezed to only one prefix. +.TP +.BR "\-S" "[n]" +"suppression of overlong signatures": Signatures are to be n lines (not including the one containing dash-dash-space) or less. If there are more, it is probably not that spirited after all. So with this option you trade it for a @@ -392,6 +387,13 @@ signature, but it is included when displaying how many lines were deleted. Hides signatures, i.e. all lines after a "signature dashes" line, i.e. a line with three characters: dash-dash-space (no more, no less). .TP +.B "\-\-sani" +Sanitize headers "To:", "From:" and "Subject:": Quoted-printable gets +fixed to the corresponding chars. German Umlauts are translated to their +"ae", "oe", "ue" pendants. +.br +Useful e.g. for searching by subject within MUAs like Berkeley mailx. +.TP .BR "\-\-sigsmax" [=n] "maximum number of tolerated signatures": Here you can define how many signatures you accept to be treated as such. @@ -412,29 +414,81 @@ test to avoid false positives for Microsoft style TOFU on such messages. .TP .B "\-t" "TOFU deletion": -Hides "traditional style" TOFU, where each line begins with an -indent string like "> ". -.br -(You may edit the indent pattern in the script itself to suit your needs, -but it is surely -.I not -recommended at all.) +Hides "traditional style" TOFU, where each line begins with the +indent string ">". .TP .B "\-w" "whitespace deletion": Hides trailing whitespace (sequences of space and tab). CAVEAT: This may lead to interesting effects with crossposts between mailing lists or with undetected signature attempts. +.SH DETECTION OPTIONS +.TP +.BR "\-P" " MESSAGE" +"user defined bounce message for picky delivery": +You may specify your own bounce message to be returned when we try to deliver +an email and bounce it because there is TOFU inside. See +.BR "\-p" . +.TP +.BR "\-p" " [ADDRESS]" +"picky delivery": +If we really find some TOFU, abort with exit code +.IR EX_UNAVAILABLE . +Otherwise redirect the message to ADDRESS if given. +.sp +Intended for use from within mail delivery agents (MDAs) or mail transport +agents (MTAs), or even from within INN, so the message bounces if TOFU is +detected, and does not get on *your* nerves. :) +.sp +As an example for usage with +.BR sendmail , +put this line into your alias file and invoke +.BR newaliases : +.sp +notofu: |"/usr/local/bin/t\-prot \-mt \-p=user@mydomain" +.sp +This will bounce messages for if any TOFU is detected +inside the message, and deliver it to otherwise. +.I Note +that TOFU is only detected if you specify +.B "\-t" +respectively +.BR "\-m" . +.sp +.B PLEASE be careful not to bounce messages to mailing lists! +.TP +.BR "\-\-check" [=FLAGS] +Run checks. If successful, print an error message and quit with +an appropriate exit code. Useful e.g. for rejecting messages from +within INN2. +.IP +Flags are separated by commas (no whitespaces), and can be the +following (right now just one flag): +.IP +.IR ratio [=n] +.br +If the quoting ratio is n or more, the message is rejected. Must be +between 0 and 1, or else it is entirely disabled. Default is 0.75 +(i.e., 75% of the message lines are quotes). +.TP +.B "\-d, \-\-debug" +Print envelope info to syslog when bouncing TOFU contaminated email. +Default syslog facility is mail.debug. Requires +.BR \-p . +.SH OTHER OPTIONS +.TP +.B "\-h, \-\-help" +Displays a short help text with a summary on all options, and exits. .TP .B "\-v, \-\-version" -Prints the current version number and release date, and exits. +Prints the current version number and exits. .SH ENVIRONMENT The environment variables .IR LC_ALL , .IR LC_MESSAGES , and .I LANG -are read and respected when interpreting output by mutt or gnupg +are read and respected when interpreting output by mutt / mutt\-kz or gnupg (unless they are overruled by the \-\-locale option). T-prot's own output is English regardless of any locale setting. .SH EXIT STATUS @@ -487,9 +541,10 @@ files as absolutely needed in any footer directory. All PGP related options are eating up lots of CPU time. Try to avoid them on unsigned and unencrypted messages. .PP -When calling t-prot from within mutt, you might use mutt's folder-hook -and message-hook facilities to turn options on only when needed, e.g. to -set up a different footer directory for each mailing list folder. +When calling t-prot from within mutt (or mutt\-kz), you might use mutt's +folder-hook and message-hook facilities to turn options on only when +needed, e.g. to set up a different footer directory for each mailing list +folder. .SH TROUBLESHOOTING .TP .IR Q : @@ -509,7 +564,7 @@ your line is empty you match unconditionally. .PP .TP .IR Q : -I use the options \-l and \-L to supress mailing list footers when +I use the options \-l and \-L to suppress mailing list footers when displaying messages in .BR mutt (1). This does work sometimes, but sometimes it does not: the footer is not @@ -551,7 +606,7 @@ Written by Jochen Striepe . All of the documentation and software included in the t-prot releases is copyrighted by Jochen Striepe (except when explicitly stated otherwise). .PP -Copyright \(co 2001-2010 Jochen Striepe. All rights reserved. +Copyright \(co 2001-2015 Jochen Striepe. All rights reserved. .PP Redistribution and use, with or without modification, are permitted provided that the following conditions are met: @@ -644,13 +699,17 @@ section). Beside that, all main features should be implemented by now. See the TODO file for more information. .SH "SEE ALSO" .BR mutt (1), +.BR mutt\-kz (1), .BR muttrc (5) and the part about "display_filter", .BR perl (1), .BR aliases (5), .sp -RFCs 2045-2049 and 5322, +RFCs 2045-2049, 3676 and 5322, .sp +.I http://freshmeat.net/articles/t\-prot/ +(a nice, solid introduction), +.br .I http://got.to/quote/ (German language), .br