summaryrefslogtreecommitdiff
path: root/doc/rfc/rfc5490.txt
diff options
context:
space:
mode:
Diffstat (limited to 'doc/rfc/rfc5490.txt')
-rw-r--r--doc/rfc/rfc5490.txt451
1 files changed, 451 insertions, 0 deletions
diff --git a/doc/rfc/rfc5490.txt b/doc/rfc/rfc5490.txt
new file mode 100644
index 0000000..8466a44
--- /dev/null
+++ b/doc/rfc/rfc5490.txt
@@ -0,0 +1,451 @@
+
+
+
+
+
+
+Network Working Group A. Melnikov
+Request for Comments: 5490 Isode Limited
+Category: Standards Track March 2009
+
+
+ The Sieve Mail-Filtering Language --
+Extensions for Checking Mailbox Status and Accessing Mailbox Metadata
+
+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) 2009 IETF Trust and the persons identified as the
+ document authors. All rights reserved.
+
+ This document is subject to BCP 78 and the IETF Trust's Legal
+ Provisions Relating to IETF Documents in effect on the date of
+ publication of this document (http://trustee.ietf.org/license-info).
+ Please review these documents carefully, as they describe your rights
+ and restrictions with respect to this document.
+
+ This document may contain material from IETF Documents or IETF
+ Contributions published or made publicly available before November
+ 10, 2008. The person(s) controlling the copyright in some of this
+ material may not have granted the IETF Trust the right to allow
+ modifications of such material outside the IETF Standards Process.
+ Without obtaining an adequate license from the person(s) controlling
+ the copyright in such materials, this document may not be modified
+ outside the IETF Standards Process, and derivative works of it may
+ not be created outside the IETF Standards Process, except to format
+ it for publication as an RFC or to translate it into languages other
+ than English.
+
+Abstract
+
+ This memo defines an extension to the Sieve mail filtering language
+ (RFC 5228) for accessing mailbox and server annotations, checking for
+ mailbox existence, and controlling mailbox creation on "fileinto"
+ action.
+
+
+
+
+
+
+Melnikov Standards Track [Page 1]
+
+RFC 5490 Sieve METADATA March 2009
+
+
+Table of Contents
+
+ 1. Introduction ....................................................2
+ 2. Conventions Used in This Document ...............................2
+ 3. "mailbox" and "mboxmetadata" Extensions .........................2
+ 3.1. Test "mailboxexists" .......................................2
+ 3.2. ":create" Argument to "fileinto" Command ...................3
+ 3.3. Test "metadata" ............................................4
+ 3.4. Test "metadataexists" ......................................4
+ 4. "servermetadata" Extension ......................................5
+ 4.1. Test "servermetadata" ......................................5
+ 4.2. Test "servermetadataexists" ................................6
+ 5. Security Considerations .........................................6
+ 6. IANA Considerations .............................................7
+ 7. Acknowledgements ................................................7
+ 8. References ......................................................8
+ 8.1. Normative References .......................................8
+ 8.2. Informative References .....................................8
+
+1. Introduction
+
+ This memo defines an extension to the Sieve mail filtering language
+ [SIEVE] for accessing mailbox and server annotations. This allows
+ for customization of the Sieve engine behaviour based on variables
+ set using [METADATA].
+
+ This document also defines an extension for checking for mailbox
+ existence and for controlling mailbox creation on "fileinto" action.
+
+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 [KEYWORDS].
+
+ Conventions for notations are as in [SIEVE] Section 1.1, including
+ the use of [ABNF].
+
+ This document is written with an assumption that readers are familiar
+ with the data model and terms defined in Section 3 of [METADATA].
+
+3. "mailbox" and "mboxmetadata" Extensions
+
+3.1. Test "mailboxexists"
+
+ Usage: mailboxexists <mailbox-names: string-list>
+
+
+
+
+
+Melnikov Standards Track [Page 2]
+
+RFC 5490 Sieve METADATA March 2009
+
+
+ The "mailboxexists" test is true if all mailboxes listed in the
+ "mailbox-names" argument exist in the mailstore, and each allows the
+ user in whose context the Sieve script runs to "deliver" messages
+ into it. When the mailstore is an IMAP server, "delivery" of
+ messages is possible if:
+
+ a. the READ-WRITE response code is present for the mailbox (see
+ Section 7.1 of [IMAP]), if IMAP Access Control List (ACL)
+ [IMAPACL] is not supported by the server, or
+
+ b. the user has 'p' or 'i' rights for the mailbox (see Section 5.2
+ of [IMAPACL]).
+
+ Note that a successful "mailboxexists" test for a mailbox doesn't
+ necessarily mean that a "fileinto" action on this mailbox would
+ succeed. For example, the "fileinto" action might put user over
+ quota. The "mailboxexists" only verifies existence of the mailbox
+ and whether the user in whose context the Sieve script runs has
+ permissions to execute "fileinto" on it.
+
+ The capability string for use with the require command is "mailbox".
+
+ Example: The following example assumes that the Sieve engine also
+ supports "reject" [REJECT] and "fileinto" [SIEVE]. However, these
+ extensions are not required in order to implement the "mailbox"
+ extension.
+
+ require ["fileinto", "reject", "mailbox"];
+ if mailboxexists "Partners" {
+ fileinto "Partners";
+ } else {
+ reject "This message was not accepted by the Mailstore";
+ }
+
+3.2. ":create" Argument to "fileinto" Command
+
+ Usage: fileinto [:create] <mailbox: string>
+
+ If the optional ":create" argument is specified with "fileinto", it
+ instructs the Sieve interpreter to create the specified mailbox, if
+ needed, before attempting to deliver the message into the specified
+ mailbox. If the mailbox already exists, this argument is ignored.
+ Failure to create the specified mailbox is considered to be an error.
+
+ The capability string for use with the ":create" parameter is
+ "mailbox".
+
+
+
+
+
+Melnikov Standards Track [Page 3]
+
+RFC 5490 Sieve METADATA March 2009
+
+
+3.3. Test "metadata"
+
+ Usage: metadata [MATCH-TYPE] [COMPARATOR]
+ <mailbox: string>
+ <annotation-name: string> <key-list: string-list>
+
+ This test retrieves the value of the mailbox annotation "annotation-
+ name" for the mailbox "mailbox" [METADATA]. The retrieved value is
+ compared to the "key-list". The test returns true if the annotation
+ exists and its value matches any of the keys.
+
+ The default match type is ":is" [SIEVE]. The default comparator is
+ "i;ascii-casemap" [SIEVE].
+
+ The capability string for use with the require command is
+ "mboxmetadata".
+
+ Annotations MUST be accessed with the permissions of the user in
+ whose context the Sieve script runs, and annotations starting with
+ the "/private" prefix MUST be those of the user in whose context the
+ Sieve script runs.
+
+ Example: The following example assumes that the Sieve engine also
+ supports the "vacation" [VACATION] extension. However, this
+ extension is not required in order to implement the "mboxmetadata"
+ extension.
+
+ require ["mboxmetadata", "vacation"];
+
+ if metadata :is "INBOX"
+ "/private/vendor/vendor.isode/auto-replies" "on" {
+
+ vacation text:
+ I'm away on holidays till March 2009.
+ Expect a delay.
+ .
+ }
+
+3.4. Test "metadataexists"
+
+ Usage: metadataexists <mailbox: string> <annotation-names: string-
+ list>
+
+ The "metadataexists" test is true if all of the annotations listed in
+ the "annotation-names" argument exist (i.e., have non-NIL values) for
+ the specified mailbox.
+
+
+
+
+
+Melnikov Standards Track [Page 4]
+
+RFC 5490 Sieve METADATA March 2009
+
+
+ The capability string for use with the require command is
+ "mboxmetadata".
+
+4. "servermetadata" Extension
+
+4.1. Test "servermetadata"
+
+ Usage: servermetadata [MATCH-TYPE] [COMPARATOR]
+ <annotation-name: string> <key-list: string-list>
+
+ This test retrieves the value of the server annotation "annotation-
+ name" [METADATA]. The retrieved value is compared to the "key-list".
+ The test returns true if the annotation exists and its value matches
+ any of the keys.
+
+ The default match type is ":is". The default comparator is "i;ascii-
+ casemap".
+
+ The capability string for use with the require command is
+ "servermetadata".
+
+ Annotations MUST be accessed with the permissions of the user in
+ whose context the Sieve script runs, and annotations starting with
+ the "/private" prefix MUST be those of the user in whose context the
+ Sieve script runs.
+
+ Example: The following example assumes that the Sieve engine also
+ supports "variables" [VARIABLES], "enotify" [NOTIFY], and "envelope"
+ [SIEVE] extensions. However, these extensions are not required in
+ order to implement the "servermetadata" extension.
+
+ require ["enotify", "servermetadata", "variables", "envelope"];
+
+ if servermetadata :matches
+ "/private/vendor/vendor.isode/notification-uri" "*" {
+ set "notif_uri" "${0}";
+ }
+
+ if not string :is "${notif_uri}" "none" {
+ # :matches is used to get the MAIL FROM address
+ if envelope :all :matches "from" "*" {
+ set "env_from" " [really: ${1}]";
+ }
+
+ # :matches is used to get the value of the Subject header
+ if header :matches "Subject" "*" {
+ set "subject" "${1}";
+ }
+
+
+
+Melnikov Standards Track [Page 5]
+
+RFC 5490 Sieve METADATA March 2009
+
+
+ # :matches is used to get the address from the From header
+ if address :matches :all "from" "*" {
+ set "from_addr" "${1}";
+ }
+
+ notify :message "${from_addr}${env_from}: ${subject}"
+ "${notif_uri}";
+ }
+
+4.2. Test "servermetadataexists"
+
+ Usage: servermetadataexists
+ <annotation-names: string-list>
+
+ The "servermetadataexists" test is true if all of the server
+ annotations listed in the "annotation-names" argument exist (i.e.,
+ have non-NIL values).
+
+ The capability string for use with the require command is
+ "servermetadata".
+
+5. Security Considerations
+
+ Extensions defined in this document deliberately don't provide a way
+ to modify annotations.
+
+ A failure to retrieve data due to the server storing the annotations
+ being down or otherwise inaccessible may alter the result of Sieve
+ processing. So implementations SHOULD treat a temporary failure to
+ retrieve annotations in the same manner as a temporary failure to
+ retrieve a Sieve script. For example, if the Sieve script is stored
+ in the Lightweight Directory Access Protocol (LDAP) and the script
+ can't be retrieved when a message is processed, then the agent
+ performing Sieve processing can, for example, assume that the script
+ doesn't exist or delay message delivery until the script can be
+ retrieved successfully. Annotations should be treated as if they are
+ a part of the script itself, so a temporary failure to retrieve them
+ should be handled in the same way as a temporary failure to retrieve
+ the Sieve script itself.
+
+ Protocols/APIs used to retrieve annotations MUST provide at least the
+ same level of confidentiality as protocols/APIs used to retrieve
+ Sieve scripts. For example, if Sieve scripts are retrieved using
+ LDAP secured with Transport Layer Security (TLS) encryption, then the
+ protocol used to retrieve annotations must use a comparable mechanism
+ for providing connection confidentiality. In particular, the
+ protocol used to retrieve annotations must not be lacking encryption.
+
+
+
+
+Melnikov Standards Track [Page 6]
+
+RFC 5490 Sieve METADATA March 2009
+
+
+6. IANA Considerations
+
+ IANA has added the following registrations to the list of Sieve
+ extensions:
+
+ To: iana@iana.org
+ Subject: Registration of new Sieve extension
+ Capability name: mailbox
+ Description: adds test for checking for mailbox existence and a new
+ optional argument to fileinto for creating a mailbox
+ before attempting mail delivery.
+ RFC number: this RFC
+ Contact address:
+ The Sieve discussion list <ietf-mta-filters@imc.org>
+
+ Capability name: mboxmetadata
+ Description: adds tests for checking for mailbox metadata item
+ existence and for retrieving of a mailbox metadata
+ value.
+ RFC number: this RFC
+ Contact address:
+ The Sieve discussion list <ietf-mta-filters@imc.org>
+
+ Capability name: servermetadata
+ Description: adds tests for checking for server metadata item
+ existence and for retrieving of a server metadata
+ value.
+ RFC number: this RFC
+ Contact address:
+ The Sieve discussion list <ietf-mta-filters@imc.org>
+
+7. Acknowledgements
+
+ Thanks to Cyrus Daboo for initial motivation for this document.
+
+ Thanks to Barry Leiba, Randall Gellens, and Aaron Stone for helpful
+ comments on this document.
+
+ The author also thanks the Open Mobile Alliance's Mobile Email
+ working group for providing a set of requirements for mobile devices,
+ guiding some of the extensions in this document.
+
+
+
+
+
+
+
+
+
+
+Melnikov Standards Track [Page 7]
+
+RFC 5490 Sieve METADATA March 2009
+
+
+8. References
+
+8.1. Normative References
+
+ [ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax
+ Specifications: ABNF", STD 68, RFC 5234, January 2008.
+
+ [IMAP] Crispin, M., "Internet Message Access Protocol - Version
+ 4rev1", RFC 3501, March 2003.
+
+ [IMAPACL] Melnikov, A., "IMAP4 Access Control List (ACL)
+ Extension", RFC 4314, December 2005.
+
+ [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+ [METADATA] Daboo, C., "The IMAP METADATA Extension", RFC 5464,
+ February 2009.
+
+ [SIEVE] Guenther, P. and T. Showalter, "Sieve: An Email
+ Filtering Language", RFC 5228, January 2008.
+
+8.2. Informative References
+
+ [NOTIFY] Melnikov, A., Leiba, B., Segmuller, W., and T. Martin,
+ "Sieve Email Filtering: Extension for Notifications",
+ RFC 5435, January 2009.
+
+ [REJECT] Stone, A., "Sieve Email Filtering: Reject and Extended
+ Reject Extensions", RFC 5429, March 2009.
+
+ [VACATION] Showalter, T. and N. Freed, "Sieve Email Filtering:
+ Vacation Extension", RFC 5230, January 2008.
+
+ [VARIABLES] Homme, K., "Sieve Email Filtering: Variables Extension",
+ RFC 5229, January 2008.
+
+Author's Address
+
+ Alexey Melnikov
+ Isode Limited
+ 5 Castle Business Village
+ 36 Station Road
+ Hampton, Middlesex TW12 2BX
+ UK
+
+ EMail: Alexey.Melnikov@isode.com
+
+
+
+
+Melnikov Standards Track [Page 8]
+