idnits 2.17.1 draft-ietf-hybi-websocket-perframe-compression-04.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 date (May 22, 2012) is 4356 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) ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) -- Possible downref: Non-RFC (?) normative reference: ref. 'LZ77' Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HyBi Working Group T. Yoshino 3 Internet-Draft Google, Inc. 4 Intended status: Standards Track May 22, 2012 5 Expires: November 23, 2012 7 WebSocket Per-frame Compression 8 draft-ietf-hybi-websocket-perframe-compression-04 10 Abstract 12 This specification defines a WebSocket extension that adds per-frame 13 compression functionality to the WebSocket Protocol. It compresses 14 the "Application data" portion of WebSocket data frames using 15 specified compression algorithm. One reserved bit RSV1 in the 16 WebSocket frame header is allocated to control application of 17 compression for each frame. This specification provides one 18 compression method available for the extension using DEFLATE. 20 Please send feedback to the hybi@ietf.org mailing list. 22 Status of this Memo 24 This Internet-Draft is submitted to IETF 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 November 23, 2012. 39 Copyright Notice 41 Copyright (c) 2012 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 . . . . . . . . . . . . . . . . . . . . . . . . . 3 57 2. Conformance Requirements . . . . . . . . . . . . . . . . . . . 4 58 3. Extension Negotiation . . . . . . . . . . . . . . . . . . . . 5 59 3.1. Negotiation Example . . . . . . . . . . . . . . . . . . . 6 60 4. Framing . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 61 4.1. Sending . . . . . . . . . . . . . . . . . . . . . . . . . 7 62 4.2. Receiving . . . . . . . . . . . . . . . . . . . . . . . . 7 63 5. DEFLATE method . . . . . . . . . . . . . . . . . . . . . . . . 8 64 5.1. Method Parameters . . . . . . . . . . . . . . . . . . . . 8 65 5.2. Application Data Transformation . . . . . . . . . . . . . 9 66 5.2.1. Compression . . . . . . . . . . . . . . . . . . . . . 9 67 5.2.2. Decompression . . . . . . . . . . . . . . . . . . . . 10 68 5.2.3. Examples . . . . . . . . . . . . . . . . . . . . . . . 10 69 5.3. Intermediaries . . . . . . . . . . . . . . . . . . . . . . 11 70 5.4. Implementation Notes . . . . . . . . . . . . . . . . . . . 11 71 6. Security Considerations . . . . . . . . . . . . . . . . . . . 12 72 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 73 7.1. Registration of the "perframe-compress" WebSocket 74 Extension Name . . . . . . . . . . . . . . . . . . . . . . 13 75 7.2. Registration of the "Per-frame Compressed" WebSocket 76 Framing Header Bit . . . . . . . . . . . . . . . . . . . . 13 77 7.3. WebSocket Per-frame Compression Method Name Registry . . . 14 78 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 15 79 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 16 80 9.1. Normative References . . . . . . . . . . . . . . . . . . . 16 81 9.2. Informative References . . . . . . . . . . . . . . . . . . 16 82 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 17 84 1. Introduction 86 _This section is non-normative._ 88 As well as other communication protocols, the WebSocket Protocol 89 [RFC6455] can benefit from compression technology. This 90 specification defines a WebSocket extension that applies a 91 compression algorithm to octets exchanged over the WebSocket Protocol 92 using its extension framework. This extension negotiates what 93 compression method to use on opening handshake, and then compresses 94 to the octets in the "Application data" portion of data frames using 95 the method. We can apply this extension to various compression 96 algorithms by specifying how to negotiate parameters and transform 97 "Application data". A client may offer multiple compression methods 98 on opening handshake, and then the server chooses one from them. 99 This extension uses the RSV1 bit of the WebSocket frame header to 100 indicate whether the frame is compressed or not, so that we can 101 choose to skip frames with incompressible contents without applying 102 extra compression. 104 This specification provides one specific compression method for this 105 extension "deflate" which is based on DEFLATE [RFC1951]. We chose 106 DEFLATE since it's widely available as library on various platforms 107 and the overhead it adds for each chunk is small. To align the end 108 of compressed data to octet boundary, this method uses the algorithm 109 described in the Section 2.1 of the PPP Deflate Protocol [RFC1979]. 110 Endpoints can take over the LZ77 sliding window [LZ77] used to build 111 previous frames to get better compression ratio. For resource- 112 limited devices, method parameters to limit the usage of memory for 113 compression context are provided. 115 The simplest "Sec-WebSocket-Extensions" header in the client's 116 opening handshake to request DEFLATE based per-frame compression is 117 the following: 119 Sec-WebSocket-Extensions: perframe-compress; method=deflate 121 The simplest header from the server to accept this extension is the 122 same. 124 2. Conformance Requirements 126 Everything in this specification except for sections explicitly 127 marked non-normative is normative. 129 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 130 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 131 document are to be interpreted as described in [RFC2119]. 133 3. Extension Negotiation 135 The registered extension token for this extension is 136 "perframe-compress". 138 To request use of the Per-frame Compression Extension, a client MUST 139 include an element with the "perframe-compress" extension token as 140 its extension identifier in the "Sec-WebSocket-Extensions" header in 141 its opening handshake. The element MUST contain exactly one 142 extension parameter named "method". The value of the "method" 143 extension parameter is a list of compression method descriptions, 144 ordered by preference. Each compression method description has a 145 method name and optional method parameters. The grammar of the list 146 is "requested-method-list" defined in the following ABNFs. 148 requested-method-list = 1#method-desc 149 method-desc = method-name *(";" method-param) 150 method-name = token 151 method-param = token ["=" (token | quoted-string)] 153 The list MAY contain multiple method descriptions with the same 154 method name. 156 To accept use of the Per-frame Compression Extension, a server MUST 157 choose one compression method description to accept from ones listed 158 by the client, and include an element with the "perframe-compress" 159 extension token in the "Sec-WebSocket-Extensions" header in its 160 opening handshake. The chosen description is called "accepted 161 request". The element MUST contain exactly one extension parameter 162 named "method". The value of the "method" extension parameter MUST 163 be a compression method description. This description is called 164 "method agreement". The method name in the "method agreement" MUST 165 be one of the accepted request. The "method agreement" MUST conform 166 the "accepted request". Its grammar is "method-agreement" defined in 167 the following ABNF. 169 method-agreement = method-desc 171 The value of the "method" parameter MUST be quoted by using 172 "quoted-string" syntax if it doesn't conform to token syntax. 174 If a client doesn't support the method and its configuration 175 specified by the "method agreement", the client MUST _Fail the 176 WebSocket Connection_. Otherwise, both endpoints MUST use the 177 algorithm described in Section 4 to exchange frames. 179 3.1. Negotiation Example 181 _This section is non-normative._ 183 These are "Sec-WebSocket-Extensions" header value examples that 184 negotiate the per-frame compression extension. 186 o Request foo method. Since foo matches token syntax, it doesn't 187 need to be quoted. 189 perframe-compress; method=foo 191 o Request foo method with a parameter x with 10 as its value. Since 192 the method parameter value contains a semicolon, it doesn't match 193 token syntax. Quotation is needed. 195 perframe-compress; method="foo; x=10" 197 o Request foo method and bar method. Since the method parameter 198 value contains a comma, it doesn't match token syntax. Quotation 199 is needed. 201 perframe-compress; method="foo, bar" 203 o Request foo method with parameter x with "Hello World" (quotation 204 for clarification) as its value and bar method. Since "Hello 205 World" contains a space, it needs to be quoted. Since quoted 206 "Hello World" contains double quotations and a space, it needs to 207 be quoted again. 209 perframe-compress; method="foo; x=\"Hello World\", bar" 211 4. Framing 213 This section describes how to apply the negotiated compression method 214 to the contents of WebSocket frames. 216 This extension allocates the RSV1 bit of the WebSocket header and 217 names it the "Per-frame Compressed" bit. Any extension requiring the 218 use of the RSV1 bit is incompatible with this extension. This bit 219 indicates whether the compression is applied to the frame or not. 220 Frames with the "Per-frame Compressed" bit set are called "per-frame 221 compressed frames". They have compressed data in their "Application 222 data" portion. Frames with the bit unset are called "per-frame 223 uncompressed frames". They have uncompressed data in their 224 "Application data" portion. 226 This extension operates only on data frames. This extension doesn't 227 modify the "Extension data" portion. 229 4.1. Sending 231 To send a frame as a per-frame compressed frame, an endpoint MUST use 232 the following algorithm. 234 1. Compress the octets in "Application data" portion of the frame 235 using the compression method. 237 2. Build a frame by putting the resulting octets in the "Application 238 data" portion instead of the original octets. The payload length 239 field of the frame MUST be the sum of the size of the "Extension 240 data" portion and the size of the resulting octets. 242 3. Set the "Per-frame Compressed" bit of the frame to 1. 244 To send a frame as a per-frame uncompressed frame, an endpoint MUST 245 set "Per-frame Compressed Bit" of the frame to 0. "Application data" 246 portion MUST be sent as-is without applying the compression method. 248 4.2. Receiving 250 To receive a per-frame compressed frame, an endpoint MUST decompress 251 the octets in the "Application data" portion. 253 An endpoint MUST receive a per-frame uncompressed frame as-is without 254 decompression. 256 5. DEFLATE method 258 This section defines a method named "deflate" for this extension that 259 compresses "Application data" using DEFLATE [RFC1951] and byte 260 boundary alignment method introduced in [RFC1979]. 262 5.1. Method Parameters 264 An endpoint MAY include one or more method parameters in the method 265 description as defined below. 267 Maximum LZ77 sliding window size 269 A client MAY attach the "s2c_max_window_bits" method parameter to 270 limit the LZ77 sliding window size that the server uses to build 271 frames. If the "accepted request" has this method parameter, the 272 server MUST NOT use LZ77 sliding window size greater than the size 273 specified by this parameter to build frames. If the "accepted 274 request" has this method parameter, the server MUST attach this 275 method parameter with the same value as one of the "accepted 276 request". 278 A server MAY attach the "c2s_max_window_bits" method parameter to 279 limit the LZ77 sliding window size that the client uses to build 280 frames. A client that received this parameter MUST NOT use LZ77 281 sliding window size greater than the size specified by this 282 parameter to build frames. 284 These parameters MUST have an integer value in the range between 8 285 to 15 indicating the base-2 logarithm of the LZ77 sliding window 286 size. 288 Disallow compression context takeover 290 A client MAY attach the "s2c_no_context_takeover" method parameter 291 to disallow the server to take over the LZ77 sliding window used 292 to build previous frames. If the "accepted request" has this 293 method parameter, the server MUST reset its LZ77 sliding window 294 for sending to empty for each frame. If the "accepted request" 295 has this method parameter, the server MUST attach this method 296 parameter. 298 A server MAY attach the "c2s_no_context_takeover" method parameter 299 to disallow the client to take over the LZ77 sliding window used 300 to build previous frames. A client that received this parameter 301 MUST reset its LZ77 sliding window for sending to empty for each 302 frame. 304 These parameters have no value. 306 A server MUST ignore any method parameter other than 307 "s2c_max_window_bits" and "s2c_no_context_takeover" in the received 308 "deflate" method description. 310 A client MUST _Fail the WebSocket Connection_ if there is any method 311 parameter other than the "s2c_max_window_bits", 312 "c2s_max_window_bits", "s2c_no_context_takeover" and 313 "c2s_no_context_takeover" in the received "deflate" method 314 description. A client MUST _Fail the WebSocket Connection_ if it 315 doesn't support the method and its configuration specified by the 316 received "deflate" method description. 318 5.2. Application Data Transformation 320 5.2.1. Compression 322 An endpoint MUST use the following algorithm to compress the 323 "Application data" portion. 325 1. Compress all the octets in the "Application data" portion using 326 DEFLATE. Multiple blocks MAY be used. Any type of block MAY be 327 used. Both block with "BFINAL" set to 0 and 1 MAY be used. 329 2. If the resulting data does not end with an empty block with no 330 compression ("BTYPE" set to 0), append an empty block with no 331 compression to the tail. 333 3. Remove 4 octets (that are 0x00 0x00 0xff 0xff) from the tail. 335 An endpoint MUST NOT use an LZ77 sliding window greater than 32,768 336 bytes to build frames to send. 338 If the "method agreement" has the "s2c_max_window_bits" method 339 parameter and its value is w, the server MUST NOT use an LZ77 sliding 340 window greater than w-th power of 2 bytes to build frames to send. 341 If the "method agreement" has the "c2s_max_window_bits" method 342 parameter and its value is w, the client MUST NOT use an LZ77 sliding 343 window greater than w-th power of 2 bytes to build frames to send. 345 If the "method agreement" has the "s2c_no_context_takeover" method 346 parameter, the server MUST reset its LZ77 sliding window for sending 347 to empty for each frame. Otherwise, the server MAY take over the 348 LZ77 sliding window used to build the last per-frame compressed 349 frame. If the "method agreement" has the "c2s_no_context_takeover" 350 method parameter, the client MUST reset its LZ77 sliding window for 351 sending to empty for each frame. Otherwise, the client MAY take over 352 the LZ77 sliding window used to build the last per-frame compressed 353 frame. 355 5.2.2. Decompression 357 An endpoint MUST use the following algorithm to decompress the 358 "Application data" portion. 360 1. Append 4 octets of 0x00 0x00 0xff 0xff to the tail. 362 2. Decompress the resulting octets using DEFLATE. 364 If the "method agreement" has the "s2c_max_window_bits" method 365 parameter and its value is w, the client MAY reduce the size of the 366 LZ77 sliding window to decompress received frames down to the w-th 367 power of 2 bytes. Otherwise, the client MUST use a 32,768 byte LZ77 368 sliding window to decompress received frames. If the "method 369 agreement" has the "c2s_max_window_bits" method parameter and its 370 value is w, the server MAY reduce the size of the LZ77 sliding window 371 to decompress received frames down to the w-th power of 2 bytes. 372 Otherwise, the server MUST use a 32,768 byte LZ77 sliding window to 373 decompress received frames. 375 If the "method agreement" has the "s2c_no_context_takeover" method 376 parameter, the client MAY reset its LZ77 sliding window for receiving 377 to empty for each frame. Otherwise, the client MUST take over the 378 LZ77 sliding window used to parse the last per-frame compressed 379 frame. If the "method agreement" has the "c2s_no_context_takeover" 380 method parameter, the server MAY reset its LZ77 sliding window for 381 receiving to empty for each frame. Otherwise, the server MUST take 382 over the LZ77 sliding window used to parse the last per-frame 383 compressed frame. 385 5.2.3. Examples 387 _This section is non-normative._ 389 These are examples of resulting data after applying the algorithm 390 above. 392 o "Hello" in one compressed block 394 * 0xf2 0x48 0xcd 0xc9 0xc9 0x07 0x00 396 "Hello" in one compressed block in the next frame 398 * 0xf2 0x00 0x11 0x00 0x00 400 o "Hello" in one block with no compression 402 * 0x00 0x05 0x00 0xfa 0xff 0x48 0x65 0x6c 0x6c 0x6f 0x00 404 o "Hello" in one block with "BFINAL" set to 1 406 * 0xf3 0x48 0xcd 0xc9 0xc9 0x07 0x00 0x00 408 o "He" and "llo" in separate blocks 410 * 0xf2 0x48 0x05 0x00 0x00 0x00 0xff 0xff 0xca 0xc9 0xc9 0x07 411 0x00 413 5.3. Intermediaries 415 When intermediaries forward frames, they MAY decompress and/or 416 compress the frames according to the constraints negotiated during 417 the opening handshake of the connection(s). 419 5.4. Implementation Notes 421 _This section is non-normative._ 423 On most common software development platforms, the operation of 424 aligning compressed data to byte boundaries using an empty block with 425 no compression is available as a library. For example, Zlib [Zlib] 426 does this when "Z_SYNC_FLUSH" is passed to deflate function. 428 To get sufficient compression ratio, LZ77 sliding window size of 429 1,024 or more is recommended. 431 6. Security Considerations 433 There are no security concerns for now. 435 7. IANA Considerations 437 7.1. Registration of the "perframe-compress" WebSocket Extension Name 439 This section describes a WebSocket extension name registration in the 440 WebSocket Extension Name Registry [RFC6455]. 442 Extension Identifier 443 perframe-compress 445 Extension Common Name 446 WebSocket Per-frame Compression 448 Extension Definition 449 This document. 451 Known Incompatible Extensions 452 None 454 The "perframe-compress" token is used in the 455 "Sec-WebSocket-Extensions" header in the WebSocket opening handshake 456 to negotiate use of the Per-frame Compression Extension. 458 7.2. Registration of the "Per-frame Compressed" WebSocket Framing 459 Header Bit 461 This section describes a WebSocket framing header bit registration in 462 the WebSocket Framing Header Bits Registry [RFC6455]. 464 Header Bit 465 RSV1 467 Common Name 468 Per-frame Compressed 470 Meaning 471 The frame is compressed or not. 473 Reference 474 Section 4 of this document. 476 The "Per-frame Compressed" framing header bit is used to indicate 477 whether the "Application data" portion of the frame is compressed by 478 the Per-frame Compression Extension or not. 480 7.3. WebSocket Per-frame Compression Method Name Registry 482 This specification creates a new IANA registry for names of 483 compression methods to be used with the WebSocket Per-frame 484 Compression Extension in accordance with the principles set out in 485 [RFC5226]. 487 As part of this registry, IANA maintains the following information: 489 Method Identifier 490 The identifier of the method, as will be used in the method 491 description as defined Section 3 of this specification. The value 492 must conform to the method-name ABNF as defined in Section 3 of 493 this specification. 495 Method Common Name 496 The name of the method, as the method is generally referred to. 498 Method Definition 499 A reference to the document in which the method being used with 500 this extension is defined. 502 WebSocket Per-frame Compression method names are to be subject to the 503 "First Come First Served" IANA registration policy [RFC5226]. 505 IANA has added initial values to the registry as follows. 507 +------------+-------------+---------------+ 508 | Identifier | Common Name | Definition | 509 +------------+-------------+---------------+ 510 | deflate | DEFLATE | This document | 511 +------------+-------------+---------------+ 513 8. Acknowledgements 515 Special thanks to Patrick McManus who wrote up the initial 516 specification of DEFLATE based compression extension for the 517 WebSocket Protocol to which I referred to write this specification. 519 9. References 521 9.1. Normative References 523 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 524 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 525 May 2008. 527 [RFC6455] Fette, I. and A. Melnikov, "The WebSocket Protocol", 528 RFC 6455, December 2011. 530 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 531 Requirement Levels", BCP 14, RFC 2119, March 1997. 533 [LZ77] Ziv, J. and A. Lempel, "A Universal Algorithm for 534 Sequential Data Compression", IEEE Transactions on 535 Information Theory, Vol. 23, No. 3, pp. 337-343. 537 9.2. Informative References 539 [RFC1951] Deutsch, P., "DEFLATE Compressed Data Format Specification 540 version 1.3", RFC 1951, May 1996. 542 [RFC1979] Woods, J., "PPP Deflate Protocol", RFC 1979, August 1996. 544 [Zlib] Gailly, J. and M. Adler, "Zlib", . 546 Author's Address 548 Takeshi Yoshino 549 Google, Inc. 551 Email: tyoshino@google.com