<pre>Network Working Group                                       W. Segmuller
Request for Comments: 5231                                      B. Leiba
Obsoletes: <a href="./rfc3431">3431</a>                          IBM T.J. Watson Research Center
Category: Standards Track                                   January 2008


              <span class="h1">Sieve Email Filtering: Relational Extension</span>

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.

Abstract

   This document describes the RELATIONAL extension to the Sieve mail
   filtering language defined in <a href="./rfc3028">RFC 3028</a>.  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.

   This document obsoletes <a href="./rfc3431">RFC 3431</a>.

Table of Contents

   <a href="#section-1">1</a>.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . . . <a href="#page-2">2</a>
   <a href="#section-2">2</a>.  Conventions Used in This Document . . . . . . . . . . . . . . . <a href="#page-2">2</a>
   <a href="#section-3">3</a>.  Comparators . . . . . . . . . . . . . . . . . . . . . . . . . . <a href="#page-2">2</a>
   <a href="#section-4">4</a>.  Match Types . . . . . . . . . . . . . . . . . . . . . . . . . . <a href="#page-3">3</a>
     <a href="#section-4.1">4.1</a>.  Match Type VALUE  . . . . . . . . . . . . . . . . . . . . . <a href="#page-3">3</a>
     <a href="#section-4.2">4.2</a>.  Match Type COUNT  . . . . . . . . . . . . . . . . . . . . . <a href="#page-3">3</a>
   <a href="#section-5">5</a>.  Interaction with Other Sieve Actions  . . . . . . . . . . . . . <a href="#page-4">4</a>
   <a href="#section-6">6</a>.  Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . <a href="#page-4">4</a>
   <a href="#section-7">7</a>.  Extended Example  . . . . . . . . . . . . . . . . . . . . . . . <a href="#page-6">6</a>
   <a href="#section-8">8</a>.  Changes since <a href="./rfc3431">RFC 3431</a>  . . . . . . . . . . . . . . . . . . . . <a href="#page-6">6</a>
   <a href="#section-9">9</a>.  IANA Considerations . . . . . . . . . . . . . . . . . . . . . . <a href="#page-7">7</a>
   <a href="#section-10">10</a>. Security Considerations . . . . . . . . . . . . . . . . . . . . <a href="#page-7">7</a>
   <a href="#section-11">11</a>. Normative References  . . . . . . . . . . . . . . . . . . . . . <a href="#page-7">7</a>










<span class="grey">Segmuller &amp; Leiba           Standards Track                     [Page 1]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-2" ></span>
<span class="grey"><a href="./rfc5231">RFC 5231</a>              Sieve: Relational Extension           January 2008</span>


<span class="h2"><a class="selflink" id="section-1" href="#section-1">1</a>.  Introduction</span>

   The RELATIONAL extension to the Sieve mail filtering language [<a href="#ref-Sieve" title="&quot;Sieve: An Email Filtering Language&quot;">Sieve</a>]
   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.

   The Sieve script can also determine the number of fields in the
   header, or the number of addresses in a recipient field, for example,
   whether there are more than 5 addresses in the to and cc fields.

   The capability string associated with the extension defined in this
   document is "relational".

<span class="h2"><a class="selflink" id="section-2" href="#section-2">2</a>.  Conventions Used in This Document</span>

   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 <a href="https://www.rfc-editor.org/bcp/bcp14">BCP 14</a>, <a href="./rfc2119">RFC 2119</a>.

   Conventions for notations are as in [<a href="#ref-Sieve" title="&quot;Sieve: An Email Filtering Language&quot;">Sieve</a>] <a href="#section-1.1">section 1.1</a>, including
   the use of [<a href="#ref-Kwds" title="&quot;Key words for use in RFCs to Indicate Requirement Levels&quot;">Kwds</a>] and the use of [<a href="#ref-ABNF" title="&quot;Augmented BNF for Syntax Specifications: ABNF&quot;">ABNF</a>].

<span class="h2"><a class="selflink" id="section-3" href="#section-3">3</a>.  Comparators</span>

   This document does not define any comparators or exempt any
   comparators from the require clause.  Any comparator used must be
   treated as defined in [<a href="#ref-Sieve" title="&quot;Sieve: An Email Filtering Language&quot;">Sieve</a>].

   The "i;ascii-numeric" comparator, as defined in [<a href="./rfc4790" title="&quot;Internet Application Protocol Collation Registry&quot;">RFC4790</a>], 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.









<span class="grey">Segmuller &amp; Leiba           Standards Track                     [Page 2]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-3" ></span>
<span class="grey"><a href="./rfc5231">RFC 5231</a>              Sieve: Relational Extension           January 2008</span>


