idnits 2.17.1 draft-ietf-jmap-blob-00.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 : ---------------------------------------------------------------------------- ** There are 29 instances of too long lines in the document, the longest one being 14 characters in excess of 72. -- 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 == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: Servers MUST apply any access controls such that if the authenticated user would be unable to discover the blobId by making queries, then this fact can't be discovered via a Blob/lookup. For example, if an Email exists in a Mailbox which the authenticated user does not have access to see, then that emailId MUST not be returned in a lookup for a blob which is referenced by that email. -- The document date (12 July 2021) is 1017 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 121, but not defined == Missing Reference: 'String' is mentioned on line 246, but not defined == Missing Reference: 'Id' is mentioned on line 256, but not defined == Missing Reference: 'BlobInfo' is mentioned on line 262, but not defined == Unused Reference: 'RFC8621' is defined on line 420, but no explicit reference was found in the text Summary: 1 error (**), 0 flaws (~~), 7 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) 12 July 2021 5 Intended status: Standards Track 6 Expires: 13 January 2022 8 JMAP Blob management extension 9 draft-ietf-jmap-blob-00 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 create and access Blobs, by 18 making inline method calls within a standard JMAP request. 20 This extension also adds a reverse lookup mechanism to discover where 21 blobs are referenced within other datatypes. 23 Status of This Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at https://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on 13 January 2022. 40 Copyright Notice 42 Copyright (c) 2021 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 47 license-info) in effect on the date of publication of this document. 48 Please review these documents carefully, as they describe your rights 49 and restrictions with respect to this document. Code Components 50 extracted from this document must include Simplified BSD License text 51 as described in Section 4.e of the Trust Legal Provisions and are 52 provided without warranty as described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 57 2. Conventions Used In This Document . . . . . . . . . . . . . . 2 58 3. Blobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 59 3.1. Blob/set . . . . . . . . . . . . . . . . . . . . . . . . 3 60 3.1.1. create . . . . . . . . . . . . . . . . . . . . . . . 3 61 3.1.2. update . . . . . . . . . . . . . . . . . . . . . . . 4 62 3.1.3. destroy . . . . . . . . . . . . . . . . . . . . . . . 4 63 3.2. Blob/get . . . . . . . . . . . . . . . . . . . . . . . . 5 64 3.3. Blob/lookup . . . . . . . . . . . . . . . . . . . . . . . 6 65 4. Security considerations . . . . . . . . . . . . . . . . . . . 7 66 5. IANA considerations . . . . . . . . . . . . . . . . . . . . . 8 67 5.1. JMAP Capability registration for "blob" . . . . . . . . . 8 68 5.2. JMAP Error Codes Registration for "unknownDataType" . . . 8 69 5.3. Creation of "JMAP Datatypes" Registry . . . . . . . . . . 8 70 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 9 71 7. Normative References . . . . . . . . . . . . . . . . . . . . 9 72 8. Informative References . . . . . . . . . . . . . . . . . . . 10 73 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 10 75 1. Introduction 77 Sometimes JMAP ([RFC8620]) interactions require creating a Blob and 78 then referencing it. In the same way that IMAP Literals ([RFC7888]) 79 were extended to reduce roundtrips for simple data, embedding simple 80 small blobs into the JMAP method stream can reduce roundtrips. 82 Likewise, when fetching an object, it can be useful to also fetch the 83 raw content of that object without a separate roundtrip. 85 Where JMAP is being proxied through a system which applies additional 86 access restrictions, it can be useful to be able to see where a blob 87 is referenced in order to decide whether to allow it to be 88 downloaded. 90 2. Conventions Used In This Document 92 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 93 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 94 "OPTIONAL" in this document are to be interpreted as described in BCP 95 14 [RFC2119] [RFC8174] when, and only when, they appear in all 96 capitals, as shown here. 98 3. Blobs 100 A blob is a sequence of zero or more octets. 102 The JMAP base spec [RFC8210] defines the "Blob/copy" method, which is 103 unchanged by this specfication. 105 3.1. Blob/set 107 This is a standard JMAP "set" method. 109 3.1.1. create 111 *Properties:* 113 Any one of: 115 * data:asText: String|null 117 * data:asBase64: String|null 119 * data:asHex: String|null 121 * catenate: [SetObject] _list of octet sources in order_ 123 Also: 125 * type: String|null 127 Result is: 129 * id: Id the blobId 131 * type: String|null _as given in the creation (if any); or detected 132 from content; or null_ 134 * size: UnsignedInt _as per RFC8620 - the size of the file in 135 Octets_ 137 Any other properties identical to those that would be returned in the 138 JSON response of the RFC8620 upload endpoint. 140 SetObject: 142 Any one of 144 * data:asText: String|null 145 * data:asBase64: String|null 147 * data:asHex: String|null 149 OR a blobId source: 151 * blobId: Id 153 * offset: UnsignedInt|null 155 * length: UnsignedInt|null 157 3.1.2. update 159 It is not possible to update a Blob, so any update will result in a 160 "notUpdated" response. 162 3.1.3. destroy 164 If an uploaded Blob is not referenced by any persistent object, the 165 server SHOULD destroy the object. Some systems use a content-based 166 ID for blobs, so the server MAY respond "destroyed" and yet that 167 blobId still exist with the same content. 169 Example: 171 Method Call: 173 [ "Blob/set", { 174 "accountId" : "account1", 175 "create" : { 176 "1": { 177 "data:asBase64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABAQMAAAAl21bKA 178 AAAA1BMVEX/AAAZ4gk3AAAAAXRSTlN/gFy0ywAAAApJRE 179 FUeJxjYgAAAAYAAzY3fKgAAAAASUVORK5CYII=", 180 "type" : "image/png" 181 }, 182 }, 183 }, "R1" ] 185 Response: 187 [ "Blob/set", { 188 "accountId" : "account1", 189 "created" : { 190 "1": { 191 "id" : "G4c6751edf9dd6903ff54b792e432fba781271beb", 192 "type" : "image/png", 193 "size" : 95 194 }, 195 }, 196 }, "R1" ] 198 3.2. Blob/get 200 A standard JMAP get. 202 *Properties:* 204 Any of 206 * data:asText 208 * data:asBase64 210 * data:asHex 212 * data _selects data:asText if the content is UTF-8, or 213 data:asBase64_ 215 * size 217 If not given, returns "data" and "size". 219 QUESTION: do we want to add range operators? 221 * offset: UnsignedInt|null 223 * length: UnsignedInt|null 225 Returns that range of octets (not characters!) from the blob. 226 Alternative possible syntax - ranges within the properties, e.g: 227 "data:asText:0:3000" 229 3.3. Blob/lookup 231 Given a list of blobIds, this method does a reverse lookup in each of 232 the provided datatypes to find the list of Ids within that datatype 233 which reference the provided blob. 235 The definition of reference is somewhat loosely defined, but roughly 236 means "you could discover this blobId by looking inside this object", 237 for example if a Mailbox contains an Email which references the 238 blobId, then it references that blobId. Likewise for a Thread. 240 *Parameters* 242 * accountId: "Id" 244 The id of the account used for the call. 246 * datatypes: [String] 248 A list of datatype names from the "JMAP Datatypes" registry for which 249 "Can Reference Blobs" is "Yes". The capability which defines each 250 type must also be requested. 252 If a datatype is not known by the server or the associated capability 253 has not been included then the server returns an "unknownDataType" 254 error. 256 * ids: [Id] 258 A list of blobId values to be looked for. 260 *Response* 262 * list: [BlobInfo] 264 A list of BlobInfo objects. 266 *BlobInfo Object* 267 * id: Id 269 The Blob Identifier. 271 * datatypes: DataType[Id List] 273 A map from datatype to list of Ids of that datatype (e.g. the 274 datatype "Email" maps to a list of emailIds) 276 e.g. 278 [ "Blob/lookup", { 279 "datatypes": ["Mailbox", "Thread", "Email"], 280 "ids": ["Gd2f81008cf07d2425418f7f02a3ca63a8bc82003", 281 "G6f954bcb620f7f50fc8f21426bde3669da3d9067"] 282 }, "R1" ] 284 Response: 286 [ "Blob/lookup", { 287 "list": [ 288 { 289 "id": "Gd2f81008cf07d2425418f7f02a3ca63a8bc82003", 290 "datatypes": { 291 "Mailbox": ["M54e97373", Mcbe6b662"], 292 "Thread": ["T1530616e"], 293 "Email": ["E16e70a73eb4", "E84b0930cf16"] 294 } 295 } 296 ], 297 "notFound": ["G6f954bcb620f7f50fc8f21426bde3669da3d9067"] 298 }, "R1"] 300 4. Security considerations 302 TO BE IMPROVED: 304 JSON parsers are not all consistent in handling non-UTF-8 data. JMAP 305 requires that all JSON data be UTF-8 encoded, so servers MUST either 306 return "data:asBase64" or "isEncodingProblem: true" and modify the 307 data to be UTF-8 safe. 309 Servers MUST apply any access controls such that if the authenticated 310 user would be unable to discover the blobId by making queries, then 311 this fact can't be discovered via a Blob/lookup. For example, if an 312 Email exists in a Mailbox which the authenticated user does not have 313 access to see, then that emailId MUST not be returned in a lookup for 314 a blob which is referenced by that email. 316 If a blob is not visible to a user at all, then the server SHOULD 317 return that blobId in the notFound array, however it may also return 318 an empty list for each datatype, as it may not be able to know if 319 other datatypes do reference that blob. 321 5. IANA considerations 323 5.1. JMAP Capability registration for "blob" 325 IANA is requested to register the "blob" JMAP Capability as follows: 327 Capability Name: urn:ietf:params:jmap:blob 329 Specification document: this document 331 Intended use: common 333 Change Controller: IETF 335 Security and privacy considerations: this document, Section XXX 337 5.2. JMAP Error Codes Registration for "unknownDataType" 339 IANA is requested to register the "unknownDataType" JMAP Error Code 340 as follows: 342 JMAP Error Code: unknownDataType 344 Intended use: common 346 Change Controller: IETF 348 Reference: this document 350 Description: The server does not recognise this data type, or the 351 capability to enable it was not present. 353 5.3. Creation of "JMAP Datatypes" Registry 355 IANA is requested to create a new registry "JMAP Datatypes" with the 356 initial content: 358 +================+=========+======+=====================================+=========+ 359 |Datatype name |Can |Can |Capability |Reference| 360 | |Reference|use | | | 361 | |Blobs |for | | | 362 | | |State | | | 363 | | |Change| | | 364 +================+=========+======+=====================================+=========+ 365 |Core |No |No |urn:ietf:params:jmap:core |[RFC8620]| 366 +----------------+---------+------+-------------------------------------+---------+ 367 |PushSubscription|No |No |urn:ietf:params:jmap:core |[RFC8620]| 368 +----------------+---------+------+-------------------------------------+---------+ 369 |Mailbox |Yes |Yes |urn:ietf:params:jmap:mail |[RFC8621]| 370 +----------------+---------+------+-------------------------------------+---------+ 371 |Thread |Yes |Yes |urn:ietf:params:jmap:mail |[RFC8621]| 372 +----------------+---------+------+-------------------------------------+---------+ 373 |Email |Yes |Yes |urn:ietf:params:jmap:mail |[RFC8621]| 374 +----------------+---------+------+-------------------------------------+---------+ 375 |EmailDelivery |No |Yes |urn:ietf:params:jmap:mail |[RFC8621]| 376 +----------------+---------+------+-------------------------------------+---------+ 377 |SearchSnippet |No |No |urn:ietf:params:jmap:mail |[RFC8621]| 378 +----------------+---------+------+-------------------------------------+---------+ 379 |Identity |No |Yes |urn:ietf:params:jmap:submission |[RFC8621]| 380 +----------------+---------+------+-------------------------------------+---------+ 381 |EmailSubmission |No |Yes |urn:ietf:params:jmap:submission |[RFC8621]| 382 +----------------+---------+------+-------------------------------------+---------+ 383 |VacationResponse|No |Yes |urn:ietf:params:jmap:vacationresponse|[RFC8621]| 384 +----------------+---------+------+-------------------------------------+---------+ 385 |MDN |No |No |urn:ietf:params:jmap:mdn |[RFC9007]| 386 +----------------+---------+------+-------------------------------------+---------+ 388 Table 1 390 6. Acknowledgements 392 TBD 394 7. Normative References 396 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 397 Requirement Levels", BCP 14, RFC 2119, 398 DOI 10.17487/RFC2119, March 1997, 399 . 401 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 402 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 403 May 2017, . 405 [RFC8210] Bush, R. and R. Austein, "The Resource Public Key 406 Infrastructure (RPKI) to Router Protocol, Version 1", 407 RFC 8210, DOI 10.17487/RFC8210, September 2017, 408 . 410 8. Informative References 412 [RFC7888] Melnikov, A., Ed., "IMAP4 Non-synchronizing Literals", 413 RFC 7888, DOI 10.17487/RFC7888, May 2016, 414 . 416 [RFC8620] Jenkins, N. and C. Newman, "The JSON Meta Application 417 Protocol (JMAP)", RFC 8620, DOI 10.17487/RFC8620, July 418 2019, . 420 [RFC8621] Jenkins, N. and C. Newman, "The JSON Meta Application 421 Protocol (JMAP) for Mail", RFC 8621, DOI 10.17487/RFC8621, 422 August 2019, . 424 Author's Address 426 Bron Gondwana (editor) 427 Fastmail 428 Level 2, 114 William St 429 Melbourne VIC 3000 430 Australia 432 Email: brong@fastmailteam.com 433 URI: https://www.fastmail.com