summaryrefslogtreecommitdiff
path: root/doc/rfc/rfc5490.txt
blob: 8466a449ddf1680dbbf8383f54112b017fa8dfc5 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
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]
^L
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]
^L
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]
^L
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]
^L
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]
^L
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]
^L
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]
^L
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]
^L