mod-mail-doc

mod-mail-doc
Prev	Kernun UTM Reference (5)	Next

Name

mod-mail-doc — format of mod-mail-doc component configuration

DESCRIPTION

General syntax rules of Kernun Firewall configuration files are described in configuration(7). This man page describes types, sections and items specific for the mod-mail-doc component configuration.

Repeatable sections/items are marked by the '*' before section/item name.

TYPES

Configuration directives have attributes of several value-types. For the basic types description, see configuration(7).

Enumeration is a list of words (names) representing integer values. Some enumerations accept both names and direct integer values; in this case, enumeration description contains values for every name (in parenthesis next to name). For other enumerations, using of names is obligatory.

The following enumerations are used in mod-mail-doc configuration directives:

direction (see common(5))

range-op (see common(5))

week-day (see time(5))

month (see time(5))

virus-status (see antivirus(5))

transparency (see acl(5))

user-auth-spec (see acl(5))

doctype-ident-method (see acl(5))

header-op (see acl(5))

mail-hdr (name-usage obligatory)

STMP/MIME Headers

Unknown, Date, From, Sender, Reply-To, To, Cc, Bcc, Message-ID, In-Reply-To, References, Subject, Comments, Keywords, Resent-Date, Resent-From, Resent-Sender, Resent-Reply-To, Resent-To, Resent-Cc, Resent-Bcc, Resent-Message-ID, Return-Path, Received, MIME-Version, Content-Type, Content-Transfer-Encoding, Content-ID, Content-Description, Content-Disposition, DKIM-Signature, X-Kernun-Loop-Info, X-Kernun-Spam-Score, X-Kernun-Virus-Status, X-Kernun-Virus-Name, X-Kernun-Quarantine-Tag, X-Orig-Content-Type, X-Orig-Content-Disposition

content-transfer-encoding (name-usage obligatory)

MIME Content-Transfer-Encoding types.

eight-bit, quoted-printable, base64

smtp-error (name-usage obligatory)

Types of SMTP command errors.

cmd-missing: SMTP command missing.
arg-invalid: SMTP cmd argument has invalid syntax.
too-long: SMTP cmd argument exceeds RFC size limitation.
no-domain: SMTP cmd argument has no domain part.
ip-address: SMTP cmd argument with IP address (deprecated).
unknown-perm: SMTP cmd argument DNS resolution failed permanently.
unknown-temp: SMTP cmd argument DNS resolution failed temporarily.

hdr-handling (name-usage obligatory)

Types of header line handling.

fail: Mail processing fails.
keep: Line is not changed.
remove: Line is removed.

mail-reaction (name-usage obligatory)

Types of reaction to mail RFCs violations.

reject: The mail is rejected.
pass: The text is passed without changes, still violating the RFC.
drop: The element (e.g. header line) is dropped from the mail.
fix: The text is corrected according to the RFC.

mail-fallback (name-usage obligatory)

Types of fallback reaction to mail RFCs violations.

reject: The mail is rejected.
pass: The text is passed without changes, still violating the RFC.
drop: The element (e.g. header line) is dropped from the mail.

mime-header-check-type (name-usage obligatory)

MIME headers matching types.

txt: Header is matched after decoding to actual value and converting to ISO-8859-2 (ignoring inconvertible chars).
enc: Header is matched after decoding and converting to UTF-8, pattern is given in MIME format encoding.
raw: Header is matched without decoding, in raw format.
err: Fallback choice for the case of header decoding error.

ITEMS AND SECTIONS

Configuration of mod-mail-doc library component consists of following prototypes:

* smtp-adr-check ... ;
* mail-correction ... ;
* mail-hdr-correction ... ;
* mail-len-correction ... ;
* mail-hdr-len-correction ... ;
* mail-filter name { ... }
* mime-header-check ... ;
* mail-acl name { ... }
* mail-doc-acl name { ... }

Description:

smtp-adr-check [addrs];

This item defines SMTP addresses matching conditions.

addrs (type: str-set, optional, default: *)

Set of addresses matching this configuration item.

The matching rules are slightly modified for the purpose of email addresses matching:

