idnits 2.17.1 draft-murchison-jmap-websocket-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 : ---------------------------------------------------------------------------- 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 (August 3, 2018) is 2092 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 321 == Outdated reference: A later version (-17) exists of draft-ietf-jmap-core-06 ** Obsolete normative reference: RFC 7235 (Obsoleted by RFC 9110) == Outdated reference: A later version (-16) exists of draft-ietf-jmap-mail-06 Summary: 1 error (**), 0 flaws (~~), 4 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Independent Submission K. Murchison 3 Internet-Draft FastMail 4 Intended status: Standards Track August 3, 2018 5 Expires: February 4, 2019 7 A JSON Meta Application Protocol (JMAP) Subprotocol for WebSocket 8 draft-murchison-jmap-websocket-01 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 Should we allow push notifications over the WS connection? 21 o Should we allow out of order processing od requests? 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 February 4, 2019. 40 Copyright Notice 42 Copyright (c) 2018 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 47 (https://trustee.ietf.org/license-info) in effect on the date of 48 publication of this document. Please review these documents 49 carefully, as they describe your rights and restrictions with respect 50 to this document. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 55 2. Conventions Used in This Document . . . . . . . . . . . . . . 3 56 3. Discovering Support for JMAP over WebSocket . . . . . . . . . 3 57 4. JMAP Subprotocol . . . . . . . . . . . . . . . . . . . . . . 3 58 4.1. Handshake . . . . . . . . . . . . . . . . . . . . . . . . 3 59 4.2. WebSocket Messages . . . . . . . . . . . . . . . . . . . 4 60 4.3. Examples . . . . . . . . . . . . . . . . . . . . . . . . 4 61 5. Security Considerations . . . . . . . . . . . . . . . . . . . 6 62 6. Privacy Considerations . . . . . . . . . . . . . . . . . . . 7 63 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 64 7.1. Registration of the WebSocket JMAP Sub-Protocol . . . . . 7 65 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 7 66 8.1. Normative References . . . . . . . . . . . . . . . . . . 7 67 8.2. Informative References . . . . . . . . . . . . . . . . . 8 68 8.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 8 69 Appendix A. Change History (To be removed by RFC Editor before 70 publication) . . . . . . . . . . . . . . . . . . . . 8 71 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 8 73 1. Introduction 75 JMAP over HTTP requires that every JMAP API request be authenticated. 76 Depending on the type of authentication used by the JMAP client and 77 the configuration of the JMAP server, authentication could be an 78 expensive operation both in time and resources. In such 79 circumstances, authenticating every JMAP API request may harm 80 performance. 82 The WebSocket binding for JMAP eliminates this performance hit by 83 authenticating just the WebSocket handshake request and having those 84 credentials remain in effect for the duration of the WebSocket 85 connection. 87 Furthermore, the WebSocket binding for JMAP can optionally compress 88 [RFC7692] JMAP API requests. Although compression of HTTP responses 89 is ubiquitous, compression of HTTP requests has very low, if any 90 deployment, and therefore isn't an option for JMAP API requests over 91 HTTP. 93 2. Conventions Used in This Document 95 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 96 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 97 "OPTIONAL" in this document are to be interpreted as described in BCP 98 14 [1] [RFC2119] [RFC8174] when, and only when, they appear in all 99 capitals, as shown here. 101 The same terminology is used in this document as in the core JMAP 102 specification. 104 3. Discovering Support for JMAP over WebSocket 106 The capabilities object is returned as part of the standard JMAP 107 Session object (see Section 2 of [I-D.ietf-jmap-core]). Servers 108 supporting this specification MUST add a property called 109 "urn:ietf:params:jmap:websocket" to the capabilities object. The 110 value of this property is an object which MUST contain the following 111 information on server capabilities: 113 wsUrl: "String" The URL to use for JMAP over WebSocket. 115 4. JMAP Subprotocol 117 The term WebSocket subprotocol refers to an application-level 118 protocol layered on top of a WebSocket connection. This document 119 specifies the WebSocket JMAP subprotocol for carrying JMAP API 120 requests and responses through a WebSocket connection. Binary data 121 MUST NOT be uploaded or downloaded through a WebSocket JMAP 122 connection. 124 4.1. Handshake 126 The JMAP WebSocket client and JMAP WebSocket server negotiate the use 127 of the WebSocket JMAP subprotocol during the WebSocket handshake, 128 either via a HTTP/1.1 Upgrade request (see Section 1.3 of [RFC6455]) 129 or a HTTP/2 Extended CONNECT request (see Section 5 of 130 [I-D.ietf-httpbis-h2-websockets]). 132 Regardless of the method used for the WebSocket handshake, the client 133 MUST make an authenticated [RFC7235] HTTP request on the JMAP 'wsURL' 134 (Section 3), and the client MUST include the value 'jmap' in the list 135 of protocols for the 'Sec-WebSocket-Protocol' header field. The 136 reply from the server MUST also contain 'jmap' in its corresponding 137 'Sec-WebSocket-Protocol' header field in order for a JMAP subprotocol 138 connection to be established. 140 If a client receives a handshake response that does not include 141 'jmap' in the 'Sec-WebSocket-Protocol' header, then a JMAP 142 subprotocol WebSocket connection was not established and the client 143 MUST close the WebSocket connection. 145 Once the handshake has successfully completed, the WebSocket 146 connection is established and can be used for JMAP API requests and 147 responses. Messages other than JMAP API requests and responses MUST 148 NOT be transmitted over this connection. 150 The credentials used for authenticating the HTTP request to initiate 151 the handshake remain in effect for the duration of the WebSocket 152 connection. 154 4.2. WebSocket Messages 156 Data frame messages in the JMAP subprotocol MUST be of the text type 157 and contain UTF-8 encoded data. The messages MUST be in the form of 158 a single JMAP request object (see Section 3.2 of 159 [I-D.ietf-jmap-core]) when sent from the client to the server, and in 160 the form of a single JMAP Response object or JSON Problem Details 161 object (see Sections 3.4 and 3.6.1 respectively of 162 [I-D.ietf-jmap-core]) when sent from the server to the client. 164 4.3. Examples 166 The following examples show WebSocket JMAP handshakes and a 167 subsequent JMAP for Mail [I-D.ietf-jmap-mail] request and response. 168 The examples assume that the JMAP 'wsURL' has been advertised in the 169 JMAP Session object as '/jmap/'. Note that folding of header fields 170 is for editorial purposes only. 172 WebSocket JMAP handshake via HTTP/1.1 which also negotiates 173 compression [RFC7692]: 175 [[ From Client ]] [[ From Server ]] 177 GET /jmap/ HTTP/1.1 178 Host: server.example.com 179 Upgrade: websocket 180 Connection: Upgrade 181 Authorization: Basic Zm9vOmJhcg== 182 Sec-WebSocket-Key: 183 dGhlIHNhbXBsZSBub25jZQ== 184 Sec-WebSocket-Protocol: jmap 185 Sec-WebSocket-Version: 13 186 Sec-Websocket-Extensions: 187 permessage-deflate 188 Origin: http://www.example.com 190 HTTP/1.1 101 Switching Protocols 191 Upgrade: websocket 192 Connection: Upgrade 193 Sec-WebSocket-Accept: 194 s3pPLMBiTxaQ9kYGzzhZRbK+xOo= 195 Sec-WebSocket-Protocol: jmap 196 Sec-Websocket-Extensions: 197 permessage-deflate 199 [WebSocket connection established] 201 { 202 "using": [ "urn:ietf:params:jmap:core", 203 "urn:ietf:params:jmap:mail" ], 204 "methodCalls": [ 205 ... 206 ] 207 } 209 { 210 "methodResponses": [ 211 ... 212 ] 213 } 215 WebSocket JMAP handshake on a HTTP/2 stream: 217 [[ From Client ]] [[ From Server ]] 219 SETTINGS 220 SETTINGS_ENABLE_CONNECT_PROTOCOL = 1 222 HEADERS + END_HEADERS 223 :method = CONNECT 224 :protocol = websocket 225 :scheme = https 226 :path = /jmap/ 227 :authority = server.example.com 228 authorization = Basic Zm9vOmJhcg== 229 sec-websocket-protocol = jmap 230 sec-websocket-version = 13 231 origin = http://www.example.com 233 HEADERS + END_HEADERS 234 :status = 200 235 sec-websocket-protocol = jmap 237 [WebSocket connection established] 239 DATA 240 { 241 "using": [ "urn:ietf:params:jmap:core", 242 "urn:ietf:params:jmap:mail" ], 243 "methodCalls": [ 244 ... 245 ] 246 } 248 DATA 249 { 250 "methodResponses": [ 251 ... 252 ] 253 } 255 5. Security Considerations 257 TODO 259 6. Privacy Considerations 261 TODO 263 7. IANA Considerations 265 7.1. Registration of the WebSocket JMAP Sub-Protocol 267 This specification requests IANA to register the WebSocket JMAP sub- 268 protocol under the "WebSocket Subprotocol Name" Registry with the 269 following data: 271 Subprotocol Identifier: JMAP 273 Subprotocol Common Name: WebSocket Transport for JMAP (JSON Meta 274 Application Protocol) 276 Subprotocol Definition: RFCXXXX (this document) 278 8. References 280 8.1. Normative References 282 [I-D.ietf-httpbis-h2-websockets] 283 McManus, P., "Bootstrapping WebSockets with HTTP/2", 284 draft-ietf-httpbis-h2-websockets-07 (work in progress), 285 June 2018. 287 [I-D.ietf-jmap-core] 288 Jenkins, N., "JSON Meta Application Protocol", draft-ietf- 289 jmap-core-06 (work in progress), July 2018. 291 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 292 Requirement Levels", BCP 14, RFC 2119, 293 DOI 10.17487/RFC2119, March 1997, 294 . 296 [RFC6455] Fette, I. and A. Melnikov, "The WebSocket Protocol", 297 RFC 6455, DOI 10.17487/RFC6455, December 2011, 298 . 300 [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 301 Protocol (HTTP/1.1): Authentication", RFC 7235, 302 DOI 10.17487/RFC7235, June 2014, 303 . 305 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 306 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 307 May 2017, . 309 8.2. Informative References 311 [I-D.ietf-jmap-mail] 312 Jenkins, N., "JMAP for Mail", draft-ietf-jmap-mail-06 313 (work in progress), July 2018. 315 [RFC7692] Yoshino, T., "Compression Extensions for WebSocket", 316 RFC 7692, DOI 10.17487/RFC7692, December 2015, 317 . 319 8.3. URIs 321 [1] https://tools.ietf.org/html/bcp14 323 Appendix A. Change History (To be removed by RFC Editor before 324 publication) 326 Changes since -00: 328 o Fleshed out section on discovery of support for JMAP over 329 WebSocket. 331 o Allow JSON Problem Details objects to be returned by the server 332 for toplevel errors. 334 o Mentioned the ability to compress JMAP API requests. 336 o Minor Editorial changes. 338 Author's Address 340 Kenneth Murchison 341 FastMail US LLC 342 1315 Walnut Street - Suite 320 343 Philadelphia, PA 19107 344 USA 346 Email: murch@fastmailteam.com