diff options
Diffstat (limited to 'doc/rfc/rfc5437.txt')
-rw-r--r-- | doc/rfc/rfc5437.txt | 787 |
1 files changed, 787 insertions, 0 deletions
diff --git a/doc/rfc/rfc5437.txt b/doc/rfc/rfc5437.txt new file mode 100644 index 0000000..4699092 --- /dev/null +++ b/doc/rfc/rfc5437.txt @@ -0,0 +1,787 @@ + + + + + + +Network Working Group P. Saint-Andre +Request for Comments: 5437 Cisco +Category: Standards Track A. Melnikov + Isode Limited + January 2009 + + + Sieve Notification Mechanism: + Extensible Messaging and Presence Protocol (XMPP) + +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 (http://trustee.ietf.org/ + license-info) in effect on the date of publication of this document. + Please review these documents carefully, as they describe your rights + and restrictions with respect to this document. + +Abstract + + This document describes a profile of the Sieve extension for + notifications, to allow notifications to be sent over the Extensible + Messaging and Presence Protocol (XMPP), also known as Jabber. + + + + + + + + + + + + + + + + + +Saint-Andre & Melnikov Standards Track [Page 1] + +RFC 5437 Sieve Notify Method: XMPP January 2009 + + +Table of Contents + + 1. Introduction ....................................................3 + 1.1. Overview ...................................................3 + 1.2. Terminology ................................................3 + 2. Definition ......................................................3 + 2.1. Notify Parameter "method" ..................................3 + 2.2. Test notify_method_capability ..............................3 + 2.3. Notify Tag ":from" .........................................4 + 2.4. Notify Tag ":importance" ...................................4 + 2.5. Notify Tag ":message" ......................................4 + 2.6. Notify Tag ":options" ......................................4 + 2.7. XMPP Syntax ................................................4 + 3. Examples ........................................................6 + 3.1. Basic Action ...............................................6 + 3.2. Action with "body" .........................................7 + 3.3. Action with "body", ":importance", ":message", and + "subject" ..................................................7 + 3.4. Action with ":from", ":message", ":importance", + "body", and "subject" ......................................8 + 4. Requirements Conformance ........................................9 + 5. Internationalization Considerations ............................10 + 6. Security Considerations ........................................11 + 7. IANA Considerations ............................................12 + 8. References .....................................................12 + 8.1. Normative References ......................................12 + 8.2. Informative References ....................................13 + + + + + + + + + + + + + + + + + + + + + + + + +Saint-Andre & Melnikov Standards Track [Page 2] + +RFC 5437 Sieve Notify Method: XMPP January 2009 + + +1. Introduction + +1.1. Overview + + The [NOTIFY] extension to the [SIEVE] mail filtering language is a + framework for providing notifications by employing URIs to specify + the notification mechanism. This document defines how xmpp URIs (see + [XMPP-URI]) are used to generate notifications via the Extensible + Messaging and Presence Protocol [XMPP], which is widely implemented + in Jabber instant messaging technologies. + +1.2. Terminology + + This document inherits terminology from [NOTIFY], [SIEVE], and + [XMPP]. In particular, the terms "parameter" and "tag" are used as + described in [NOTIFY] to refer to aspects of Sieve scripts, and the + term "key" is used as described in [XMPP-URI] to refer to aspects of + an XMPP URI. + + The capitalized key words "MUST", "MUST NOT", "REQUIRED", "SHALL", + "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT + RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be + interpreted as described in [TERMS]. + +2. Definition + +2.1. Notify Parameter "method" + + The "method" parameter MUST be a URI that conforms to the xmpp URI + scheme (as specified in [XMPP-URI]) and that identifies an XMPP + account associated with the email inbox. The URI MAY include the + resource identifier of an XMPP address and/or the query component + portion of an XMPP URI, but SHOULD NOT include an authority component + or fragment identifier component. The processing application MUST + extract an XMPP address from the URI in accordance with the + processing rules specified in [XMPP-URI]. The resulting XMPP address + MUST be encapsulated in XMPP syntax as the value of the XMPP 'to' + attribute. + +2.2. Test notify_method_capability + + In response to a notify_method_capability test for the "online" + notification-capability, an implementation SHOULD return a value of + "yes" if it has knowledge of an active presence session (see + [XMPP-IM]) for the specified XMPP notification-uri; otherwise, it + SHOULD return a value of "maybe" (since typical XMPP systems may not + allow a Sieve engine to gain knowledge about the presence of XMPP + entities). + + + +Saint-Andre & Melnikov Standards Track [Page 3] + +RFC 5437 Sieve Notify Method: XMPP January 2009 + + +2.3. Notify Tag ":from" + + If included, the ":from" tag MUST be an electronic address that + conforms to the "Mailbox" rule defined in [RFC5321]. The value of + the ":from" tag MAY be included in the human-readable XML character + data of the XMPP notification; alternatively or in addition, it MAY + be transformed into formal XMPP syntax, in which case it MUST be + encapsulated as the value of an XMPP SHIM (Stanza Headers and + Internet Metadata) [SHIM] header named "Resent-From". + +2.4. Notify Tag ":importance" + + The ":importance" tag has no special meaning for this notification + mechanism, and this specification puts no restriction on its use. + The value of the ":importance" tag MAY be transformed into XMPP + syntax (in addition to or instead of including appropriate text in + the XML character data of the XMPP <body/> element); if so, it SHOULD + be encapsulated as the value of an XMPP SHIM (Stanza Headers and + Internet Metadata) [SHIM] header named "Urgency", where the XML + character of that header is "high" if the value of the ":importance" + tag is "1", "medium" if the value of the ":importance" tag is "2", + and "low" if the value of the ":importance" tag is "3". + +2.5. Notify Tag ":message" + + If the ":message" tag is included, that string MUST be transformed + into the XML character data of an XMPP <body/> element (where the + string is generated according to the guidelines specified in Section + 3.6 of [NOTIFY]). + +2.6. Notify Tag ":options" + + The ":options" tag has no special meaning for this notification + mechanism. Any handling of this tag is the responsibility of an + implementation. + +2.7. XMPP Syntax + + The xmpp mechanism results in the sending of an XMPP message to + notify a recipient about an email message. The general XMPP syntax + is as follows: + + o The notification MUST be an XMPP <message/> stanza. + + + + + + + + +Saint-Andre & Melnikov Standards Track [Page 4] + +RFC 5437 Sieve Notify Method: XMPP January 2009 + + + o The value of the XMPP 'from' attribute SHOULD be the XMPP address + of the notification service associated with the Sieve engine or + the XMPP address of the entity to be notified. The value of the + XMPP 'from' attribute MUST NOT be generated from the Sieve ":from" + tag. + + o The value of the XMPP 'to' attribute MUST be the XMPP address + specified in the XMPP URI contained in the "method" notify + parameter. + + o The value of the XMPP 'type' attribute MUST be 'headline' or + 'normal'. + + o The XMPP <message/> stanza MUST include a <body/> child element. + If the ":message" tag is included in the Sieve script, that string + MUST be used as the XML character data of the <body/> element. If + not and if the XMPP URI contained in the "method" notify parameter + specified a "body" key in the query component, that value SHOULD + be used. Otherwise, the XML character data SHOULD be some + configurable text indicating that the message is a Sieve + notification. + + o The XMPP <message/> stanza MAY include a <subject/> child element. + If the XMPP URI contained in the "method" notify parameter + specified a "subject" key in the query component, that value + SHOULD be used as the XML character data of the <subject/> + element. Otherwise, the XML character data SHOULD be some + configurable text indicating that the message is a Sieve + notification. + + o The XMPP <message/> stanza SHOULD include a URI, for the recipient + to use as a hint in locating the message, encapsulated as the XML + character data of a <url/> child element of an <x/> element + qualified by the 'jabber:x:oob' namespace, as specified in [OOB]. + If included, the URI SHOULD be an Internet Message Access Protocol + [IMAP] URL that specifies the location of the message, as defined + in [IMAP-URL], but MAY be another URI type that can specify or + hint at the location of an email message, such as a URI for an + HTTP resource [HTTP] or a Post Office Protocol Version 3 (POP3) + mailbox [POP-URL] at which the message can be accessed. It is not + expected that an XMPP user agent shall directly handle such a URI, + but instead that it shall invoke an appropriate helper application + to handle the URI. + + o The XMPP <message/> stanza MAY include an XMPP SHIM (Stanza + Headers and Internet Metadata) [SHIM] header named "Resent-From". + If the Sieve script included a ":from" tag, the "Resent-From" + + + + +Saint-Andre & Melnikov Standards Track [Page 5] + +RFC 5437 Sieve Notify Method: XMPP January 2009 + + + value MUST be the value of the ":from" tag; otherwise, the + "Resent-From" value SHOULD be the envelope recipient address of + the original email message that triggered the notification. + +3. Examples + + In the following examples, the sender of the email has an address of + <mailto:juliet@example.org>, the entity to be notified has an email + address of <mailto:romeo@example.com> and an XMPP address of + romeo@im.example.com (resulting in an XMPP URI of + <xmpp:romeo@im.example.com>), and the notification service associated + with the Sieve engine has an XMPP address of notify.example.com. + + Note: In the following examples, line breaks are included in XMPP + URIs solely for the purpose of readability. + +3.1. Basic Action + + The following is a basic Sieve notify action with only a method. The + XML character data of the XMPP <body/> and <subject/> elements are + therefore generated by the Sieve engine based on configuration. In + addition, the Sieve engine includes a URI pointing to the message. + + Basic action (Sieve syntax) + + notify "xmpp:romeo@im.example.com" + + The resulting XMPP <message/> stanza might be as follows: + + Basic action (XMPP syntax) + + <message from='notify.example.com' + to='romeo@im.example.com' + type='headline' + xml:lang='en'> + <subject>SIEVE</subject> + <body><juliet@example.com> You got mail.</body> + <x xmlns='jabber:x:oob'> + <url> + imap://romeo@example.com/INBOX;UIDVALIDITY=385759043/;UID=18 + </url> + </x> + </message> + + + + + + + + +Saint-Andre & Melnikov Standards Track [Page 6] + +RFC 5437 Sieve Notify Method: XMPP January 2009 + + +3.2. Action with "body" + + The following action contains a "body" key in the query component of + the XMPP URI but no ":message" tag in the Sieve script. As a result, + the XML character data of the XMPP <body/> element in the XMPP + notification is taken from the XMPP URI. In addition, the Sieve + engine includes a URI pointing to the message. + + Action with "body" (Sieve syntax) + + notify "xmpp:romeo@im.example.com?message + ;body=Wherefore%20art%20thou%3F" + + The resulting XMPP <message/> stanza might be as follows. + + Action with "body" (XMPP syntax) + + <message from='notify.example.com' + to='romeo@im.example.com' + type='headline' + xml:lang='en'> + <subject>SIEVE</subject> + <body>Wherefore art thou?</body> + <x xmlns='jabber:x:oob'> + <url> + imap://romeo@example.com/INBOX;UIDVALIDITY=385759044/;UID=19 + </url> + </x> + </message> + +3.3. Action with "body", ":importance", ":message", and "subject" + + The following action specifies an ":importance" tag and a ":message" + tag in the Sieve script, as well as a "body" key and a "subject" key + in the query component of the XMPP URI. As a result, the ":message" + tag from the Sieve script overrides the "body" key from the XMPP URI + when generating the XML character data of the XMPP <body/> element. + In addition, the Sieve engine includes a URI pointing to the message. + + Action with "body", ":importance", ":message", and "subject" (Sieve + syntax) + + notify :importance "1" + :message "Contact Juliet immediately!" + "xmpp:romeo@im.example.com?message + ;body=You%27re%20in%20trouble + ;subject=ALERT%21" + + + + +Saint-Andre & Melnikov Standards Track [Page 7] + +RFC 5437 Sieve Notify Method: XMPP January 2009 + + + The resulting XMPP <message/> stanza might be as follows. + + Action with "body", ":importance", ":message", and "subject" (XMPP + syntax) + + <message from='notify.example.com' + to='romeo@im.example.com' + type='headline' + xml:lang='en'> + <subject>ALERT!</subject> + <body>Contact Juliet immediately!</body> + <headers xmlns='http://jabber.org/protocol/shim'> + <header name='Urgency'>high</header> + </headers> + <x xmlns='jabber:x:oob'> + <url> + imap://romeo@example.com/INBOX;UIDVALIDITY=385759045/;UID=20 + </url> + </x> + </message> + +3.4. Action with ":from", ":message", ":importance", "body", and + "subject" + + The following action specifies a ":from" tag, an ":importance" tag, + and a ":message" tag in the Sieve script, as well as a "body" key and + a "subject" key in the query component of the XMPP URI. As a result, + the ":message" tag from the Sieve script overrides the "body" key + from the XMPP URI when generating the XML character data of the XMPP + <body/> element. In addition, the Sieve engine includes a URI + pointing to the message, as well as an XMPP SHIM (Stanza Headers and + Internet Metadata) [SHIM] header named "Resent-From" (which + encapsulates the value of the ":from" tag). + + Action with ":from", ":importance", ":message", "body", and "subject" + (Sieve syntax) + + notify :from "romeo.my.romeo@example.com" + :importance "1" + :message "Contact Juliet immediately!" + "xmpp:romeo@im.example.com?message + ;body=You%27re%20in%20trouble + ;subject=ALERT%21" + + The resulting XMPP <message/> stanza might be as follows. + + + + + + +Saint-Andre & Melnikov Standards Track [Page 8] + +RFC 5437 Sieve Notify Method: XMPP January 2009 + + + Action with ":from", ":importance", ":message", "body", and "subject" + (XMPP syntax) + + <message from='notify.example.com' + to='romeo@im.example.com' + type='headline' + xml:lang='en'> + <subject>ALERT!</subject> + <body>Contact Juliet immediately!</body> + <headers xmlns='http://jabber.org/protocol/shim'> + <header name='Resent-From'>romeo.my.romeo@example.com</header> + <header name='Urgency'>high</header> + </headers> + <x xmlns='jabber:x:oob'> + <url> + imap://romeo@example.com/INBOX;UIDVALIDITY=385759045/;UID=21 + </url> + </x> + </message> + +4. Requirements Conformance + + Section 3.8 of [NOTIFY] specifies a set of requirements for Sieve + notification methods. The conformance of the xmpp notification + mechanism is provided here. + + 1. An implementation of the xmpp notification method SHOULD NOT + modify the final notification text (e.g., to limit the length); + however, a given deployment MAY do so (e.g., if recipients pay + per character or byte for XMPP messages). Modification of + characters themselves should not be necessary, since XMPP + character data is encoded in [UTF-8]. + + 2. An implementation MAY ignore parameters specified in the + ":from", ":importance", and ":options" tags. + + 3. There is no recommended default message for an implementation to + include if the ":message" tag is not specified. + + 4. A notification sent via the xmpp notification method MAY include + a timestamp in the textual message. + + 5. The value of the XMPP 'from' attribute MUST be the XMPP address + of the notification service associated with the Sieve engine. + The value of the Sieve ":from" tag MAY be transformed into the + value of an XMPP SHIM (Stanza Headers and Internet Metadata) + [SHIM] header named "Resent-From". + + + + +Saint-Andre & Melnikov Standards Track [Page 9] + +RFC 5437 Sieve Notify Method: XMPP January 2009 + + + 6. The value of the XMPP 'to' attribute MUST be the XMPP address + specified in the XMPP URI contained in the "method" parameter. + + 7. In accordance with [XMPP-URI], an implementation MUST ignore any + URI action or key it does not understand (i.e., the URI MUST be + processed as if the action or key were not present). It is + RECOMMENDED to support the XMPP "message" query type (see + [QUERIES]) and the associated "body" and "subject" keys, which + SHOULD be mapped to the XMPP <body/> and <subject/> child + elements of the XMPP <message/> stanza, respectively. However, + if included, then the Sieve notify ":message" tag MUST be mapped + to the XMPP <body/> element, overriding the "body" key (if any) + included in the XMPP URI. + + 8. An implementation MUST NOT include any other extraneous + information not specified in parameters to the notify action. + + 9. In response to a notify_method_capability test for the "online" + notification-capability, an implementation SHOULD return a value + of "yes" if it has knowledge of an active presence session (see + [XMPP-IM]) for the specified XMPP notification-uri, but only if + the entity that requested the test is authorized to know the + presence of the associated XMPP entity (e.g., via explicit + presence subscription as specified in [XMPP-IM]); otherwise, it + SHOULD return a value of "maybe" (since typical XMPP systems may + not allow a Sieve engine to gain knowledge about the presence of + XMPP entities). + + 10. An implementation SHOULD NOT attempt to retry delivery of a + notification if it receives an XMPP error of type "auth" or + "cancel", MAY attempt to retry delivery if it receives an XMPP + error of type "wait", and MAY attempt to retry delivery if it + receives an XMPP error of "modify", but only if it makes + appropriate modifications to the notification (see [XMPP]); in + any case, the number of retries SHOULD be limited to a + configurable number no less than 3 and no more than 10. An + implementation MAY throttle notifications if the number of + notifications within a given time period becomes excessive + according to local service policy. Duplicate suppression (if + any) is a matter of implementation and is not specified herein. + +5. Internationalization Considerations + + Although an XMPP address may contain nearly any [UNICODE] character, + the value of the "method" parameter MUST be a Uniform Resource + Identifier (see [URI]) rather than an Internationalized Resource + Identifier (see [IRI]). The rules specified in [XMPP-URI] MUST be + followed when generating XMPP URIs. + + + +Saint-Andre & Melnikov Standards Track [Page 10] + +RFC 5437 Sieve Notify Method: XMPP January 2009 + + + In accordance with Section 13 of RFC 3920, all data sent over XMPP + MUST be encoded in [UTF-8]. + +6. Security Considerations + + Depending on the information included, sending a notification can be + comparable to forwarding mail to the notification recipient. Care + must be taken when forwarding mail automatically, to ensure that + confidential information is not sent into an insecure environment. + In particular, implementations MUST conform to the security + considerations given in [NOTIFY], [SIEVE], and [XMPP]. + + [NOTIFY] specifies that a notification method MUST provide mechanisms + for avoiding notification loops. One type of notification loop can + be caused by message forwarding; however, such loops are prevented + because XMPP does not support the forwarding of messages from one + XMPP address to another. Another type of notification loop can be + caused by auto-replies to XMPP messages received by the XMPP + notification service associated with the Sieve engine; therefore, + such a service MUST NOT auto-reply to XMPP messages it receives. + + A common use case might be for a user to create a script that enables + the Sieve engine to act differently if the user is currently + available at a particular type of service (e.g., send notifications + to the user's XMPP address if the user has an active session at an + XMPP service). Whether the user is currently available can be + determined by means of a notify_method_capability test for the + "online" notification-capability. In XMPP, information about current + network availability is called "presence" (see also [MODEL]). Since + [XMPP-IM] requires that a user must approve a presence subscription + before an entity can gain access to the user's presence information, + a limited but reasonably safe implementation might be for the Sieve + engine to request a subscription to the user's presence. The user + would then need to approve that subscription request so that the + Sieve engine can act appropriately depending on whether the user is + online or offline. However, the Sieve engine MUST NOT use the user's + presence information when processing scripts on behalf of a script + owner other than the user, unless the Sieve engine has explicit + knowledge (e.g., via integration with an XMPP server's presence + authorization rules) that the script owner is authorized to know the + user's presence. While it would be possible to design a more + advanced approach to the delegation of presence authorization, any + such approach is left to future standards work. + + + + + + + + +Saint-Andre & Melnikov Standards Track [Page 11] + +RFC 5437 Sieve Notify Method: XMPP January 2009 + + +7. IANA Considerations + + The following template provides the IANA registration of the Sieve + notification mechanism specified in this document: + + To: iana@iana.org + Subject: Registration of new Sieve notification mechanism + Mechanism name: xmpp + Mechanism URI: RFC 5122 [XMPP-URI] + Mechanism-specific options: none + Permanent and readily available reference: RFC 5437 + Person and email address to contact for further information: + Peter Saint-Andre <registrar@xmpp.org> + + This information has been added to the list of Sieve notification + mechanisms maintained at <http://www.iana.org>. + +8. References + +8.1. Normative References + + [NOTIFY] Melnikov, A., Ed., Leiba, B., Ed., Segmuller, W., and T. + Martin, "Sieve Email Filtering: Extension for + Notifications", RFC 5435, January 2009. + + [OOB] Saint-Andre, P., "Out of Band Data", XSF XEP 0066, + August 2006. + + [QUERIES] Saint-Andre, P., "XMPP URI Scheme Query Components", XSF + XEP 0147, September 2006. + + [RFC5321] Klensin, J., "Simple Mail Transfer Protocol", RFC 5321, + October 2008. + + [SHIM] Saint-Andre, P. and J. Hildebrand, "Stanza Headers and + Internet Metadata", XSF XEP 0131, July 2006. + + [SIEVE] Guenther, P., Ed. and T. Showalter, Ed., "Sieve: An Email + Filtering Language", RFC 5228, January 2008. + + [TERMS] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [XMPP-URI] Saint-Andre, P., "Internationalized Resource Identifiers + (IRIs) and Uniform Resource Identifiers (URIs) for the + Extensible Messaging and Presence Protocol (XMPP)", + RFC 5122, February 2008. + + + + +Saint-Andre & Melnikov Standards Track [Page 12] + +RFC 5437 Sieve Notify Method: XMPP January 2009 + + +8.2. Informative References + + [HTTP] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., + Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext + Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. + + [IMAP] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION + 4rev1", RFC 3501, March 2003. + + [IMAP-URL] Melnikov, A. and C. Newman, "IMAP URL Scheme", RFC 5092, + November 2007. + + [IRI] Duerst, M. and M. Suignard, "Internationalized Resource + Identifiers (IRIs)", RFC 3987, January 2005. + + [MODEL] Day, M., Rosenberg, J., and H. Sugano, "A Model for + Presence and Instant Messaging", RFC 2778, February 2000. + + [POP-URL] Gellens, R., "POP URL Scheme", RFC 2384, August 1998. + + [UNICODE] The Unicode Consortium, "The Unicode Standard, Version + 3.2.0", 2000. + + The Unicode Standard, Version 3.2.0 is defined by The + Unicode Standard, Version 3.0 (Reading, MA, Addison- + Wesley, 2000. ISBN 0-201-61633-5), as amended by the + Unicode Standard Annex #27: Unicode 3.1 + (http://www.unicode.org/reports/tr27/) and by the Unicode + Standard Annex #28: Unicode 3.2 + (http://www.unicode.org/reports/tr28/). + + [URI] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform + Resource Identifier (URI): Generic Syntax", STD 66, + RFC 3986, January 2005. + + [UTF-8] Yergeau, F., "UTF-8, a transformation format of ISO + 10646", STD 63, RFC 3629, November 2003. + + [XMPP] Saint-Andre, P., "Extensible Messaging and Presence + Protocol (XMPP): Core", RFC 3920, October 2004. + + [XMPP-IM] Saint-Andre, P., "Extensible Messaging and Presence + Protocol (XMPP): Instant Messaging and Presence", + RFC 3921, October 2004. + + + + + + + +Saint-Andre & Melnikov Standards Track [Page 13] + +RFC 5437 Sieve Notify Method: XMPP January 2009 + + +Authors' Addresses + + Peter Saint-Andre + Cisco + + EMail: psaintan@cisco.com + + + Alexey Melnikov + Isode Limited + + EMail: Alexey.Melnikov@isode.com + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Saint-Andre & Melnikov Standards Track [Page 14] + |