Regular expressions are matched as usual.
Addresses defined by string ended with the '@' character match given local-part in any domain.
Addresses defined by string beginning by the '@' character match any address within given domain.
Other addresses containing the '@' character match exactly given address.
Addresses defined by string containing no '@' character match any address within given domain and any its subdomain.

mail-correction [clear [signed [fallback fallback]]];

Items of this type define corrections of various mail RFCs violations.

clear (type: mail-reaction, optional, default: fix): reaction to errors in non-signed parts of mail
signed (type: mail-reaction, optional, default: pass): reaction to errors in signed parts of mail
fallback fallback (type: mail-fallback, optional, default: pass): reaction in case of fixing failure

mail-hdr-correction [clear [signed [fallback fallback] [header]]];

Items of this type define corrections of various mail RFCs violations, where the decision is based on the header name.

clear (type: mail-reaction, optional, default: fix): reaction to errors in non-signed parts of mail
signed (type: mail-reaction, optional, default: pass): reaction to errors in signed parts of mail
fallback fallback (type: mail-fallback, optional, default: pass): reaction in case of fixing failure
header (type: str-set, optional, default: *)

mail-len-correction [clear [signed [fallback fallback] [limit]]];

Items of this type define corrections of various mail RFCs violations, where the decision is based on the line length.

clear (type: mail-reaction, optional, default: fix): reaction to errors in non-signed parts of mail
signed (type: mail-reaction, optional, default: pass): reaction to errors in signed parts of mail
fallback fallback (type: mail-fallback, optional, default: pass): reaction in case of fixing failure
limit (type: uint16, optional, default: 0): Lower bound for line length; lines shorter than this limit are not affected by this item.

mail-hdr-len-correction [clear [signed [fallback fallback] [header [limit]]]];

Items of this type define corrections of various mail RFCs violations, where the decision is based on the header name and line length.

clear (type: mail-reaction, optional, default: fix): reaction to errors in non-signed parts of mail
signed (type: mail-reaction, optional, default: pass): reaction to errors in signed parts of mail
fallback fallback (type: mail-fallback, optional, default: pass): reaction in case of fixing failure
header (type: str-set, optional, default: *)
limit (type: uint16, optional, default: 0): Lower bound for line length; lines shorter than this limit are not affected by this item.

mail-filter name {

  stamp-limit ... ;
  stamp-filter ... ;
* unflagged-8bit ... ;
* bad-end-of-line ... ;
* invalid-header ... ;
* long-header-lines ... ;
* invalid-chars ... ;
* header-8bit-chars ... ;
* bad-boundary-chars ... ;
* bad-boundary-length ... ;
* long-body-lines ... ;
* long-encoded-lines ... ;
  enc-line-len ... ;
* bad-mime-struct ... ;
* invalid-encoding ... ;
  treat-rfc822-as-text ... ;
}

This section defines SMTP/MIME document handling attributes.

Items & subsections:

stamp-limit [number [text]];

Maximum number of Received-headers in mail.

This check prevents from mail loops of three categories:

loops caused by wrong forwarding policy of a user
loops caused by DNS resolution errors or attack
loops caused by proxy of forwarder misconfiguration.

number (type: uint16, optional, default: 30)
text (type: str, optional, default: <NULL>): If omitted, default text is used.

stamp-filter;

SMTP stamp headers removal.

Enabling this feature causes removing 'Received:' headers (containing local-dependent information) from mails. Number of removed lines is counted and added to mail as a special header X-Kernun-Loop-Info.

unflagged-8bit [clear [signed [fallback fallback]]];

Handling of unannounced 8bit transport.

Some MUAs ignore RFC and use non-US-ASCII characters in mail bodies or MIME documents without announcing (in MAIL commands and MIME headers) the 8bit transport.

By default, the proxy fixes unsigned and passes signed mails with this violation; this item allows to change this behavior.

clear (type: mail-reaction, optional, default: fix): reaction to errors in non-signed parts of mail
signed (type: mail-reaction, optional, default: pass): reaction to errors in signed parts of mail
fallback fallback (type: mail-fallback, optional, default: pass): reaction in case of fixing failure
Constraints:: DROP reaction is not allowed here.

