summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorSergey Poznyakoff <gray@gnu.org.ua>2003-01-05 16:52:16 +0000
committerSergey Poznyakoff <gray@gnu.org.ua>2003-01-05 16:52:16 +0000
commitc1271bd1a67b4a3806f4b9b3358b0c301f50d717 (patch)
tree2555c4505ee4f0e21eaf84701ab9000218c9573c /doc
parentb81d473b7f1fb755b0560222675d20d525ac3ef2 (diff)
downloadmailutils-c1271bd1a67b4a3806f4b9b3358b0c301f50d717.tar.gz
mailutils-c1271bd1a67b4a3806f4b9b3358b0c301f50d717.tar.bz2
Sieve Extension: Relational Tests
Diffstat (limited to 'doc')
-rw-r--r--doc/rfc/rfc3431.txt452
1 files changed, 452 insertions, 0 deletions
diff --git a/doc/rfc/rfc3431.txt b/doc/rfc/rfc3431.txt
new file mode 100644
index 000000000..a1673f4e7
--- /dev/null
+++ b/doc/rfc/rfc3431.txt
@@ -0,0 +1,452 @@
+
+
+
+
+
+
+Network Working Group W. Segmuller
+Request for Comment: 3431 IBM T.J. Watson Research Center
+Category: Standards Track December 2002
+
+
+ Sieve Extension: Relational Tests
+
+Status of this Memo
+
+ This document specifies an Internet standards track protocol for the
+ Internet community, and requests discussion and suggestions for
+ improvements. Please refer to the current edition of the "Internet
+ Official Protocol Standards" (STD 1) for the standardization state
+ and status of this protocol. Distribution of this memo is unlimited.
+
+Copyright Notice
+
+ Copyright (C) The Internet Society (2002). All Rights Reserved.
+
+Abstract
+
+ This document describes the RELATIONAL extension to the Sieve mail
+ filtering language defined in RFC 3028. This extension extends
+ existing conditional tests in Sieve to allow relational operators.
+ In addition to testing their content, it also allows for testing of
+ the number of entities in header and envelope fields.
+
+1 Introduction
+
+ Sieve [SIEVE] is a language for filtering e-mail messages at the time
+ of final delivery. It is designed to be 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
+ Internet Messages Access Protocol (IMAP) servers, as it has no
+ variables, loops, nor the ability to shell out to external programs.
+
+ The RELATIONAL extension provides relational operators on the
+ address, envelope, and header tests. This extension also provides a
+ way of counting the entities in a message header or address field.
+
+ With this extension, the sieve script may now determine if a field is
+ greater than or less than a value instead of just equivalent. One
+ use is for the x-priority field: move messages with a priority
+ greater than 3 to the "work on later" folder. Mail could also be
+ sorted by the from address. Those userids that start with 'a'-'m' go
+ to one folder, and the rest go to another folder.
+
+
+
+Segmuller Standards Track [Page 1]
+
+RFC 3431 Sieve Extension: Relational Tests December 2002
+
+
+ The sieve script can also determine the number of fields in the
+ header, or the number of addresses in a recipient field. For
+ example: are there more than 5 addresses in the to and cc fields.
+
+2 Conventions used in this document
+
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
+ document are to be interpreted as described in BCP 14, RFC 2119.
+
+ Conventions for notations are as in [SIEVE] section 1.1, including
+ the use of [KEYWORDS] and "Syntax:" label for the definition of
+ action and tagged arguments syntax, and the use of [ABNF].
+
+ The capability string associated with extension defined in this
+ document is "relational".
+
+3 Comparators
+
+ This document does not define any comparators or exempt any
+ comparators from the require clause. Any comparator used, other than
+ "i;octet" and "i;ascii-casemap", MUST be declared a require clause as
+ defined in [SIEVE].
+
+ The "i;ascii-numeric" comparator, as defined in [ACAP], MUST be
+ supported for any implementation of this extension. The comparator
+ "i;ascii-numeric" MUST support at least 32 bit unsigned integers.
+
+ Larger integers MAY be supported. Note: the "i;ascii-numeric"
+ comparator does not support negative numbers.
+
+4 Match Type
+
+ This document defines two new match types. They are the VALUE match
+ type and the COUNT match type.
+
+ The syntax is:
+
+ MATCH-TYPE =/ COUNT / VALUE
+
+ COUNT = ":count" relational-match
+
+ VALUE = ":value" relational-match
+
+ relational-match = DQUOTE ( "gt" / "ge" / "lt"
+ / "le" / "eq" / "ne" ) DQUOTE
+
+
+
+
+
+Segmuller Standards Track [Page 2]
+
+RFC 3431 Sieve Extension: Relational Tests December 2002
+
+
+4.1 Match Type Value
+
+ The VALUE match type does a relational comparison between strings.
+
+ The VALUE match type may be used with any comparator which returns
+ sort information.
+
+ Leading and trailing white space MUST be removed from the value of
+ the message for the comparison. White space is defined as
+
+ SP / HTAB / CRLF
+
+ A value from the message is considered the left side of the relation.
+ A value from the test expression, the key-list for address, envelope,
+ and header tests, is the right side of the relation.
+
+ If there are multiple values on either side or both sides, the test
+ is considered true, if any pair is true.
+
+4.2 Match Type Count
+
+ The COUNT match type first determines the number of the specified
+ entities in the message and does a relational comparison of the
+ number of entities to the values specified in the test expression.
+
+ The COUNT match type SHOULD only be used with numeric comparators.
+
+ The Address Test counts the number of recipients in the specified
+ fields. Group names are ignored.
+
+ The Envelope Test counts the number of recipients in the specified
+ envelope parts. The envelope "to" will always have only one entry,
+ which is the address of the user for whom the sieve script is
+ running. There is no way a sieve script can determine if the message
+ was actually sent to someone else using this test. The envelope
+ "from" will be 0 if the MAIL FROM is blank, or 1 if MAIL FROM is not
+ blank.
+
+ The Header Test counts the total number of instances of the specified
+ fields. This does not count individual addresses in the "to", "cc",
+ and other recipient fields.
+
+ In all cases, if more than one field name is specified, the counts
+ for all specified fields are added together to obtain the number for
+ comparison. Thus, specifying ["to", "cc"] in an address COUNT test,
+ comparing the total number of "to" and "cc" addresses; if separate
+ counts are desired, they must be done in two comparisons, perhaps
+ joined by "allof" or "anyof".
+
+
+
+Segmuller Standards Track [Page 3]
+
+RFC 3431 Sieve Extension: Relational Tests December 2002
+
+
+5 Security Considerations
+
+ Security considerations are discussed in [SIEVE].
+
+ An implementation MUST ensure that the test for envelope "to" only
+ reflects the delivery to the current user. It MUST not be possible
+ for a user to determine if this message was delivered to someone else
+ using this test.
+
+6 Example
+
+ Using the message:
+
+ received: ...
+ received: ...
+ subject: example
+ to: foo@example.com.invalid, baz@example.com.invalid
+ cc: qux@example.com.invalid
+
+ The test:
+
+ address :count "ge" :comparator "i;ascii-numeric" ["to", "cc"]
+ ["3"]
+
+ would be true and the test
+
+ anyof ( address :count "ge" :comparator "i;ascii-numeric"
+ ["to"] ["3"],
+ address :count "ge" :comparator "i;ascii-numeric"
+ ["cc"] ["3"] )
+
+ would be false.
+
+ To check the number of received fields in the header, the
+ following test may be used:
+
+ header :count "ge" :comparator "i;ascii-numeric"
+ ["received"] ["3"]
+
+ This would return false. But
+
+ header :count "ge" :comparator "i;ascii-numeric"
+ ["received", "subject"] ["3"]
+
+ would return true.
+
+
+
+
+
+
+Segmuller Standards Track [Page 4]
+
+RFC 3431 Sieve Extension: Relational Tests December 2002
+
+
+ The test:
+
+ header :count "ge" :comparator "i;ascii-numeric"
+ ["to", "cc"] ["3"]
+
+ will always return false on an RFC 2822 compliant message [RFC2822],
+ since a message can have at most one "to" field and at most one "cc"
+ field. This test counts the number of fields, not the number of
+ addresses.
+
+7 Extended Example
+
+ require ["relational", "comparator-i;ascii-numeric"];
+
+ if header :value "lt" :comparator "i;ascii-numeric"
+ ["x-priority"] ["3"]
+ {
+ fileinto "Priority";
+ }
+
+ elseif address :count "gt" :comparator "i;ascii-numeric"
+ ["to"] ["5"]
+ {
+ # everything with more than 5 recipients in the "to" field
+ # is considered SPAM
+ fileinto "SPAM";
+ }
+
+ elseif address :value "gt" :all :comparator "i;ascii-casemap"
+ ["from"] ["M"]
+ {
+ fileinto "From N-Z";
+ } else {
+ fileinto "From A-M";
+ }
+
+ if allof ( address :count "eq" :comparator "i;ascii-numeric"
+ ["to", "cc"] ["1"] ,
+ address :all :comparator "i;ascii-casemap"
+ ["to", "cc"] ["me@foo.example.com.invalid"]
+ {
+ fileinto "Only me";
+ }
+
+
+
+
+
+
+
+
+Segmuller Standards Track [Page 5]
+
+RFC 3431 Sieve Extension: Relational Tests December 2002
+
+
+8 IANA Considerations
+
+ The following template specifies the IANA registration of the Sieve
+ extension specified in this document:
+
+ To: iana@iana.org
+ Subject: Registration of new Sieve extension
+
+ Capability name: RELATIONAL
+ Capability keyword: relational
+ Capability arguments: N/A
+ Standards Track/IESG-approved experimental RFC number: this RFC
+ Person and email address to contact for further information:
+ Wolfgang Segmuller
+ IBM T.J. Watson Research Center
+ 30 Saw Mill River Rd
+ Hawthorne, NY 10532
+
+ Email: whs@watson.ibm.com
+
+ This information should be added to the list of sieve extensions
+ given on http://www.iana.org/assignments/sieve-extensions.
+
+9 References
+
+9.1 Normative References
+
+ [SIEVE] Showalter, T., "Sieve: A Mail Filtering Language", RFC
+ 3028, January 2001.
+
+ [Keywords] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+ [ABNF] Crocker, D., "Augmented BNF for Syntax Specifications:
+ ABNF", RFC 2234, November 1997.
+
+ [RFC2822] Resnick, P., "Internet Message Format", RFC 2822, April
+ 2001.
+
+9.2 Non-Normative References
+
+ [ACAP] Newman, C. and J. G. Myers, "ACAP -- Application
+ Configuration Access Protocol", RFC 2244, November 1997.
+
+
+
+
+
+
+
+
+Segmuller Standards Track [Page 6]
+
+RFC 3431 Sieve Extension: Relational Tests December 2002
+
+
+10 Author's Address
+
+ Wolfgang Segmuller
+ IBM T.J. Watson Research Center
+ 30 Saw Mill River Rd
+ Hawthorne, NY 10532
+
+ EMail: whs@watson.ibm.com
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Segmuller Standards Track [Page 7]
+
+RFC 3431 Sieve Extension: Relational Tests December 2002
+
+
+11 Full Copyright Statement
+
+ Copyright (C) The Internet Society (2002). 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
+ 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.
+
+ The limited permissions granted above are perpetual and will not be
+ revoked by the Internet Society or its successors or assigns.
+
+ This document and the information contained herein is provided on an
+ "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
+ TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
+ BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
+ HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
+ MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+
+Acknowledgement
+
+ Funding for the RFC Editor function is currently provided by the
+ Internet Society.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Segmuller Standards Track [Page 8]
+
+

Return to:

Send suggestions and report system problems to the System administrator.