[Docs] [txt|pdf|xml] [Tracker] [Email] [Diff1] [Diff2] [Nits]
Versions: 00 01 02 03 04 05 06 07 08 09
Network Working Group M. Kerwin
Internet-Draft
Intended status: Standards Track July 28, 2014
Expires: January 29, 2015
HTTP/2 Encoded Data
draft-kerwin-http2-encoded-data-02
Abstract
This document introduces new frame types for transporting encoded
data in HTTP/2, and an associated error code.
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 January 29, 2015.
Copyright Notice
Copyright (c) 2014 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 January 29, 2015 [Page 1]
Internet-Draft http2-encoded-data July 2014
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. Notational Conventions . . . . . . . . . . . . . . . . . 2
2. Additions to HTTP/2 . . . . . . . . . . . . . . . . . . . . . 2
2.1. ACCEPT_ENCODED_DATA . . . . . . . . . . . . . . . . . . . 3
2.2. ENCODED_DATA . . . . . . . . . . . . . . . . . . . . . . 4
2.3. DATA_ENCODING_ERROR . . . . . . . . . . . . . . . . . . . 6
3. Encoding Schemes . . . . . . . . . . . . . . . . . . . . . . 6
4. Security Considerations . . . . . . . . . . . . . . . . . . . 6
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6
5.1. HTTP/2 Frame Type Registry Update . . . . . . . . . . . . 7
5.2. HTTP/2 Error Code Registry Update . . . . . . . . . . . . 7
5.3. HTTP/2 Encoding Schemes Registry . . . . . . . . . . . . 7
6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 8
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 8
7.1. Normative References . . . . . . . . . . . . . . . . . . 8
7.2. Informative References . . . . . . . . . . . . . . . . . 8
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 9
1. Introduction
This document introduces a mechanism for applying encoding,
particularly compression, to data transported between two HTTP/2
endpoints, 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 two new HTTP/2 frame types
([I-D.ietf-httpbis-http2], Section 11.2) and a new HTTP/2 error code
([I-D.ietf-httpbis-http2], Section 7), to allow the application of
encoding, particularly compression, to data.
Note that while encoding 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 _unencoded_ data. This is particularly relevant
when detecting malformed messages ([I-D.ietf-httpbis-http2],
Section 8.1.2.5).
Kerwin Expires January 29, 2015 [Page 2]
Internet-Draft http2-encoded-data July 2014
2.1. ACCEPT_ENCODED_DATA
An ACCEPT_ENCODED_DATA frame (type code=0xTBA) is used to indicate
the sender's ability and willingness to receive ENCODED_DATA frames
that are encoded using the schemes identified in its payload.
The payload length of an ACCEPT_ENCODED_DATA frame MUST be an exact
multiple of 16 bits (2 bytes). An endpoint that receives an
ACCEPT_ENCODED_DATA frame with an odd length MUST treat this as a
connection error ([I-D.ietf-httpbis-http2], Section 5.4.1) of type
PROTOCOL_ERROR.
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Encoding (8) | Rank (8) | ...
+---------------+---------------+-------------------------------+
ACCEPT_ENCODED_DATA Frame Payload
The ACCEPT_ENCODED_DATA frame contains zero or more tuples
comprising the following fields:
o Encoding: An 8-bit identifier which identifies the encoding being
advertised (see Section 3).
o Rank: An 8-bit integer value.
The rank fulfils the same role as in the HTTP/1.1 TE header
([RFC7230], Section 4.3). The rank value is an integer in the range
0 through 255, where 1 is the least preferred and 255 is the most
preferred; a value of 0 means "not acceptable".
An endpoint that receives an ACCEPT_ENCODED_DATA frame containing
an {encoding,rank} tuple with an unknown or unsupported encoding
identifier MUST ignore that tuple.
Each ACCEPT_ENCODED_DATA frame fully replaces the set of tuples
sent in a previous frame; if an encoding identifier is omitted from a
subsequent ACCEPT_ENCODED_DATA frame it is deemed "not acceptable".
An endpoint may advertise support for an encoding scheme and later
decide that it no longer supports that scheme. After sending an
ACCEPT_ENCODED_DATA that omits the encoding identifier in question,
or includes it with a rank of 0, the endpoint SHOULD continue to
accept ENCODED_DATA frames using that scheme for a reasonable
amount of time to account for encoded frames that are already in
flight.
Kerwin Expires January 29, 2015 [Page 3]
Internet-Draft http2-encoded-data July 2014
The ACCEPT_ENCODED_DATA frame does not define any flags, and is not
subject to flow control.
2.2. ENCODED_DATA
ENCODED_DATA frames (type code=0xTBA) are semantically identical to
DATA frames ([I-D.ietf-httpbis-http2], Section 6.1), but have an
encoding applied to their payload. Significantly, ENCODED_DATA
frames are subject to flow control ([I-D.ietf-httpbis-http2],
Section 5.2).
Any encoding or decoding context for an ENCODED_DATA frame is
unique to that frame.
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|Pad Length? (8)|
+---------------+
| Encoding (8) |
+---------------+-----------------------------------------------+
| Data (*) ...
+---------------------------------------------------------------+
| Padding (*) ...
+---------------------------------------------------------------+
ENCODED_DATA Frame Payload
The ENCODED_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 Encoding: An 8-bit identifier which identifies the encoding that
has been applied to the Data field (see Section 3).
o Data: Encoded application data. The amount of encoded data is the
remainder of the frame payload after subtracting the length of the
other fields that are present.
o Padding: Padding octets that contain no application semantic
value. Padding octets MUST be set to zero when sending and
ignored when receiving.
The ENCODED_DATA frame defines the following flags:
Kerwin Expires January 29, 2015 [Page 4]
Internet-Draft http2-encoded-data July 2014
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 ([I-D.ietf-httpbis-http2],
Section 5.1).
o PADDED (0x8): Bit 4 being set indicates that the Pad Length
field is present.
o SEGMENT_CONTINUES (0x10): Bit 5 being set indicates that the
current segment continues after the current frame
([I-D.kerwin-http2-segments], Section 2). Intermediaries MUST NOT
coalesce frames across a segment boundary and MUST preserve
segment boundaries when forwarding frames.
On receiving an ENCODED_DATA frame, an intermediary MAY decode the
data and forward it in one or more DATA frames. If the downstream
peer does not support the encoding scheme used in the received frame,
as advertised in an ACCEPT_ENCODED_DATA frame, the intermediary
MUST decode the data and either: forward it in one or more DATA
frames, or encode it with a scheme supported by the downstream peer
and forward it in one or more ENCODED_DATA frames.
An intermediary MAY coalesce multiple adjacent ENCODED_DATA and
DATA frames if all of the frames, with the optional exception of
the final frame in the sequence, have the SEGMENT_CONTINUES flag
set. The coalesced payload MAY be subsequently emitted in any
combination of ENCODED_DATA and DATA frames. The payloads of any
resulting ENCODED_DATA frame MUST be correctly encoded according to
those frames' encodings; this could require the payloads of the
original frames to be decoded and subsequently re-encoded into the
new frames rather than simply concatenated.
An ENCODED_DATA frame MUST NOT be sent on a connection before
receiving an ACCEPT_ENCODED_DATA frame. A sender MUST NOT apply an
encoding that has not first been advertised by the peer in an
ACCEPT_ENCODED_DATA frame, or was advertised with a rank of 0.
Endpoints that receive a frame with an encoding they do not recognise
or support MUST treat this as a connection error of type
PROTOCOL_ERROR.
If an endpoint detects that the payload of an ENCODED_DATA frame is
incorrectly encoded it MUST treat this as a stream error (see
[I-D.ietf-httpbis-http2], Section 5.4.2) of type
DATA_ENCODING_ERROR (Section 2.3).
ENCODED_DATA frames are subject to flow control and can only be
sent when a stream is in the "open" or "half closed (remote)" states.
Kerwin Expires January 29, 2015 [Page 5]
Internet-Draft http2-encoded-data July 2014
The entire ENCODED_DATA frame payload is included in flow control,
including the encoded data, and Pad Length and Padding fields if
present. If an ENCODED_DATA frame is received whose stream is not
in "open" or "half closed (local)" state, the recipient MUST respond
with a stream error ([I-D.ietf-httpbis-http2], Section 5.4.2) of type
STREAM_CLOSED.
2.3. DATA_ENCODING_ERROR
The following new error code is defined:
o DATA_ENCODING_ERROR (0xTBA): The endpoint detected that its peer
sent an ENCODED_DATA frame with an invalid encoding.
3. Encoding Schemes
The following encoding schemes are defined:
o ENCODING_COMPRESS (1): The compress coding is an adaptive
Lempel-Ziv-Welch (LZW) coding [Welch] that is commonly produced by
the UNIX file compression program "compress".
o ENCODING_ZLIB (2): The zlib coding is a "zlib" data format
[RFC1950] containing a "deflate" compressed data stream [RFC1951]
that uses a combination of the Lempel-Ziv (LZ77) compression
algorithm and Huffman coding.
o ENCODING_GZIP (3): The gzip coding is an LZ77 coding with a 32
bit CRC that is commonly produced by the gzip file compression
program [RFC1952].
4. Security Considerations
Further to the Use of Compression in HTTP/2
([I-D.ietf-httpbis-http2], Section 10.6), intermediaries MUST NOT
apply compression to DATA frames, or alter the compression of
ENCODED_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 can only be
merged into a single compressed frame if they occupy the same
segment.
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
Kerwin Expires January 29, 2015 [Page 6]
Internet-Draft http2-encoded-data July 2014
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
([I-D.ietf-httpbis-http2], Section 11.2). The entries in the
following table are registered by this document.
+---------------------+------+-------------+
| Frame Type | Code | Section |
+---------------------+------+-------------+
| ACCEPT_ENCODED_DATA | TBD | Section 2.1 |
| ENCODED_DATA | TBD | Section 2.2 |
+---------------------+------+-------------+
5.2. HTTP/2 Error Code Registry Update
This document updates the "HTTP/2 Error Code" registry
([I-D.ietf-httpbis-http2], 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 | |
+---------------------+------+----------------------+---------------+
5.3. HTTP/2 Encoding Schemes Registry
This document establishes a registry for encoding scheme codes. The
"HTTP/2 Encoding Schemes" registry manages an 8-bit space. The
"HTTP/2 Encoding Schemes" registry operates under either of the "IETF
Review" or "IESG Approval" policies [RFC5226] for values between 0x00
and 0xef, with values between 0xf0 and 0xff being reserved for
experimental use.
New entries in this registry require the following information:
o Frame Type: A name or label for the encoding scheme.
o Code: The 8-bit code assigned to the encoding scheme.
o Specification: A reference to a specification that includes a
description of the encoding scheme.
Kerwin Expires January 29, 2015 [Page 7]
Internet-Draft http2-encoded-data July 2014
An initial set of encoding scheme code registrations can be found in
Section 3.
6. Acknowledgements
Thanks to Keith Morgan for his advice, input, and editorial
contributions.
7. References
7.1. Normative References
[I-D.ietf-httpbis-http2]
Belshe, M., Peon, R., and M. Thomson, "Hypertext Transfer
Protocol version 2", draft-ietf-httpbis-http2-13 (work in
progress), June 2014.
[I-D.kerwin-http2-segments]
Kerwin, M., "HTTP/2 Segments", draft-kerwin-
http2-segments-00 (work in progress), July 2014.
[RFC1950] Deutsch, L. and J-L. Gailly, "ZLIB Compressed Data Format
Specification version 3.3", RFC 1950, May 1996.
[RFC1951] Deutsch, P., "DEFLATE Compressed Data Format Specification
version 1.3", RFC 1951, May 1996.
[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.
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", BCP 26, RFC 5226,
May 2008.
[Welch] Welch, T., "A Technique for High-Performance Data
Compression", IEEE Computer 17(6), June 1984.
7.2. Informative References
[RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol
(HTTP/1.1): Message Syntax and Routing", RFC 7230, June
2014.
Kerwin Expires January 29, 2015 [Page 8]
Internet-Draft http2-encoded-data July 2014
Author's Address
Matthew Kerwin
Email: matthew@kerwin.net.au
URI: http://matthew.kerwin.net.au/
Kerwin Expires January 29, 2015 [Page 9]
Html markup produced by rfcmarkup 1.129d, available from
https://tools.ietf.org/tools/rfcmarkup/