bad-end-of-line [clear [signed [fallback fallback]]];

Handling of incorrect EOL sequences.

Some buggy MUAs use no or two CR chars before LF.

By default, the proxy fixes unsigned and passes signed mails with this violation; this item allows to change this behavior.

clear (type: mail-reaction, optional, default: fix): reaction to errors in non-signed parts of mail
signed (type: mail-reaction, optional, default: pass): reaction to errors in signed parts of mail
fallback fallback (type: mail-fallback, optional, default: pass): reaction in case of fixing failure
Constraints:: DROP reaction is not allowed here.

invalid-header [clear [signed [fallback fallback] [header]]];

Handling of headers with invalid format.

Some MUAs create mail/MIME headers with various format errors (missing semicolon, unquoted chars like spaces, missing terminating double quote etc.).

Such headers cannot be fixed, so if you configure FIX reaction, the FALLBACK elem will be used, instead.

By default, the proxy passes all mails with bad headers, this item allows to change this behavior.

clear (type: mail-reaction, optional, default: fix): reaction to errors in non-signed parts of mail
signed (type: mail-reaction, optional, default: pass): reaction to errors in signed parts of mail
fallback fallback (type: mail-fallback, optional, default: pass): reaction in case of fixing failure
header (type: str-set, optional, default: *)

long-header-lines [clear [signed [fallback fallback] [header [limit]]]];

Handling of too long headers.

Some MUAs create mail/MIME headers exceeding the allowed length limit (1000 chars).

By default, the proxy tries to pass signed mails with this violation and tries to fix it for unsigned mails. In case of unsuccessful correction it passes such a mail. This item allows to change this behavior.

clear (type: mail-reaction, optional, default: fix): reaction to errors in non-signed parts of mail
signed (type: mail-reaction, optional, default: pass): reaction to errors in signed parts of mail
fallback fallback (type: mail-fallback, optional, default: pass): reaction in case of fixing failure
header (type: str-set, optional, default: *)
limit (type: uint16, optional, default: 0): Lower bound for line length; lines shorter than this limit are not affected by this item.

invalid-chars [clear [signed [fallback fallback]]];

Handling of bare NUL and CR characters.

Some MUAs ignore RFC and use NUL char (0x00) and bare CR (not followed by LF) in mail bodies or document headers.

By default, the proxy fixes unsigned and passes signed mails with this violation, this item allows to change this behavior. The only exception is the case of NUL in header which cannot be handled at all.

clear (type: mail-reaction, optional, default: fix): reaction to errors in non-signed parts of mail
signed (type: mail-reaction, optional, default: pass): reaction to errors in signed parts of mail
fallback fallback (type: mail-fallback, optional, default: pass): reaction in case of fixing failure
Constraints:: DROP reaction is not allowed here.

header-8bit-chars [clear [signed [fallback fallback] [header]]];

Handling of non-US-ASCII characters in headers.

Some MUAs ignore RFC and use non-US-ASCII characters in mail or MIME documents headers.

Such headers cannot be fixed, so if you configure FIX reaction, the FALLBACK elem will be used, instead.

By default, the proxy passes all mails with non ASCII headers, this item allows to change this behavior.

clear (type: mail-reaction, optional, default: fix): reaction to errors in non-signed parts of mail
signed (type: mail-reaction, optional, default: pass): reaction to errors in signed parts of mail
fallback fallback (type: mail-fallback, optional, default: pass): reaction in case of fixing failure
header (type: str-set, optional, default: *)

bad-boundary-chars [clear [signed [fallback fallback]]];

Handling of BOUNDARY values with invalid characters.

Some MUAs ignore RFC and use invalid characters in boundaries.By default, the proxy fixes unsigned and passes signed mails with incorrect boundary content, this item allows to change this behavior.

clear (type: mail-reaction, optional, default: fix): reaction to errors in non-signed parts of mail
signed (type: mail-reaction, optional, default: pass): reaction to errors in signed parts of mail
fallback fallback (type: mail-fallback, optional, default: pass): reaction in case of fixing failure
Constraints:: DROP reaction is not allowed here.

