Network Working Group M. Kerwin
Internet-Draft June 16, 2015
Intended status: Experimental
Expires: December 18, 2015
HTTP/2 Encoded Data
draft-kerwin-http2-encoded-data-06
Abstract
This document introduces a new frame type for transporting gzip-
encoded data between peers in the Hypertext Transfer Protocol Version
2 (HTTP/2), and an associated error code for handling invalid
encoding.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on December 18, 2015.
Copyright Notice
Copyright (c) 2015 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Kerwin Expires December 18, 2015 [Page 1]
Internet-Draft http2-encoded-data June 2015
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. Notational Conventions . . . . . . . . . . . . . . . . . 2
2. Additions to HTTP/2 . . . . . . . . . . . . . . . . . . . . . 2
2.1. SETTINGS_ACCEPT_GZIPPED_DATA . . . . . . . . . . . . . . 3
2.2. GZIPPED_DATA . . . . . . . . . . . . . . . . . . . . . . 3
2.3. DATA_ENCODING_ERROR . . . . . . . . . . . . . . . . . . . 5
3. Fragmentation . . . . . . . . . . . . . . . . . . . . . . . . 5
4. Security Considerations . . . . . . . . . . . . . . . . . . . 5
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 5
5.1. HTTP/2 Frame Type Registry Update . . . . . . . . . . . . 5
5.2. HTTP/2 Settings Registry Update . . . . . . . . . . . . . 6
5.3. HTTP/2 Error Code Registry Update . . . . . . . . . . . . 6
6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 6
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 6
7.1. Normative References . . . . . . . . . . . . . . . . . . 6
7.2. Informative References . . . . . . . . . . . . . . . . . 7
Appendix A. Changelog . . . . . . . . . . . . . . . . . . . . . 7
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 8
1. Introduction
This document introduces a mechanism for applying gzip encoding
[RFC1952] to data transported between two endpoints in the Hypertext
Transfer Protocol Version 2 (HTTP/2) [RFC7540], analogous to
Transfer-Encoding in HTTP/1.1 [RFC7230].
1.1. Notational Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119].
2. Additions to HTTP/2
This document introduces a new HTTP/2 frame type ([RFC7540],
Section 11.2), a new HTTP/2 setting ([RFC7540], Section 11.3), and a
new HTTP/2 error code ([RFC7540], Section 7), to allow the
compression of data.
Note that while compressing some or all data in a stream might affect
the total length of the corresponding HTTP message body, the
"content-length" header, if present, should continue to reflect the
total length of the _uncompressed_ data. This is particularly
relevant when detecting malformed messages ([RFC7540],
Section 8.1.2.6).
Kerwin Expires December 18, 2015 [Page 2]
Internet-Draft http2-encoded-data June 2015
2.1. SETTINGS_ACCEPT_GZIPPED_DATA
SETTINGS_ACCEPT_GZIPPED_DATA (0xTBA) is used to indicate the sender's
ability and willingness to receive GZIPPED_DATA frames. An endpoint
MUST NOT send a GZIPPED_DATA frame unless it receives this setting
with a value of 1.
The initial value is 0, which indicates that GZIPPED_DATA frames are
not supported. Any value other than 0 or 1 MUST be treated as a
connection error ([RFC7540], Section 5.4.1) of type PROTOCOL_ERROR.
An endpoint may advertise support for GZIPPED_DATA frames and later
decide that it no longer supports them. After sending an
ACCEPT_GZIPPED_DATA setting with the value 0, the endpoint SHOULD
continue to accept GZIPPED_DATA frames for a reasonable amount of
time to account for frames that may already be in flight.
2.2. GZIPPED_DATA
GZIPPED_DATA frames (type code=0xTBA) are semantically identical to
DATA frames ([RFC7540], Section 6.1), but their payload is encoded
using gzip compression. Gzip compression is an LZ77 coding with a 32
bit CRC that is commonly produced by the gzip file compression
program [RFC1952]. Significantly, GZIPPED_DATA frames are subject to
flow control ([RFC7540], Section 5.2).
Any compression or decompression context for a GZIPPED_DATA frame is
unique to that frame.
+---------------+
|Pad Length? (8)|
+---------------+-----------------------------------------------+
| Data (*) ...
+---------------------------------------------------------------+
| Padding (*) ...
+---------------------------------------------------------------+
GZIPPED_DATA Frame Payload
The GZIPPED_DATA frame contains the following fields:
o Pad Length: An 8-bit field containing the length of the frame
padding in units of octets. This field is optional and is only
present if the PADDED flag is set.
o Data: Encoded application data. The amount of compressed data is
the remainder of the frame payload after subtracting the length of
the other fields that are present.
Kerwin Expires December 18, 2015 [Page 3]
Internet-Draft http2-encoded-data June 2015
o Padding: Padding octets that contain no application semantic
value. Padding octets MUST be set to zero when sending and
ignored when receiving.
The GZIPPED_DATA frame defines the following flags:
o "END_STREAM" (0x1): Bit 1 being set indicates that this frame is
the last that the endpoint will send for the identified stream.
Setting this flag causes the stream to enter one of the "half
closed" states or the "closed" state ([RFC7540], Section 5.1).
o "PADDED" (0x8): Bit 4 being set indicates that the Pad Length
field is present.
A GZIPPED_DATA frame MUST NOT be sent if the ACCEPT_GZIPPED_DATA
setting of the peer is set to 0.
An intermediary, on receiving a GZIPPED_DATA frame, MAY decode the
data and forward it to its downstream peer in one or more DATA
frames. If the downstream peer has not advertised support for
GZIPPED_DATA frames (by sending an ACCEPT_GZIPPED_DATA setting with
the value 1) the intermediary MUST decode the data before forwarding
it.
If an endpoint detects that the payload of a GZIPPED_DATA frame is
not encoded correctly, for example with an incorrect checksum, the
endpoint MUST treat this as a stream error (see [RFC7540],
Section 5.4.2) of type DATA_ENCODING_ERROR (Section 2.3). The
endpoint MAY then choose to immediately send an ACCEPT_GZIPPED_DATA
setting with the value 0.
If an intermediary propagates a GZIPPED_DATA frame from the source
peer to the destination peer without modifying the payload or its
encoding, and receives a DATA_ENCODING_ERROR from the receiving peer,
it SHOULD pass the error on to the source peer.
GZIPPED_DATA frames MUST be associated with a stream. If a
GZIPPED_DATA frame is received whose stream identifier field is 0x0,
the recipient MUST respond with a connection error ([RFC7540],
Section 5.4.1) of type PROTOCOL_ERROR.
GZIPPED_DATA frames are subject to flow control and can only be sent
when a stream is in the "open" or "half closed (remote)" states. The
entire GZIPPED_DATA frame payload is included in flow control,
including the Pad Length and Padding fields if present. If a
GZIPPED_DATA frame is received whose stream is not in "open" or "half
closed (local)" state, the recipient MUST respond with a stream error
([RFC7540], Section 5.4.2) of type STREAM_CLOSED.
Kerwin Expires December 18, 2015 [Page 4]
Internet-Draft http2-encoded-data June 2015
The total number of padding octets is determined by the value of the
Pad Length field. If the length of the padding is greater than the
length of the remainder of the frame payload, the recipient MUST
treat this as a connection error ([RFC7540], Section 5.4.1) of type
PROTOCOL_ERROR.
Note: A frame can be increased in size by one octet by including a
Pad Length field with a value of zero.
Padding is a security feature; see Section 10.7 of [RFC7540].
2.3. DATA_ENCODING_ERROR
The following new error code is defined:
o "DATA_ENCODING_ERROR" (0xTBA): The endpoint detected that its peer
sent a GZIPPED_DATA frame with an invalid encoding.
3. Fragmentation
Traversing a network segment with small frame size limits introduces
the risk of fragmenting an encoded stream.
4. Security Considerations
Further to the Use of Compression in HTTP/2 ([RFC7540],
Section 10.6), intermediaries MUST NOT apply compression to DATA
frames, or alter the compression of GZIPPED_DATA frames other than
decompressing, unless additional information is available that allows
the intermediary to identify the source of data. In particular,
frames that are not compressed cannot be compressed, and frames that
are separately compressed cannot be merged into a single compressed
frame.
5. IANA Considerations
This document updates the registries for frame types and error codes
in the "Hypertext Transfer Protocol (HTTP) 2 Parameters" section.
This document also establishes a new registry for HTTP/2 encoding
scheme codes. This new registry is entered into the "Hypertext
Transfer Protocol (HTTP) 2 Parameters" section.
5.1. HTTP/2 Frame Type Registry Update
This document updates the "HTTP/2 Frame Type" registry ([RFC7540],
Section 11.2). The entries in the following table are registered by
this document.
Kerwin Expires December 18, 2015 [Page 5]
Internet-Draft http2-encoded-data June 2015
+--------------+------+-------------+
| Frame Type | Code | Section |
+--------------+------+-------------+
| GZIPPED_DATA | TBD | Section 2.2 |
+--------------+------+-------------+
5.2. HTTP/2 Settings Registry Update
This document updates the "HTTP/2 Settings" registry ([RFC7540],
Section 11.3). The entries in the following table are registered by
this document.
+---------------------+------+---------------+---------------+
| Frame Type | Code | Initial Value | Specification |
+---------------------+------+---------------+---------------+
| ACCEPT_GZIPPED_DATA | TBD | 0 | Section 2.1 |
+---------------------+------+---------------+---------------+
5.3. HTTP/2 Error Code Registry Update
This document updates the "HTTP/2 Error Code" registry ([RFC7540],
Section 11.4). The entries in the following table are registered by
this document.
+---------------------+------+----------------------+---------------+
| Name | Code | Description | Specification |
+---------------------+------+----------------------+---------------+
| DATA_ENCODING_ERROR | TBD | Invalid encoding | Section 2.3 |
| | | detected | |
+---------------------+------+----------------------+---------------+
6. Acknowledgements
Thanks to Keith Morgan for his advice, input, and editorial
contributions.
7. References
7.1. Normative References
[RFC1952] Deutsch, P., Gailly, J-L., Adler, M., Deutsch, L., and G.
Randers-Pehrson, "GZIP file format specification version
4.3", RFC 1952, May 1996.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
Kerwin Expires December 18, 2015 [Page 6]
Internet-Draft http2-encoded-data June 2015
[RFC7540] Belshe, M., Peon, R., and M. Thomson, "Hypertext Transfer
Protocol Version 2 (HTTP/2)", RFC 7540, May 2015.
7.2. Informative References
[RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol
(HTTP/1.1): Message Syntax and Routing", RFC 7230, June
2014.
Appendix A. Changelog
Since -05:
o changed ACCEPT_ENCODED_DATA back from a frame to a setting, since
it carries a single scalar value now
Since -04:
o reduced encoding options to only gzip (suggested by Martin
Thomson)
o remove fragmentation and segment stuff, including reference to
'http2-segments' I-D
o updated HTTP/2 reference from I-D to (freshly published) RFC7230
Since -03:
o added 'identity' encoding; removed 'compress' and 'zlib'
(suggested by PHK)
o added SEGMENT flag, for segments that don't continue
o clarified that ACCEPT is for a connection, and ENCODED_DATA is for
a stream
o copied "padding" text from HTTP/2 draft
Since -02:
o moved all discussion of fragmentation and segments to its own
section
Since -01:
o referenced new draft-kerwin-http2-segments to handle fragmentation
Since -00:
Kerwin Expires December 18, 2015 [Page 7]
Internet-Draft http2-encoded-data June 2015
o changed ACCEPT_ENCODED_DATA from a complex setting to a frame
o improved IANA Considerations section (with lots of input from
Keith Morgan)
Author's Address
Matthew Kerwin
Email: matthew@kerwin.net.au
URI: http://matthew.kerwin.net.au/
Kerwin Expires December 18, 2015 [Page 8]