idnits 2.17.1 draft-ietf-extra-imap-fetch-preview-08.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 1, 2020) is 1392 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 3501 (Obsoleted by RFC 9051) Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 EXTRA M. Slusarz 3 Internet-Draft Open-Xchange Inc. 4 Intended status: Standards Track July 1, 2020 5 Expires: January 2, 2021 7 IMAP4 Extension: Message Preview Generation 8 draft-ietf-extra-imap-fetch-preview-08 10 Abstract 12 This document specifies an Internet Message Access Protocol (IMAP) 13 protocol extension allowing a client to request a server-generated 14 abbreviated text representation of message data useful as a 15 contextual preview of the entire message. 17 Status of This Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at https://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on January 2, 2021. 34 Copyright Notice 36 Copyright (c) 2020 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (https://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. Code Components extracted from this document must 45 include Simplified BSD License text as described in Section 4.e of 46 the Trust Legal Provisions and are provided without warranty as 47 described in the Simplified BSD License. 49 Table of Contents 51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 52 2. Conventions Used In This Document . . . . . . . . . . . . . . 3 53 3. FETCH Data Item . . . . . . . . . . . . . . . . . . . . . . . 3 54 3.1. Command . . . . . . . . . . . . . . . . . . . . . . . . . 4 55 3.2. Response . . . . . . . . . . . . . . . . . . . . . . . . 4 56 3.3. Preview Text Format . . . . . . . . . . . . . . . . . . . 5 57 4. PREVIEW Priority Modifiers . . . . . . . . . . . . . . . . . 5 58 4.1. LAZY . . . . . . . . . . . . . . . . . . . . . . . . . . 5 59 5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 6 60 6. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 7 61 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 62 8. Security Considerations . . . . . . . . . . . . . . . . . . . 8 63 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 64 9.1. Normative References . . . . . . . . . . . . . . . . . . 8 65 9.2. Informative References . . . . . . . . . . . . . . . . . 9 66 Appendix A. Change History (To be removed by RFC Editor before 67 publication) . . . . . . . . . . . . . . . . . . . . 9 68 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 12 69 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 12 71 1. Introduction 73 Many modern mail clients display small extracts of the body text as 74 an aid to allow a user to quickly decide whether they are interested 75 in viewing the full message contents. Mail clients implementing the 76 Internet Message Access Protocol [RFC3501] would benefit from a 77 standardized, consistent way to generate these brief textual previews 78 of messages. 80 Generation of a preview on the server has several benefits. First, 81 it allows consistent representation of previews across all clients. 82 This standardized display can reduce user confusion when using 83 multiple clients, as abbreviated message representations in clients 84 will show identical message contents. 86 Second, server-side preview generation is more efficient. A client- 87 based algorithm needs to issue, at a minimum, a FETCH BODYSTRUCTURE 88 command in order to determine which MIME [RFC2045] body part(s) 89 should be represented in the preview. Subsequently, at least one 90 FETCH BODY command may be needed to retrieve body data used in 91 preview generation. These FETCH commands cannot be pipelined since 92 the BODYSTRUCTURE query must be parsed on the client before the list 93 of parts to be retrieved via the BODY command(s) can be determined. 95 Additionally, it may be difficult to predict the amount of body data 96 that must be retrieved to adequately represent the part via a 97 preview, therefore requiring inefficient fetching of excessive data 98 in order to account for this uncertainty. For example, a preview 99 algorithm to display data contained in a text/html [RFC2854] part 100 will likely strip the markup tags to obtain textual content. 101 However, without fetching the entire content of the part, there is no 102 way to guarantee that sufficient non-tag content will exist unless 103 either 1) the entire part is retrieved or 2) an additional partial 104 FETCH is executed when the client determines that it does not possess 105 sufficient data from a previous partial FETCH to display an adequate 106 representation of the preview. 108 Finally, server generation allows caching in a centralized location. 109 Using server-generated previews allows global generation once per 110 message, and then cached for the retention period of the source 111 message. Retrieval of message data may be expensive within a server, 112 for example, so a server can be configured to reduce its storage 113 retrieval load by pre-generating preview data. 115 A server indicates support for this extension via the "PREVIEW" 116 capability name. 118 2. Conventions Used In This Document 120 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 121 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 122 "OPTIONAL" in this document are to be interpreted as described in BCP 123 14 [RFC2119] [RFC8174] when, and only when, they appear in all 124 capitals, as shown here. 126 "User" is used to refer to a human user, whereas "client" refers to 127 the software being run by the user. 129 In examples, "C:" and "S:" indicate lines sent by the client and 130 server respectively. If a single "C:" or "S:" label applies to 131 multiple lines, then the line breaks between those lines are for 132 editorial clarity only and are not part of the actual protocol 133 exchange. 135 As with all IMAP extension documents, the case used in writing IMAP 136 protocol elements herein is chosen for editorial clarity, and 137 implementations must pay attention to the numbered rules at the 138 beginning of [RFC3501] Section 9. 140 3. FETCH Data Item 141 3.1. Command 143 To retrieve a preview for a message, the "PREVIEW" FETCH attribute is 144 used when issuing a FETCH command. 146 3.2. Response 148 The server returns a variable-length string that is the generated 149 preview for that message. 151 Example: Retrieving preview information in a SELECTed mailbox 153 C: A1 FETCH 1 (PREVIEW) 154 S: * 1 FETCH (PREVIEW "Preview text!") 155 S: A1 OK FETCH complete. 157 A server SHOULD strive to generate the same string for a given 158 message for each request. However, since previews are understood to 159 be an approximation of the message data and not a canonical view of 160 its contents, a client MUST NOT assume that a message preview is 161 immutable for a given message. This relaxed requirement permits a 162 server to offer previews as an option without requiring potentially 163 burdensome storage and/or processing requirements to guarantee 164 immutability for a use case that does not require this strictness. 165 For example, the underlying IMAP server may change due to a system 166 software upgrade; an account's state information may be retained in 167 the migration but the new server may generate different PREVIEW text 168 than the old server. 170 It is possible that preview text is not available now, but might be 171 available later -- perhaps the server's preview-generating resources 172 are overloaded, there is a server-imposed timeout during preview 173 generation, or there is some transient issue with fetching the 174 message body. In such cases, the server will return NIL as the 175 preview response, and the client can try to retrieve the preview 176 later. 178 On the other hand, it is possible that the server has determined that 179 no meaningful preview text can be generated for a particular message, 180 and that decision won't change later. Examples of this involve 181 encrypted messages, content types the server does not support 182 previews of, and other situations where the server is not able to 183 extract information for a preview. In such cases, the server will 184 return a zero-length string. Clients SHOULD NOT send another FETCH 185 for a preview for such messages. (As discussed previously, preview 186 data is not immutable so there is chance that at some point in the 187 future the server would be able to generate meaningful text. 188 However, this scenario is expected to be rare so a client should not 189 continually send out requests to try to capture this infrequent 190 occurrence. 192 3.3. Preview Text Format 194 The generated preview text MUST be treated as text/plain [RFC2046] 195 media type data by the client. 197 The generated string MUST NOT be content transfer encoded and MUST be 198 encoded in UTF-8 [RFC3629]. The server SHOULD remove any formatting 199 markup and do whatever processing might be useful in rendering the 200 preview as plain text. 202 For purposes of this section, a "preview character" is defined as a 203 single UCS character encoded in UTF-8. Note: a single preview 204 character may compromise multiple octets, so any buffers implemented 205 to conform to the string limitations identified in this document 206 should be sized to prevent possible overflow errors. 208 The server SHOULD limit the length of the preview text to 200 preview 209 characters. This length should provide sufficient data to generally 210 support both various languages (and their different average word 211 lengths) and diverse client display size requirements. 213 The server MUST NOT output preview text longer than 256 preview 214 characters. 216 If the preview is not generated based on the body content of the 217 message, and the LANGUAGE [RFC5255] extension is supported by the 218 server, the preview text SHOULD be generated according to the 219 language rules that apply to human-readable text. For example, a 220 message that consists of a single image MIME part has no human- 221 readable text from which to generate preview information. Instead, 222 the server may wish to output a description that the message contains 223 an image and describe some attributes of the image, such as image 224 format, size, and filename. This descriptive text is not a product 225 of the message body itself but is rather auto-generated data by the 226 server, and should thus use the rules defined for human-generated 227 text described in the LANGUAGE extension (if supported on the 228 server). 230 4. PREVIEW Priority Modifiers 232 4.1. LAZY 234 The LAZY modifier directs the server to return the preview 235 representation only if that data can be returned without undue delay 236 to the client. 238 This modifier allows a client to inform the server that preview data 239 is nice-to-have, but the server SHOULD NOT block the return of other 240 FETCH information at the expense of generating the preview data. 242 For example, a client displaying the initial mailbox listing to a 243 user may want to display preview information associated with messages 244 in that listing. However, this information is secondary to providing 245 the mailbox listing, with message details, and the client is willing 246 to load any unavailable previews in the background and display them 247 as they are provided by the server. In this case, the client would 248 send the LAZY modifier directing the server to only return pre- 249 generated preview data so that retrieval of the other FETCH 250 information is not blocked by possibly expensive preview generation. 252 Generally, the LAZY modifier will only be used once per mailbox load 253 during the initial listing. If preview information is not available 254 during this initial FETCH, the expectation is that a second non-LAZY 255 FETCH will take place after mailbox listing activities are complete. 256 Thus, a maximum of 2 PREVIEW FETCH queries should occur for any 257 message in a selected mailbox. A client SHOULD NOT continually issue 258 LAZY PREVIEW FETCH commands in a selected mailbox as the server is 259 under no requirement to return preview information for this command, 260 which could lead to an unnecessary waste of system and network 261 resources. See Example 2 in the Examples section for how this can be 262 implemented. 264 The LAZY modifier MUST be implemented by any server that supports the 265 PREVIEW extension. 267 5. Examples 269 Example 1: Requesting PREVIEW without LAZY modifier. 271 C: A1 CAPABILITY 272 S: * CAPABILITY IMAP4rev1 PREVIEW 273 S: A1 OK Capability command completed. 274 [...a mailbox is SELECTed...] 275 C: A2 FETCH 1 (RFC822.SIZE PREVIEW) 276 S: * 1 FETCH (RFC822.SIZE 5647 PREVIEW {200} 277 S: Lorem ipsum dolor sit amet, consectetur adipiscing elit. 278 S: Curabitur aliquam turpis et ante dictum, et pulvinar dui congue. 279 S: Maecenas hendrerit, lorem non imperdiet pellentesque, nulla 280 S: ligula nullam 281 S: ) 282 S: A2 OK FETCH complete. 284 Example 2: Requesting PREVIEW with LAZY modifier, to obtain previews 285 during initial mailbox listing if readily available; otherwise, load 286 previews in background. 288 C: D1 FETCH 1:3 (ENVELOPE PREVIEW (LAZY)) 289 S: * 1 FETCH (ENVELOPE ("Wed, 25 Oct 2017 15:03:11 +0000" [...]) 290 PREVIEW "Preview text for message 1.") 291 S: * 2 FETCH (PREVIEW "" ENVELOPE 292 ("Thu, 26 Oct 2017 12:17:23 +0000" [...])) 293 S: * 3 FETCH (ENVELOPE ("Fri, 27 Oct 2017 22:19:21 +0000" [...]) 294 PREVIEW NIL) 295 S: D1 OK FETCH completed. 296 [...Client knows that message 2 has a preview that is empty; 297 therefore, client only needs to request message 3 preview again 298 (e.g. in background)...] 299 C: D2 FETCH 3 (PREVIEW) 300 S: * 3 FETCH (PREVIEW {30} 301 S: Message data from message 3. 302 S: ) 303 S: D2 OK Fetch completed. 305 Example 3: Retrieve preview information for search results within a 306 single mailbox. Use SEARCHRES [RFC5182] extension to save a round- 307 trip. 309 C: E1 CAPABILITY 310 S: * CAPABILITY IMAP4rev1 PREVIEW SEARCHRES 311 S: E1 OK Capability command completed. 312 [...a mailbox is SELECTed...] 313 C: E2 SEARCH RETURN (SAVE) FROM "FOO" 314 C: E3 FETCH $ (UID PREVIEW (LAZY)) 315 S: E2 OK SEARCH completed. 316 S: * 5 FETCH (UID 13 PREVIEW "Preview!") 317 S: * 9 FETCH (UID 23 PREVIEW NIL) 318 S: E3 OK FETCH completed. 319 [...Retrieve message 9 preview in background...] 320 C: E4 UID FETCH 23 (PREVIEW) 321 S: * 9 FETCH (UID 23 PREVIEW "Another preview!") 322 S: E4 OK FETCH completed. 324 6. Formal Syntax 326 The following syntax specification uses the augmented Backus-Naur 327 Form (BNF) as described in ABNF [RFC5234]. It includes definitions 328 from IMAP [RFC3501]. 330 capability =/ "PREVIEW" 332 fetch-att =/ "PREVIEW" [SP "(" preview-mod *(SP 333 preview-mod) ")"] 335 msg-att-dynamic =/ "PREVIEW" SP nstring 337 preview-mod = "LAZY" 339 7. IANA Considerations 341 IMAP4 [RFC3501] capabilities are registered by publishing a standards 342 track or IESG-approved experimental RFC. The registry is currently 343 located at: 345 http://www.iana.org/assignments/imap-capabilities 347 This document requests that IANA adds the "PREVIEW" capability to the 348 IMAP4 [RFC3501] capabilities registry. 350 8. Security Considerations 352 Implementation of this extension might enable denial-of-service 353 attacks against server resources, due to excessive memory or CPU 354 usage during preview generation or increased storage usage if preview 355 results are stored on the server after generation. Servers MAY limit 356 the resources that preview generation uses. In order to mitigate 357 such attacks, servers SHOULD log the client authentication identity 358 on FETCH PREVIEW operations in order to facilitate tracking of 359 abusive clients. 361 Just as the messages they summarize, preview data may contain 362 sensitive information. If generated preview data is stored on the 363 server, e.g. for caching purposes, these previews MUST be protected 364 with equivalent authorization and confidentiality controls as the 365 source message. 367 9. References 369 9.1. Normative References 371 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 372 Extensions (MIME) Part Two: Media Types", RFC 2046, 373 DOI 10.17487/RFC2046, November 1996, 374 . 376 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 377 Requirement Levels", BCP 14, RFC 2119, 378 DOI 10.17487/RFC2119, March 1997, 379 . 381 [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION 382 4rev1", RFC 3501, DOI 10.17487/RFC3501, March 2003, 383 . 385 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 386 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 387 2003, . 389 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 390 Specifications: ABNF", STD 68, RFC 5234, 391 DOI 10.17487/RFC5234, January 2008, 392 . 394 [RFC5255] Newman, C., Gulbrandsen, A., and A. Melnikov, "Internet 395 Message Access Protocol Internationalization", RFC 5255, 396 DOI 10.17487/RFC5255, June 2008, 397 . 399 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 400 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 401 May 2017, . 403 9.2. Informative References 405 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 406 Extensions (MIME) Part One: Format of Internet Message 407 Bodies", RFC 2045, DOI 10.17487/RFC2045, November 1996, 408 . 410 [RFC2854] Connolly, D. and L. Masinter, "The 'text/html' Media 411 Type", RFC 2854, DOI 10.17487/RFC2854, June 2000, 412 . 414 [RFC5182] Melnikov, A., "IMAP Extension for Referencing the Last 415 SEARCH Result", RFC 5182, DOI 10.17487/RFC5182, March 416 2008, . 418 Appendix A. Change History (To be removed by RFC Editor before 419 publication) 421 Changes from draft-slusarz-imap-fetch-snippet-00: 423 o Added standardized language to Section 2 regarding IMAP ABNF 424 conventions 426 o Changed draft name to draft-ietf-extra-imap-fetch-snippet-## 428 Changes from draft-ietf-extra-imap-fetch-snippet-00: 430 o Changed nomenclature from "snippet" to "preview" 432 o Changed draft name to draft-ietf-extra-imap-fetch-preview-## 434 o Update to RFC 8174 boilerplate 436 o Updated length requirements for PREVIEW=FUZZY 438 o Added preview-atom ABNF to limit use of "=" character 440 o UTF-8 is a normative reference 442 o Clarify that characters for purpose of length limitations are 443 defined as UCS characters as encoded by UTF-8 445 o Fix some incorrect literal lengths in examples 447 Changes from draft-ietf-extra-imap-fetch-preview-00: 449 o Updated postal address 451 o Added example to FETCH response section 453 o Added example on how LANGUAGE extension may influence preview 454 generation 456 o Added recommendation that only one LAZY FETCH be executed for a 457 message per mailbox 459 o Added request to create algorithm and modifier registries 461 o Added requirement that algorithm and modifier names conform to RFC 462 6648 464 o Added DoS attack info to security considerations 466 o Distinguish between NIL response and zero-length string 468 o Don't use deprecated "X-" convention in example 470 o Spelling and nits 471 Changes from draft-ietf-extra-imap-fetch-preview-01: 473 o Fix capability ABNF 475 o Removed CAPABILITY string for examples where it did not add 476 valuable context 478 o Altered preview data in examples to cover a variety of potential 479 server return scenarios 481 o Added "SHOULD be registered" language to algorithm names and 482 priority modifiers 484 Changes from draft-ietf-extra-imap-fetch-preview-02: 486 o Move Acknowledgments to un-numbered appendix 488 o Improved abstract text 490 o Consistently use "priority modifiers" instead of "modifiers" 492 o Update example to conform with RFC 3501 UID FETCH requirements 494 Changes from draft-ietf-extra-imap-fetch-preview-03: 496 o Remove preview modifier registry request 498 o Improve instructions for registration of algorithms 500 o Add storage information to security considerations 502 o Clarify parsing of algorithm list in FETCH command 504 o Clarify difference between NIL response and zero-length string 506 o Add normative reference for text/plain 508 o Add warning regarding buffers and multiple octet preview 509 characters 511 o Clarify how to handle preview data return when using an explicit 512 algorithm list 514 o Various editorial fixes 516 Changes from draft-ietf-extra-imap-fetch-preview-04: 518 o Make clear that preview caching is tied to retention period of the 519 source message 521 Changes from draft-ietf-extra-imap-fetch-preview-05: 523 o Clarify "zero-length string" preview data vs. NIL preview data 525 o MIME data -> media type 527 o Capability registration should not include the algorithm name 529 o Give example of how PREVIEW data might change over time 531 Changes from draft-ietf-extra-imap-fetch-preview-06: 533 o Change algorithm names to media types 535 o FUZZY algorithm changed to text/imap-fetch-preview 537 o Remove server broadcast of PREVIEW algorithm extensions from 538 capability 540 o Default, fallback algorithm in absence of client selection now 541 MUST be text/imap-fetch-preview 543 o LAZY modifier should work on default algorithm if no specific 544 algorithm is provided as an argument 546 Changes from draft-ietf-extra-imap-fetch-preview-07: 548 o Remove algorithm selection; PREVIEW always returns text in format 549 defined in Section 3.3 551 Acknowledgments 553 The author would like to thank the following people for their 554 comments and contributions to this document: Stephan Bosch, Bron 555 Gondwana, Teemu Huovila, Neil Jenkins, Steffen Lehmann, Barry Leiba, 556 Alexey Melnikov, Chris Newman, Pete Resnick, Jeff Sipek, Timo 557 Sirainen, Steffen Templin, and Aki Tuomi. 559 Author's Address 560 Michael M. Slusarz 561 Open-Xchange Inc. 562 530 Lytton Avenue 563 Palo Alto, California 94301 564 US 566 Email: michael.slusarz@open-xchange.com