bad-boundary-length [clear [signed [fallback fallback]]];

Handling of BOUNDARY strings longer than 70 characters.

Some MUAs ignore RFC and use too long boundaries.By default, the proxy fixes all mails with too long boundary string, this item allows to change this behavior.

WARNING! This violation is very dangerous and not very often hence we strongly recommend not to pass such mails!

clear (type: mail-reaction, optional, default: fix): reaction to errors in non-signed parts of mail
signed (type: mail-reaction, optional, default: pass): reaction to errors in signed parts of mail
fallback fallback (type: mail-fallback, optional, default: pass): reaction in case of fixing failure
Constraints:: DROP reaction is not allowed here.

long-body-lines [clear [signed [fallback fallback] [limit]]];

Handling of mail body lines longer than 998 character.

Some MUAs ignore RFC and use too long lines.By default, the proxy fixes unsigned and passes signed mails with this violation; this item allows to change this behavior.

WARNING! Allowing to pass very long lines may be dangerous!

clear (type: mail-reaction, optional, default: fix): reaction to errors in non-signed parts of mail
signed (type: mail-reaction, optional, default: pass): reaction to errors in signed parts of mail
fallback fallback (type: mail-fallback, optional, default: pass): reaction in case of fixing failure
limit (type: uint16, optional, default: 0): Lower bound for line length; lines shorter than this limit are not affected by this item.
Constraints:: DROP reaction is not allowed here.

long-encoded-lines [clear [signed [fallback fallback] [limit]]];

Handling of mail body encoded lines longer than 76 character.

Some MUAs ignore RFC and use too long lines.By default, the proxy fixes unsigned and passes signed mails with this violation; this item allows to change this behavior.

WARNING! Allowing to pass very long lines may be dangerous!

clear (type: mail-reaction, optional, default: fix): reaction to errors in non-signed parts of mail
signed (type: mail-reaction, optional, default: pass): reaction to errors in signed parts of mail
fallback fallback (type: mail-fallback, optional, default: pass): reaction in case of fixing failure
limit (type: uint16, optional, default: 0): Lower bound for line length; lines shorter than this limit are not affected by this item.
Constraints:: DROP reaction is not allowed here.

enc-line-len [len];

Encoded lines line length limit.

len (type: uint16, optional, default: 80)

bad-mime-struct [clear [signed [fallback fallback]]];

Handling of invalid structure of MIME documents.

Some MUAs ignore RFC and send MIME documents with invlaid format (e.g. missing empty lines as separatoes etc.).

By default, the proxy fixes unsigned and passes signed mails with this violation; this item allows to change this behavior.

clear (type: mail-reaction, optional, default: fix): reaction to errors in non-signed parts of mail
signed (type: mail-reaction, optional, default: pass): reaction to errors in signed parts of mail
fallback fallback (type: mail-fallback, optional, default: pass): reaction in case of fixing failure
Constraints:: DROP reaction is not allowed here.

invalid-encoding [clear [signed [fallback fallback] [header]]];

Handling of invalid Content-Transfer-Encoding modes.

Some MUAs ignore RFC and use invalid Content-Transfer-Encoding (e.g. BINARY despite no meaning of it in current SMTP).By default, the proxy fixes unsigned and passes signed mails with this violation; fixing means converting to 8bit mode. This item allows to change this behavior, various encoding modes can be handled separately according their names.

clear (type: mail-reaction, optional, default: fix): reaction to errors in non-signed parts of mail
signed (type: mail-reaction, optional, default: pass): reaction to errors in signed parts of mail
fallback fallback (type: mail-fallback, optional, default: pass): reaction in case of fixing failure
header (type: str-set, optional, default: *)
Constraints:: DROP reaction is not allowed here.

treat-rfc822-as-text;

Handle included documents as text.

If a mailserver reports mail delivery failure it can include original mail into the report. If such a mail is incorrect the proxy will reject whole mail. This item tells proxy to read included documents as plain text and thus to avoid rejection risc.

[End of section mail-filter description.]

