idnits 2.17.1 draft-ietf-jmap-websocket-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 : ---------------------------------------------------------------------------- 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 seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (December 5, 2018) is 1969 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) -- Looks like a reference, but probably isn't: '1' on line 425 == Unused Reference: 'I-D.ietf-jmap-mail' is defined on line 415, but no explicit reference was found in the text == Outdated reference: A later version (-17) exists of draft-ietf-jmap-core-12 ** Obsolete normative reference: RFC 7235 (Obsoleted by RFC 9110) == Outdated reference: A later version (-16) exists of draft-ietf-jmap-mail-12 Summary: 1 error (**), 0 flaws (~~), 5 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 JMAP K. Murchison 3 Internet-Draft FastMail 4 Intended status: Standards Track December 5, 2018 5 Expires: June 8, 2019 7 A JSON Meta Application Protocol (JMAP) Subprotocol for WebSocket 8 draft-ietf-jmap-websocket-00 10 Abstract 12 This document defines a binding for the JSON Meta Application 13 Protocol (JMAP) over a WebSocket transport layer. A WebSocket 14 binding for JMAP provides higher performance than the current HTTP 15 binding for JMAP. 17 Open Issues 19 o What mechanism should be used to allow the client to choose what 20 types of objects for which is wishes to receive push notifications 21 over the WS connection? Shoul this be done via a new method type 22 or can it be done with header fields and/or query parameters on 23 the WS handshake? 25 Status of This Memo 27 This Internet-Draft is submitted in full conformance with the 28 provisions of BCP 78 and BCP 79. 30 Internet-Drafts are working documents of the Internet Engineering 31 Task Force (IETF). Note that other groups may also distribute 32 working documents as Internet-Drafts. The list of current Internet- 33 Drafts is at https://datatracker.ietf.org/drafts/current/. 35 Internet-Drafts are draft documents valid for a maximum of six months 36 and may be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet-Drafts as reference 38 material or to cite them other than as "work in progress." 40 This Internet-Draft will expire on June 8, 2019. 42 Copyright Notice 44 Copyright (c) 2018 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents 49 (https://trustee.ietf.org/license-info) in effect on the date of 50 publication of this document. Please review these documents 51 carefully, as they describe your rights and restrictions with respect 52 to this document. Code Components extracted from this document must 53 include Simplified BSD License text as described in Section 4.e of 54 the Trust Legal Provisions and are provided without warranty as 55 described in the Simplified BSD License. 57 Table of Contents 59 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 60 2. Conventions Used in This Document . . . . . . . . . . . . . . 3 61 3. Discovering Support for JMAP over WebSocket . . . . . . . . . 3 62 4. JMAP Subprotocol . . . . . . . . . . . . . . . . . . . . . . 3 63 4.1. Handshake . . . . . . . . . . . . . . . . . . . . . . . . 3 64 4.2. WebSocket Messages . . . . . . . . . . . . . . . . . . . 4 65 4.3. Examples . . . . . . . . . . . . . . . . . . . . . . . . 5 66 5. Security Considerations . . . . . . . . . . . . . . . . . . . 9 67 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 68 6.1. Registration of the WebSocket JMAP Subprotocol . . . . . 9 69 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 9 70 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 9 71 8.1. Normative References . . . . . . . . . . . . . . . . . . 9 72 8.2. Informative References . . . . . . . . . . . . . . . . . 10 73 8.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 10 74 Appendix A. Change History (To be removed by RFC Editor before 75 publication) . . . . . . . . . . . . . . . . . . . . 10 76 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 11 78 1. Introduction 80 JMAP over HTTP requires that every JMAP API request be authenticated. 81 Depending on the type of authentication used by the JMAP client and 82 the configuration of the JMAP server, authentication could be an 83 expensive operation both in time and resources. In such 84 circumstances, authenticating every JMAP API request may harm 85 performance. 87 The WebSocket binding for JMAP eliminates this performance hit by 88 authenticating just the WebSocket handshake request and having those 89 credentials remain in effect for the duration of the WebSocket 90 connection. 92 Furthermore, the WebSocket binding for JMAP can optionally compress 93 [RFC7692] JMAP API requests. Although compression of HTTP responses 94 is ubiquitous, compression of HTTP requests has very low, if any 95 deployment, and therefore isn't a viable option for JMAP API requests 96 over HTTP. 98 2. Conventions Used in This Document 100 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 101 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 102 "OPTIONAL" in this document are to be interpreted as described in BCP 103 14 [1] [RFC2119] [RFC8174] when, and only when, they appear in all 104 capitals, as shown here. 106 The same terminology is used in this document as in the core JMAP 107 specification. 109 3. Discovering Support for JMAP over WebSocket 111 The capabilities object is returned as part of the standard JMAP 112 Session object (see Section 2 of [I-D.ietf-jmap-core]). Servers 113 supporting this specification MUST add a property called 114 "urn:ietf:params:jmap:websocket" to the capabilities object. The 115 value of this property is an object which MUST contain the following 116 information on server capabilities: 118 wsUrl: "String" The URL to use for JMAP over WebSocket. 120 4. JMAP Subprotocol 122 The term WebSocket subprotocol refers to an application-level 123 protocol layered on top of a WebSocket connection. This document 124 specifies the WebSocket JMAP subprotocol for carrying JMAP API 125 requests, responses, and push notifications through a WebSocket 126 connection. Binary data MUST NOT be uploaded or downloaded through a 127 WebSocket JMAP connection. 129 4.1. Handshake 131 The JMAP WebSocket client and JMAP WebSocket server negotiate the use 132 of the WebSocket JMAP subprotocol during the WebSocket handshake, 133 either via a HTTP/1.1 Upgrade request (see Section 1.3 of [RFC6455]) 134 or a HTTP/2 Extended CONNECT request (see Section 5 of [RFC8441]). 136 Regardless of the method used for the WebSocket handshake, the client 137 MUST make an authenticated [RFC7235] HTTP request on the JMAP 'wsURL' 138 (Section 3), and the client MUST include the value 'jmap' in the list 139 of protocols for the 'Sec-WebSocket-Protocol' header field. The 140 reply from the server MUST also contain 'jmap' in its corresponding 141 'Sec-WebSocket-Protocol' header field in order for a JMAP subprotocol 142 connection to be established. 144 If a client receives a handshake response that does not include 145 'jmap' in the 'Sec-WebSocket-Protocol' header, then a JMAP 146 subprotocol WebSocket connection was not established and the client 147 MUST close the WebSocket connection. 149 Once the handshake has successfully completed, the WebSocket 150 connection is established and can be used for JMAP API requests, 151 responses, and push notifications. Any other message types MUST NOT 152 be transmitted over this connection. 154 The credentials used for authenticating the HTTP request to initiate 155 the handshake remain in effect for the duration of the WebSocket 156 connection. 158 4.2. WebSocket Messages 160 Data frame messages in the JMAP subprotocol MUST be of the text type 161 and contain UTF-8 encoded data. The messages MUST be in the form of 162 a single JMAP Request object (see Section 3.2 of 163 [I-D.ietf-jmap-core]) when sent from the client to the server, and in 164 the form of a single JMAP Response object, JSON Problem Details 165 object, or JMAP StateChange object (see Sections 3.3, 3.5.1, and 7.1 166 respectively of [I-D.ietf-jmap-core]) when sent from the server to 167 the client. 169 4.2.1. JMAP Requests 171 JMAP over WebSocket allows out of order processing of requests, 172 thereby requiring a mechanism for the client to correlate requests 173 and responses. 175 To this end, this specification adds one extra argument to the 176 request object: 178 o *id*: "String" (default: ) A client-specified identifier for the 179 request. 181 Additionally, the "maxConcurrentRequests" field in the "capabilities" 182 object (see Section 2 of [I-D.ietf-jmap-core]) limits the number of 183 inflight requests over the WebSocket. 185 4.2.2. JMAP Responses 187 This specification adds two extra arguments to the Response object: 189 o *@type*: "String" A string having value "Response" to identify the 190 JSON object as a JMAP Response. 192 o *requestId*: "String|null" The client-specified identifier in the 193 corresponding request. If "null", no identifier was provided in 194 the request. 196 4.2.3. JMAP Request-level Errors 198 This specification adds two extra arguments to the Problem Details 199 object: 201 o *@type*: "String" A string having value "RequestError" to identify 202 the JSON object as a JSON Problem Details object. 204 o *requestId*: "String|null" The client-specified identifier in the 205 corresponding request. If "null", no identifier was provided in 206 the request. 208 4.2.4. JMAP Push Notifications 210 This specification adds one extra argument to the StateChange object: 212 o *@type*: "String" A string having value "StateChange" to identify 213 the JSON object as a JMAP StateChange object. 215 4.3. Examples 217 The following examples show WebSocket JMAP opening handshakes, a JMAP 218 Core/echo request and response, and a subsequent closing handshake. 219 The examples assume that the JMAP 'wsURL' has been advertised in the 220 JMAP Session object as '/jmap/ws/'. Note that folding of header 221 fields is for editorial purposes only. 223 WebSocket JMAP connection via HTTP/1.1: 225 [[ From Client ]] [[ From Server ]] 227 GET /jmap/ws/ HTTP/1.1 228 Host: server.example.com 229 Upgrade: websocket 230 Connection: Upgrade 231 Authorization: Basic Zm9vOmJhcg== 232 Sec-WebSocket-Key: 233 dGhlIHNhbXBsZSBub25jZQ== 234 Sec-WebSocket-Protocol: jmap 235 Sec-WebSocket-Version: 13 236 Origin: http://www.example.com 238 HTTP/1.1 101 Switching Protocols 239 Upgrade: websocket 240 Connection: Upgrade 241 Sec-WebSocket-Accept: 242 s3pPLMBiTxaQ9kYGzzhZRbK+xOo= 243 Sec-WebSocket-Protocol: jmap 245 [WebSocket connection established] 247 WS_DATA 248 { 249 "id": "R1", 250 "using": [ "urn:ietf:params:jmap:core" ], 251 "methodCalls": [ 252 [ 253 "Core/echo", { 254 "hello": true, 255 "high": 5 256 }, 257 "b3ff" 258 ] 259 ] 260 } 262 WS_DATA 263 { 264 "@type": "Response", 265 "requestId": "R1", 266 "methodResponses": [ 267 [ 268 "Core/echo", { 269 "hello": true, 270 "high": 5 271 }, 272 "b3ff" 273 ] 274 ] 275 } 277 WS_DATA 278 The quick brown fox jumps 279 over the lazy dog. 281 WS_DATA 282 { 283 "@type": "RequestError", 284 "requestId": "null", 285 "type": 286 "urn:ietf:params:jmap:error:notJSON", 287 "status": 400, 288 "detail": 289 "The request did not parse as I-JSON." 290 } 292 WS_DATA 293 { 294 "@type": "StateChange", 295 "changed": { 296 "a123": { 297 "Mailbox": "0af7a512ce70", 298 } 299 } 300 } 302 WS_CLOSE 304 WS_CLOSE 306 [WebSocket connection closed] 307 WebSocket JMAP connection on a HTTP/2 stream which also negotiates 308 compression [RFC7692]: 310 [[ From Client ]] [[ From Server ]] 312 SETTINGS 313 SETTINGS_ENABLE_CONNECT_PROTOCOL = 1 315 HEADERS + END_HEADERS 316 :method = CONNECT 317 :protocol = websocket 318 :scheme = https 319 :path = /jmap/ 320 :authority = server.example.com 321 authorization = Basic Zm9vOmJhcg== 322 sec-websocket-protocol = jmap 323 sec-websocket-version = 13 324 sec-websocket-extensions = 325 permessage-deflate 326 origin = http://www.example.com 328 HEADERS + END_HEADERS 329 :status = 200 330 sec-websocket-protocol = jmap 331 sec-websocket-extensions = 332 permessage-deflate 334 [WebSocket connection established] 336 DATA 337 WS_DATA 338 [compressed text] 340 DATA 341 WS_DATA 342 [compressed text] 344 ... 346 DATA + END_STREAM 347 WS_CLOSE 349 DATA + END_STREAM 350 WS_CLOSE 352 [WebSocket connection closed] 353 [HTTP/2 stream closed] 355 5. Security Considerations 357 The security considerations for both WebSocket (see Section 10 of 358 [RFC6455]) and JMAP (see Section 8 of [I-D.ietf-jmap-core]) apply to 359 the WebSocket JMAP subprotocol. 361 6. IANA Considerations 363 6.1. Registration of the WebSocket JMAP Subprotocol 365 This specification requests IANA to register the WebSocket JMAP 366 subprotocol under the "WebSocket Subprotocol Name" Registry with the 367 following data: 369 Subprotocol Identifier: JMAP 371 Subprotocol Common Name: WebSocket Transport for JMAP (JSON Meta 372 Application Protocol) 374 Subprotocol Definition: RFCXXXX (this document) 376 7. Acknowledgments 378 The author would like to thank the following individuals for 379 contributing their ideas and support for writing this specification: 380 Neil Jenkins and Robert Mueller. 382 8. References 384 8.1. Normative References 386 [I-D.ietf-jmap-core] 387 Jenkins, N. and C. Newman, "JSON Meta Application 388 Protocol", draft-ietf-jmap-core-12 (work in progress), 389 December 2018. 391 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 392 Requirement Levels", BCP 14, RFC 2119, 393 DOI 10.17487/RFC2119, March 1997, 394 . 396 [RFC6455] Fette, I. and A. Melnikov, "The WebSocket Protocol", 397 RFC 6455, DOI 10.17487/RFC6455, December 2011, 398 . 400 [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 401 Protocol (HTTP/1.1): Authentication", RFC 7235, 402 DOI 10.17487/RFC7235, June 2014, 403 . 405 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 406 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 407 May 2017, . 409 [RFC8441] McManus, P., "Bootstrapping WebSockets with HTTP/2", 410 RFC 8441, DOI 10.17487/RFC8441, September 2018, 411 . 413 8.2. Informative References 415 [I-D.ietf-jmap-mail] 416 Jenkins, N. and C. Newman, "JMAP for Mail", draft-ietf- 417 jmap-mail-12 (work in progress), December 2018. 419 [RFC7692] Yoshino, T., "Compression Extensions for WebSocket", 420 RFC 7692, DOI 10.17487/RFC7692, December 2015, 421 . 423 8.3. URIs 425 [1] https://tools.ietf.org/html/bcp14 427 Appendix A. Change History (To be removed by RFC Editor before 428 publication) 430 Changes since murchison-02: 432 o Renamed as a JMAP WG document. 434 o Allow out of order processing. 436 o Allow push notifications. 438 o Modified examples. 440 o Add Security Considerations text. 442 o Minor Editorial changes. 444 Changes since murchison-01: 446 o Updated WebSocket over HTTP/2 reference to RFC8144. 448 Changes since murchison-00: 450 o Fleshed out section on discovery of support for JMAP over 451 WebSocket. 453 o Allow JSON Problem Details objects to be returned by the server 454 for toplevel errors. 456 o Mentioned the ability to compress JMAP API requests. 458 o Minor Editorial changes. 460 Author's Address 462 Kenneth Murchison 463 FastMail US LLC 464 1429 Walnut Street - Suite 1201 465 Philadelphia, PA 19102 466 USA 468 Email: murch@fastmailteam.com