view Side-By-Side changes
Date: Tue, 09 Apr 2002 11:28:09 GMT Server: Apache/1.3.20 (Unix) Last-Modified: Mon, 27 Apr 1998 14:27:00 GMT ETag: "3dd9bc-bfe1-354495b4" Accept-Ranges: bytes Content-Length: 49121 Connection: close Content-Type: text/plain Network Working Group T. Showalter Internet Draft: Sieve Carnegie Mellon Document:draft-showalter-sieve-03.txt Januarydraft-showalter-sieve-04.txt August 1998 Expire in six months(DD Jun 1998)(31 January 1999) 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.netftp.ietf.org (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. Copyright Copyright (C) The Internet Society 1998. All Rights Reserved. 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 Expires 31Jun 1998Jan 1999 [Page 1] Internet DRAFT SieveJanuary 21,August 7, 1998 Table of Contents Status of this memo Copyright 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 0.3. Noted Changes0.3.1 since 02 draft1. 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. Literal data 2.4.1. Numbers2.5.2.4.2. Strings2.5.2.2.4.2.1. String lists2.5.3.2.4.2.2. Headers2.5.4.2.4.2.3. Addresses2.6.2.5. Tests 2.5.1. String Comparison 2.6.1. Match Keyword 2.6.2. Comparators 2.7. Tagged Arguments 2.8. Blocks 2.9. Commands 2.9.1. Positional Arguments 2.9.2. Optional Arguments 2.9.3. Blocks as Arguments 2.11. Evaluation 2.11.1. Implicit keep 3. Conditionals and Control Structures3.1. If4. Actions 4.1. Action reject 4.2. Action fileinto 4.3. Action forward 4.4. Action keep4.5. Action replyShowalter Expires 31 Jan 1999 [Page 2] Internet DRAFT Sieve August 7, 1998 4.6. Action stop 4.7. Action discard 5. Tests 5.1. Test allof 5.2. Test anyof 5.3. Test existsShowalter Expires 31 Jun 1998 [Page 2] Internet DRAFT Sieve January 21, 19985.4. Test false 5.5. Test header 5.6. Test not 5.7. Test size5.8. Test support 5.9. Test true6. 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 Appendix B. Full Copyright Statement Showalter Expires 31Jun 1998Jan 1999 [Page 3] Internet DRAFT SieveJanuary 21,August 7, 1998 Showalter Expires 31Jun 1998Jan 1999 [Page 2] Internet DRAFT SieveJanuary 21,August 7, 1998 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""foo" in an address"tjs+fmh@andrew.cmu.edu")"tjs+foo@andrew.cmu.edu") is not handled, and will be moved to an extension for those systems that offer it. A vacation command has been requested for an extension; a preliminary draft exists and will be submitted to the internet-drafts repository.ItVacation functionality is 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). An "include" command is not included, but has been suggested for an extension. Showalter Expires 31Jun 1998Jan 1999 [Page 4] Internet DRAFT SieveJanuary 21,August 7, 1998 0.2.2. Known Bugs The formalgrammar. (It's better than it was).grammar probably still has some holes in it. The reject command needs to be rechecked against the DSN specification. The error-handling clauses of this specification may not be completely sensible, and may conflict. The discussion of the limits of actions is not there. Only one forwardor rejectshould be allowed per message.reject should prohibit fileinto. reply should prohibit reject. My knowledge of email is not comprehensive,Keep andas 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.reject are mutually exclusive. 0.3. Open IssuesThe support 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 anyof/allof 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 rejected 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 Expires 31 Jun 1998 [Page 5] Internet DRAFT Sieve January 21, 1998I 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)?0.3. Noted Changes0.3.1 since 02This draftChanged reply to specify thatwas unfortunately rushed and probably contains numerous errors. This is purely themessage infault of thereply goeseditor. For this reason, readers are asked tothe return-path address (envelope from). Added supportsubscribe to thegrammar. (bug) Changed reply to take a stringmailing list noted above for discussion, asan argument. (bug) Changed "bounce" to "reject". Was slightly more than a search- replace, but may have bugs anyway. (clarity) DSN format reject messages are now REQUIRED. (feature) Reject now overrides everything period, and is not merely a demand to send a DSNwell as some inevitable corrections. The grammar has changed substantially to allow easier modification by extensions at thesender. (feature) Changed "all-of"expense of some additional definition in the rest of the draft. Support and"any-of" to "allof"reply have been removed, and"anyof" respectively since Chris said we might want math.the format of stringlists has changed. Showalter Expires 31Jun 1998Jan 1999 [Page6]5] Internet DRAFT SieveJanuary 21,August 7, 1998 1. Introduction This memo documents a 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]-compliantmessages and support of multiple folders,messages, but otherwise shouldwork with a wide variety ofgeneralize to other systems thatsupportmeet 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 isfinallymoved to theuser- accessibleuser-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 [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. In the sections of this document that discuss the requirements ofShowalter Expires 31 Jun 1998 [Page 7] Internet DRAFT Sieve January 21, 1998various keywords and operators, the following conventions have been Showalter Expires 31 Jan 1999 [Page 6] Internet DRAFT Sieve August 7, 1998 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 Expires 31Jun 1998Jan 1999 [Page8]7] Internet DRAFT SieveJanuary 21,August 7, 1998 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 containsCommands can take atest; depending on the resultsnumber ofthe test, one setarguments; arguments can be either literal data, tests, or blocks ofcommands in a control structure is taken.commands. 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; } XXX this example is broken 2.4. Literal data Literal data means data that is not executed and is supplied as arguments, such as numbers and strings. Showalter Expires 31 Jan 1999 [Page 8] Internet DRAFT Sieve August 7, 1998 2.4.1. 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 Expires 31 Jun 1998 [Page 9] Internet DRAFT Sieve January 21, 1998or 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.2.4.2. 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 oncontext (such as in globs, defined in section 2.6 on string comparison).context. 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. Showalter Expires 31 Jan 1999 [Page 9] Internet DRAFT Sieve August 7, 1998 Note that a comment may occur in between the "text:" and the CRLF, but not within the string itself.Example: if anyof (header ("from") contains ("bart", "homer", "smithers", "burns", "lisa"), header ("subject") contains ("URGENT")) { Showalter Expires 31 Jun 1998 [Page 10] Internet DRAFT Sieve January 21, 1998 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 that2.4.2.1. 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")["To", "Cc"] contains("me@frobnitzm.edu", "me00@landru.melon.edu")'["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.["To"]'. 2.4.2.2. 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 Expires 31 Jun 1998 [Page 11] Internet DRAFT Sieve January 21, 1998 2.5.4.2.4.2.3. 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.2.5. Tests Tests are given as arguments to commands in order to control how the run. Generally, a test is used to decide if a block of code should be evaluated. Showalter Expires 31 Jan 1999 [Page 10] Internet DRAFT Sieve August 7, 1998 2.5.1. 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 arethreetwo allowed match keywords describing the allowed match in this draft; they are"is", "contains",":is" and"matches".":contains". Match keywords are supplied to those commands which allow them to specify whether the match is to be a complete match or not. These are used as tagged arguments to tests that perform string comparison. Exactly one of them is necessary for a command. The"contains"":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"":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 keyIn order to specify what type of match isnot substring, but contains certain special characterssupposed to happen, commands thatmatch characterssupport matching take optional tagged arguments ":is" and ":contains". Commands default to using ":is" matching. Note that these modifiers may interact with comparators; in particular, some comparators are notthemselves. These characters are * Match zero or more characters ? Match any single character \ Escape next character Escaped special characters dosuitable for matching with ":contains". It is an error to use a comparator with ":contains" that is nottake 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 Expires 31 Jun 1998 [Page 12] Internet DRAFT Sieve January 21, 1998compatible with it. 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 specification uses that registry. ACAP defines multiple comparator types. Only equality types are used in this specification. Showalter Expires 31 Jan 1999 [Page 11] Internet DRAFT Sieve August 7, 1998 All implementations MUST support the "i;octet" comparator, which simply compares one octet with the next. If left unspecified, the default is octet.If an implementation supports a comparator "elbonia", it MUST provide the capability "comparator-elbonia" for support tests.Some comparators may not be usable with substring matches; that is, they may only work with"is".":is". It is an error to try and use a comparator with "matches" or "contains" that is not compatible with it. A comparator is specified with commands that support matching by the ":comparator" option. This option is followed by a string providing the name of the comparator to be used. So in this example, Example: if header "Subject" :contains :comparator "i;ascii-casemap" "make money fast" { discard; would discard any message with subjects such as "Make Money Fast" and "MaKe MONEY fAST". 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, asTagged Arguments This document provides for tagged arguments in thefollowing script, the messagestyle of CommonLISP. A tagged argument isfiled into INBOX. With anyan an argument for a command that begins with ":", and consists of a tag naming theshort messages offered above,argument, such as ":contains". This argument means that zero or more of thefollowing script produces no actions. Example: if size over 500K discard; In cases like this,next tokens have some particular meaning, depending on the"keep" action is taken. The "keep" action is defined toargument. These next tokens may be numbers or strings, but are never blocks. To keep theaction that is taken in a situationlanguage simple, tagged arguments should not take tagged arguments as arguments. One case where this is useful is the ":comparator" argument, which allows the userdoes no filtering. For instance, under an IMAP-based system, this implies filing into INBOX.to specify which ACAP comparator will be used to compare two strings, since different languages may impose different orderings on UTF-8 [UTF-8] characters. Tagged arguments may appear in any order, and may be interspersed with positional arguments. OPEN: Perhaps tagged arguments should always be before positional arguments. Showalter Expires 31 Jan 1999 [Page 12] Internet DRAFT Sieveimposes specific limitsAugust 7, 1998 2.8. Blocks Blocks are sets of commands enclosed within curly braces. Blocks are supplied to commands so that the commands can implement control structures. So a control structure is just a command that happens to take a test and a block as its arguments; depending onactions; for instance,the result of the control structure, it runs the code in the block zero or more times. (Note that by the commands supplied in the specification, there are no loops, so the control structures supplied--if, elsif, and else--run arejected message mayblock either once or notalsoat all.) 2.9. Commands Sieve scripts are made up of commands. Commands can take any of the tokens above as arguments, and arguments may befiled intoeither tagged or positional arguments. A command begins with amailbox. These restrictionsname, which is a simple token. It ends with either a semicolon or a block. (Commands ending with blocks arenotedused to implement control structures.) Commands never take both a semicolon and a block, nor do they ever take more than one block as an argument. 2.9.1. Positional Arguments Positional arguments are familiar from any programming language. A command takes zero or more untagged positional arguments in order to specify its behavior. Positional arguments are given their value based on their order in the command. 2.9.2. Optional Arguments Optional arguments are tagged arguments that may be omitted; when omitted, they are given default values. 2.9.3. Blocks as Arguments Commands may take blocks as arguments. A block is always the last argument to aper-command basis. [no they're not]command, and when it exists, it replaces the semicolon that would otherwise end the command. 2.11. Evaluation Precedence is not important in any of the commands in this base specification. However, as an extension might make order of operation important, all arguments to rules MUST be evaluated in Showalter Expires 31Jun 1998Jan 1999 [Page 13] Internet DRAFT SieveJanuary 21,August 7, 1998 left-to-right order. Those operations that can implement short- circuit evaluation (such as "allof" and "anyof") MUST do so. Sieve imposes specific limits on actions; for instance, a rejected message may not also be filed into a mailbox. These restrictions are noted on a per-command basis. OPEN: Or rather, they should be. 2.11.1. Implicit keep If evaluation of a script fails to result in one "fileinto", "keep", or "reject", a "keep" action is implicitly taken. So the message is filed into the user's primary mailbox; that is, For instance, with any of the short messages offered above, the following script produces no actions. Example: if size over 500K discard; 3. Conditionals and Control Structures In order for a script to do more than one set of actions, control structures are needed. In Sieve, a control structure is a command that takes a block as an argument. In this document, onlyonethe "if" control structure issupplied. 3.1. Ifprovided. There are three pieces to if: "if", "elsif", and "else". Syntax: if <test> <command>[else <command>]Syntax: elsif <test> <command> Syntax: else <block> The"if" control structure is borrowed fromsemantics are similar to anynumber ofother programminglanguages. Itlanguage this appears in. When the interpreter sees an "if", it evaluates the test associated with it. If the test isevaluated intrue, it executes theusual way ifblock associated with it. If the test of the "if" istrue thenfalse, it evaluates the test of the firstcommand (or setShowalter Expires 31 Jan 1999 [Page 14] Internet DRAFT Sieve August 7, 1998 "elsif" (if any). If the test ofcommands) supplied"elsif" isevaluated. Iftrue, it runs the elsif's block. An elsif may be followed by an elsif, in which case, the interpreter repeats this process until it runs out of elsifs. When thetest is false andinterpreter runs out of elsifs, there may be anelse keyword follows"else" case. If there is, and none of the ifblock,or elsif tests were true, thesecond command is evaluated. The commands may be command blocks. [OPEN:interpreter runs the else case. Thisallows C-style dangling statements; I construe this asprovides afeature.]way of performing exactly one of the blocks in the chain. In the following example, both Message A and B are dropped. Example: if header "from" contains "coyote" { discard; }else ifelsif header("subject") contains ("$$$")["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")["From"] contains("coyote")["coyote"] { forward "acm@frobnitzm.edu"; } else if header "Subject" contains "$$$" { forward "postmaster@frobnitzm.edu"; } else forward "field@frobnitzm.edu";Showalter Expires 31 Jun 1998 [Page 14] Internet DRAFT Sieve January 21, 19984. Actions This document supplies six actions that may be taken on a message: keep, fileinto, forward, reject, discard, and stop. 4.1. Action reject Syntax: reject <reason-string> The "reject" action resends the message to the sender, wrapping it in a "reject" form, noting that it was rejected by the recipient. In the following script, message A is rejected and returned to the sender. Example: if header "from" contains "coyote@znic.net" { Showalter Expires 31 Jan 1999 [Page 15] Internet DRAFT Sieve August 7, 1998 reject "I am not taking mail from you, and I don't want your birdseed, either!"; } A reject message MUST 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 MUST 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 "reject" prevent all other actions from taking affect?A rejected message may not be filed, forwarded, or kept. A message that triggers a "reject" action is never allowed to be kept by the user, and the "reject" overrides all other actions.Showalter Expires 31 Jun 1998 [Page 15] Internet DRAFT Sieve January 21, 1998A message may only be rejected once. 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 tests.In the following script, message A is filed into folder "INBOX.harassment". Example: if header("to")["to"] contains "coyote" { fileinto "INBOX.harassment"; } Showalter Expires 31 Jan 1999 [Page 16] Internet DRAFT Sieve August 7, 1998 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-styleforward -- thatforward--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.) OPEN: At least one person rejects to this definition, claiming that a sendmail-style forward is inherently broken. 4.4. Action keep Syntax: keepShowalter Expires 31 Jun 1998 [Page 16] Internet DRAFT Sieve January 21, 1998The "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> The "reply" action is used to generate a form letter reply to the original sender, as specified in the return-path header of the incoming message. 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;Example: ifyou need to send me a large message, please contact me first and arrange outer means. . ;size under 1M keep; else 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 afterShowalter Expires 31Jun 1998Jan 1999 [Page 17] Internet DRAFT SieveJanuary 21,August 7, 1998Sunday. I have thrown your message out. Please resend it later. . ; discard;Example: [There needs to be an example here.] 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")["from"] contains("idiot@frobnitzm.edu")["idiot@frobnitzm.edu"] discard; Discard takes no arguments. While an important part of this language, "discard" has the potential to create serious problems forusers. For instance, ausers: 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 allof Syntax: allof ( <test> , <test> , ... <test> ) The allof test preforms a logical AND on the tests supplied to it. Example: allof (false, false) => false allof (false, true) => false allof (true, true) => true The allof test takes as its argument a test-list. Showalter Expires 31Jun 1998Jan 1999 [Page 18] Internet DRAFT SieveJanuary 21,August 7, 1998 5.2. Test anyof Syntax: anyof ( <test> , <test> , ... <test> ) The anyof test preforms a logical OR on the tests supplied to it. Example: anyof (false, false) => false anyof (false, true) => true anyof (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. Thetest exists ("From", "To", "Cc") is equivalent to header ("From", "To", "Cc") contains "" Thefollowing example throws out mail that doesn't have a From header and a Date header. Example: if not exists("From","Date")["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. Showalter Expires 31Jun 1998Jan 1999 [Page 19] Internet DRAFT SieveJanuary 21,August 7, 1998 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")["X-Y-Z"] is("") => false header ("X-Caffeine") matches ("")[""] => false header("X-Caffeine")["X-Y-Z"] contains("")[""] => true 5.6. Test not Syntax: not <test> The "not" test takes some other test as an argument, and yields the opposite result. 5.7. Test size Syntax: size<"over"<":over" /"under">":under"> <limit [quantifier]> The "size" test deals with the size of a message.The test is true only if the firstIt takes either a tagged argumentis "over" andof ":over" or ":under", followed by a number representing the size of themessage is strictly greater than the number of octets specified as limit.message. If thefirstargument is"under", then the test is true only if":over", and themessagesizeis strictly less than the numberofoctets specified as limit. In either case, ifthe messagesizeisexactlygreater than thelimit,number provided, the test is true; otherwise, it is false.The size of a messageIf the argument isdefined to be":under", and thenumbersize ofoctets from the initial header until the last character inthe messagebody. 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. Showalter Expires 31 Jun 1998 [Page 20] Internet DRAFT Sieve January 21, 1998 Example: if support "black-magic" { black-magic ("zork@frobnitzm.edu"); } 5.9. Test true Syntax: true The "true"is less than the number provided, the test isalways true.true; otherwise, it 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. 6. Errors in Processing a Script In any programming language, errors are inevitable. Users are expected to make errors, andchanges in the environment, such as a change in a user's rights on a mailbox, can causeeven if a script works correctly today, it may fail tomorrow due tofail.quotas, mailboxes being removed or renamed, or some piece of hardware being down. It is imperative that mailbe allowed toget through. Implementations SHOULD check a script before it is run in order to ensure that it is valid. Implementations SHOULD NOT try and recover Showalter Expires 31 Jan 1999 [Page 20] Internet DRAFT Sieve August 7, 1998 from a script with errors, and should instead file mail into the user's 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 extensionsShowalter Expires 31 Jun 1998 [Page 21] Internet DRAFT Sieve January 21, 1998supported 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 "support" test, 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: fileinto The string "fileinto" indicates the implementation Showalter Expires 31 Jan 1999 [Page 21] Internet DRAFT Sieve August 7, 1998 supports filing into mailboxes. comparator- The string "comparator-elbonia" is provided if the implementation supports the "elbonia" comparator. Therefore, all implementations have at least the "comparator-i;octet" capability. 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.Showalter Expires 31 Jun 1998 [Page 22] Internet DRAFT Sieve January 21, 1998(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. Showalter Expires 31 Jan 1999 [Page 22] Internet DRAFT Sieve August 7, 1998 9. Acknowledgments I am very thankful to Chris Newman for his support and his ABNF syntax checker, to John Myers and Steve Hole for outlining the requirements for the original drafts, and to Rob Earhart for an early implementation and a great deal of help. I am also indebted to all of the readers of the 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 whichis listed earlier MUST take priority. (This shouldn't happen. Please let me know if it does.) action = reject / discard / fileinto / forward / keep / reply / stop address = string ;; any legal [IMAIL] address. anyof = "anyof" test-list allof = "allof" test-list block = "{" [WSP] commands [WSP] "}" ;; C-style block CHAR-NOT-DOT = (%x01-2d / %x2f-%xff) ;; all the characters that aren't "." control-structure = if command = ( action ";" ) / block / control-structure Showalter Expires 31 Jun 1998 [Page 23] Internet DRAFT Sieve January 21, 1998 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" existsis listed earlier MUST take priority. (This shouldn't happen. Please let me know if it does.) argument ="exists" WSPstringfalse/ string-list / number / tag / test block ="false" fileinto"{" [WSP] commands [WSP] "}" ;; C-style block CHAR-NOT-DOT ="fileinto" WSP string(%x01-2d / %x2f-%xff) ;;string is a mailbox; semantics are defined byall the;; underlying mail system forwardcharacters that aren't "." command ="forward"identifier WSPaddress if*(argument WSP) [WSP] ";" commands ="if" WSP test WSP command [ "else"*([WSP] command] ;; Commands are typically blocks. header = "header" WSP string-list WSP match-keyword WSP string-list keep[WSP]) comment ="keep" match-keyword"#" *VCHAR CRLF identifier =("contains" / "matches"(ALPHA /"is") ["-" comparator]"_") *(ALPHA DIGIT "_") 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 ".".not = "not" WSP testnumber = 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 " Showalter Expires 31 Jan 1999 [Page 23] Internet DRAFT Sieve August 7, 1998 ;; \\ inside a string maps to \ ;; All other characters map to themselves.Showalter Expires 31 Jun 1998 [Page 24] Internet DRAFT Sieve January 21, 1998;; Note that newlines and other weird characters ;; are all allowed strings.reject = "reject" WSP string ;; string is the reason contained in the DSN. reply = "reply" WSP string size = "size" WSP ( "over" / "under" ) WSP number stop = "stop"string = quoted-string / multi-line string-list ="(""[" [WSP] *(string [WSP] "," [WSP]) string [WSP]")""]" / string ;; if there is only a single string, theparensbrackets are optionalsupporttag ="support" WSP string":" identifier test =[WSP] (anyof / allof / exists / false / header / not / size / support) [WSP]identifier *(WSP argument) [WSP test-list] test-list = [WSP] "(" [WSP] *(test [WSP] "," [WSP]) test [WSP] ")" [WSP]true = "true"WSP = 1*(SP / 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 toreject, forward,reject orreplyforward 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 "reject" per message processed, and MAY limit the number of forwardand replyactions 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 limitShowalter Expires 31 Jun 1998 [Page 25] Internet DRAFT Sieve January 21, 1998is 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 15213E-Mail: tjs@andrew.cmu.eduShowalter Expires 31JunJan 1999 [Page 24] Internet DRAFT Sieve August 7, 1998 E-Mail: tjs+@andrew.cmu.edu Showalter Expires 31 Jan 1999 [Page26]25] Internet DRAFT SieveJanuary 21,August 7, 1998 Appendices Appendix A. References [ABNF] Crocker, D., "Augmented BNF for Syntax Specifications: ABNF", Internet Mail Consortium,Work in Progress.RFC 2234, November 1997. [DSN] Moore, K., and G. Vaudreuil, "An Extensible Message Format for Delivery Status Notifications", RFC 1894,January,January 1996. [FLAMES] Borenstein, Nathaniel S., and Chris A. Thyberg, "Power, Ease of Use, and Cooperative Work in a Practical Multimedia Message System", Int. J. of Man-Machine Studies, April, 1991. Reprinted in Computer-Supported Cooperative Work and Groupware, Saul Greenberg, editor, Harcourt Brace Jovanovich, 1991. Reprinted in Readings in Groupware and Computer-Supported Cooperative Work, Ronald Baecker, editor, Morgan Kaufmann, 1993. [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. Appendix B. Full Copyright Statement Copyright (C) The Internet Society 1998. All Rights Reserved. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are Showalter Expires 31 Jan 1999 [Page 26] Internet DRAFT Sieve August 7, 1998 included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English.Showalter Expires 31 Jun 1998 [Page 27] Internet DRAFT Sieve January 21, 1998The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns. This document will expire beforeJuneJanuary 31,1998.1999. Showalter Expires 31Jun 1998Jan 1999 [Page28]27] ----