mime-header-check name [txt] value;

mime-header-check name enc pattern;

mime-header-check name raw value;

mime-header-check name err;

Entry condition - MIME header content.

name (type: str-set): Header name set (pure strings are case insensitive)
<branching element> (type: mime-header-check-type, optional, default: txt)
value (type: str-set): Set of header values (in ISO-8859-2 charset).
pattern (type: str-list): List of header patterns (case sensitive substrings in any charset) encoded in MIME format.
Constraints:: MIME encoded strings must comply with MIME definition.

mail-acl name {

* from ... ;
* time ... ;
  time-period-set { ... }
* parent-acl ... ;
  deny ... ;
  accept ... ;
  rule ... ;
  direction ... ;
* size ... ;
* content-type ... ;
  virus-status ... ;
* modify-header ... ;
  replace ... ;
* sender ... ;
* recipient ... ;
* recipients ... ;
* spam-score ... ;
* header ... ;
  from-quarantine ... ;
  prefix-subject ... ;
}

The first ACL on the third level decides how to treat the whole mail after finishing all checks.

The mail-acl section is derived from acl-3 section prototype. For detail description of it, see acl(5).

Changes to the mail-acl section:

Item server is not valid.

Item user is not valid.

Item mime-type is not valid.

Item force-doctype-ident is not valid.

Item html-filter is not valid.

Added items & subsections:

sender [addrs];

Entry condition (SMTP only) - MAIL FROM address.

addrs (type: str-set, optional, default: *)

Set of addresses matching this configuration item.

The matching rules are slightly modified for the purpose of email addresses matching:

Regular expressions are matched as usual.
Addresses defined by string ended with the '@' character match given local-part in any domain.
Addresses defined by string beginning by the '@' character match any address within given domain.
Other addresses containing the '@' character match exactly given address.
Addresses defined by string containing no '@' character match any address within given domain and any its subdomain.

recipient [addrs];

Entry condition (SMTP only) - RCPT TO address.

addrs (type: str-set, optional, default: *)

Set of addresses matching this configuration item.

The matching rules are slightly modified for the purpose of email addresses matching:

Regular expressions are matched as usual.
Addresses defined by string ended with the '@' character match given local-part in any domain.
Addresses defined by string beginning by the '@' character match any address within given domain.
Other addresses containing the '@' character match exactly given address.
Addresses defined by string containing no '@' character match any address within given domain and any its subdomain.

recipients unknown [addrs];

recipients lt limit [addrs];

recipients le limit [addrs];

recipients eq limit [addrs];

recipients ne limit [addrs];

recipients gt limit [addrs];

recipients ge limit [addrs];

recipients in lower upper [addrs];

recipients ni lower upper [addrs];

Entry condition - number of recipients.

<branching element> (type: range-op)

limit (type: uint64)

Tested value limitation.

lower (type: uint64)

Tested value lower bound.

upper (type: uint64)

Tested value upper bound.

addrs (type: str-set, optional, default: *)

Restriction to addresses - only ones matching this condition are counted.

Exact address matching conditions are described at SENDER or RECIPENT items.

spam-score unknown;

spam-score lt limit;

spam-score le limit;

spam-score eq limit;

spam-score ne limit;

spam-score gt limit;

spam-score ge limit;

spam-score in lower upper;

spam-score ni lower upper;

Entry condition - antispam check score.

For score interpretation, see mod-antispam(5).

<branching element> (type: range-op)
limit (type: uint64): Tested value limitation.
lower (type: uint64): Tested value lower bound.
upper (type: uint64): Tested value upper bound.

header name [txt] value;

header name enc pattern;

header name raw value;

header name err;

Entry condition - MIME header content.

name (type: str-set): Header name set (pure strings are case insensitive)
<branching element> (type: mime-header-check-type, optional, default: txt)
value (type: str-set): Set of header values (in ISO-8859-2 charset).
pattern (type: str-list): List of header patterns (case sensitive substrings in any charset) encoded in MIME format.
Constraints:: MIME encoded strings must comply with MIME definition.

from-quarantine [tags];

