home *** CD-ROM | disk | FTP | other *** search
Text File | 1997-10-28 | 46.6 KB | 1,516 lines |
-
-
-
-
-
-
- Network Working Group T. Showalter
- Internet Draft: Sieve Carnegie Mellon
- Document: draft-showalter-sieve-02.txt October 1997
- Expire in six months (12/1/97)
-
-
- Sieve -- a Mail Filtering Language
-
-
- Status of this memo
-
- This document is an Internet-Draft. Internet-Drafts are working
- documents of the Internet Engineering Task Force (IETF), its areas,
- and its working groups. Note that other groups may also distribute
- working documents as Internet-Drafts.
-
- Internet-Drafts are draft documents valid for a maximum of six months
- and may be updated, replaced, or obsoleted by other documents at any
- time. It is inappropriate to use Internet-Drafts as reference
- material or to cite them other than as ``work in progress.''
-
- To learn the current status of any Internet-Draft, please check the
- ``1id-abstracts.txt'' listing contained in the Internet-Drafts Shadow
- Directories on ftp.is.co.za (Africa), ftp.nordu.net (Europe),
- munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or
- ftp.isi.edu (US West Coast).
-
- The protocol discussed in this document is experimental and subject
- to change. Persons planning on either implementing or using this
- protocol are STRONGLY URGED to get in touch with the author before
- embarking on such a project.
-
- Abstract
-
- This document describes a mail filtering language for filtering
- messages at time of final delivery. It is designed to be independent
- of protocol, and implementable on either a mail client or mail
- server. It is meant to be extensible, simple, and independent of
- access protocol, mail architecture, and operating system. It is
- suitable for running on a mail server where users may not be allowed
- to execute arbitrary programs, such as on black box IMAP servers, as
- it has no variables, loops, or ability to shell out to external
- programs.
-
-
-
-
-
-
-
-
- Showalter [Page 1]
-
- Internet DRAFT Sieve October 24, 1997
-
-
-
-
-
- Table of Contents
-
-
-
- Status of this memo
- Abstract
- 0. Meta-information on this draft
- 0.1. Discussion
- 0.2. Known Problems
- 0.2.1. Probable Extensions
- 0.2.2. Known Bugs
- 0.3. Open Issues
- 1. Introduction
- 1.1. Conventions used in this document
- 1.2. Example mail messages
- 2. Design
- 2.1. Form of the language
- 2.2. Whitespace
- 2.3. Comments
- 2.4. Numbers
- 2.5. Strings
- 2.5.2. String lists
- 2.5.3. Headers
- 2.5.4. Addresses
- 2.6. String Comparison
- 2.6.1. Match Keyword
- 2.6.2. Comparators
- 2.7. Evaluation
- 3. Conditionals and Control Structures
- 3.1. If
- 3.2. Require
- 4. Actions
- 4.1. Action bounce
- 4.2. Action fileinto
- 4.3. Action forward
- 4.4. Action keep
- 4.5. Action reply
- 4.6. Action stop
- 4.7. Action discard
- 5. Tests
- 5.1. Test all-of
- 5.2. Test any-of
- 5.3. Test exists
- 5.4. Test false
- 5.5. Test header
-
-
-
- Showalter [Page 2]
-
- Internet DRAFT Sieve October 24, 1997
-
-
- 5.6. Test not
- 5.7. Test size
- 5.8. Test support
- 5.9. Test true
- 6. Errors in Processing a Script
- 7. Extensibility
- 7.1. Capability String
- 7.2. Registry
- 7.3. Capability Transport
- 8. Transmission
- 9. Acknowledgments
- 10. Formal Grammar
- 11. Security Considerations
- 12. Author's Address
- Appendices
- Appendix A. References
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Showalter [Page 3]
-
- Internet DRAFT Sieve October 24, 1997
-
-
- 0. Meta-information on this draft
-
- This information is intended to facilitate discussion. It will be
- removed when this document leaves the Internet-Draft stage.
-
- 0.1. Discussion
-
- This draft is being discussed on the MTA Filters mailing list at
- <ietf-mta-filters@imc.org>. Subscription requests can be sent to
- <ietf-mta-filters-request@imc.org> (send an email message with the
- word "subscribe" in the body). More information on the mailing list
- along with a WWW archive of back messages is available at
- <http://www.imc.org/ietf-mta-filters>.
-
- 0.2. Known Problems
-
- 0.2.1. Probable Extensions
-
- The following suggestions have been made, and will probably be
- addressed by extensions.
-
- An extension for regular expressions will be written. While regular
- expressions are of questionable utility for most users, the
- programmers writing implementations desperately want regular
- expressions.
-
- Envelope-matching commands are not readily supported by all mail
- systems, and putting them in the draft will result in a system that
- cannot be implemented by a mail architecture that does not adequately
- store envelopes.
-
- "Detailed" addressing or "sub-addressing" (i.e., the "fmh" in an
- address "tjs+fmh@andrew.cmu.edu") is not handled, and will be moved
- to an extension for those systems that offer it.
-
- A previous version included a "valid" test. I have tentatively
- removed it because Randy had noted it was too fuzzy to implement, and
- that's probably true.
-
- A vacation command has been requested for an extension. It isn't in
- the draft because having vacation assumes you can store the addresses
- of people who have already received vacation notifications, which
- isn't always the case.
-
- A suggestion was made to set IMAP flags on delivery (e.g., \Flagged,
- \Deleted, \Answered, \Seen).
-
-
-
-
-
- Showalter [Page 4]
-
- Internet DRAFT Sieve October 24, 1997
-
-
- An "include" command is not included, but has been suggested for an
- extension.
-
- 0.2.2. Known Bugs
-
- The formal grammar.
-
- The bounce command needs to be rechecked against the DSN
- specification.
-
- The error-handling clauses of this specification may not be
- completely sensible, and may conflict.
-
- My knowledge of email is not comprehensive, and as a result, there
- might be a better way to express some of the concepts in here.
- Please let me know if there is a good way to clean up the wording.
-
- 0.3. Open Issues
-
- The support and require tests cause some serious problems with
- control structures. To some extent, this is solved by separating the
- block construct out from the conditionals themselves. This has been
- done in this draft (flames welcome, but it seems to be cleaner to
- me).
-
- Comma is mandatory in any-of/all-of but forbidden in a list of
- strings; it should be required in both. This needs to be fixed. I'm
- clinging to the status quo trying to fix the rest of the problems at
- the moment.
-
- Should there be a way to specify headers transmitted by reply?
- Perhaps a separate command, since there are probably sites that are
- going to be really paranoid about what headers get sent.
-
- In the event that there is an error while processing a script, what
- happens? The draft implies you file into INBOX, but what if you've
- already taken actions before you do this? (The parts of the draft
- that require syntax checking stuff are all SHOULDs.)
-
- I tried to fill in some of the blanks in previous versions; among
- them, the description of what a bounced input message looks like, but
- it's still nearly incomplete.
-
- I moved the substring matching stuff out of the header command and
- into a section of its own as it is reusable by extensions.
- Suggestions on this section would be appreciated.
-
-
-
-
-
- Showalter [Page 5]
-
- Internet DRAFT Sieve October 24, 1997
-
-
- I tried to fill in the blanks in the section on extensibility and
- borrowed some stuff from the ACAP spec (specifically, the comparator
- registry), but it's probably not complete or good enough.
-
- Finally, I suspect that there are a lot of problems relating to what
- filtering for the masses will do to mailing lists, especially what
- will happen the first time someone rolls their own vacation program
- consisting of a reply command. Should it be an error to reply to a
- message that is not addressed to you (specifically)?
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Showalter [Page 6]
-
- Internet DRAFT Sieve October 24, 1997
-
-
- 1. Introduction
-
- This draft is offered to provide a standard language that can be used
- to create filters for electronic mail. It is not tied to any
- particular operating system or mail architecture. It requires the
- use of [IMAIL]-compliant messages and support of multiple folders,
- but should work with a wide variety of systems that support these
- criteria.
-
- The language is powerful enough to be useful, but limited in power in
- order to allow for a safe server-side filtering system. The
- intention is to make it impossible for users to do anything more
- complex (and dangerous) than write simple mail filters, along with
- facilitating GUI-based editors. The language is not Turing-complete,
- and provides no way to write a loop or a function. Variables are not
- provided.
-
- Implementations of the language are expected to take place at time of
- final delivery, when the message is finally moved to the user-
- accessible mailbox. In systems where the MTA does final delivery,
- such as and traditional UNIX mail, is reasonable to sort when the MTA
- deposits mail into the user's mailbox. If the MTA does not do final
- delivery, or lacks the power to sort into separate mailboxes, as is
- the case under POP3, the MUA must do filtering into local-disk
- folders.
-
- There are a number of reasons to use a filtering system. Mail
- traffic for most users has been increasing due both to increased
- usage of e-mail, the emergence of unsolicited email as a form of
- advertising, and increased usage of mailing lists.
-
- Experience at Carnegie Mellon has shown that if a filtering system is
- made available to users, many will make use of it in order to file
- messages from specific users or mailing lists. However, many others
- did not make use of the Andrew system's FLAMES filtering language due
- to difficulty in setting it up.
-
- Because of the expectation that users will make use of filtering if
- it is offered and easy to use, this language has been made simple
- enough to allow many users to make use of it, but rich enough that it
- can be used productively. However, it is expected that GUI-based
- editors will be the preferred way of editing filters for a large
- number of users.
-
- 1.1. Conventions used in this document
-
- In examples, line breaks have been inserted for readability.
-
-
-
-
- Showalter [Page 7]
-
- Internet DRAFT Sieve October 24, 1997
-
-
- In the sections of this document that discuss the requirements of
- various keywords and operators, the following conventions have been
- adopted.
-
- The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", "CAN", and
- "MAY" in this document are to be interpreted as defined in
- [KEYWORDS].
-
- Each section on a test, action, or control structure has a line
- labeled "Syntax:". This line describes the syntax of the command,
- including its name and its arguments. Required arguments are listed
- inside angle brackets ("<" and ">"). Optional arguments are listed
- inside square brackets ("[" and "]"). However, the formal grammar
- for these commands in section 10 and is the authoritative reference
- on how to construct these commands.
-
- 1.2. Example mail messages
-
- The following mail messages will be used throughout this document in
- examples.
-
- Message A
- -----------------------------------------------------------
- Date: Tue, 1 Apr 1997 09:06:31 -0800 (PST)
- From: coyote@desert.org
- To: roadrunner@birdseed.org
- Subject: I have a present for you
-
- Look, I'm sorry about the whole anvil thing, and I really
- didn't mean to try and drop it on you from the top of the
- cliff. I want to try to make it up to you. I've got some
- great birdseed over here at my place -- top of the line
- stuff -- and if you come by, I'll have it all wrapped up
- for you. I'm really sorry for all the problems I've caused
- for you over the years, but I know we can work this out.
- --
- Wile E. Coyote "Super Genius" coyote@znic.net
- -----------------------------------------------------------
-
-
-
-
-
-
-
-
-
-
-
-
-
- Showalter [Page 8]
-
- Internet DRAFT Sieve October 24, 1997
-
-
- Message B
- -----------------------------------------------------------
- From: youcouldberich!@reply-by-postal-mail
- Sender: b1ff@de.res.frobnitzm.edu
- To: rube@landru.melon.net
- Date: Mon, 31 Mar 1997 18:26:10 -0800 (PST)
- Subject: $$$ YOU, TOO, CAN BE A MILLIONAIRE! $$$
-
- YOU MAY HAVE ALREADY WON TEN MILLION DOLLARS, BUT I DOUBT
- IT! SO JUST POST THIS TO SIX HUNDRED NEWSGROUPS! IT WILL
- GUARANTEE THAT YOU GET AT LEAST FIVE RESPONSES WITH MONEY!
- MONEY! MONEY! COLD HARD CASH! YOU WILL RECEIVE OVER
- $20,000 IN LESS THAN TWO MONTHS! AND IT'S LEGAL!!!!!!!!!
- !!!!!!!!!!!!!!!!!!111111111!!!!!!!11111111111!!1 JUST
- SEND $5 IN SMALL, UNMARKED BILLS TO THE ADDRESSES BELOW!
- -----------------------------------------------------------
-
- 2. Design
-
- 2.1. Form of the language
-
- This language is made up as a set of commands. Each command is
- either an action or a conditional. Each conditional contains a test;
- depending on the results of the test, one set of commands in a
- control structure is taken.
-
- 2.2. Whitespace
-
- Whitespace is used to separate commands. Whitespace is made up of
- tabs, newlines (CRLF, never just CR or LF), and the space character.
- The amount of whitespace used is not significant.
-
- 2.3. Comments
-
- Comments begin with a "#" character that is not contained within a
- string and continue until the next CRLF.
-
- Example: if size over 100K { # this is a comment
- discard;
- }
-
- 2.4. Numbers
-
- Numbers are given as ordinary decimal numbers. However, those
- numbers that have a tendency to be fairly large, such as message
- sizes, may have a "K", "M", or "G" appended to indicate a multiple of
- a base-two number. To be comparable with the power-of-two-based
- versions of SI units that computers frequently use, K specifies kilo,
-
-
-
- Showalter [Page 9]
-
- Internet DRAFT Sieve October 24, 1997
-
-
- or 1,024 (2^10) times the value of the number; M specifies mega, or
- 1,048,576 (2^20) times the value of the number; and G specifies giga,
- or 1,073,741,824 (2^30) times the value of the number.
-
- Implementations MUST provide 31 bits of magnitude in numbers, but may
- provide more.
-
- Negative, fractional, and decimal numbers are not permitted by this
- specification.
-
- 2.5. Strings
-
- Scripts involve large numbers of strings, as they are used for
- pattern matching, addresses, and textual bodies, etc. Typically,
- short quoted strings suffice for most uses, but a more convenient
- form is provided for longer strings such as bodies of messages.
-
- A quoted string starts and ends with a single double quote (the <">
- character). A backslash ("\") inside of a quoted string is followed
- by either another backslash or a double quote. This two-character
- sequence represents a single backslash or double-quote within the
- string, respectively.
-
- Other escape sequences may be permitted depending on context (such as
- in globs, defined in section 2.6 on string comparison). An undefined
- escape sequence (such as "\a" in a context where "a" has no special
- meaning) is interpreted as if there were no backslash (in this case,
- "\a" is just "a").
-
- Non-printing characters such as tabs, CR and LF, and control
- characters are permitted in strings. NUL (ASCII 0) is not allowed in
- strings.
-
- For entering larger amounts of text, such as an email message, a
- multi-line form is allowed. It starts with the keyword "text:",
- followed by a CRLF, and ends with the sequence of a CRLF, a single
- period, and another CRLF. In order to allow the message to begin
- lines with a single-dot, lines are dot-stuffed. That is, when
- composing a message body, an extra `.' is added before each line
- which begins with a `.'. When the server interprets the script,
- these extra dots are removed.
-
- Note that a comment may occur in between the "text:" and the CRLF,
- but not within the string itself.
-
- Example: if any-of (header ("from") contains
- ("bart" "homer" "smithers" "burns" "lisa"),
- header ("subject") contains ("URGENT")) {
-
-
-
- Showalter [Page 10]
-
- Internet DRAFT Sieve October 24, 1997
-
-
- keep;
- } else {
- reply text: # multi-line message here:
- You are not one of the people I regularly
- correspond with. I have deleted your message
- due to the large volume of email I regularly
- receive. If you feel that you need to speak
- with me directly, and cannot find your answer
- in my web pages, please send mail with the
- word "URGENT" in the subject line. Thank you
- for your time.
- .
- ;
- }
-
- 2.5.2. String lists
-
- When matching patterns, strings frequently come in groups. For this
- reason, a list of strings is allowed in many tests, implying that if
- the test is true using any one of the strings, then the test is true.
- Implementations are encouraged to use short-circuit evaluation in
- these cases.
-
- For instance, the test `header ("To" "Cc") contains
- ("me@frobnitzm.edu" "me00@landru.melon.edu")' is true if either the
- To header or Cc header of the input message contains either of the
- e-mail addresses "me@frobnitzm.edu" or "me00@landru.melon.edu".
-
- Conversely, in any case where a list of strings would be appropriate,
- a single string is allowed without being a member of a list; it is
- equivalent to a list with a single member. So the test `exists "To"'
- is equivalent to the test `exists ("To")'.
-
- 2.5.3. Headers
-
- Headers are a subset of strings. In the Internet Message
- Specification [IMAIL], each header line is allowed to have whitespace
- nearly anywhere in the line, including after the field name and
- before the subsequent colon. Extra spaces between the header name
- and the ":" in a header field are ignored by the interpreter.
-
- A header name never contains a colon. The "From" header refers to a
- line beginning "From:" (or "From :", etc.). No header will match
- the string "From:" due to the trailing colon.
-
-
-
-
-
-
-
- Showalter [Page 11]
-
- Internet DRAFT Sieve October 24, 1997
-
-
- 2.5.4. Addresses
-
- A number of commands call for email addresses, which are also a
- subset of strings. These addresses must be compliant with [IMAIL].
- Implementations MUST ensure the addresses are syntactically valid,
- and need not ensure that they are actually deliverable.
-
- 2.6. String Comparison
-
- When matching one string against another, there are a number of ways
- of performing the match. These are accomplished with three matches
- -- an exact match, a substring match, and a wildcard glob-style
- match. In order to provide for matches between character sets and
- case insensitivity, Sieve borrows ACAP's comparator registry.
-
- 2.6.1. Match Keyword
-
- There are three allowed match keywords describing the allowed match
- in this draft; they are "is", "contains", and "matches".
-
- The "contains" version describes a substring match. If the value
- argument contains the key argument as a substring, the match is true.
- For instance, the string "frobnitzm" contains "frob" and "nit", but
- not "fbm". The null key ("") is contained in all values.
-
- The "is" version describes an absolute match; if the contents of the
- first string are absolutely the same as the contents of the second
- string, they match. Only the string "frobnitzm" is the string
- "frobnitzm". The null key only "is" the null value.
-
- The "matches" is a UNIX-style "glob" match; it specifies that the key
- is not substring, but contains certain special characters that match
- characters that are not themselves. These characters are
-
- * Match zero or more characters
- ? Match any single character
- \ Escape next character
-
- Escaped special characters do not take on the meanings listed above.
-
- The value "frobnitzm" matches the keys "*nit*", "f*b*m", and "fr?b*",
- but not "nit" or "frob". The null key matches only the null value.
-
- The "contains" and "matches" versions necessitate that one string
- supplied as an argument is a key, and the other is a value. Commands
- that utilize these comparisons, generally of the form "<value>
- <match-keyword> <key>", must be sure to differentiate which is which.
-
-
-
-
- Showalter [Page 12]
-
- Internet DRAFT Sieve October 24, 1997
-
-
- 2.6.2. Comparators
-
- In order to allow for character set-independent matches, the match
- keyword may be coupled with a comparator name. Comparators are
- described for [ACAP]; a registry is defined for ACAP, and this draft
- borrows that registry.
-
- All implementations MUST support the octet comparator, which simply
- compares one octet with the next. If left unspecified, the
- comparator is octet.
-
- If an implementation supports a comparator "elbonia", it MUST provide
- the capability "comparator-elbonia" for support and require commands.
-
- Some comparators may not be usable with substring matches; that is,
- they may only work with "is". [OPEN: Not sure what to do about
- this.] It is an error to try and use a comparator with "matches" or
- "contains" that is not compatible with it.
-
- OPEN: Are there any other comparators that SHOULD or MUST be
- supported?
-
-
- 2.7. Evaluation
-
- If evaluation of the script fails to file the message into any
- mailbox, as in the following script, the message is filed into INBOX.
- With any of the short messages offered above, the following script
- produces no actions.
-
-
- Example: if size over 500K discard;
-
- In cases like this, the "keep" action is taken. The "keep" action is
- defined to be the action that is taken in a situation where the user
- does no filtering. For instance, under an IMAP-based system, this
- implies filing into INBOX.
-
- Implementations define the specific meanings of actions.
- Implementations MAY impose restrictions on the actions taken, such as
- only honoring one "reply", "bounce", or "forward" per message.
-
- In this case, which is honored? I'm tempted to say random, but
- restrict it to those commands that send mail back out (fileinto as
- many mailboxes as you want).
-
- Precedence is not important in any of the commands in this base
- specification. However, as an extension might make order of
-
-
-
- Showalter [Page 13]
-
- Internet DRAFT Sieve October 24, 1997
-
-
- operation important, all arguments to rules MUST be evaluated in
- left-to-right order. Those operations that can implement short-
- circuit evaluation (such as "all-of" and "any-of") MUST do so.
-
- 3. Conditionals and Control Structures
-
-
- In order for a script to do more than one set of actions, control
- structures are needed.
-
- 3.1. If
-
-
- Syntax: if <test> <command> [else <command>]
-
- The "if" control structure is borrowed from any number of programming
- languages. It is evaluated in the usual way if the test is true then
- the first command (or set of commands) supplied is evaluated. If the
- test is false and an else keyword follows the if block, the second
- command is evaluated. The commands may be command blocks. [OPEN:
- This allows C-style dangling statements; I construe this as a
- feature.]
-
- In the following example, both Message A and B are dropped.
-
- Example: if header "from" contains "coyote" {
- discard;
- } else if header ("subject") contains ("$$$") {
- discard;
- } else fileinto "INBOX";
-
-
- Only one command or block of commands in an if ... else if ... else
- chain is executed.
-
- In the script below, when run over message A, forwards the message to
- acm@frobnitzm.edu; message B, to postmaster@frobnitzm.edu; any other
- message is forwarded to field@frobnitzm.edu.
-
- Example: if header ("From") contains ("coyote") {
- forward "acm@frobnitzm.edu";
- } else if header "Subject" contains "$$$" {
- forward "postmaster@frobnitzm.edu";
- } else
- forward "field@frobnitzm.edu";
-
-
-
-
-
-
- Showalter [Page 14]
-
- Internet DRAFT Sieve October 24, 1997
-
-
- 3.2. Require
-
-
- Syntax: require <extension-name>
-
- Require SHOULD be declared in a user script before an extension is
- used. It instructs the evaluator that the extension named
- extension-name, supplied as a string, MUST be present in order to
- allow further processing. If the string specifies an extension that
- the evaluating mechanism supports, then processing continues.
- Otherwise, an error has been encountered, and the script should not
- be evaluated.
-
- Require is intended to indicate that a script needs an extension not
- described in this document, or a feature that is not mandatory.
-
- The following example will fail on any server that does not implement
- the extension known as DWIM.
-
- Example: require "dwim";
- if header ("subject") contains-nocase ("the secret
- message") {
- dwim blurdybloop body;
- } stop
-
- OPEN: I have serious concerns with require; it makes it impossible to
- separate parsing from evaluation, and introduces some awkward
- cases. For instance, a script "if size under 1 { require "foo";
- do_foo; } else {... }" Even if the test will never happen, this
- require will prevent the script from working. Just support
- seems to make more sense.
-
-
- 4. Actions
-
-
- This document supplies six actions that may be taken on a message:
- keep, fileinto, forward, bounce, discard, and stop.
-
- 4.1. Action bounce
-
-
- Syntax: bounce <reason-string>
-
- The "bounce" action resends the message to the sender, wrapping it in
- a "bounce" form, noting that it was rejected by the recipient. In
- the following script, message A is bounced to the sender.
-
-
-
-
- Showalter [Page 15]
-
- Internet DRAFT Sieve October 24, 1997
-
-
- Example: if header "from" contains "coyote@znic.net" {
- bounce "I am not taking mail from you, and I don't want
- your birdseed, either!";
- }
-
- A bounce message SHOULD takes the form of a failed DSN as specified
- by [DSN]. The human-readable portion of the message, the first
- component of the DSN, contains the human readable message describing
- the error, although it SHOULD contain additional text alerting the
- original sender that mail was refused by a filter. This part of the
- DSN might appear as follows:
-
- ------------------------------------------------------------
- Message was refused by recipient's mail filtering program.
- Reason given was as follows:
-
- I am not taking mail from you, and I don't want your
- birdseed, either!
- ------------------------------------------------------------
-
- The action-value field as defined in the DSN specification SHOULD be
- "failed".
-
- OPEN: This section is probably incomplete. I am not sure that the
- right answer is to make it easy to refuse messages, but
- secretly keep a copy. Should bounce prevent all other
- actions from taking affect?
-
-
- 4.2. Action fileinto
-
-
- Syntax: fileinto <folder>
-
- The "fileinto" action drops the message into a named folder.
- Implementations SHOULD support fileinto, but may not be able to in
- cases where the filtering agent is not able to write to the users'
- folders (such as a [POP3] implementation running inside the mail
- server where the folders are stored on the users' local disks).
-
- As such, a server supporting fileinto MUST provide the "fileinto"
- capability for the support and require tests.
-
-
-
-
-
-
-
-
-
- Showalter [Page 16]
-
- Internet DRAFT Sieve October 24, 1997
-
-
- In the following script, message A is filed into folder
- "INBOX.harassment".
-
- Example: if header ("to") contains "coyote" {
- fileinto "INBOX.harassment";
- }
-
- 4.3. Action forward
-
-
- Syntax: forward <address>
-
- The "forward" action is used to forward the message to another user
- at the supplied address, as a mail forwarding feature does. The
- "forward" action makes no changes to the message body or headers, and
- only modifies the envelope recipient.
-
- A simple script can be used for forwarding:
-
- Example: forward "bart@frobnitzm.edu";
-
- The forward command performs an MTA-style forward -- that is, what
- you get from a .forward file using sendmail under UNIX. The address
- on the SMTP envelope is replaced with the one on the forward command
- and the message is sent back out. (This is not an MUA-style forward,
- which creates a new message with a different sender and message ID,
- wrapping the old message in a new one.)
-
- 4.4. Action keep
-
-
- Syntax: keep
-
- The "keep" action is whatever action is taken in lieu of all other
- actions, if no filtering happens at all; generally, this simply means
- to file the message into the user's main mailbox. This command
- provides a way to execute this action without needing to know the
- name of the user's main mailbox, providing a way to call it without
- needing to understand the user's setup, or the underlying mail
- system.
-
- Example: if size under 1M keep; else discard;
-
- 4.5. Action reply
-
-
- Syntax: reply <message>
-
-
-
-
- Showalter [Page 17]
-
- Internet DRAFT Sieve October 24, 1997
-
-
- The "reply" action is used to generate a form letter reply to the
- original sender. Message is a string to be sent as a reply message.
- In the following example, any message larger than 500K (524288
- octets) would be replied to with a message explaining that it was
- rejected; otherwise, the message would be filed into INBOX (by
- default).
-
- Example: if size over 500K {
- reply text:
- Your message was unnecessarily large. I reject all large
- messages; if you need to send me a large message, please
- contact me first and arrange outer means.
- .
- ; discard; }
-
- 4.6. Action stop
-
-
- Syntax: stop
-
- The "stop" action ends all processing. If no actions have been
- executed, then the keep action is taken.
-
- In the following script, if the mail is from the address
- "boss@frobnitzm.edu" it is forwarded to "pleeb@frobnitzm.edu";
- otherwise the mail receives a reply, and is thrown out.
-
- Example: if header ("from") matches ("boss@frobnitzm.edu") {
- forward "pleeb@xanadu.wv.us";
- stop;
- } reply text:
- I'm on vacation and not taking any messages; try after
- Sunday. I have thrown your message out. Please resend
- it later.
- .
- ; discard;
-
- 4.7. Action discard
-
-
- Syntax: discard
-
- Discard drops the message. In the following script, any mail from
- "idiot@frobnitzm.edu" is thrown out.
-
- Example: if header ("from") contains ("idiot@frobnitzm.edu")
- discard;
-
-
-
-
- Showalter [Page 18]
-
- Internet DRAFT Sieve October 24, 1997
-
-
- While an important part of this language, "discard" has the potential
- to create serious problems for users. For instance, a student
- leaving themselves logged in to a machine in a computer lab may find
- their script changed to just "discard". In order to protect users in
- this situation (along with similar situations), implementations MAY
- keep messages destroyed by a script for an indefinite period, and MAY
- disallow scripts that throw out all mail.
-
- 5. Tests
-
-
- Tests are used in conditionals to decide which part(s) of the
- conditional to execute.
-
- 5.1. Test all-of
-
-
- Syntax: all-of ( <test> , <test> , ... <test> )
-
- The all-of test preforms a logical AND on the tests supplied to it.
-
- Example: all-of (false, false) => false
- all-of (false, true) => false
- all-of (true, true) => true
-
- 5.2. Test any-of
-
-
- Syntax: any-of ( <test> , <test> , ... <test> )
-
- The any-of test preforms a logical OR on the tests supplied to it.
-
- Example: any-of (false, false) => false
- any-of (false, true) => true
- any-of (true, true) => true
-
- 5.3. Test exists
-
-
- Syntax: exists <header-name-list>
-
- The "exists" test is true if the headers listed in the
- <header-name-list> argument exist within the message. All of the
- headers must exist or the test is false. The test
- exists ("From" "To" "Cc")
- is equivalent to
- header ("From" "To" "Cc") contains ""
-
-
-
-
- Showalter [Page 19]
-
- Internet DRAFT Sieve October 24, 1997
-
-
- The following example throws out mail that doesn't have a From header
- and a Date header.
-
- Example: if not exists ("From" "Date") {
- discard;
- }
-
- 5.4. Test false
-
-
- Syntax: false
-
- The "false" test always evaluates to false.
-
- 5.5. Test header
-
-
- Syntax: header <header-name-list> <match-keyword> <key-list>
-
- The "header" test evaluates to true if the any header name matches
- any key. How the match is done is described by the second argument,
- which is one of the string comparison arguments discussed in section
- 2.6. The first argument to header, the header-name-list, is a list
- of headers to get values from to be searched. The key-list is a list
- of keys.
-
- If a header listed in the header-name-list argument exists, it
- contains the null key (""). However, if the named header is not
- present, it does not contain the null key. So if a message contained
- the header
-
- X-Caffeine: C8H10N4O2
-
- these tests on that header evaluate as follows:
-
- header ("X-Caffeine") is ("") => false
- header ("X-Caffeine") matches ("") => false
- header ("X-Caffeine") contains ("") => true
-
- 5.6. Test not
-
-
- Syntax: not <test>
-
- The "not" test takes some other test as an argument, and yields the
- opposite result.
-
-
-
-
-
- Showalter [Page 20]
-
- Internet DRAFT Sieve October 24, 1997
-
-
- 5.7. Test size
-
-
- Syntax: size <"over" / "under"> <limit [quantifier]>
-
- The "size" test deals with the size of a message. The test is true
- only if the first argument is "over" and the size of the message is
- strictly greater than the number of octets specified as limit. If
- the first argument is "under", then the test is true only if the
- message size is strictly less than the number of octets specified as
- limit. In either case, if the message size is exactly the limit, the
- test is false.
-
- The size of a message is defined to be the number of octets from the
- initial header until the last character in the message body.
-
- 5.8. Test support
-
-
- Syntax: support <extension-name>
-
- The "support" test evaluates to true if the extension named by
- <extension-name> is supported. In the following script, all mail is
- filed into INBOX unless the "black-magic" extension is supported.
- Otherwise, behavior is defined by the black-magic extension.
-
-
- Example: if support "black-magic" {
- black-magic ("zork@frobnitzm.edu");
- }
-
- 5.9. Test true
-
-
- Syntax: true
-
- The "true" test is always true.
-
- 6. Errors in Processing a Script
-
- In any programming language, errors are inevitable. Users are
- expected to make errors, and changes in the environment, such as a
- change in a user's rights on a mailbox, can cause a script to fail.
- It is imperative that mail be allowed to get through.
-
- Implementations SHOULD check a script before it is run in order to
- ensure that it is valid. Implementations SHOULD NOT try and recover
- from a script with errors, and should file mail into the user's
-
-
-
- Showalter [Page 21]
-
- Internet DRAFT Sieve October 24, 1997
-
-
- primary mailbox.
-
- Users MUST be notified of errors in processing a script. The method
- by which users are notified is implementation defined, but a mail
- message clearly describing the error is suggested if a preferable
- alternative cannot be found.
-
- In an implementation that allows for a script to be checked when it
- is turned over to the server, the script can be checked for errors
- before it is submitted. Implementations SHOULD notify the user of
- the error and refuse to accept a syntactically invalid script or one
- that makes use of extensions that the server does not report.
-
- Implementations MUST allow mail to be filed without filtering in case
- of a syntax error in the script. Implementations MUST avoid sending
- multiple messages describing the same error.
-
- Implementations are REQUIRED to notify users of errors in filtering
- scripts. If there are errors in the script being used, mail SHOULD
- be filed into the user's main mailbox. Implementations MUST NOT
- discard mail unless a command explicitly demands it.
-
- 7. Extensibility
-
- New control structures, actions, and tests can be added to the
- language. Sites must make these features known to their users; this
- document does not define a way to discover the list of extensions
- supported by the server.
-
- Any extensions to this language MUST define a string that uniquely
- identifies that extension. If a new version of an extension changes
- the functionality of a previously defined extension, it MUST use a
- different name. The purpose of such a string is for the "require"
- and "support" conditionals, which mandates that script requires the
- use of that extension.
-
- Additionally, in a situation where there is a submission protocol and
- an extension advertisement mechanism aware of the details of this
- language, scripts submitted can be checked against the mail server to
- prevent use of an extension that that the server does not support.
-
- 7.1. Capability String
-
- Capability strings are typically short strings describing what
- capabilities are supported by the server. The following capability
- strings are defined by this document:
-
-
-
-
-
- Showalter [Page 22]
-
- Internet DRAFT Sieve October 24, 1997
-
-
- fileinto The string "fileinto" indicates the implementation
- supports filing into mailboxes.
-
-
- 7.2. Registry
-
- In order to provide a standard set of extensions, a registry is
- provided by IANA. Capability names may be registered on a first-
- come, first-served basis. Extensions designed for interoperable use
- should be defined as standards track or IESG approved experimental
- RFCs.
-
- To: XXX@XXX.XXX Subject: Registration of new Sieve extension
-
- Capability name:
-
- Capability keyword:
-
- Capability arguments:
-
- Standards Track/IESG-approved experimental RFC number:
-
- Person and email address to contact for further information:
-
- 7.3. Capability Transport
-
- As the range of mail systems that this draft is intended to apply to
- is quite large, a method of advertising which capabilities an
- implementation supports is difficult due to the wide range of
- possible implementations. Such a mechanism, however, should have the
- following properties.
-
- (1) The implementation can advertise the complete set of extensions
- that it supports.
-
-
- OPEN: There needs to be a more complete description here.
-
-
- 8. Transmission
-
- The MIME type for a SIEVE script is "application/sieve". Scripts are
- encoded in UTF-8 during transmission.
-
- 9. Acknowledgments
-
- I am very thankful to Chris Newman for his support and his ABNF
- syntax checker. I am also indebted to all of the readers of the
-
-
-
- Showalter [Page 23]
-
- Internet DRAFT Sieve October 24, 1997
-
-
- ietf-mta-filters@imc.org mailing list.
-
- 10. Formal Grammar
-
- The grammar used in this section is the same as the ABNF described in
- [ABNF].
-
- In the case of alternative or optional rules in which a later rule
- overlaps an earlier rule, the rule which is listed earlier MUST take
- priority. (This shouldn't happen. Please let me know if it does.)
-
- action = bounce / discard / fileinto / forward / keep / reply / stop
-
- address = string
- ;; any legal [IMAIL] address.
-
- any-of = "any-of" test-list
-
- all-of = "all-of" test-list
-
- block = "{" [WSP] commands [WSP] "}"
- ;; C-style block
-
- bounce = "bounce" WSP string
- ;; string is the reason contained in the bounce message.
-
- control-structure = if
-
- command = ( action ";" ) / block / control-structure
-
- commands = *([WSP] command [WSP])
-
- comment = "#" *VCHAR CRLF
-
- comparator = "octet"
- ;; octet is the only comparator mandated by this specification
- ;; but others may be defined by the ACAP registry.
-
- discard = "discard"
-
- exists = "exists" WSP string
-
- false = "false"
-
- fileinto = "fileinto" WSP string
- ;; string is a mailbox; semantics are defined by the
- ;; underlying mail system
-
-
-
-
- Showalter [Page 24]
-
- Internet DRAFT Sieve October 24, 1997
-
-
- forward = "forward" WSP address
-
- if = "if" WSP test WSP command [ "else" command ]
- ;; Commands are typically blocks.
-
- header = "header" WSP string-list WSP match-keyword WSP string-list
-
- keep = "keep"
-
- match-keyword = ("contains" / "matches" / "is") ["-" comparator]
-
- multi-line = "text:" [WSP] CRLF
- *((1*CHAR-NOT-DOT *CHAR CRLF) / ("." 1*CHAR-NOT-DOT *CHAR CRLF) /
- (".." *CHAR CRLF) / CRLF)
- "." CRLF
- ;; Note when used,
- ;; a leading ".." on a line is mapped to ".".
-
- CHAR-NOT-DOT = (%x01-2d / %x2f-%xff)
- ;; all the characters that aren't "."
-
- not = "not" WSP test
-
- number = 1*DIGIT [QUANTIFIER]
- ;; quantifier is a multiplier (or bit shift)
-
- QUANTIFIER = "K" / "M" / "G"
- ;; K == 2^10; M == 2^20; G = 2^30
-
- quoted-string = DQUOTE *CHAR DQUOTE
- ;; \" inside a string maps to "
- ;; \\ inside a string maps to \
- ;; All other characters map to themselves.
- ;; Note that newlines and other weird characters
- ;; are all allowed strings.
-
- reply = "reply" WSP multi-line
-
- size = "size" WSP ( "over" / "under" ) WSP number
-
- SPACE = %d32
-
- stop = "stop"
-
- string = quoted-string / multi-line
-
- string-list = "(" [WSP] *(string WSP) string [WSP] ")" / string
- ;; if there is only a single string, the parens are optional
-
-
-
- Showalter [Page 25]
-
- Internet DRAFT Sieve October 24, 1997
-
-
- test = [WSP] (any-of / all-of / exists / false / header /
- not / size) [WSP]
-
- test-list = [WSP] "(" [WSP] *(test [WSP] "," [WSP])
- test [WSP] ")" [WSP]
-
- true = "true"
-
- WSP = 1*(SPACE / CRLF / HTAB) / comment
- ;; just whitespace. anyplace this is allowed, a comment is
- ;; as well
-
- 11. Security Considerations
-
- Users must get their mail. It is imperative that whatever method
- implementations use to store the user-defined filtering scripts be
- secure.
-
- It is equally important that implementations sanity-check the user's
- scripts, and not allow users to create on-demand mailbombs. For
- instance, an implementation that allows a user to bounce, forward, or
- reply multiple times to a single message might also allow a user to
- create a mailbomb triggered by mail from a specific user.
-
- Therefore, an implementation SHOULD only allow one "bounce" per
- message processed, and MAY limit the number of forward and reply
- actions taken. An implementation MUST refuse to forward a message to
- itself. [OPEN: What do you do when a site limit prevents you from
- this? Say I do three replies; which ones take effect when the limit
- is 1? 2? 0?]
-
- Several commands, such as "discard", "forward", and "fileinto" allow
- for actions to be taken that are potentially very dangerous.
-
- 12. Author's Address
-
- Tim Showalter
- Carnegie Mellon University
- 5000 Forbes Avenue
- Pittsburgh, PA 15213
-
- E-Mail: tjs@andrew.cmu.edu
-
-
-
-
-
-
-
-
-
- Showalter [Page 26]
-
- Internet DRAFT Sieve October 24, 1997
-
-
- Appendices
-
- Appendix A. References
-
- [ABNF] Crocker, D., "Augmented BNF for Syntax Specifications: ABNF",
- Internet Mail Consortium, Work in Progress.
-
- [DSN] Moore, K., and G. Vaudreuil, "An Extensible Message Format for
- Delivery Status Notifications", RFC 1894, January, 1996.
-
- [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", RFC 2119, Harvard University, March 1997.
-
- [IMAP] Crispin, M., "Internet Mail Access Protocol - version 4rev1",
- RFC 2060, University of Washington, December 1996.
-
- [IMAIL] Crocker, D., "Standard for the Format of ARPA Internet Text
- Messages", STD 11, RFC 822, University of Delaware, August 1982.
-
- [MIME] Freed, N., and N. Borenstein, "Multipurpose Internet Mail
- Extensions (MIME) Part One: Format of Internet Message Bodies", RFC
- 2045, Innosoft and First Virtual, November 1996.
-
- [SMTP] Postel, J., "Simple Mail Transfer Protocol", STD 10, RFC 821,
- USC/Information Sciences Institute, August 1982.
-
- [UTF-8] Yergeau, F. "UTF-8, a transformation format of Unicode and
- ISO 10646", RFC 2044, Alis Technologies, October 1996.
-
-
-
- This document will expire before December 1, 1997.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Showalter [Page 27]
-
-