idnits 2.17.1 draft-gondwana-jmap-blob-01.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 : ---------------------------------------------------------------------------- -- The draft header indicates that this document updates RFC8620, but the abstract doesn't seem to directly say this. It does mention RFC8620 though, so this could be OK. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (16 November 2020) is 1251 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) == Missing Reference: 'SetObject' is mentioned on line 115, but not defined Summary: 0 errors (**), 0 flaws (~~), 2 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 JMAP B. Gondwana, Ed. 3 Internet-Draft Fastmail 4 Updates: 8620 (if approved) 16 November 2020 5 Intended status: Standards Track 6 Expires: 20 May 2021 8 JMAP Blob management extension 9 draft-gondwana-jmap-blob-01 11 Abstract 13 The JMAP base protocol (RFC8620) provides the ability to upload and 14 download arbitrary binary data via HTTP PUT and GET on defined 15 endpoint. This binary data is called a "Blob". 17 This extension adds additional ways to handle Blobs, by making inline 18 method calls within a standard JMAP request. 20 Status of This Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at https://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on 20 May 2021. 37 Copyright Notice 39 Copyright (c) 2020 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 44 license-info) in effect on the date of publication of this document. 45 Please review these documents carefully, as they describe your rights 46 and restrictions with respect to this document. Code Components 47 extracted from this document must include Simplified BSD License text 48 as described in Section 4.e of the Trust Legal Provisions and are 49 provided without warranty as described in the Simplified BSD License. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 54 2. Conventions Used In This Document . . . . . . . . . . . . . . 3 55 3. Blobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 56 3.1. Blob/set . . . . . . . . . . . . . . . . . . . . . . . . 3 57 3.1.1. create . . . . . . . . . . . . . . . . . . . . . . . 3 58 3.1.2. update . . . . . . . . . . . . . . . . . . . . . . . 4 59 3.1.3. destroy . . . . . . . . . . . . . . . . . . . . . . . 4 60 3.2. Blob/get . . . . . . . . . . . . . . . . . . . . . . . . 5 61 3.3. Blob/lookup . . . . . . . . . . . . . . . . . . . . . . . 6 62 4. Security considerations . . . . . . . . . . . . . . . . . . . 6 63 5. IANA considerations . . . . . . . . . . . . . . . . . . . . . 7 64 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 7 65 7. Normative References . . . . . . . . . . . . . . . . . . . . 7 66 8. Informative References . . . . . . . . . . . . . . . . . . . 7 67 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 7 69 1. Introduction 71 Sometimes JMAP ([RFC8620]) interactions require creating a Blob and 72 then referencing it. In the same way that IMAP Literals ([RFC7888]) 73 were extended to reduce roundtrips for simple data, embedding simple 74 small blobs into the JMAP method stream can reduce roundtrips. 76 Likewise, when fetching an object, it can be useful to also fetch the 77 raw content of that object without a separate roundtrip. 79 Where JMAP is being proxied through a system which is providing 80 additional access restrictions, it can be useful to be able to see 81 where a blob is referenced in order to decide whether to allow it to 82 be downloaded. 84 2. Conventions Used In This Document 86 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 87 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 88 "OPTIONAL" in this document are to be interpreted as described in BCP 89 14 [RFC2119] [RFC8174] when, and only when, they appear in all 90 capitals, as shown here. 92 3. Blobs 94 A blob is a sequence of zero or more octets. 96 The JMAP base spec [RFC8210] defines the "Blob/copy" method, which is 97 unchanged by this specfication. 99 3.1. Blob/set 101 This is a standard JMAP "set" method. 103 3.1.1. create 105 *Properties:* 107 Any one of: 109 * data:asText: String|null 111 * data:asBase64: String|null 113 * data:asHex: String|null 115 * catenate: [SetObject] _list of byte sources in order_ 117 Also: 119 * type: String|null 121 Result is: 123 * id: Id the blobId 125 * type: String|null _as given in the creation (if any); or detected 126 from content; or null_ 128 * size: UnsignedInt _as per RFC8620 - the size of the file in 129 Octets_ 131 Any other properties identical to those that would be returned in the 132 JSON response of the RFC8620 upload endpoint. 134 SetObject: 136 Any one of 138 * data:asText: String|null 140 * data:asBase64: String|null 142 * data:asHex: String|null 144 OR a blobId source: 146 * blobId: Id 148 * offset: UnsignedInt|null 150 * length: UnsignedInt|null 152 3.1.2. update 154 It is not possible to update a Blob, so any update will result in a 155 "notUpdated" response. 157 3.1.3. destroy 159 If an uploaded Blob is not referenced by any persistent object, the 160 server SHOULD destroy the object. Some systems use a content-based 161 ID for blobs, so the server MAY respond "destroyed" and yet that 162 blobId still exist with the same content. 164 Example: 166 Method Call: 168 [ "Blob/set", { 169 "accountId" : "account1", 170 "create" : { 171 "1": { 172 "data:asBase64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABAQMAAAAl21bKA 173 AAAA1BMVEX/AAAZ4gk3AAAAAXRSTlN/gFy0ywAAAApJRE 174 FUeJxjYgAAAAYAAzY3fKgAAAAASUVORK5CYII=", 175 "type" : "image/png" 176 }, 177 }, 178 }, "R1" ] 180 Response: 182 [ "Blob/set", { 183 "accountId" : "account1", 184 "created" : { 185 "1": { 186 "id" : "G4c6751edf9dd6903ff54b792e432fba781271beb", 187 "type" : "image/png", 188 "size" : 95 189 }, 190 }, 191 }, "R1" ] 193 3.2. Blob/get 195 A standard JMAP get. 197 *Properties:* 199 Any of 201 * data:asText 203 * data:asBase64 205 * data:asHex 207 * data _selects data:asText if the content is UTF-8, or 208 data:asBase64_ 210 * size 212 If not given, returns "data" and "size". 214 QUESTION: do we want to add range operators? 216 * offset: UnsignedInt|null 218 * length: UnsignedInt|null 220 Returns that range of bytes (not characters!) from the blob 222 3.3. Blob/lookup 224 A reverse lookup! 226 Work to be done here, but something like this. 228 Map from blobId to object type: 230 e.g. 232 [ "Blob/lookup", { 233 "objects": ["Mailbox", "Thread", "Email"], 234 "ids": ["Gd2f81008cf07d2425418f7f02a3ca63a8bc82003", 235 "G6f954bcb620f7f50fc8f21426bde3669da3d9067"] 236 }, "R1" ] 238 Response: 240 [ "Blob/lookup", { 241 "list": [ 242 { 243 "id": "Gd2f81008cf07d2425418f7f02a3ca63a8bc82003", 244 "Mailbox": ["M54e97373", Mcbe6b662"], 245 "Thread": ["T1530616e"], 246 "Email": ["E16e70a73eb4", "E84b0930cf16"] 247 }, 248 ], 249 "notFound": ["G6f954bcb620f7f50fc8f21426bde3669da3d9067"] 250 }, "R1"] 252 This tells which objects of each type "contain" a reference to that 253 blobId. "Contain" is defined somewhat losely here, so for example 254 "the Mailbox contains an Email which references this blobId" is the 255 standard in the response above, likewise for Thread. 257 4. Security considerations 259 TO BE IMPROVED: 261 JSON parsers are not all consistent in handling non-UTF-8 data. JMAP 262 requires that all JSON data be UTF-8 encoded, so servers MUST either 263 return "data:asBase64" or "isEncodingProblem: true" and modify the 264 data to be UTF-8 safe. 266 5. IANA considerations 268 TBD 270 6. Acknowledgements 272 TBD 274 7. Normative References 276 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 277 Requirement Levels", BCP 14, RFC 2119, 278 DOI 10.17487/RFC2119, March 1997, 279 . 281 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 282 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 283 May 2017, . 285 [RFC8210] Bush, R. and R. Austein, "The Resource Public Key 286 Infrastructure (RPKI) to Router Protocol, Version 1", 287 RFC 8210, DOI 10.17487/RFC8210, September 2017, 288 . 290 [RFC8620] Jenkins, N. and C. Newman, "The JSON Meta Application 291 Protocol (JMAP)", RFC 8620, DOI 10.17487/RFC8620, July 292 2019, . 294 8. Informative References 296 [RFC7888] Melnikov, A., Ed., "IMAP4 Non-synchronizing Literals", 297 RFC 7888, DOI 10.17487/RFC7888, May 2016, 298 . 300 Author's Address 302 Bron Gondwana (editor) 303 Fastmail 304 Level 2, 114 William St 305 Melbourne VIC 3000 306 Australia 308 Email: brong@fastmailteam.com 309 URI: https://www.fastmail.com