Entry condition (SMTP only) - mail sent by admin from quarantine.

This item is valid in smtp-proxy only. If omitted, any mail can match this ACL.

tags (type: str-set, optional, default: *): Allowed X-Kernun-Quarantine-Tag header values

prefix-subject prefix;

Change Subject: mail header.

prefix (type: str): String to be written before the original Subject.
Constraints:: Subject prefix must comply with RFC.

[End of section mail-acl description.]

mail-doc-acl name {

* from ... ;
* time ... ;
  time-period-set { ... }
* parent-acl ... ;
  deny ... ;
  accept ... ;
  rule ... ;
  direction ... ;
* size ... ;
* content-type ... ;
* mime-type ... ;
  virus-status ... ;
* modify-header ... ;
  force-doctype-ident ... ;
  replace ... ;
  html-filter ... ;
* sender ... ;
* recipient ... ;
* spam-score ... ;
* header ... ;
* filename ... ;
  from-quarantine ... ;
  add-virus-names ... ;
}

The second ACL on the third level decides how to process particular document(s) contained in the mail.

The mail-doc-acl section is derived from acl-3 section prototype. For detail description of it, see acl(5).

Changes to the mail-doc-acl section:

Item server is not valid.

Item user is not valid.

Item ADD-VIRUS-NAMES is not allowed if DENY is on.

Added items & subsections:

sender [addrs];

Entry condition (SMTP only) - MAIL FROM address.

addrs (type: str-set, optional, default: *)

Set of addresses matching this configuration item.

The matching rules are slightly modified for the purpose of email addresses matching:

Regular expressions are matched as usual.
Addresses defined by string ended with the '@' character match given local-part in any domain.
Addresses defined by string beginning by the '@' character match any address within given domain.
Other addresses containing the '@' character match exactly given address.
Addresses defined by string containing no '@' character match any address within given domain and any its subdomain.

recipient [addrs];

Entry condition (SMTP only) - RCPT TO address.

addrs (type: str-set, optional, default: *)

Set of addresses matching this configuration item.

The matching rules are slightly modified for the purpose of email addresses matching:

Regular expressions are matched as usual.
Addresses defined by string ended with the '@' character match given local-part in any domain.
Addresses defined by string beginning by the '@' character match any address within given domain.
Other addresses containing the '@' character match exactly given address.
Addresses defined by string containing no '@' character match any address within given domain and any its subdomain.

spam-score unknown;

spam-score lt limit;

spam-score le limit;

spam-score eq limit;

spam-score ne limit;

spam-score gt limit;

spam-score ge limit;

spam-score in lower upper;

spam-score ni lower upper;

Entry condition - antispam check score.

For score interpretation, see mod-antispam(5).

<branching element> (type: range-op)
limit (type: uint64): Tested value limitation.
lower (type: uint64): Tested value lower bound.
upper (type: uint64): Tested value upper bound.

header name [txt] value;

header name enc pattern;

header name raw value;

header name err;

Entry condition - MIME header content.

name (type: str-set): Header name set (pure strings are case insensitive)
<branching element> (type: mime-header-check-type, optional, default: txt)
value (type: str-set): Set of header values (in ISO-8859-2 charset).
pattern (type: str-list): List of header patterns (case sensitive substrings in any charset) encoded in MIME format.
Constraints:: MIME encoded strings must comply with MIME definition.

filename names;

Entry condition - name of document.

The name is expected either in the FILENAME parameter of Content-Disposition header, or in the NAME parameter of Content-Type header.Only the last part of the file name (without path) is used for matching.

names (type: str-set)

from-quarantine [tags];

Entry condition (SMTP only) - mail sent by admin from quarantine.

This item is valid in smtp-proxy only. If omitted, any mail can match this ACL.

tags (type: str-set, optional, default: *): Allowed X-Kernun-Quarantine-Tag header values

add-virus-names;

Add X-Kernun-Virus-Name header for each virus found.

[End of section mail-doc-acl description.]

Prev	Up	Next
mod-html-filter	Home	mod-match

Name

DESCRIPTION

TYPES

ITEMS AND SECTIONS

SEE ALSO