.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .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" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" 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 "Courier::Filter::Module::Parts 3pm" .TH Courier::Filter::Module::Parts 3pm "2022-10-21" "perl v5.34.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Courier::Filter::Module::Parts \- Message (MIME multipart and ZIP archive) parts filter module for the Courier::Filter framework .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Courier::Filter::Module::Parts; \& \& my $module = Courier::Filter::Module::Parts\->new( \& max_message_size \& => $max_message_size, \& max_part_size => $max_part_size, \& views => [\*(Aqraw\*(Aq, \*(Aqzip\*(Aq], \& signatures => [ \& { \& # One or more of the following options: \& mime_type => \*(Aqtext/html\*(Aq || qr/html/i, \& file_name => \*(Aqfile_name.ext\*(Aq || qr/\e.(com|exe)$/i, \& size => 106496, \& digest_md5 => \*(Aqb09e26c292759d654633d3c8ed00d18d\*(Aq, \& encrypted => 0, \& \& # Optionally any of the following: \& views => [\*(Aqraw\*(Aq, \*(Aqzip\*(Aq], \& response => $response_text \& }, \& ... \& ], \& \& logger => $logger, \& inverse => 0, \& trusting => 0, \& testing => 0, \& debugging => 0 \& ); \& \& my $filter = Courier::Filter\->new( \& ... \& modules => [ $module ], \& ... \& ); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This class is a filter module class for use with Courier::Filter. It matches a message if one of the message's parts (\s-1MIME\s0 parts, or files in a \s-1ZIP\s0 archive) matches one of the configured signatures. .SS "Constructor" .IX Subsection "Constructor" The following constructor is provided: .IP "\fBnew(%options)\fR: returns \fICourier::Filter::Module::Parts\fR" 4 .IX Item "new(%options): returns Courier::Filter::Module::Parts" Creates a new \fBParts\fR filter module. .Sp \&\f(CW%options\fR is a list of key/value pairs representing any of the following options: .RS 4 .IP "\fBviews\fR" 4 .IX Item "views" An arrayref containing the global default set of \fIviews\fR the filter module should apply to message parts when matching the configured signatures against them. A view is the way how a \s-1MIME\s0 part's (MIME-decoded) data is interpreted. Defaults to \fB['raw']\fR. .Sp The following views are supported: .RS 4 .IP "\fBraw\fR" 4 .IX Item "raw" The \s-1MIME\s0 part is MIME-decoded but not otherwise transformed. The raw \s-1MIME\s0 part is then matched against the configured signatures. .IP "\fBzip\fR" 4 .IX Item "zip" If the \s-1MIME\s0 part has a file name ending in \f(CW\*(C`.zip\*(C'\fR, it is considered a \s-1ZIP\s0 archive, and all unencrypted files in the archive are matched as individual message parts against the configured signatures. The zip view requires the \&\fBArchive::Zip\fR Perl module to be installed. .RE .RS 4 .RE .IP "\fBmax_message_size\fR" 4 .IX Item "max_message_size" .PD 0 .IP "\fBmax_size\fR (\s-1DEPRECATED\s0)" 4 .IX Item "max_size (DEPRECATED)" .PD An integer value controlling the maximum size (in bytes) of the overall message text for a message to be processed by this filter module. Messages larger than this value will never be processed, and thus will never match. If \fBundef\fR, there is no size limit. Defaults to \fB1024**2\fR (1MB). .Sp As \s-1MIME\s0 multipart and \s-1ZIP\s0 archive processing can be quite \s-1CPU\-\s0 and memory-intensive (although the \fBParts\fR filter module makes use of temporary files since version 0.13), you should definitely restrict the message size to some sensible value that easily fits in your server's memory. 1024**2 (1MB) should be appropriate for most uses of this filter module. .Sp The \f(CW\*(C`max_message_size\*(C'\fR option was previously called \f(CW\*(C`max_size\*(C'\fR, but the latter is now deprecated and may not be supported in future versions of the \&\fBParts\fR filter module. .IP "\fBmax_part_size\fR" 4 .IX Item "max_part_size" An integer value controlling the maximum size (in bytes) of any single message part (i.e. \s-1MIME\s0 part in a message, or file in an archive) for that part to be processed by this filter module. Parts larger than this value will never be processed, and thus will never match. If \fBundef\fR, there is no size limit. .Sp Defaults to the value of the \f(CW\*(C`max_message_size\*(C'\fR option, so you don't really need to specify a part size limit if you are comfortable with using the same value for both. See the \f(CW\*(C`max_message_size\*(C'\fR option for its default. .Sp If you make use of the \fB'zip'\fR view, be aware of the risk posed by so-called \&\fIdecompression bombs\fR, which allow messages to easily fall below the overall message size limit, while a file in a small attached \s-1ZIP\s0 archive can decompress to a huge size. The part size limit prevents huge files from being decompressed. .IP "\fBsignatures\fR" 4 .IX Item "signatures" \&\fIRequired\fR. A reference to an array containing the list of \fIsignatures\fR against which message parts are to be matched. A signature in turn is a reference to a hash containing one or more so-called signature \fIaspects\fR (as key/value pairs) and any signature \fIoptions\fR (also as key/value pairs). .Sp \&\fISignature aspects\fR .Sp Aspects may either be scalar values (for exact, case-sensitive matches), or regular expression objects created with the \f(CW\*(C`qr//\*(C'\fR operator (for inexact, partial matches). For a signature to match a message part, \fIall\fR of the signature's specified aspects must match those of the message part. For the filter module to match a message, \fIany\fR of the signatures must match \fIany\fR of the message's parts. .Sp A signature aspect can be any of the following: .RS 4 .IP "\fBmime_type\fR" 4 .IX Item "mime_type" The \s-1MIME\s0 type of the message part ('type/sub\-type'). .IP "\fBfile_name\fR" 4 .IX Item "file_name" The file name of the message part. .IP "\fBsize\fR" 4 .IX Item "size" The exact size (in bytes) of the decoded message part. .IP "\fBdigest_md5\fR" 4 .IX Item "digest_md5" The \s-1MD5\s0 digest of the decoded message part (32 hex digits, as printed by `md5sum`). .IP "\fBencrypted\fR" 4 .IX Item "encrypted" A boolean value denoting whether the message part is encrypted and its contents are inaccessible to the \fBParts\fR filter module. .RE .RS 4 .Sp \&\fISignature options\fR .Sp A signature option can be any of the following: .IP "\fBviews\fR" 4 .IX Item "views" An arrayref containing the set of \fIviews\fR the filter module should apply to message parts when matching \fIthis\fR signature against them. For a list of supported views, see the description of the constructor's \f(CW\*(C`views\*(C'\fR option. Defaults to the global set of views specified to the constructor. .IP "\fBresponse\fR" 4 .IX Item "response" A string that is to be returned as the match result in case of a match. Defaults to \fB\*(L"Prohibited message part detected.\*(R"\fR. .RE .RS 4 .Sp \&\fIExample\fR .Sp So for instance, a signature list could look like this: .Sp .Vb 10 \& signatures => [ \& { \& mime_type => qr/html/i, \& response => \*(AqNo HTML mail, please.\*(Aq \& }, \& { \& file_name => qr/\e.(com|exe|lnk|pif|scr|vbs)$/i, \& response => \*(AqExecutable content detected\*(Aq \& }, \& { \& size => 106496, \& digest_md5 => \*(Aqb09e26c292759d654633d3c8ed00d18d\*(Aq, \& views => [\*(Aqraw\*(Aq, \*(Aqzip\*(Aq], # Look into ZIP archives, too! \& response => \*(AqWorm detected: W32.Swen\*(Aq \& }, \& { \& size => 22528, \& # Cannot set a specific digest_md5 since W32.Mydoom \& # is polymorphic. \& response => \*(AqWorm suspected: W32.Mydoom\*(Aq \& }, \& { \& encrypted => 1, \& views => [\*(Aqzip\*(Aq], \& response => \*(AqWorm suspected \*(Aq . \& \*(Aq(only worms and fools use ZIP encryption)\*(Aq \& } \& ] .Ve .RE .RE .RS 4 .Sp All options of the \fBCourier::Filter::Module\fR constructor are also supported by the constructor of the \fBParts\fR filter module. Please see \&\*(L"new\*(R" in Courier::Filter::Module for their descriptions. .RE .SS "Instance methods" .IX Subsection "Instance methods" See \*(L"Instance methods\*(R" in Courier::Filter::Module for a description of the provided instance methods. .SH "SEE ALSO" .IX Header "SEE ALSO" Courier::Filter::Module, Courier::Filter::Overview. .PP For \s-1AVAILABILITY, SUPPORT,\s0 and \s-1LICENSE\s0 information, see Courier::Filter::Overview. .SH "AUTHOR" .IX Header "AUTHOR" Julian Mehnle