<span class="h2"><a class="selflink" id="section-4" href="#section-4">4</a>.  Match Types</span>

   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
           ; "gt" means "greater than", the C operator "&gt;".
           ; "ge" means "greater than or equal", the C operator "&gt;=".
           ; "lt" means "less than", the C operator "&lt;".
           ; "le" means "less than or equal", the C operator "&lt;=".
           ; "eq" means "equal to", the C operator "==".
           ; "ne" means "not equal to", the C operator "!=".

<span class="h3"><a class="selflink" id="section-4.1" href="#section-4.1">4.1</a>.  Match Type VALUE</span>

   The VALUE match type does a relational comparison between strings.

   The VALUE match type may be used with any comparator that returns
   sort information.

   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.

<span class="h3"><a class="selflink" id="section-4.2" href="#section-4.2">4.2</a>.  Match Type COUNT</span>

   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, as defined below, 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 addresses (the number of
   "mailbox" elements, as defined in [<a href="./rfc2822" title="&quot;Internet Message Format&quot;">RFC2822</a>]) in the specified fields.
   Group names are ignored, but the contained mailboxes are counted.



<span class="grey">Segmuller &amp; Leiba           Standards Track                     [Page 3]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-4" ></span>
<span class="grey"><a href="./rfc5231">RFC 5231</a>              Sieve: Relational Extension           January 2008</span>


   The Envelope Test counts the number of addresses 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.  Using this test, there is no way a Sieve script can
   determine if the message was actually sent to someone else.  The
   envelope "from" will be 0 if the MAIL FROM is empty, or 1 if MAIL
   FROM is not empty.

   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
   compares 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".

<span class="h2"><a class="selflink" id="section-5" href="#section-5">5</a>.  Interaction with Other Sieve Actions</span>

   This specification adds two match types.  The VALUE match type only
   works with comparators that return sort information.  The COUNT match
   type only makes sense with numeric comparators.

   There is no interaction with any other Sieve operations, nor with any
   known extensions.  In particular, this specification has no effect on
   implicit KEEP, nor on any explicit message actions.

<span class="h2"><a class="selflink" id="section-6" href="#section-6">6</a>.  Example</span>

   Using the message:

      received: ...
      received: ...
      subject: example
      to: foo@example.com, baz@example.com
      cc: qux@example.com

   The test:

      address :count "ge" :comparator "i;ascii-numeric"
                      ["to", "cc"] ["3"]

   would evaluate to true, and the test






<span class="grey">Segmuller &amp; Leiba           Standards Track                     [Page 4]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-5" ></span>
<span class="grey"><a href="./rfc5231">RFC 5231</a>              Sieve: Relational Extension           January 2008</span>


      anyof ( address :count "ge" :comparator "i;ascii-numeric"
                      ["to"] ["3"],
              address :count "ge" :comparator "i;ascii-numeric"
                      ["cc"] ["3"] )

   would evaluate to 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 evaluate to false.  But

      header :count "ge" :comparator "i;ascii-numeric"
                      ["received", "subject"] ["3"]

   would evaluate to true.

   The test:

      header :count "ge" :comparator "i;ascii-numeric"
                      ["to", "cc"] ["3"]

   will always evaluate to false on an <a href="./rfc2822">RFC 2822</a> compliant message
   [<a href="./rfc2822" title="&quot;Internet Message Format&quot;">RFC2822</a>], 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.






















<span class="grey">Segmuller &amp; Leiba           Standards Track                     [Page 5]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-6" ></span>
<span class="grey"><a href="./rfc5231">RFC 5231</a>              Sieve: Relational Extension           January 2008</span>


<span class="h2"><a class="selflink" id="section-7" href="#section-7">7</a>.  Extended Example</span>

      require ["relational", "comparator-i;ascii-numeric", "fileinto"];

      if header :value "lt" :comparator "i;ascii-numeric"
                ["x-priority"] ["3"]
      {
         fileinto "Priority";
      }

      elsif address :count "gt" :comparator "i;ascii-numeric"
                 ["to"] ["5"]
      {
         # everything with more than 5 recipients in the "to" field
         # is considered SPAM
         fileinto "SPAM";
      }

      elsif 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"] )
      {
         fileinto "Only me";
      }

<span class="h2"><a class="selflink" id="section-8" href="#section-8">8</a>.  Changes since <a href="./rfc3431">RFC 3431</a></span>

   Apart from several minor editorial/wording changes, the following
   list describes the notable changes to this specification since <a href="./rfc3431">RFC</a>
   <a href="./rfc3431">3431</a>.

   o  Updated references, including changing the comparator reference
      from the Application Configuration Access Protocol (ACAP) to the
      "Internet Application Protocol Collation Registry" document
      [<a href="./rfc4790" title="&quot;Internet Application Protocol Collation Registry&quot;">RFC4790</a>].

   o  Updated and corrected the examples.





