HTTP/2 Extended SETTINGS Extension
draft-bishop-httpbis-extended-settings-00

Abstract

HTTP/2 defines the SETTINGS frame to contain a single 32-bit value per setting. While this is sufficient to convey everything used in the core HTTP/2 specification, some protocols will require more complex values, such as arrays of code-points or strings.

For such protocols, this extension defines a parallel to the SETTINGS frame, EXTENDED_SETTINGS, where the value of a setting is not a 32-bit value, but a variable-length opaque data blob whose interpretation is subject entirely to the definition of the protocol using it.

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 15, 2016.

Copyright Notice

Copyright (c) 2016 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.

Table of Contents

• 1. Introduction
• 2. Detection of Support
• 3. Extension Frame Types
• 3.1. EXTENDED_SETTINGS Frame
• 3.1.1. EXTENDED_SETTINGS Format
• 3.2. EXTENDED_SETTINGS_ACK Frame
• 4. Settings Synchronization
• 5. Security Considerations
• 6. IANA Considerations
• 6.1. Extended Settings Identifiers
• 6.2. New HTTP/2 Frames
• 6.3. HTTP/2 SETTINGS_HTTP_CERT_AUTH Setting
• 7. References
• 7.1. Normative References
• 7.2. Informative References
• Author's Address

1. Introduction

In [I-D.bishop-httpbis-http2-additional-certs], values for which IANA registries already exist must be communicated between two HTTP/2 implementations. Since the SETTINGS frame constrains setting values to a 32-bit value, the existing version of that draft divides the 32-bit value into halves and dedicates bits to each currently-known value. This requires the creation of two duplicative IANA registries, and enormously constrains future extensibility since each future supported value will consume one of only sixteen bits. It also causes divergence from other places in the protocol where a bitmask is not required and a more sensible value can be used.

[MS-HTTP2E], likewise, defines a very limited bitmap in the 32-bit value – two bits are defined, all others are reserved (and not useful). The setting fits easily in a single byte, and need not consume a four-byte value every time it is transferred. With minor changes to semantics, a simple flag would have been sufficient – the primary requirement is communication to the remote endpoint that an extension is supported.

Alternately, a number of recent and in-progress HTTP/2 extensions describe properties of the connection that are informative to the peer ([RFC7838], [I-D.ietf-httpbis-origin-frame]). These can be viewed as connection properties that do not fit into a 32-bit value and therefore have new frame types defined to carry them instead.

Each extension could define its own SETTINGS-equivalent frame to carry this data, as some extensions already have, but to do so every time a new extension might require such a capability seems similarly wasteful, given the limited frame type space (also an IANA registry).

Instead, this draft proposes a unified EXTENDED_SETTINGS frame (and accompanying settings synchronization logic) which permits values of lengths other than 32 bits. These values are interpreted as defined by the specification defining them, operate under similar semantics to the original SETTINGS frame, and should make development of future extensions much simpler.

2. Detection of Support

An HTTP/2 peer that supports the EXTENDED_SETTINGS frame indicates this using the HTTP/2 SETTINGS_EXTENDED_SETTINGS (0xSETTING-TBD) setting.

The initial value for the SETTINGS_EXTENDED_SETTINGS setting is 0 (0x00), indicating that the peer does not support the EXTENDED_SETTINGS frame. A peer that is able to parse the EXTENDED_SETTINGS frame MUST set this value to 1 (0x01).

This setting MUST be sent before any of the frame types in Section 3 are sent, but those frames MAY be sent before the setting is acknowledged and MAY be sent regardless of whether the peer has sent this setting.

3. Extension Frame Types

3.1. EXTENDED_SETTINGS Frame

The EXTENDED_SETTINGS frame (type=0xFRAME-TBD1) conveys configuration parameters that affect how endpoints communicate, such as preferences and constraints on peer behavior which occur in a form other than a 32-bit value. Individually, an EXTENDED_SETTINGS parameter can also be referred to as a “setting”.

EXTENDED_SETTINGS parameters are not negotiated; they describe characteristics of the sending peer, which are used by the receiving peer. However, a negotiation can be implied by the use of EXTENDED_SETTINGS – a peer uses EXTENDED_SETTINGS to advertise a set of supported values. The recipient can then choose which entries from this list are also acceptable and proceed with the value it has chosen. (This choice could be announced in a field of an extension frame, or in a different setting.)

Different values for the same parameter can be advertised by each peer. For example, a server might support many different signing algorithms, while a resource constrained client has only one or two that it can validate.

An EXTENDED_SETTINGS frame MAY be sent at any time by either endpoint over the lifetime of the connection.

Each parameter in an EXTENDED_SETTINGS frame replaces any existing value for that parameter. Parameters are processed in the order in which they appear, and a receiver of an EXTENDED_SETTINGS frame does not need to maintain any state other than the current value of its parameters. Therefore, the value of a EXTENDED_SETTINGS parameter is the last value that is seen by a receiver.

EXTENDED_SETTINGS parameters can request acknowledgement by the receiving peer. To enable this, the EXTENDED_SETTINGS frame defines the following flag:

REQUEST_ACK (0x1):

When set, bit 0 indicates that this frame contains values which the sender wants to know were understood and applied. For more information, see Section 4.

Like SETTINGS frames, EXTENDED_SETTINGS frames always apply to a connection, never a single stream. The stream identifier for an EXTENDED_SETTINGS frame MUST be zero (0x0). If an endpoint receives an EXTENDED_SETTINGS frame whose stream identifier field is anything other than 0x0, the endpoint MUST respond with a connection error ([RFC7540], section 5.4.1) of type PROTOCOL_ERROR.

The EXTENDED_SETTINGS frame affects connection state. A badly formed or incomplete EXTENDED_SETTINGS frame MUST be treated as a connection error ([RFC7540], section 5.4.1) of type PROTOCOL_ERROR.

3.1.1. EXTENDED_SETTINGS Format

The payload of an EXTENDED_SETTINGS frame consists of zero or more parameters, each consisting of an unsigned 16-bit setting identifier and a length-prefixed binary value.

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
+-------------------------------+---------------+---------------+
|        Identifier (16)        |         Length (16)           |
+-----------------------------------------------+---------------+
|                          Contents (?)                       ...
+---------------------------------------------------------------+

+-----------------------+--------------+-------------------------+
| Frame Type            | Code         | Specification           |
+-----------------------+--------------+-------------------------+
| EXTENDED_SETTINGS     | 0xFRAME-TBD1 | {{settings-frame}}      |
| EXTENDED_SETTINGS_ACK | 0xFRAME-TBD2 | {{ack}}                 |
+-----------------------+--------------+-------------------------+