idnits 2.17.1 draft-svirid-websocket2-over-http2-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 : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The abstract seems to contain references ([RFC6455]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (October 18, 2016) is 2740 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Obsolete informational reference (is this intentional?): RFC 7540 (Obsoleted by RFC 9113) Summary: 3 errors (**), 0 flaws (~~), 1 warning (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group I. Svirid 3 Internet-Draft October 18, 2016 4 Intended status: Informational 5 Expires: April 21, 2017 7 WebSocket2 over HTTP/2 8 draft-svirid-websocket2-over-http2-00 10 Abstract 12 This document specifies a new protocol called WebSocket2 ontop of 13 HTTP/2. The WebSocket2 protocol enables two-way binary communication 14 between a client running untrusted code in a controlled environment 15 to a remote host that has opted-in to communications from that code. 17 This protocol has little incommon with the WebSocket protocol 18 [RFC6455] other than client side API compatibility. 20 Please send feedback to the ietf-http-wg@w3.org mailing list. 22 Status of This Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at http://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on April 21, 2017. 39 Copyright Notice 41 Copyright (c) 2016 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (http://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 57 1.1. Conventions and Terminology . . . . . . . . . . . . . . . 3 58 2. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 3 59 2.1. WebSocket2 Protocol . . . . . . . . . . . . . . . . . . . 3 60 3. Handshake . . . . . . . . . . . . . . . . . . . . . . . . . . 3 61 3.1. Client Handshake Request . . . . . . . . . . . . . . . . 3 62 3.2. Server Handshake Reply . . . . . . . . . . . . . . . . . 4 63 3.2.1. Handshake Error Reasons . . . . . . . . . . . . . . . 5 64 3.3. Post Handshake . . . . . . . . . . . . . . . . . . . . . 5 65 4. Data Framing . . . . . . . . . . . . . . . . . . . . . . . . 5 66 4.1. Text Frame . . . . . . . . . . . . . . . . . . . . . . . 6 67 4.2. Binary Frame . . . . . . . . . . . . . . . . . . . . . . 6 68 4.3. Error Frame . . . . . . . . . . . . . . . . . . . . . . . 6 69 4.3.1. Error Frame Codes . . . . . . . . . . . . . . . . . . 7 70 5. VarSize . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 71 6. Compression . . . . . . . . . . . . . . . . . . . . . . . . . 8 72 6.1. LZ4 Compressed Payload . . . . . . . . . . . . . . . . . 8 73 6.2. Deflate Compressed Payload . . . . . . . . . . . . . . . 8 74 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 9 75 7.1. Normative References . . . . . . . . . . . . . . . . . . 9 76 7.2. Informative References . . . . . . . . . . . . . . . . . 9 77 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 9 78 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 9 80 1. Introduction 82 You can read about why two way data streaming is important from the 83 introduction to WebSockets in RFC6455 Section 1 84 . 86 WebSocket2 over HTTP/2 is a protocol ontop HTTP/2 designed for modern 87 times. Previous WebSocket client side API will be fully backward 88 compatible with WebSocket2. 90 In this document, we describe WebSocket2 and how to layer WebSocket2 91 semantics onto HTTP/2 semantics by defining detailed mapping, 92 replacement of operations and events. 94 1.1. Conventions and Terminology 96 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 97 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 98 document are to be interpreted as described in RFC 2119 [RFC2119]. 100 2. Overview 102 WebSocket2 is functionally equivalent to binary streaming between a 103 sandboxed client and inexplicit host, but layered on top of HTTP2. 105 Key advantages of WebSocket2 over WebSocket: 107 o No masking 109 o Simpler handshake and negotiation 111 o Lz4 compression method 113 Key advantages of WebSocket2 over HTTP/2 include: 115 o Two-way real time communication 117 o Server push and delivery without client request 119 o Binary transmission 121 2.1. WebSocket2 Protocol 123 The protocol has two main parts, the handshake and data transfer. 124 Data transmitted using WebSocket2 supports compression. 126 3. Handshake 128 The main job of the handshake is to request authority and if granted 129 by the server, to negotiate a compression medium. 131 3.1. Client Handshake Request 133 The client MUST use the :method GET. 135 The client MUST send a sec-ws2-version header that MUST specify the 136 websocket2 version being used. 138 The client MAY send a sec-ws2-compression header that advertises the 139 compression methods the client supports. Valid key value pairs 140 include: 142 o lz4=1-9; 143 * This client supports lz4 with compression levels from 1 to 9 145 o lz4=1; 146 * This client supports lz4 with compression levels 1 148 o deflate=8-15; 149 * This client supports deflate with sliding window bits from 8-15 151 Duplicate keys MUST NOT be present. 153 The client MUST NOT set the END_STREAM flag when sending the headers. 155 A client handshake request may look like: 157 :method: GET 158 :scheme: wss 159 :authority: example.org 160 :path: /demo 161 sec-ws2-version: 1 162 sec-ws2-compression: lz4=1-9; deflate=8-15; 164 3.2. Server Handshake Reply 166 END_STREAM on the HTTP/2 Header frame MUST only be set in the case of 167 rejection. 169 The server MUST send ONLY ONE of the advertised compression methods 170 or exclude the sec-ws2-compression header from the response, 171 signaling that no compression will be used. 173 The server MUST include the sec-ws2-error header in the reply with an 174 outlined error reason. 176 A successful server handshake reply may look like: 178 :status: 200 179 sec-ws2-compression: lz4=1; 180 sec-ws2-error: success 182 This signals that the server chose to use lz4 with a compression 183 level of 1. Now both the client and server MUST use only this 184 compression method. 186 3.2.1. Handshake Error Reasons 188 Valid error reasons are: 190 success 191 * The server accepted the client 193 invalid_version 194 * This version of websockets is not supported by the server 196 cannot_negotiate_compression 197 * This means the client did not offer any compression that 198 the server requires 200 rejected 201 * This means the server rejected the client and does not want 202 to say why. This means the server supports websockets, but 203 rejected this particular client 205 3.3. Post Handshake 207 Following the handshake the client or server MUST NEVER set the 208 END_STREAM flag on any HTTP/2 DATA frame UNLESS the stream is to be 209 gracefully terminated. Only a HTTP/2 DATA frame containing a 210 WebSocket2 error frame allow the END_STREAM flag to be set. 212 4. Data Framing 214 Once a handshake has been successfully completed the remote endpoints 215 can begin to send data to each other. Data is sent using the HTTP/2 216 transport layer fully adhering to DATA Frames, Section 6.1 [RFC7540]. 217 WebSocket2 has its own encapsulated framing protocol that is not to 218 be confused with HTTP/2 DATA Frames. 220 Three frame types are defined: 222 text (represented by 0) 223 binary (represented by 1) 224 error (represented by 2) 226 Three compression types are defined: 228 none (represented by 0) 229 lz4 (represented by 1) 230 deflate (represented by 2) 232 A WebSocket2 over HTTP/2 frame starts with the full frame length in a 233 special format called VarSize. If the first octet is less than 254, 234 this is the full frame length. If the first octet is 254, read the 235 next 16 bits as a little endian unsigned number for the frame length. 236 If the first octet is 255, read the next 32 bits as a little endian 237 unsigned number for the frame length. 239 Next are 4 reserved bits that MUST be set to 0. 241 The next 2 bits specify the compression type. 243 The next 2 bits specify the frame type. 245 Next is the payload which MAY be compressed if compression was 246 negotiated. 248 The term PAYLOAD in this section refers to data AFTER decompression 249 if compression was negotiated. 251 0 1 2 252 +--------------+--------------+--------------+ 253 | Frame Length | R - C - F | | -> 254 | (8,24,40) | S | T | T | Payload | -> 255 | | V | P | P | | -> 256 | |(4) -(2)-(2)| | -> 257 +--------------+------------+----------------+ 259 4.1. Text Frame 261 The text frame has a Frame Type value of 0. The payload must be 262 UTF-8 encoded text. The whole message MUST contain valid UTF-8. 263 Invalid UTF-8 in the payload requires the remote end point to send an 264 error frame and close their side of the stream. 266 4.2. Binary Frame 268 The binary frame has a Frame Type value of 1. The payload must be 269 arbitrary binary data which the application layer passes without 270 comprehension. 272 4.3. Error Frame 274 The error frame has a Frame Type value of 2. It MUST contain a VALID 275 32 bit error code. If the code is shorter than 32 bits, 0 bits MUST 276 make up the rest to fill a total of 32 bits. Currently there are no 277 error codes less than 32 bits. 279 The HTTP/2 transport layer DATA frame carrying the WebSocket2 error 280 frame MUST have the END_STREAM flag set. 282 No further WebSocket2 frames may be sent from this point onward and 283 the stream is half closed. 285 The remote endpoint that receives the error frame MUST flush all 286 pending sends followed by an error frame of its own with the CLOS 287 error code. The HTTP/2 Data frame carrying this WebSocket2 frame 288 MUST have the END_STREAM flag set. 290 The full WebSocket2 error frame with the length: 292 0 01234567 2 3 4 5 293 +--------+--------+--------+--------+--------+--------+ 294 | | | Error Code | 295 | 5 |00000010| (32 bits) | 296 | | | | 297 +--------+--------+--------+--------+--------+--------+ 299 4.3.1. Error Frame Codes 301 Valid error frame codes currently are: 303 CLOS 305 * This should be sent when a client or server want to close the 306 stream gracefully. 308 UTF8 310 * This should be sent when invalid UTF8 was passed in a text frame 311 by a remote endpoint. 313 DECO 315 * This should be sent when decompression failed by a remote 316 endpoint. 318 FRAM 320 * This should be sent when an invalid Frame Type was specified. 322 LRGE 324 * This should be sent when an endpoint rejects a frame due to it 325 being too large. This is up to the endpoint. 327 5. VarSize 329 VarSize is a variable sized binary ranging from 1-5 octets. It 330 represents an unsigned value. If the first octet is equal to 254, 331 read the next 16 bits as little endian unsigned. If the first octet 332 is equal to 255, read the next 32 bits as little endian unsigned. 333 Otherwise if the first octet is less than 254, treat this as the 334 final value. 336 6. Compression 338 WebSocket defined one compression method which used deflate and kept 339 a sliding window. This compression is great but has limitations. 340 Also keeping a sliding window is memory intensive. 342 Lz4 is a compression method that is great for any kind of data while 343 being very cheap. 345 Currently two compression methods are defined lz4 and deflate. The 346 protocol is open to tweaking or accepting more in the future. 348 6.1. LZ4 Compressed Payload 350 A lz4 compressed payload is a VarSize number of the decompressed size 351 followed by the actual compressed payload. The lz4 compression level 352 to use MUST be what was negotiated in the handshake. 354 A lz4 compressed payload may look like: 356 0 1 2 3 357 +--------+--------+--------+--------+--------+--------+ 358 | | Decompressed | Compressed payload | -> 359 | 254 | Size | | -> 360 | | | | -> 361 +--------+--------+--------+--------+--------+--------+ 363 6.2. Deflate Compressed Payload 365 The deflate compression method implements [RFC7692] but defines more 366 strict bounds. There is no ability to reset compression context. 368 * Both client and server MUST use the sliding window bits as 369 determined by the server. 370 * The client MUST use a memory level of 8. 371 * The client MUST use a compression level of 9 (best_compression). 373 Any sliding window MUST NEVER have its context reset. 375 If the deflated payload trailing 4 octets are 0x00, 0x00, 0xFF, 0xFF, 376 remove them before sending the payload. 378 Before inflating the payload append 0x00, 0x00, 0xFF, 0xFF to the end 379 of it. 381 7. References 383 7.1. Normative References 385 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 386 Requirement Levels", BCP 14, RFC 2119, 387 DOI 10.17487/RFC2119, March 1997, 388 . 390 [RFC7692] Yoshino, T., "Compression Extensions for WebSocket", 391 RFC 7692, DOI 10.17487/RFC7692, December 2015, 392 . 394 7.2. Informative References 396 [RFC6455] Fette, I. and A. Melnikov, "The WebSocket Protocol", 397 RFC 6455, DOI 10.17487/RFC6455, December 2011, 398 . 400 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 401 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 402 DOI 10.17487/RFC7540, May 2015, 403 . 405 Appendix A. Acknowledgements 407 The author wishes to thank Kari hurtta for contributing the 408 handshake. 410 The author wishes to thank the participants of the WebSocket 411 protocol, participants of the HTTP/2 protocol and participants of the 412 QUIC protocol. 414 Author's Address 416 Ivan Svirid 417 Toronto, ON 418 Canada 420 Email: vans_163@yahoo.com