<span class="grey">Segmuller &amp; Leiba           Standards Track                     [Page 6]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-7" ></span>
<span class="grey"><a href="./rfc5231">RFC 5231</a>              Sieve: Relational Extension           January 2008</span>


   o  Added definition comments to ABNF for "gt", "lt", etc.

   o  Clarified what <a href="./rfc2822">RFC 2822</a> elements are counted in the COUNT test.

   o  Removed the requirement to strip white space from header fields
      before comparing; a more general version of this requirement has
      been added to the Sieve base spec.

<span class="h2"><a class="selflink" id="section-9" href="#section-9">9</a>.  IANA Considerations</span>

   The following template specifies the IANA registration of the
   relational Sieve extension specified in this document:

   To: iana@iana.org
   Subject: Registration of new Sieve extension

   Capability name: relational
   Description:     Extends existing conditional tests in Sieve language
                    to allow relational operators
   RFC number:      <a href="./rfc5231">RFC 5231</a>
   Contact address: The Sieve discussion list &lt;ietf-mta-filters@imc.org&gt;

<span class="h2"><a class="selflink" id="section-10" href="#section-10">10</a>.  Security Considerations</span>

   An implementation MUST ensure that the test for envelope "to" only
   reflects the delivery to the current user.  Using this test, it MUST
   not be possible for a user to determine if this message was delivered
   to someone else.

   Additional security considerations are discussed in [<a href="#ref-Sieve" title="&quot;Sieve: An Email Filtering Language&quot;">Sieve</a>].

<span class="h2"><a class="selflink" id="section-11" href="#section-11">11</a>.  Normative References</span>

   [<a id="ref-ABNF">ABNF</a>]     Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
              Specifications: ABNF", <a href="./rfc4234">RFC 4234</a>, October 2005.

   [<a id="ref-Kwds">Kwds</a>]     Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", <a href="./rfc2119">RFC 2119</a>, March 1997.

   [<a id="ref-RFC2822">RFC2822</a>]  Resnick, P., "Internet Message Format", <a href="./rfc2822">RFC 2822</a>,
              April 2001.

   [<a id="ref-RFC4790">RFC4790</a>]  Newman, C., Duerst, M., and A. Gulbrandsen, "Internet
              Application Protocol Collation Registry", <a href="./rfc4790">RFC 4790</a>,
              March 2007.

   [<a id="ref-Sieve">Sieve</a>]    Guenther, P., Ed. and T. Showalter, Ed., "Sieve: An Email
              Filtering Language", <a href="./rfc5228">RFC 5228</a>, January 2008.



<span class="grey">Segmuller &amp; Leiba           Standards Track                     [Page 7]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-8" ></span>
<span class="grey"><a href="./rfc5231">RFC 5231</a>              Sieve: Relational Extension           January 2008</span>


Authors' Addresses

   Wolfgang Segmuller
   IBM T.J. Watson Research Center
   19 Skyline Drive
   Hawthorne, NY  10532
   US

   Phone: +1 914 784 7408
   EMail: werewolf@us.ibm.com


   Barry Leiba
   IBM T.J. Watson Research Center
   19 Skyline Drive
   Hawthorne, NY  10532
   US

   Phone: +1 914 784 7941
   EMail: leiba@watson.ibm.com































<span class="grey">Segmuller &amp; Leiba           Standards Track                     [Page 8]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-9" ></span>
<span class="grey"><a href="./rfc5231">RFC 5231</a>              Sieve: Relational Extension           January 2008</span>


Full Copyright Statement

   Copyright (C) The IETF Trust (2008).

   This document is subject to the rights, licenses and restrictions
   contained in <a href="https://www.rfc-editor.org/bcp/bcp78">BCP 78</a>, and except as set forth therein, the authors
   retain all their rights.

   This document and the information contained herein are provided on an
   "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
   OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
   THE INTERNET ENGINEERING TASK FORCE DISCLAIM 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.

Intellectual Property

   The IETF takes no position regarding the validity or scope of any
   Intellectual Property Rights or other rights that might be claimed to
   pertain to the implementation or use of the technology described in
   this document or the extent to which any license under such rights
   might or might not be available; nor does it represent that it has
   made any independent effort to identify any such rights.  Information
   on the procedures with respect to rights in RFC documents can be
   found in <a href="https://www.rfc-editor.org/bcp/bcp78">BCP 78</a> and <a href="https://www.rfc-editor.org/bcp/bcp79">BCP 79</a>.

   Copies of IPR disclosures made to the IETF Secretariat and any
   assurances of licenses to be made available, or the result of an
   attempt made to obtain a general license or permission for the use of
   such proprietary rights by implementers or users of this
   specification can be obtained from the IETF on-line IPR repository at
   <a href="http://www.ietf.org/ipr">http://www.ietf.org/ipr</a>.

   The IETF invites any interested party to bring to its attention any
   copyrights, patents or patent applications, or other proprietary
   rights that may cover technology that may be required to implement
   this standard.  Please address the information to the IETF at
   ietf-ipr@ietf.org.












Segmuller &amp; Leiba           Standards Track                     [Page 9]
</pre>