idnits 2.17.1 draft-ietf-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 : ---------------------------------------------------------------------------- ** 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 (4 October 2021) is 929 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 122, but not defined == Missing Reference: 'String' is mentioned on line 279, but not defined == Missing Reference: 'Id' is mentioned on line 289, but not defined == Missing Reference: 'BlobInfo' is mentioned on line 295, but not defined == Unused Reference: 'RFC8621' is defined on line 486, 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) 4 October 2021 5 Intended status: Standards Track 6 Expires: 7 April 2022 8 JMAP Blob management extension 9 draft-ietf-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 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 7 April 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 . . . . . . . . . . . . . . 3 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 . . . . . . . . . . . . . . . . . . . . . . . 7 65 4. Security considerations . . . . . . . . . . . . . . . . . . . 8 66 5. IANA considerations . . . . . . . . . . . . . . . . . . . . . 9 67 5.1. JMAP Capability registration for "blob" . . . . . . . . . 9 68 5.2. JMAP Error Codes Registration for "unknownDataType" . . . 9 69 5.3. Creation of "JMAP Datatypes" Registry . . . . . . . . . . 9 70 6. Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 71 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 11 72 8. Normative References . . . . . . . . . . . . . . . . . . . . 11 73 9. Informative References . . . . . . . . . . . . . . . . . . . 11 74 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 12 76 1. Introduction 78 Sometimes JMAP ([RFC8620]) interactions require creating a Blob and 79 then referencing it. In the same way that IMAP Literals ([RFC7888]) 80 were extended to reduce roundtrips for simple data, embedding simple 81 small blobs into the JMAP method stream can reduce roundtrips. 83 Likewise, when fetching an object, it can be useful to also fetch the 84 raw content of that object without a separate roundtrip. 86 Where JMAP is being proxied through a system which applies additional 87 access restrictions, it can be useful to be able to see where a blob 88 is referenced in order to decide whether to allow it to be 89 downloaded. 91 2. Conventions Used In This Document 93 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 94 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 95 "OPTIONAL" in this document are to be interpreted as described in BCP 96 14 [RFC2119] [RFC8174] when, and only when, they appear in all 97 capitals, as shown here. 99 3. Blobs 101 A blob is a sequence of zero or more octets. 103 The JMAP base spec [RFC8210] defines the Blob/copy method, which is 104 unchanged by this specfication. 106 3.1. Blob/set 108 This is a standard JMAP set method. 110 3.1.1. create 112 *Properties:* 114 Any one of: 116 * data:asText: String|null 118 * data:asBase64: String|null 120 * data:asHex: String|null 122 * catenate: [SetObject] _list of octet sources in order_ 124 Also: 126 * type: String|null 128 Result is: 130 * id: Id the blobId 132 * type: String|null _as given in the creation (if any); or detected 133 from content; or null_ 135 * size: UnsignedInt _as per RFC8620 - the size of the file in 136 Octets_ 138 Any other properties identical to those that would be returned in the 139 JSON response of the RFC8620 upload endpoint. 141 SetObject: 143 Any one of 145 * data:asText: String|null 147 * data:asBase64: String|null 149 * data:asHex: String|null 151 OR a blobId source: 153 * blobId: Id 155 * offset: UnsignedInt|null 157 * length: UnsignedInt|null 159 3.1.2. update 161 It is not possible to update a Blob, so any update will result in a 162 notUpdated response. 164 3.1.3. destroy 166 If an uploaded Blob is not referenced by any persistent object, the 167 server SHOULD destroy the object. Some systems use a content-based 168 ID for blobs, so the server MAY respond destroyed and yet that blobId 169 still exist with the same content. 171 Example: 173 Method Call: 175 [ "Blob/set", { 176 "accountId" : "account1", 177 "create" : { 178 "1": { 179 "data:asBase64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABAQMAAAAl21bKA 180 AAAA1BMVEX/AAAZ4gk3AAAAAXRSTlN/gFy0ywAAAApJRE 181 FUeJxjYgAAAAYAAzY3fKgAAAAASUVORK5CYII=", 182 "type" : "image/png" 183 }, 184 }, 185 }, "R1" ] 187 Response: 189 [ "Blob/set", { 190 "accountId" : "account1", 191 "created" : { 192 "1": { 193 "id" : "G4c6751edf9dd6903ff54b792e432fba781271beb", 194 "type" : "image/png", 195 "size" : 95 196 }, 197 }, 198 }, "R1" ] 200 3.2. Blob/get 202 A standard JMAP get with two additional parameters: 204 * offset: UnsignedInt|null - start this many octets into the blob 205 data 207 * length: UnsignedInt|null - return at most this many octets of the 208 blob data 210 *Properties:* 212 Any of 214 * data:asText 216 * data:asBase64 218 * data:asHex 219 * data _selects data:asText if the content is UTF-8, or 220 data:asBase64_ 222 * size 224 If not given, returns data and size. 226 The size value is always the number of octets in the blob, regardless 227 of offset and length, while all the data fields contain just the 228 octets within the selected range. If there are no octets within the 229 selected range, the data fields will be the empty string. 231 data:asHex - lowercase hexadecimal (0-9, a-f) 233 Example (a blob containing the string "The quick brown fox jumped 234 over the lazy dog!") 236 Method Call: 238 [ "Blob/get", { 239 "accountId" : "account1", 240 "ids" : [ "G6ec94756e3e046be78fcb33953b85b944e70673e", "not-a-blob" ], 241 "properties" : [ "data:asText", "data:asBase64", 242 "data:asHex", "size" ], 243 "offset" : 4, 244 "length" : 9 245 }, "R1" ] 247 Response: 249 [ "Blob/get", { 250 "accountId" : "account1", 251 "list" : [ 252 { 253 "id" : "G6ec94756e3e046be78fcb33953b85b944e70673e", 254 "data:asText" : "quick bro", 255 "data:asBase64" : "cXVpY2sgYnJvCg==", 256 "data:asHex" : "717569636b2062726f", 257 "size" : 46 258 } 259 ], 260 "notFound" : [ "not-a-blob" ] 261 }, "R1" ] 262 3.3. Blob/lookup 264 Given a list of blobIds, this method does a reverse lookup in each of 265 the provided datatypes to find the list of Ids within that datatype 266 which reference the provided blob. 268 The definition of reference is somewhat loosely defined, but roughly 269 means "you could discover this blobId by looking inside this object", 270 for example if a Mailbox contains an Email which references the 271 blobId, then it references that blobId. Likewise for a Thread. 273 *Parameters* 275 * accountId: "Id" 277 The id of the account used for the call. 279 * types: [String] 281 A list of datatype names from the "JMAP Datatypes" registry for which 282 "Can Reference Blobs" is "Yes". The capability which defines each 283 type must also be requested. 285 If a datatype is not known by the server or the associated capability 286 has not been included then the server returns an "unknownDataType" 287 error. 289 * ids: [Id] 291 A list of blobId values to be looked for. 293 *Response* 295 * list: [BlobInfo] 297 A list of BlobInfo objects. 299 *BlobInfo Object* 301 * id: Id 303 The Blob Identifier. 305 * types: DataType[Id List] 307 A map from datatype to list of Ids of that datatype (e.g. the 308 datatype "Email" maps to a list of emailIds) 309 e.g. 311 [ "Blob/lookup", { 312 "types": ["Mailbox", "Thread", "Email"], 313 "ids": ["Gd2f81008cf07d2425418f7f02a3ca63a8bc82003", 314 "not-a-blob"] 315 }, "R1" ] 317 Response: 319 [ "Blob/lookup", { 320 "list": [ 321 { 322 "id": "Gd2f81008cf07d2425418f7f02a3ca63a8bc82003", 323 "types": { 324 "Mailbox": ["M54e97373", Mcbe6b662"], 325 "Thread": ["T1530616e"], 326 "Email": ["E16e70a73eb4", "E84b0930cf16"] 327 } 328 } 329 ], 330 "notFound": ["not-a-blob"] 331 }, "R1"] 333 4. Security considerations 335 TO BE IMPROVED: 337 JSON parsers are not all consistent in handling non-UTF-8 data. JMAP 338 requires that all JSON data be UTF-8 encoded, so servers MUST either 339 return data:asBase64 or isEncodingProblem: true and modify the data 340 to be UTF-8 safe. 342 Servers MUST apply any access controls such that if the authenticated 343 user would be unable to discover the blobId by making queries, then 344 this fact can't be discovered via a Blob/lookup. For example, if an 345 Email exists in a Mailbox which the authenticated user does not have 346 access to see, then that emailId MUST not be returned in a lookup for 347 a blob which is referenced by that email. 349 If a blob is not visible to a user at all, then the server SHOULD 350 return that blobId in the notFound array, however it may also return 351 an empty list for each datatype, as it may not be able to know if 352 other datatypes do reference that blob. 354 5. IANA considerations 356 5.1. JMAP Capability registration for "blob" 358 IANA is requested to register the "blob" JMAP Capability as follows: 360 Capability Name: urn:ietf:params:jmap:blob 362 Specification document: this document 364 Intended use: common 366 Change Controller: IETF 368 Security and privacy considerations: this document, Section XXX 370 5.2. JMAP Error Codes Registration for "unknownDataType" 372 IANA is requested to register the "unknownDataType" JMAP Error Code 373 as follows: 375 JMAP Error Code: unknownDataType 377 Intended use: common 379 Change Controller: IETF 381 Reference: this document 383 Description: The server does not recognise this data type, or the 384 capability to enable it was not present. 386 5.3. Creation of "JMAP Datatypes" Registry 388 IANA is requested to create a new registry "JMAP Datatypes" with the 389 initial content: 391 +================+=========+======+=====================================+=========+ 392 |Datatype name |Can |Can |Capability |Reference| 393 | |Reference|use | | | 394 | |Blobs |for | | | 395 | | |State | | | 396 | | |Change| | | 397 +================+=========+======+=====================================+=========+ 398 |Core |No |No |urn:ietf:params:jmap:core |[RFC8620]| 399 +----------------+---------+------+-------------------------------------+---------+ 400 |PushSubscription|No |No |urn:ietf:params:jmap:core |[RFC8620]| 401 +----------------+---------+------+-------------------------------------+---------+ 402 |Mailbox |Yes |Yes |urn:ietf:params:jmap:mail |[RFC8621]| 403 +----------------+---------+------+-------------------------------------+---------+ 404 |Thread |Yes |Yes |urn:ietf:params:jmap:mail |[RFC8621]| 405 +----------------+---------+------+-------------------------------------+---------+ 406 |Email |Yes |Yes |urn:ietf:params:jmap:mail |[RFC8621]| 407 +----------------+---------+------+-------------------------------------+---------+ 408 |EmailDelivery |No |Yes |urn:ietf:params:jmap:mail |[RFC8621]| 409 +----------------+---------+------+-------------------------------------+---------+ 410 |SearchSnippet |No |No |urn:ietf:params:jmap:mail |[RFC8621]| 411 +----------------+---------+------+-------------------------------------+---------+ 412 |Identity |No |Yes |urn:ietf:params:jmap:submission |[RFC8621]| 413 +----------------+---------+------+-------------------------------------+---------+ 414 |EmailSubmission |No |Yes |urn:ietf:params:jmap:submission |[RFC8621]| 415 +----------------+---------+------+-------------------------------------+---------+ 416 |VacationResponse|No |Yes |urn:ietf:params:jmap:vacationresponse|[RFC8621]| 417 +----------------+---------+------+-------------------------------------+---------+ 418 |MDN |No |No |urn:ietf:params:jmap:mdn |[RFC9007]| 419 +----------------+---------+------+-------------------------------------+---------+ 421 Table 1 423 6. Changes 425 EDITOR: please remove this section before publication. 427 The source of this document exists on github at: 428 https://github.com/brong/draft-gondwana-jmap-blob/ 429 (https://github.com/brong/draft-gondwana-jmap-blob/) 431 *draft-ieft-jmap-blob-01*: 433 * renamed 'datatypes' to 'types' to align with PushSubscription from 434 RFC8620. 436 * added example for Blob/get 438 * specified offset and length precisely 439 *draft-ieft-jmap-blob-00*: 441 * initial adoption as an IETF document, otherwise identical to 442 draft-gondwana-jmap-blob-02 444 *draft-gondwana-jmap-blob-02* 446 * renamed 'objects' to 'datatypes' 448 * specified Blob/lookup 450 * added IANA registry for datatypes 452 *draft-gondwana-jmap-blob-01* 454 * added an example 456 *draft-gondwana-jmap-blob-00* 458 * initial proposal 460 7. Acknowledgements 462 TBD 464 8. Normative References 466 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 467 Requirement Levels", BCP 14, RFC 2119, 468 DOI 10.17487/RFC2119, March 1997, 469 . 471 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 472 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 473 May 2017, . 475 [RFC8210] Bush, R. and R. Austein, "The Resource Public Key 476 Infrastructure (RPKI) to Router Protocol, Version 1", 477 RFC 8210, DOI 10.17487/RFC8210, September 2017, 478 . 480 9. Informative References 482 [RFC7888] Melnikov, A., Ed., "IMAP4 Non-synchronizing Literals", 483 RFC 7888, DOI 10.17487/RFC7888, May 2016, 484 . 486 [RFC8621] Jenkins, N. and C. Newman, "The JSON Meta Application 487 Protocol (JMAP) for Mail", RFC 8621, DOI 10.17487/RFC8621, 488 August 2019, . 490 [RFC8620] Jenkins, N. and C. Newman, "The JSON Meta Application 491 Protocol (JMAP)", RFC 8620, DOI 10.17487/RFC8620, July 492 2019, . 494 Author's Address 496 Bron Gondwana (editor) 497 Fastmail 498 Level 2, 114 William St 499 Melbourne VIC 3000 500 Australia 502 Email: brong@fastmailteam.com 503 URI: https://www.fastmail.com