idnits 2.17.1 draft-kerwin-http2-encoded-data-09.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 (October 11, 2016) is 2752 days in the past. Is this intentional? Checking references for intended status: Experimental ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 7540 (Obsoleted by RFC 9113) -- Obsolete informational reference (is this intentional?): RFC 3230 (Obsoleted by RFC 9530) -- Obsolete informational reference (is this intentional?): RFC 7230 (Obsoleted by RFC 9110, RFC 9112) Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Kerwin 3 Internet-Draft October 11, 2016 4 Intended status: Experimental 5 Expires: April 14, 2017 7 HTTP/2 Gzipped Data 8 draft-kerwin-http2-encoded-data-09 10 Abstract 12 This document introduces a new frame type for transporting gzip- 13 encoded data between peers in the Hypertext Transfer Protocol Version 14 2 (HTTP/2), and an associated error code for handling invalid 15 encoding. 17 Note to Readers 19 The issues list for this draft can be found at 20 23 The most recent (often unpublished) draft is at 24 26 Status of This Memo 28 This Internet-Draft is submitted in full conformance with the 29 provisions of BCP 78 and BCP 79. 31 Internet-Drafts are working documents of the Internet Engineering 32 Task Force (IETF). Note that other groups may also distribute 33 working documents as Internet-Drafts. The list of current Internet- 34 Drafts is at http://datatracker.ietf.org/drafts/current/. 36 Internet-Drafts are draft documents valid for a maximum of six months 37 and may be updated, replaced, or obsoleted by other documents at any 38 time. It is inappropriate to use Internet-Drafts as reference 39 material or to cite them other than as "work in progress." 41 This Internet-Draft will expire on April 14, 2017. 43 Copyright Notice 45 Copyright (c) 2016 IETF Trust and the persons identified as the 46 document authors. All rights reserved. 48 This document is subject to BCP 78 and the IETF Trust's Legal 49 Provisions Relating to IETF Documents 50 (http://trustee.ietf.org/license-info) in effect on the date of 51 publication of this document. Please review these documents 52 carefully, as they describe your rights and restrictions with respect 53 to this document. Code Components extracted from this document must 54 include Simplified BSD License text as described in Section 4.e of 55 the Trust Legal Provisions and are provided without warranty as 56 described in the Simplified BSD License. 58 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 61 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 2 62 2. Additions to HTTP/2 . . . . . . . . . . . . . . . . . . . . . 3 63 2.1. SETTINGS_ACCEPT_GZIPPED_DATA . . . . . . . . . . . . . . 3 64 2.2. GZIPPED_DATA . . . . . . . . . . . . . . . . . . . . . . 3 65 2.3. DATA_ENCODING_ERROR . . . . . . . . . . . . . . . . . . . 5 66 3. Experimental Status . . . . . . . . . . . . . . . . . . . . . 5 67 4. Security Considerations . . . . . . . . . . . . . . . . . . . 6 68 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 69 5.1. HTTP/2 Frame Type Registry Update . . . . . . . . . . . . 6 70 5.2. HTTP/2 Settings Registry Update . . . . . . . . . . . . . 7 71 5.3. HTTP/2 Error Code Registry Update . . . . . . . . . . . . 7 72 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 7 73 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 7 74 7.1. Normative References . . . . . . . . . . . . . . . . . . 7 75 7.2. Informative References . . . . . . . . . . . . . . . . . 8 76 Appendix A. Changelog . . . . . . . . . . . . . . . . . . . . . 8 77 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 9 79 1. Introduction 81 This document introduces a mechanism for applying gzip encoding 82 [RFC1952] to data transported between two endpoints in the Hypertext 83 Transfer Protocol Version 2 (HTTP/2) [RFC7540], analogous to 84 Transfer-Encoding in HTTP/1.1 [RFC7230]. 86 1.1. Notational Conventions 88 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 89 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 90 document are to be interpreted as described in [RFC2119]. 92 2. Additions to HTTP/2 94 This document introduces a new HTTP/2 frame type ([RFC7540], 95 Section 11.2), a new HTTP/2 setting ([RFC7540], Section 11.3), and a 96 new HTTP/2 error code ([RFC7540], Section 7), to allow the 97 compression of data. 99 Note that while compressing some or all data in a stream might affect 100 the total length of the corresponding HTTP message body, the 101 "content-length" header, if present, should continue to reflect the 102 total length of the _uncompressed_ data. This is particularly 103 relevant when detecting malformed messages ([RFC7540], 104 Section 8.1.2.6). 106 2.1. SETTINGS_ACCEPT_GZIPPED_DATA 108 *NOTE*: This is an experimental value; if standardised, a permanent 109 value will be assigned. 111 SETTINGS_ACCEPT_GZIPPED_DATA (0xf000) is used to indicate the 112 sender's ability and willingness to receive GZIPPED_DATA frames. An 113 endpoint MUST NOT send a GZIPPED_DATA frame unless it receives this 114 setting with a value of 1. 116 The initial value is 0, which indicates that GZIPPED_DATA frames are 117 not supported. Any value other than 0 or 1 MUST be treated as a 118 connection error ([RFC7540], Section 5.4.1) of type PROTOCOL_ERROR. 120 An endpoint may advertise support for GZIPPED_DATA frames and later 121 decide that it no longer supports them. After sending an 122 ACCEPT_GZIPPED_DATA setting with the value 0, the endpoint SHOULD 123 continue to accept GZIPPED_DATA frames for a reasonable amount of 124 time to account for frames that may already be in flight. 126 2.2. GZIPPED_DATA 128 *NOTE*: This is an experimental value; if standardised, a permanent 129 value will be assigned. 131 GZIPPED_DATA frames (type code=0xf000) are semantically identical to 132 DATA frames ([RFC7540], Section 6.1), but their payload is encoded 133 using gzip compression. Significantly: the order of DATA and 134 GZIPPED_DATA frames is semantically significant; and GZIPPED_DATA 135 frames are subject to flow control ([RFC7540], Section 5.2). Gzip 136 compression is an LZ77 coding with a 32 bit CRC that is commonly 137 produced by the gzip file compression program [RFC1952]. 139 Any compression or decompression context for a GZIPPED_DATA frame is 140 unique to that frame. An endpoint MAY interleave DATA and 141 GZIPPED_DATA frames on a single stream. 143 +---------------+ 144 |Pad Length? (8)| 145 +---------------+-----------------------------------------------+ 146 | Data (*) ... 147 +---------------------------------------------------------------+ 148 | Padding (*) ... 149 +---------------------------------------------------------------+ 151 GZIPPED_DATA Frame Payload 153 The GZIPPED_DATA frame contains the following fields: 155 o Pad Length: An 8-bit field containing the length of the frame 156 padding in units of octets. This field is optional and is only 157 present if the PADDED flag is set. 159 o Data: Encoded application data. The amount of encoded data is the 160 remainder of the frame payload after subtracting the length of the 161 other fields that are present. 163 o Padding: Padding octets that contain no application semantic 164 value. Padding octets MUST be set to zero when sending and 165 ignored when receiving. 167 The GZIPPED_DATA frame defines the following flags: 169 o "END_STREAM" (0x1): Bit 1 being set indicates that this frame is 170 the last that the endpoint will send for the identified stream. 171 Setting this flag causes the stream to enter one of the "half 172 closed" states or the "closed" state ([RFC7540], Section 5.1). 174 o "PADDED" (0x8): Bit 4 being set indicates that the Pad Length 175 field is present. 177 A GZIPPED_DATA frame MUST NOT be sent if the ACCEPT_GZIPPED_DATA 178 setting of the peer is set to 0. See Section 3. 180 An intermediary, on receiving a GZIPPED_DATA frame, MAY decode the 181 data and forward it to its downstream peer in one or more DATA 182 frames. If the downstream peer has not advertised support for 183 GZIPPED_DATA frames (by sending an ACCEPT_GZIPPED_DATA setting with 184 the value 1) the intermediary MUST decode the data before forwarding 185 it. 187 If an endpoint detects that the payload of a GZIPPED_DATA frame is 188 not encoded correctly, for example with an incorrect checksum, the 189 endpoint MUST treat this as a stream error (see [RFC7540], 190 Section 5.4.2) of type DATA_ENCODING_ERROR (Section 2.3). The 191 endpoint MAY then choose to immediately send an ACCEPT_GZIPPED_DATA 192 setting with the value 0. 194 If an intermediary propagates a GZIPPED_DATA frame from the source 195 peer to the destination peer without modifying the payload or its 196 encoding, and receives a DATA_ENCODING_ERROR from the receiving peer, 197 it SHOULD pass the error on to the source peer. 199 GZIPPED_DATA frames MUST be associated with a stream. If a 200 GZIPPED_DATA frame is received whose stream identifier field is 0x0, 201 the recipient MUST respond with a connection error ([RFC7540], 202 Section 5.4.1) of type PROTOCOL_ERROR. 204 GZIPPED_DATA frames are subject to flow control and can only be sent 205 when a stream is in the "open" or "half closed (remote)" states. The 206 entire GZIPPED_DATA frame payload is included in flow control, 207 including the Pad Length and Padding fields if present. If a 208 GZIPPED_DATA frame is received whose stream is not in "open" or "half 209 closed (local)" state, the recipient MUST respond with a stream error 210 ([RFC7540], Section 5.4.2) of type STREAM_CLOSED. 212 GZIPPED_DATA frames can include padding. Padding fields and flags 213 are identical to those defined for DATA frames ([RFC7540], 214 Section 6.1). 216 2.3. DATA_ENCODING_ERROR 218 The following new error code is defined: 220 o "DATA_ENCODING_ERROR" (0xf0000000): The endpoint detected that its 221 peer sent a GZIPPED_DATA frame with an invalid encoding. 223 *NOTE*: This is an experimental value; if standardised, a 224 permanent value will be assigned. 226 3. Experimental Status 228 This extension is classified as an experiment because it alters the 229 base semantics of HTTP/2; a change that, if specified insufficiently 230 or implemented incorrectly, could result in data loss that is hard to 231 detect or diagnose. 233 [RFC7540], Section 5.5, mandates that "implementations MUST discard 234 frames that have unknown or unsupported types"; so if an endpoint or 235 intermediary mishandles GZIPPED_DATA frames, for example by 236 incorrectly emitting an ACCEPT_GZIPPED_DATA setting or propagating 237 GZIPPED_DATA frames, and those frames are subsequently discarded, 238 data will be lost. There is no reliable mechanism to detect such a 239 loss[*]. 241 The experiment therefore is to explore the robustness of the HTTP/2 242 ecosystem in the presence of such potential failures. 244 [*] For some unreliable mechanisms (i.e. not guaranteed to be in use 245 in all cases, and/or requiring inspection of HTTP headers) see: 247 o Section 8.1.2.6 of [RFC7540], for using the content-length header 248 to detect malformed messages 250 o [RFC3230], for HTTP instance digests 252 4. Security Considerations 254 Further to the Use of Compression in HTTP/2 ([RFC7540], 255 Section 10.6), intermediaries MUST NOT apply compression to DATA 256 frames, or alter the compression of GZIPPED_DATA frames other than 257 decompressing, unless additional information is available that allows 258 the intermediary to identify the source of data. In particular, 259 frames that are not compressed cannot be compressed, and frames that 260 are separately compressed cannot be merged into a single compressed 261 frame. 263 5. IANA Considerations 265 This document updates the registries for frame types, settings, and 266 error codes in the "Hypertext Transfer Protocol (HTTP) 2 Parameters" 267 section. 269 5.1. HTTP/2 Frame Type Registry Update 271 This document updates the "HTTP/2 Frame Type" registry ([RFC7540], 272 Section 11.2). The entries in the following table are registered by 273 this document. 275 +--------------+------+-------------+ 276 | Frame Type | Code | Section | 277 +--------------+------+-------------+ 278 | GZIPPED_DATA | TBD | Section 2.2 | 279 +--------------+------+-------------+ 281 5.2. HTTP/2 Settings Registry Update 283 This document updates the "HTTP/2 Settings" registry ([RFC7540], 284 Section 11.3). The entries in the following table are registered by 285 this document. 287 +---------------------+------+---------------+---------------+ 288 | Frame Type | Code | Initial Value | Specification | 289 +---------------------+------+---------------+---------------+ 290 | ACCEPT_GZIPPED_DATA | TBD | 0 | Section 2.1 | 291 +---------------------+------+---------------+---------------+ 293 5.3. HTTP/2 Error Code Registry Update 295 This document updates the "HTTP/2 Error Code" registry ([RFC7540], 296 Section 11.4). The entries in the following table are registered by 297 this document. 299 +---------------------+------+----------------------+---------------+ 300 | Name | Code | Description | Specification | 301 +---------------------+------+----------------------+---------------+ 302 | DATA_ENCODING_ERROR | TBD | Invalid encoding | Section 2.3 | 303 | | | detected | | 304 +---------------------+------+----------------------+---------------+ 306 6. Acknowledgements 308 Thanks to Keith Morgan for his advice, input, and editorial 309 contributions. 311 7. References 313 7.1. Normative References 315 [RFC1952] Deutsch, P., "GZIP file format specification version 4.3", 316 RFC 1952, DOI 10.17487/RFC1952, May 1996, 317 . 319 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 320 Requirement Levels", BCP 14, RFC 2119, 321 DOI 10.17487/RFC2119, March 1997, 322 . 324 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 325 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 326 DOI 10.17487/RFC7540, May 2015, 327 . 329 7.2. Informative References 331 [RFC3230] Mogul, J. and A. Van Hoff, "Instance Digests in HTTP", 332 RFC 3230, DOI 10.17487/RFC3230, January 2002, 333 . 335 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 336 Protocol (HTTP/1.1): Message Syntax and Routing", 337 RFC 7230, DOI 10.17487/RFC7230, June 2014, 338 . 340 Appendix A. Changelog 342 Since -08: 344 o use experimental values for frame/setting/error codes 346 Since -07: 348 o define "reliable" in the 'experimental' section, and provide 349 pointers to potential workarounds 351 o remove fragmentation, since the text added no value 353 Since -06: 355 o change document title from "Encoded" to "Gzipped" 357 o improve text under GZIPPED_DATA (Section 2.2) 359 o clarify that GZIPPED_DATA and DATA can be interleaved 361 o explain experimental status and risks of broken implementations 363 Since -05: 365 o changed ACCEPT_ENCODED_DATA back from a frame to a setting, since 366 it carries a single scalar value now 368 Since -04: 370 o reduced encoding options to only gzip (suggested by Martin 371 Thomson) 373 o remove fragmentation and segment stuff, including reference to 374 'http2-segments' I-D 376 o updated HTTP/2 reference from I-D to (freshly published) RFC7230 377 Since -03: 379 o added 'identity' encoding; removed 'compress' and 'zlib' 380 (suggested by PHK) 382 o added SEGMENT flag, for segments that don't continue 384 o clarified that ACCEPT is for a connection, and ENCODED_DATA is for 385 a stream 387 o copied "padding" text from HTTP/2 draft 389 Since -02: 391 o moved all discussion of fragmentation and segments to its own 392 section 394 Since -01: 396 o referenced new draft-kerwin-http2-segments to handle fragmentation 398 Since -00: 400 o changed ACCEPT_ENCODED_DATA from a complex setting to a frame 402 o improved IANA Considerations section (with lots of input from 403 Keith Morgan) 405 Author's Address 407 Matthew Kerwin 409 Email: matthew@kerwin.net.au 410 URI: http://matthew.kerwin.net.au/