idnits 2.17.1 draft-showalter-sieve-04.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. ** The document is more than 15 pages and seems to lack a Table of Contents. == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** There are 3 instances of too long lines in the document, the longest one being 6 characters in excess of 72. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? RFC 2119 keyword, line 317: '... YOU MAY HAVE ALREADY WON TEN MILLIO...' RFC 2119 keyword, line 369: '... Implementations MUST provide 31 bits ...' RFC 2119 keyword, line 445: '... Implementations MUST ensure the addre...' RFC 2119 keyword, line 504: '... implementations MUST support the "...' RFC 2119 keyword, line 524: '...her comparators that SHOULD or MUST be...' (23 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 165 has weird spacing: '...ggested for ...' == Line 195 has weird spacing: '... of the heade...' == Line 196 has weird spacing: '... into a se...' == Line 199 has weird spacing: '... in the secti...' == Line 200 has weird spacing: '...orrowed some ...' == (18 more instances...) -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (August 1998) is 9386 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Missing reference section? 'FLAMES' on line 1134 looks like a reference -- Missing reference section? 'KEYWORDS' on line 1142 looks like a reference -- Missing reference section? 'IMAIL' on line 1148 looks like a reference -- Missing reference section? 'ACAP' on line 496 looks like a reference -- Missing reference section? 'UTF-8' on line 1158 looks like a reference -- Missing reference section? 'DSN' on line 1131 looks like a reference -- Missing reference section? 'POP3' on line 732 looks like a reference -- Missing reference section? 'ABNF' on line 1128 looks like a reference -- Missing reference section? 'IMAP' on line 1145 looks like a reference -- Missing reference section? 'MIME' on line 1151 looks like a reference -- Missing reference section? 'SMTP' on line 1155 looks like a reference Summary: 10 errors (**), 0 flaws (~~), 8 warnings (==), 13 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group T. Showalter 3 Internet Draft: Sieve Carnegie Mellon 4 Document: draft-showalter-sieve-04.txt August 1998 5 Expire in six months (31 January 1999) 7 Sieve -- a Mail Filtering Language 9 Status of this memo 11 This document is an Internet-Draft. Internet-Drafts are working 12 documents of the Internet Engineering Task Force (IETF), its areas, 13 and its working groups. Note that other groups may also distribute 14 working documents as Internet-Drafts. 16 Internet-Drafts are draft documents valid for a maximum of six months 17 and may be updated, replaced, or obsoleted by other documents at any 18 time. It is inappropriate to use Internet-Drafts as reference 19 material or to cite them other than as ``work in progress.'' 21 To learn the current status of any Internet-Draft, please check the 22 ``1id-abstracts.txt'' listing contained in the Internet-Drafts Shadow 23 Directories on ftp.is.co.za (Africa), ftp.nordu.net (Europe), 24 munnari.oz.au (Pacific Rim), ftp.ietf.org (US East Coast), or 25 ftp.isi.edu (US West Coast). 27 The protocol discussed in this document is experimental and subject 28 to change. Persons planning on either implementing or using this 29 protocol are STRONGLY URGED to get in touch with the author before 30 embarking on such a project. 32 Copyright 34 Copyright (C) The Internet Society 1998. All Rights Reserved. 36 Abstract 38 This document describes a mail filtering language for filtering 39 messages at time of final delivery. It is designed to be independent 40 of protocol, and implementable on either a mail client or mail 41 server. It is meant to be extensible, simple, and independent of 42 access protocol, mail architecture, and operating system. It is 43 suitable for running on a mail server where users may not be allowed 44 to execute arbitrary programs, such as on black box IMAP servers, as 45 it has no variables, loops, or ability to shell out to external 46 programs. 48 Internet DRAFT Sieve August 7, 1998 50 Table of Contents 52 Status of this memo 53 Copyright 54 Abstract 55 0. Meta-information on this draft 56 0.1. Discussion 57 0.2. Known Problems 58 0.2.1. Probable Extensions 59 0.2.2. Known Bugs 60 0.3. Open Issues 61 0.3. Noted Changes 62 1. Introduction 63 1.1. Conventions used in this document 64 1.2. Example mail messages 65 2. Design 66 2.1. Form of the language 67 2.2. Whitespace 68 2.3. Comments 69 2.4. Literal data 70 2.4.1. Numbers 71 2.4.2. Strings 72 2.4.2.1. String lists 73 2.4.2.2. Headers 74 2.4.2.3. Addresses 75 2.5. Tests 76 2.5.1. String Comparison 77 2.6.1. Match Keyword 78 2.6.2. Comparators 79 2.7. Tagged Arguments 80 2.8. Blocks 81 2.9. Commands 82 2.9.1. Positional Arguments 83 2.9.2. Optional Arguments 84 2.9.3. Blocks as Arguments 85 2.11. Evaluation 86 2.11.1. Implicit keep 87 3. Conditionals and Control Structures 88 4. Actions 89 4.1. Action reject 90 4.2. Action fileinto 91 4.3. Action forward 92 4.4. Action keep 93 Internet DRAFT Sieve August 7, 1998 95 4.6. Action stop 96 4.7. Action discard 97 5. Tests 98 5.1. Test allof 99 5.2. Test anyof 100 5.3. Test exists 101 5.4. Test false 102 5.5. Test header 103 5.6. Test not 104 5.7. Test size 105 6. Errors in Processing a Script 106 7. Extensibility 107 7.1. Capability String 108 7.2. Registry 109 7.3. Capability Transport 110 8. Transmission 111 9. Acknowledgments 112 10. Formal Grammar 113 11. Security Considerations 114 12. Author's Address 115 Appendices 116 Appendix A. References 117 Appendix B. Full Copyright Statement 118 Internet DRAFT Sieve August 7, 1998 119 Internet DRAFT Sieve August 7, 1998 121 0. Meta-information on this draft 123 This information is intended to facilitate discussion. It will be 124 removed when this document leaves the Internet-Draft stage. 126 0.1. Discussion 128 This draft is being discussed on the MTA Filters mailing list at 129 . Subscription requests can be sent to 130 (send an email message with the 131 word "subscribe" in the body). More information on the mailing list 132 along with a WWW archive of back messages is available at 133 . 135 0.2. Known Problems 137 0.2.1. Probable Extensions 139 The following suggestions have been made, and will probably be 140 addressed by extensions. 142 An extension for regular expressions will be written. While regular 143 expressions are of questionable utility for most users, the 144 programmers writing implementations desperately want regular 145 expressions. 147 Envelope-matching commands are not readily supported by all mail 148 systems, and putting them in the draft will result in a system that 149 cannot be implemented by a mail architecture that does not adequately 150 store envelopes. 152 "Detailed" addressing or "sub-addressing" (i.e., the "foo" in an 153 address "tjs+foo@andrew.cmu.edu") is not handled, and will be moved 154 to an extension for those systems that offer it. 156 A vacation command has been requested for an extension; a preliminary 157 draft exists and will be submitted to the internet-drafts repository. 158 Vacation functionality is isn't in the draft because having vacation 159 assumes you can store the addresses of people who have already 160 received vacation notifications, which isn't always the case. 162 A suggestion was made to set IMAP flags on delivery (e.g., \Flagged, 163 \Deleted, \Answered, \Seen). 165 An "include" command is not included, but has been suggested for an 166 extension. 168 Internet DRAFT Sieve August 7, 1998 170 0.2.2. Known Bugs 172 The formal grammar probably still has some holes in it. 174 The reject command needs to be rechecked against the DSN 175 specification. 177 The error-handling clauses of this specification may not be 178 completely sensible, and may conflict. 180 The discussion of the limits of actions is not there. Only one 181 forward should be allowed per message. Keep and reject are mutually 182 exclusive. 184 0.3. Open Issues 186 In the event that there is an error while processing a script, what 187 happens? The draft implies you file into INBOX, but what if you've 188 already taken actions before you do this? (The parts of the draft 189 that require syntax checking stuff are all SHOULDs.) 191 I tried to fill in some of the blanks in previous versions; among 192 them, the description of what a rejected input message looks like, 193 but it's still nearly incomplete. 195 I moved the substring matching stuff out of the header command and 196 into a section of its own as it is reusable by extensions. 197 Suggestions on this section would be appreciated. 199 I tried to fill in the blanks in the section on extensibility and 200 borrowed some stuff from the ACAP spec (specifically, the comparator 201 registry), but it's probably not complete or good enough. 203 0.3. Noted Changes 205 This draft was unfortunately rushed and probably contains numerous 206 errors. This is purely the fault of the editor. For this reason, 207 readers are asked to subscribe to the mailing list noted above for 208 discussion, as well as some inevitable corrections. 210 The grammar has changed substantially to allow easier modification by 211 extensions at the expense of some additional definition in the rest 212 of the draft. 214 Support and reply have been removed, and the format of stringlists 215 has changed. 217 Internet DRAFT Sieve August 7, 1998 219 1. Introduction 221 This memo documents a language that can be used to create filters for 222 electronic mail. It is not tied to any particular operating system or 223 mail architecture. It requires the use of [IMAIL]-compliant 224 messages, but otherwise should generalize to other systems that meet 225 these criteria. 227 The language is powerful enough to be useful, but limited in power in 228 order to allow for a safe server-side filtering system. The 229 intention is to make it impossible for users to do anything more 230 complex (and dangerous) than write simple mail filters, along with 231 facilitating GUI-based editors. The language is not Turing-complete, 232 and provides no way to write a loop or a function. Variables are not 233 provided. 235 Implementations of the language are expected to take place at time of 236 final delivery, when the message is moved to the user-accessible 237 mailbox. In systems where the MTA does final delivery, such as and 238 traditional UNIX mail, is reasonable to sort when the MTA deposits 239 mail into the user's mailbox. If the MTA does not do final delivery, 240 or lacks the power to sort into separate mailboxes, as is the case 241 under POP3, the MUA must do filtering into local-disk folders. 243 There are a number of reasons to use a filtering system. Mail 244 traffic for most users has been increasing due both to increased 245 usage of e-mail, the emergence of unsolicited email as a form of 246 advertising, and increased usage of mailing lists. 248 Experience at Carnegie Mellon has shown that if a filtering system is 249 made available to users, many will make use of it in order to file 250 messages from specific users or mailing lists. However, many others 251 did not make use of the Andrew system's FLAMES [FLAMES] filtering 252 language due to difficulty in setting it up. 254 Because of the expectation that users will make use of filtering if 255 it is offered and easy to use, this language has been made simple 256 enough to allow many users to make use of it, but rich enough that it 257 can be used productively. However, it is expected that GUI-based 258 editors will be the preferred way of editing filters for a large 259 number of users. 261 1.1. Conventions used in this document 263 In examples, line breaks have been inserted for readability. 265 In the sections of this document that discuss the requirements of 266 various keywords and operators, the following conventions have been 268 Internet DRAFT Sieve August 7, 1998 270 adopted. 272 The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", "CAN", and 273 "MAY" in this document are to be interpreted as defined in 274 [KEYWORDS]. 276 Each section on a test, action, or control structure has a line 277 labeled "Syntax:". This line describes the syntax of the command, 278 including its name and its arguments. Required arguments are listed 279 inside angle brackets ("<" and ">"). Optional arguments are listed 280 inside square brackets ("[" and "]"). However, the formal grammar 281 for these commands in section 10 and is the authoritative reference 282 on how to construct these commands. 284 1.2. Example mail messages 286 The following mail messages will be used throughout this document in 287 examples. 289 Message A 290 ----------------------------------------------------------- 291 Date: Tue, 1 Apr 1997 09:06:31 -0800 (PST) 292 From: coyote@desert.org 293 To: roadrunner@birdseed.org 294 Subject: I have a present for you 296 Look, I'm sorry about the whole anvil thing, and I really 297 didn't mean to try and drop it on you from the top of the 298 cliff. I want to try to make it up to you. I've got some 299 great birdseed over here at my place -- top of the line 300 stuff -- and if you come by, I'll have it all wrapped up 301 for you. I'm really sorry for all the problems I've caused 302 for you over the years, but I know we can work this out. 303 -- 304 Wile E. Coyote "Super Genius" coyote@znic.net 305 ----------------------------------------------------------- 307 Internet DRAFT Sieve August 7, 1998 309 Message B 310 ----------------------------------------------------------- 311 From: youcouldberich!@reply-by-postal-mail 312 Sender: b1ff@de.res.frobnitzm.edu 313 To: rube@landru.melon.net 314 Date: Mon, 31 Mar 1997 18:26:10 -0800 (PST) 315 Subject: $$$ YOU, TOO, CAN BE A MILLIONAIRE! $$$ 317 YOU MAY HAVE ALREADY WON TEN MILLION DOLLARS, BUT I DOUBT 318 IT! SO JUST POST THIS TO SIX HUNDRED NEWSGROUPS! IT WILL 319 GUARANTEE THAT YOU GET AT LEAST FIVE RESPONSES WITH MONEY! 320 MONEY! MONEY! COLD HARD CASH! YOU WILL RECEIVE OVER 321 $20,000 IN LESS THAN TWO MONTHS! AND IT'S LEGAL!!!!!!!!! 322 !!!!!!!!!!!!!!!!!!111111111!!!!!!!11111111111!!1 JUST 323 SEND $5 IN SMALL, UNMARKED BILLS TO THE ADDRESSES BELOW! 324 ----------------------------------------------------------- 326 2. Design 328 2.1. Form of the language 330 This language is made up as a set of commands. Commands can take a 331 number of arguments; arguments can be either literal data, tests, or 332 blocks of commands. 334 2.2. Whitespace 336 Whitespace is used to separate commands. Whitespace is made up of 337 tabs, newlines (CRLF, never just CR or LF), and the space character. 338 The amount of whitespace used is not significant. 340 2.3. Comments 342 Comments begin with a "#" character that is not contained within a 343 string and continue until the next CRLF. 345 Example: if size over 100K { # this is a comment 346 discard; 347 } 349 XXX this example is broken 351 2.4. Literal data 353 Literal data means data that is not executed and is supplied as 354 arguments, such as numbers and strings. 356 Internet DRAFT Sieve August 7, 1998 358 2.4.1. Numbers 360 Numbers are given as ordinary decimal numbers. However, those 361 numbers that have a tendency to be fairly large, such as message 362 sizes, may have a "K", "M", or "G" appended to indicate a multiple of 363 a base-two number. To be comparable with the power-of-two-based 364 versions of SI units that computers frequently use, K specifies kilo, 365 or 1,024 (2^10) times the value of the number; M specifies mega, or 366 1,048,576 (2^20) times the value of the number; and G specifies giga, 367 or 1,073,741,824 (2^30) times the value of the number. 369 Implementations MUST provide 31 bits of magnitude in numbers, but may 370 provide more. 372 Negative, fractional, and decimal numbers are not permitted by this 373 specification. 375 2.4.2. Strings 377 Scripts involve large numbers of strings, as they are used for 378 pattern matching, addresses, and textual bodies, etc. Typically, 379 short quoted strings suffice for most uses, but a more convenient 380 form is provided for longer strings such as bodies of messages. 382 A quoted string starts and ends with a single double quote (the <"> 383 character). A backslash ("\") inside of a quoted string is followed 384 by either another backslash or a double quote. This two-character 385 sequence represents a single backslash or double-quote within the 386 string, respectively. 388 Other escape sequences may be permitted depending on context. An 389 undefined escape sequence (such as "\a" in a context where "a" has no 390 special meaning) is interpreted as if there were no backslash (in 391 this case, "\a" is just "a"). 393 Non-printing characters such as tabs, CR and LF, and control 394 characters are permitted in strings. NUL (ASCII 0) is not allowed in 395 strings. 397 For entering larger amounts of text, such as an email message, a 398 multi-line form is allowed. It starts with the keyword "text:", 399 followed by a CRLF, and ends with the sequence of a CRLF, a single 400 period, and another CRLF. In order to allow the message to begin 401 lines with a single-dot, lines are dot-stuffed. That is, when 402 composing a message body, an extra `.' is added before each line 403 which begins with a `.'. When the server interprets the script, 404 these extra dots are removed. 406 Internet DRAFT Sieve August 7, 1998 408 Note that a comment may occur in between the "text:" and the CRLF, 409 but not within the string itself. 411 2.4.2.1. String lists 413 When matching patterns, strings frequently come in groups. For this 414 reason, a list of strings is allowed in many tests, implying that if 415 the test is true using any one of the strings, then the test is true. 416 Implementations are encouraged to use short-circuit evaluation in 417 these cases. 419 For instance, the test `header ["To", "Cc"] contains 420 ["me@frobnitzm.edu", "me00@landru.melon.edu"]' is true if either the 421 To header or Cc header of the input message contains either of the 422 e-mail addresses "me@frobnitzm.edu" or "me00@landru.melon.edu". 424 Conversely, in any case where a list of strings would be appropriate, 425 a single string is allowed without being a member of a list; it is 426 equivalent to a list with a single member. So the test `exists "To"' 427 is equivalent to the test `exists ["To"]'. 429 2.4.2.2. Headers 431 Headers are a subset of strings. In the Internet Message 432 Specification [IMAIL], each header line is allowed to have whitespace 433 nearly anywhere in the line, including after the field name and 434 before the subsequent colon. Extra spaces between the header name 435 and the ":" in a header field are ignored by the interpreter. 437 A header name never contains a colon. The "From" header refers to a 438 line beginning "From:" (or "From :", etc.). No header will match 439 the string "From:" due to the trailing colon. 441 2.4.2.3. Addresses 443 A number of commands call for email addresses, which are also a 444 subset of strings. These addresses must be compliant with [IMAIL]. 445 Implementations MUST ensure the addresses are syntactically valid, 446 and need not ensure that they are actually deliverable. 448 2.5. Tests 450 Tests are given as arguments to commands in order to control how the 451 run. Generally, a test is used to decide if a block of code should 452 be evaluated. 454 Internet DRAFT Sieve August 7, 1998 456 2.5.1. String Comparison 458 When matching one string against another, there are a number of ways 459 of performing the match. These are accomplished with three matches 460 -- an exact match, a substring match, and a wildcard glob-style 461 match. In order to provide for matches between character sets and 462 case insensitivity, Sieve borrows ACAP's comparator registry. 464 2.6.1. Match Keyword 466 There are two allowed match keywords describing the allowed match in 467 this draft; they are ":is" and ":contains". Match keywords are 468 supplied to those commands which allow them to specify whether the 469 match is to be a complete match or not. 471 These are used as tagged arguments to tests that perform string 472 comparison. Exactly one of them is necessary for a command. 474 The ":contains" version describes a substring match. If the value 475 argument contains the key argument as a substring, the match is true. 476 For instance, the string "frobnitzm" contains "frob" and "nit", but 477 not "fbm". The null key ("") is contained in all values. 479 The ":is" version describes an absolute match; if the contents of the 480 first string are absolutely the same as the contents of the second 481 string, they match. Only the string "frobnitzm" is the string 482 "frobnitzm". The null key only "is" the null value. 484 In order to specify what type of match is supposed to happen, 485 commands that support matching take optional tagged arguments ":is" 486 and ":contains". Commands default to using ":is" matching. Note 487 that these modifiers may interact with comparators; in particular, 488 some comparators are not suitable for matching with ":contains". It 489 is an error to use a comparator with ":contains" that is not 490 compatible with it. 492 2.6.2. Comparators 494 In order to allow for character set-independent matches, the match 495 keyword may be coupled with a comparator name. Comparators are 496 described for [ACAP]; a registry is defined for ACAP, and this 497 specification uses that registry. 499 ACAP defines multiple comparator types. Only equality types are used 500 in this specification. 502 Internet DRAFT Sieve August 7, 1998 504 All implementations MUST support the "i;octet" comparator, which 505 simply compares one octet with the next. If left unspecified, the 506 default is octet. 508 Some comparators may not be usable with substring matches; that is, 509 they may only work with ":is". It is an error to try and use a 510 comparator with "matches" or "contains" that is not compatible with 511 it. 513 A comparator is specified with commands that support matching by the 514 ":comparator" option. This option is followed by a string providing 515 the name of the comparator to be used. So in this example, 517 Example: if header "Subject" :contains :comparator "i;ascii-casemap" 518 "make money fast" { 519 discard; 521 would discard any message with subjects such as "Make Money Fast" and 522 "MaKe MONEY fAST". 524 OPEN: Are there any other comparators that SHOULD or MUST be 525 supported? 527 2.7. Tagged Arguments 529 This document provides for tagged arguments in the style of 530 CommonLISP. 532 A tagged argument is an an argument for a command that begins with 533 ":", and consists of a tag naming the argument, such as ":contains". 534 This argument means that zero or more of the next tokens have some 535 particular meaning, depending on the argument. These next tokens may 536 be numbers or strings, but are never blocks. 538 To keep the language simple, tagged arguments should not take tagged 539 arguments as arguments. 541 One case where this is useful is the ":comparator" argument, which 542 allows the user to specify which ACAP comparator will be used to 543 compare two strings, since different languages may impose different 544 orderings on UTF-8 [UTF-8] characters. 546 Tagged arguments may appear in any order, and may be interspersed 547 with positional arguments. 549 OPEN: Perhaps tagged arguments should always be before positional 550 arguments. 552 Internet DRAFT Sieve August 7, 1998 554 2.8. Blocks 556 Blocks are sets of commands enclosed within curly braces. Blocks are 557 supplied to commands so that the commands can implement control 558 structures. 560 So a control structure is just a command that happens to take a test 561 and a block as its arguments; depending on the result of the control 562 structure, it runs the code in the block zero or more times. (Note 563 that by the commands supplied in the specification, there are no 564 loops, so the control structures supplied--if, elsif, and else--run a 565 block either once or not at all.) 567 2.9. Commands 569 Sieve scripts are made up of commands. Commands can take any of the 570 tokens above as arguments, and arguments may be either tagged or 571 positional arguments. 573 A command begins with a name, which is a simple token. It ends with 574 either a semicolon or a block. (Commands ending with blocks are used 575 to implement control structures.) Commands never take both a 576 semicolon and a block, nor do they ever take more than one block as 577 an argument. 579 2.9.1. Positional Arguments 581 Positional arguments are familiar from any programming language. A 582 command takes zero or more untagged positional arguments in order to 583 specify its behavior. Positional arguments are given their value 584 based on their order in the command. 586 2.9.2. Optional Arguments 588 Optional arguments are tagged arguments that may be omitted; when 589 omitted, they are given default values. 591 2.9.3. Blocks as Arguments 593 Commands may take blocks as arguments. A block is always the last 594 argument to a command, and when it exists, it replaces the semicolon 595 that would otherwise end the command. 597 2.11. Evaluation 599 Precedence is not important in any of the commands in this base 600 specification. However, as an extension might make order of 601 operation important, all arguments to rules MUST be evaluated in 603 Internet DRAFT Sieve August 7, 1998 605 left-to-right order. Those operations that can implement short- 606 circuit evaluation (such as "allof" and "anyof") MUST do so. 608 Sieve imposes specific limits on actions; for instance, a rejected 609 message may not also be filed into a mailbox. These restrictions are 610 noted on a per-command basis. 612 OPEN: Or rather, they should be. 614 2.11.1. Implicit keep 616 If evaluation of a script fails to result in one "fileinto", "keep", 617 or "reject", a "keep" action is implicitly taken. So the message is 618 filed into the user's primary mailbox; that is, 620 For instance, with any of the short messages offered above, the 621 following script produces no actions. 623 Example: if size over 500K discard; 625 3. Conditionals and Control Structures 627 In order for a script to do more than one set of actions, control 628 structures are needed. In Sieve, a control structure is a command 629 that takes a block as an argument. 631 In this document, only the "if" control structure is provided. There 632 are three pieces to if: "if", "elsif", and "else". 634 Syntax: if 636 Syntax: elsif 638 Syntax: else 640 The semantics are similar to any other programming language this 641 appears in. When the interpreter sees an "if", it evaluates the test 642 associated with it. If the test is true, it executes the block 643 associated with it. 645 If the test of the "if" is false, it evaluates the test of the first 647 Internet DRAFT Sieve August 7, 1998 649 "elsif" (if any). If the test of "elsif" is true, it runs the 650 elsif's block. An elsif may be followed by an elsif, in which case, 651 the interpreter repeats this process until it runs out of elsifs. 653 When the interpreter runs out of elsifs, there may be an "else" case. 654 If there is, and none of the if or elsif tests were true, the 655 interpreter runs the else case. 657 This provides a way of performing exactly one of the blocks in the 658 chain. 660 In the following example, both Message A and B are dropped. 662 Example: if header "from" contains "coyote" { 663 discard; 664 } elsif header ["subject"] :contains ["$$$"] { 665 discard; 666 } else fileinto "INBOX"; 668 In the script below, when run over message A, forwards the message to 669 acm@frobnitzm.edu; message B, to postmaster@frobnitzm.edu; any other 670 message is forwarded to field@frobnitzm.edu. 672 Example: if header ["From"] contains ["coyote"] { 673 forward "acm@frobnitzm.edu"; 674 } else if header "Subject" contains "$$$" { 675 forward "postmaster@frobnitzm.edu"; 676 } else 677 forward "field@frobnitzm.edu"; 679 4. Actions 681 This document supplies six actions that may be taken on a message: 682 keep, fileinto, forward, reject, discard, and stop. 684 4.1. Action reject 686 Syntax: reject 688 The "reject" action resends the message to the sender, wrapping it in 689 a "reject" form, noting that it was rejected by the recipient. In 690 the following script, message A is rejected and returned to the 691 sender. 693 Example: if header "from" contains "coyote@znic.net" { 695 Internet DRAFT Sieve August 7, 1998 697 reject "I am not taking mail from you, and I don't want 698 your birdseed, either!"; 699 } 701 A reject message MUST takes the form of a failed DSN as specified by 702 [DSN]. The human-readable portion of the message, the first 703 component of the DSN, contains the human readable message describing 704 the error, although it SHOULD contain additional text alerting the 705 original sender that mail was refused by a filter. This part of the 706 DSN might appear as follows: 708 ------------------------------------------------------------ 709 Message was refused by recipient's mail filtering program. 710 Reason given was as follows: 712 I am not taking mail from you, and I don't want your 713 birdseed, either! 714 ------------------------------------------------------------ 716 The action-value field as defined in the DSN specification MUST be 717 "failed". 719 A rejected message may not be filed, forwarded, or kept. A message 720 that triggers a "reject" action is never allowed to be kept by the 721 user, and the "reject" overrides all other actions. 723 A message may only be rejected once. 725 4.2. Action fileinto 727 Syntax: fileinto 729 The "fileinto" action drops the message into a named folder. 730 Implementations SHOULD support fileinto, but may not be able to in 731 cases where the filtering agent is not able to write to the users' 732 folders (such as a [POP3] implementation running inside the mail 733 server where the folders are stored on the users' local disks). 735 In the following script, message A is filed into folder 736 "INBOX.harassment". 738 Example: if header ["to"] contains "coyote" { 739 fileinto "INBOX.harassment"; 740 } 742 Internet DRAFT Sieve August 7, 1998 744 4.3. Action forward 746 Syntax: forward
748 The "forward" action is used to forward the message to another user 749 at the supplied address, as a mail forwarding feature does. The 750 "forward" action makes no changes to the message body or headers, and 751 only modifies the envelope recipient. 753 A simple script can be used for forwarding: 755 Example: forward "bart@frobnitzm.edu"; 757 The forward command performs an MTA-style forward--that is, what you 758 get from a .forward file using sendmail under UNIX. The address on 759 the SMTP envelope is replaced with the one on the forward command and 760 the message is sent back out. (This is not an MUA-style forward, 761 which creates a new message with a different sender and message ID, 762 wrapping the old message in a new one.) 764 OPEN: At least one person rejects to this definition, claiming that 765 a sendmail-style forward is inherently broken. 767 4.4. Action keep 769 Syntax: keep 771 The "keep" action is whatever action is taken in lieu of all other 772 actions, if no filtering happens at all; generally, this simply means 773 to file the message into the user's main mailbox. This command 774 provides a way to execute this action without needing to know the 775 name of the user's main mailbox, providing a way to call it without 776 needing to understand the user's setup, or the underlying mail 777 system. 779 Example: if size under 1M keep; else discard; 781 4.6. Action stop 783 Syntax: stop 785 The "stop" action ends all processing. If no actions have been 786 executed, then the keep action is taken. 788 Internet DRAFT Sieve August 7, 1998 790 Example: [There needs to be an example here.] 792 4.7. Action discard 794 Syntax: discard 796 Discard drops the message. In the following script, any mail from 797 "idiot@frobnitzm.edu" is thrown out. 799 Example: if header ["from"] contains ["idiot@frobnitzm.edu"] 800 discard; 802 Discard takes no arguments. 804 While an important part of this language, "discard" has the potential 805 to create serious problems for users: A student leaving themselves 806 logged in to a machine in a computer lab may find their script 807 changed to just "discard". In order to protect users in this 808 situation (along with similar situations), implementations MAY keep 809 messages destroyed by a script for an indefinite period, and MAY 810 disallow scripts that throw out all mail. 812 5. Tests 814 Tests are used in conditionals to decide which part(s) of the 815 conditional to execute. 816 5.1. Test allof 818 Syntax: allof ( , , ... ) 820 The allof test preforms a logical AND on the tests supplied to it. 822 Example: allof (false, false) => false 823 allof (false, true) => false 824 allof (true, true) => true 826 The allof test takes as its argument a test-list. 828 Internet DRAFT Sieve August 7, 1998 830 5.2. Test anyof 832 Syntax: anyof ( , , ... ) 834 The anyof test preforms a logical OR on the tests supplied to it. 836 Example: anyof (false, false) => false 837 anyof (false, true) => true 838 anyof (true, true) => true 840 5.3. Test exists 842 Syntax: exists 844 The "exists" test is true if the headers listed in the 845 argument exist within the message. All of the 846 headers must exist or the test is false. 848 The following example throws out mail that doesn't have a From header 849 and a Date header. 851 Example: if not exists ["From","Date"] { 852 discard; 853 } 855 5.4. Test false 857 Syntax: false 859 The "false" test always evaluates to false. 861 5.5. Test header 863 Syntax: header 865 The "header" test evaluates to true if the any header name matches 866 any key. How the match is done is described by the second argument, 867 which is one of the string comparison arguments discussed in section 868 2.6. The first argument to header, the header-name-list, is a list 869 of headers to get values from to be searched. The key-list is a list 870 of keys. 872 Internet DRAFT Sieve August 7, 1998 874 If a header listed in the header-name-list argument exists, it 875 contains the null key (""). However, if the named header is not 876 present, it does not contain the null key. So if a message contained 877 the header 879 X-Caffeine: C8H10N4O2 881 these tests on that header evaluate as follows: 883 header ["X-Y-Z"] is [""] => false 884 header ["X-Y-Z"] contains [""] => true 886 5.6. Test not 888 Syntax: not 890 The "not" test takes some other test as an argument, and yields the 891 opposite result. 893 5.7. Test size 895 Syntax: size <":over" / ":under"> 897 The "size" test deals with the size of a message. It takes either a 898 tagged argument of ":over" or ":under", followed by a number 899 representing the size of the message. 901 If the argument is ":over", and the size of the message is greater 902 than the number provided, the test is true; otherwise, it is false. 904 If the argument is ":under", and the size of the message is less than 905 the number provided, the test is true; otherwise, it is false. 907 The size of a message is defined to be the number of octets from the 908 initial header until the last character in the message body. 910 6. Errors in Processing a Script 912 In any programming language, errors are inevitable. Users are 913 expected to make errors, and even if a script works correctly today, 914 it may fail tomorrow due to quotas, mailboxes being removed or 915 renamed, or some piece of hardware being down. It is imperative that 916 mail get through. 918 Implementations SHOULD check a script before it is run in order to 919 ensure that it is valid. Implementations SHOULD NOT try and recover 921 Internet DRAFT Sieve August 7, 1998 923 from a script with errors, and should instead file mail into the 924 user's primary mailbox. 926 Users MUST be notified of errors in processing a script. The method 927 by which users are notified is implementation defined, but a mail 928 message clearly describing the error is suggested if a preferable 929 alternative cannot be found. 931 In an implementation that allows for a script to be checked when it 932 is turned over to the server, the script can be checked for errors 933 before it is submitted. Implementations SHOULD notify the user of 934 the error and refuse to accept a syntactically invalid script or one 935 that makes use of extensions that the server does not report. 937 Implementations MUST allow mail to be filed without filtering in case 938 of a syntax error in the script. Implementations MUST avoid sending 939 multiple messages describing the same error. 941 Implementations are REQUIRED to notify users of errors in filtering 942 scripts. If there are errors in the script being used, mail SHOULD 943 be filed into the user's main mailbox. Implementations MUST NOT 944 discard mail unless a command explicitly demands it. 946 7. Extensibility 948 New control structures, actions, and tests can be added to the 949 language. Sites must make these features known to their users; this 950 document does not define a way to discover the list of extensions 951 supported by the server. 953 Any extensions to this language MUST define a string that uniquely 954 identifies that extension. If a new version of an extension changes 955 the functionality of a previously defined extension, it MUST use a 956 different name. The purpose of such a string is for the "support" 957 test, which mandates that script requires the use of that extension. 959 Additionally, in a situation where there is a submission protocol and 960 an extension advertisement mechanism aware of the details of this 961 language, scripts submitted can be checked against the mail server to 962 prevent use of an extension that that the server does not support. 964 7.1. Capability String 966 Capability strings are typically short strings describing what 967 capabilities are supported by the server. The following capability 968 strings are defined by this document: 970 fileinto The string "fileinto" indicates the implementation 972 Internet DRAFT Sieve August 7, 1998 974 supports filing into mailboxes. 976 comparator- The string "comparator-elbonia" is provided if the 977 implementation supports the "elbonia" comparator. 978 Therefore, all implementations have at least the 979 "comparator-i;octet" capability. 981 7.2. Registry 983 In order to provide a standard set of extensions, a registry is 984 provided by IANA. Capability names may be registered on a first- 985 come, first-served basis. Extensions designed for interoperable use 986 should be defined as standards track or IESG approved experimental 987 RFCs. 989 To: XXX@XXX.XXX 990 Subject: Registration of new Sieve extension 992 Capability name: 993 Capability keyword: 994 Capability arguments: 995 Standards Track/IESG-approved experimental RFC number: 996 Person and email address to contact for further information: 998 7.3. Capability Transport 1000 As the range of mail systems that this draft is intended to apply to 1001 is quite large, a method of advertising which capabilities an 1002 implementation supports is difficult due to the wide range of 1003 possible implementations. Such a mechanism, however, should have the 1004 following properties. 1006 (1) The implementation can advertise the complete set of extensions 1007 that it supports. 1009 OPEN: There needs to be a more complete description here. 1011 8. Transmission 1013 The MIME type for a SIEVE script is "application/sieve". Scripts are 1014 encoded in UTF-8 during transmission. 1016 Internet DRAFT Sieve August 7, 1998 1018 9. Acknowledgments 1020 I am very thankful to Chris Newman for his support and his ABNF 1021 syntax checker, to John Myers and Steve Hole for outlining the 1022 requirements for the original drafts, and to Rob Earhart for an early 1023 implementation and a great deal of help. I am also indebted to all 1024 of the readers of the ietf-mta-filters@imc.org mailing list. 1026 10. Formal Grammar 1028 The grammar used in this section is the same as the ABNF described in 1029 [ABNF]. 1031 In the case of alternative or optional rules in which a later rule 1032 overlaps an earlier rule, the rule which is listed earlier MUST take 1033 priority. (This shouldn't happen. Please let me know if it does.) 1035 argument = string / string-list / number / tag / test 1037 block = "{" [WSP] commands [WSP] "}" 1038 ;; C-style block 1040 CHAR-NOT-DOT = (%x01-2d / %x2f-%xff) 1041 ;; all the characters that aren't "." 1043 command = identifier WSP *(argument WSP) [WSP] ";" 1045 commands = *([WSP] command [WSP]) 1047 comment = "#" *VCHAR CRLF 1049 identifier = (ALPHA / "_") *(ALPHA DIGIT "_") 1051 multi-line = "text:" [WSP] CRLF 1052 *((1*CHAR-NOT-DOT *CHAR CRLF) / ("." 1*CHAR-NOT-DOT *CHAR CRLF) / 1053 (".." *CHAR CRLF) / CRLF) 1054 "." CRLF 1055 ;; Note when used, 1056 ;; a leading ".." on a line is mapped to ".". 1058 number = 1*DIGIT [QUANTIFIER] 1059 ;; quantifier is a multiplier (or bit shift) 1061 QUANTIFIER = "K" / "M" / "G" 1062 ;; K == 2^10; M == 2^20; G = 2^30 1064 quoted-string = DQUOTE *CHAR DQUOTE 1065 ;; \" inside a string maps to " 1067 Internet DRAFT Sieve August 7, 1998 1069 ;; \\ inside a string maps to \ 1070 ;; All other characters map to themselves. 1071 ;; Note that newlines and other weird characters 1072 ;; are all allowed strings. 1074 string = quoted-string / multi-line 1076 string-list = "[" [WSP] *(string [WSP] "," [WSP]) string [WSP] "]" / string 1077 ;; if there is only a single string, the brackets are optional 1079 tag = ":" identifier 1081 test = identifier *(WSP argument) [WSP test-list] 1083 test-list = [WSP] "(" [WSP] *(test [WSP] "," [WSP]) 1084 test [WSP] ")" [WSP] 1086 WSP = 1*(SP / CRLF / HTAB) / comment 1087 ;; just whitespace. anyplace this is allowed, a comment is 1088 ;; as well 1090 11. Security Considerations 1092 Users must get their mail. It is imperative that whatever method 1093 implementations use to store the user-defined filtering scripts be 1094 secure. 1096 It is equally important that implementations sanity-check the user's 1097 scripts, and not allow users to create on-demand mailbombs. For 1098 instance, an implementation that allows a user to reject or forward 1099 multiple times to a single message might also allow a user to create 1100 a mailbomb triggered by mail from a specific user. 1102 Therefore, an implementation SHOULD only allow one "reject" per 1103 message processed, and MAY limit the number of forward actions taken. 1104 An implementation MUST refuse to forward a message to itself. [OPEN: 1105 What do you do when a site limit prevents you from this? Say I do 1106 three replies; which ones take effect when the limit is 1? 2? 0?] 1108 Several commands, such as "discard", "forward", and "fileinto" allow 1109 for actions to be taken that are potentially very dangerous. 1111 12. Author's Address 1113 Tim Showalter 1114 Carnegie Mellon University 1115 5000 Forbes Avenue 1116 Pittsburgh, PA 15213 1118 Internet DRAFT Sieve August 7, 1998 1120 E-Mail: tjs+@andrew.cmu.edu 1122 Internet DRAFT Sieve August 7, 1998 1124 Appendices 1126 Appendix A. References 1128 [ABNF] Crocker, D., "Augmented BNF for Syntax Specifications: ABNF", 1129 Internet Mail Consortium, RFC 2234, November 1997. 1131 [DSN] Moore, K., and G. Vaudreuil, "An Extensible Message Format for 1132 Delivery Status Notifications", RFC 1894, January 1996. 1134 [FLAMES] Borenstein, Nathaniel S., and Chris A. Thyberg, "Power, Ease 1135 of Use, and Cooperative Work in a Practical Multimedia Message 1136 System", Int. J. of Man-Machine Studies, April, 1991. Reprinted in 1137 Computer-Supported Cooperative Work and Groupware, Saul Greenberg, 1138 editor, Harcourt Brace Jovanovich, 1991. Reprinted in Readings in 1139 Groupware and Computer-Supported Cooperative Work, Ronald Baecker, 1140 editor, Morgan Kaufmann, 1993. 1142 [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate 1143 Requirement Levels", RFC 2119, Harvard University, March 1997. 1145 [IMAP] Crispin, M., "Internet Mail Access Protocol - version 4rev1", 1146 RFC 2060, University of Washington, December 1996. 1148 [IMAIL] Crocker, D., "Standard for the Format of ARPA Internet Text 1149 Messages", STD 11, RFC 822, University of Delaware, August 1982. 1151 [MIME] Freed, N., and N. Borenstein, "Multipurpose Internet Mail 1152 Extensions (MIME) Part One: Format of Internet Message Bodies", RFC 1153 2045, Innosoft and First Virtual, November 1996. 1155 [SMTP] Postel, J., "Simple Mail Transfer Protocol", STD 10, RFC 821, 1156 USC/Information Sciences Institute, August 1982. 1158 [UTF-8] Yergeau, F. "UTF-8, a transformation format of Unicode and 1159 ISO 10646", RFC 2044, Alis Technologies, October 1996. 1161 Appendix B. Full Copyright Statement 1163 Copyright (C) The Internet Society 1998. All Rights Reserved. 1165 This document and translations of it may be copied and furnished to 1166 others, and derivative works that comment on or otherwise explain it 1167 or assist in its implementation may be prepared, copied, published 1168 and distributed, in whole or in part, without restriction of any 1169 kind, provided that the above copyright notice and this paragraph are 1171 Internet DRAFT Sieve August 7, 1998 1173 included on all such copies and derivative works. However, this 1174 document itself may not be modified in any way, such as by removing 1175 the copyright notice or references to the Internet Society or other 1176 Internet organizations, except as needed for the purpose of 1177 developing Internet standards in which case the procedures for 1178 copyrights defined in the Internet Standards process must be 1179 followed, or as required to translate it into languages other than 1180 English. 1182 The limited permissions granted above are perpetual and will not be 1183 revoked by the Internet Society or its successors or assigns. 1185 This document will expire before January 31, 1999.