idnits 2.17.1 draft-bishop-httpbis-extended-settings-01.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 : ---------------------------------------------------------------------------- ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 112: '...D_SETTINGS frame MUST set this value t...' RFC 2119 keyword, line 114: '... This setting MUST be sent before an...' RFC 2119 keyword, line 115: '...but those frames MAY be sent before th...' RFC 2119 keyword, line 116: '...acknowledged and MAY be sent regardles...' RFC 2119 keyword, line 144: '...D_SETTINGS frame MAY be sent at any ti...' (18 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (November 15, 2016) is 2718 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 7540 (Obsoleted by RFC 9113) == Outdated reference: A later version (-05) exists of draft-bishop-httpbis-http2-additional-certs-02 == Outdated reference: A later version (-06) exists of draft-ietf-httpbis-origin-frame-01 Summary: 3 errors (**), 0 flaws (~~), 3 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTPbis M. Bishop 3 Internet-Draft Microsoft 4 Intended status: Informational November 15, 2016 5 Expires: May 19, 2017 7 HTTP/2 Extended SETTINGS Extension 8 draft-bishop-httpbis-extended-settings-01 10 Abstract 12 HTTP/2 defines the SETTINGS frame to contain a single 32-bit value 13 per setting. While this is sufficient to convey everything used in 14 the core HTTP/2 specification, some protocols will require more 15 complex values, such as arrays of code-points or strings. 17 For such protocols, this extension defines a parallel to the SETTINGS 18 frame, EXTENDED_SETTINGS, where the value of a setting is not a 19 32-bit value, but a variable-length opaque data blob whose 20 interpretation is subject entirely to the definition of the protocol 21 using it. 23 Status of This Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at http://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on May 19, 2017. 40 Copyright Notice 42 Copyright (c) 2016 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents 47 (http://trustee.ietf.org/license-info) in effect on the date of 48 publication of this document. Please review these documents 49 carefully, as they describe your rights and restrictions with respect 50 to this document. Code Components extracted from this document must 51 include Simplified BSD License text as described in Section 4.e of 52 the Trust Legal Provisions and are provided without warranty as 53 described in the Simplified BSD License. 55 Table of Contents 57 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 58 2. Detection of Support . . . . . . . . . . . . . . . . . . . . 3 59 3. Extension Frame Types . . . . . . . . . . . . . . . . . . . . 3 60 3.1. EXTENDED_SETTINGS Frame . . . . . . . . . . . . . . . . . 3 61 3.1.1. EXTENDED_SETTINGS Format . . . . . . . . . . . . . . 4 62 3.2. EXTENDED_SETTINGS_ACK Frame . . . . . . . . . . . . . . . 5 63 4. Settings Synchronization . . . . . . . . . . . . . . . . . . 5 64 5. Security Considerations . . . . . . . . . . . . . . . . . . . 6 65 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 66 6.1. Signature Methods . . . . . . . . . . . . . . . . . . . . 6 67 6.2. HTTP/2 SETTINGS_HTTP_CERT_AUTH Setting . . . . . . . . . 6 68 6.3. New HTTP/2 Frames . . . . . . . . . . . . . . . . . . . . 7 69 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 7 70 7.1. Normative References . . . . . . . . . . . . . . . . . . 7 71 7.2. Informative References . . . . . . . . . . . . . . . . . 7 72 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 8 74 1. Introduction 76 In [I-D.bishop-httpbis-http2-additional-certs], values for which IANA 77 registries already exist must be communicated between two HTTP/2 78 implementations. Since the SETTINGS frame constrains setting values 79 to a 32-bit value, the existing version of that draft divides the 80 32-bit value into halves and dedicates bits to each currently-known 81 value. This requires the creation of two duplicative IANA 82 registries, and enormously constrains future extensibility since each 83 future supported value will consume one of only sixteen bits. It 84 also causes divergence from other places in the protocol where a 85 bitmask is not required and a more sensible value can be used. 87 [MS-HTTP2E], likewise, defines a very limited bitmap in the 32-bit 88 value - two bits are defined, all others are reserved (and not 89 useful). The setting fits easily in a single byte, and need not 90 consume a four-byte value every time it is transferred. 92 Alternately, a number of recent and in-progress HTTP/2 extensions 93 describe properties of the connection that are informative to the 94 peer ([RFC7838], [I-D.ietf-httpbis-origin-frame]). These are 95 essentially settings that did not fit into a 32-bit value. 97 Each extension could define its own SETTINGS-equivalent frame to 98 carry its own data, as these extensions already have, but to do so 99 every time a new extension might require such a capability seems 100 similarly wasteful, given the limited frame type space (also an IANA 101 registry). 103 2. Detection of Support 105 An HTTP/2 peer that supports the EXTENDED_SETTINGS frame indicate 106 this using the HTTP/2 "SETTINGS_EXTENDED_SETTINGS" (0xSETTING-TBD) 107 setting. 109 The initial value for the "SETTINGS_EXTENDED_SETTINGS" setting is 0 110 (0x00), indicating that the peer does not support the 111 EXTENDED_SETTINGS frame. A peer that is able to parse the 112 EXTENDED_SETTINGS frame MUST set this value to 1 (0x01). 114 This setting MUST be sent before any of the frame types in Section 3 115 are sent, but those frames MAY be sent before the setting is 116 acknowledged and MAY be sent regardless of whether the peer has sent 117 this setting. 119 3. Extension Frame Types 121 3.1. EXTENDED_SETTINGS Frame 123 The EXTENDED_SETTINGS frame (type=0xTBD1) conveys configuration 124 parameters that affect how endpoints communicate, such as preferences 125 and constraints on peer behavior which occur in a form other than a 126 32-bit value. The EXTENDED_SETTINGS frame is also used to 127 acknowledge the receipt of those parameters. Individually, an 128 EXTENDED_SETTINGS parameter can also be referred to as a "setting". 130 EXTENDED_SETTINGS parameters are not negotiated; they describe 131 characteristics of the sending peer, which are used by the receiving 132 peer. However, a negotiation can be implied by the use of 133 EXTENDED_SETTINGS - a peer uses EXTENDED_SETTINGS to advertise a set 134 of supported values. The recipient can then choose which entries 135 from this list are also acceptable and proceed with the value it has 136 chosen. (This choice could be announced in a field of an extension 137 frame, or in a value in SETTINGS.) 139 Different values for the same parameter can be advertised by each 140 peer. For example, a server might support many different signing 141 algorithms, while a resource constrained client has only one or two 142 that it can validate. 144 An EXTENDED_SETTINGS frame MAY be sent at any time by either endpoint 145 over the lifetime of the connection. 147 Each parameter in an EXTENDED_SETTINGS frame replaces any existing 148 value for that parameter. Parameters are processed in the order in 149 which they appear, and a receiver of an EXTENDED_SETTINGS frame does 150 not need to maintain any state other than the current value of its 151 parameters. Therefore, the value of a EXTENDED_SETTINGS parameter is 152 the last value that is seen by a receiver. 154 EXTENDED_SETTINGS parameters can request acknowledgement by the 155 receiving peer. To enable this, the EXTENDED_SETTINGS frame defines 156 the following flag: 158 REQUEST_ACK (0x1): When set, bit 0 indicates that this frame 159 contains values which the sender wants to know were understood and 160 applied. For more information, see Section 4. 162 Like SETTINGS frames, EXTENDED_SETTINGS frames always apply to a 163 connection, never a single stream. The stream identifier for an 164 EXTENDED_SETTINGS frame MUST be zero (0x0). If an endpoint receives 165 an EXTENDED_SETTINGS frame whose stream identifier field is anything 166 other than 0x0, the endpoint MUST respond with a connection error 167 (Section 5.4.1) of type PROTOCOL_ERROR. 169 The EXTENDED_SETTINGS frame affects connection state. A badly formed 170 or incomplete EXTENDED_SETTINGS frame MUST be treated as a connection 171 error (Section 5.4.1) of type PROTOCOL_ERROR. 173 3.1.1. EXTENDED_SETTINGS Format 175 The payload of a SETTINGS frame consists of zero or more parameters, 176 each consisting of an unsigned 16-bit setting identifier and a 177 length-prefixed binary value. 179 0 1 2 3 180 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 181 +-------------------------------+-+-------------+---------------+ 182 | Identifier (16) |B| Length (15) | 183 +---------------------------------|-------------+---------------+ 184 | Contents (?) ... 185 +---------------------------------------------------------------+ 187 Figure 1: EXTENDED_SETTINGS frame payload 189 A zero-length content indicates that the setting value is a Boolean 190 given by the B bit. If Length is not zero, the B bit MUST be zero, 191 and MUST be ignored by receivers. The initial value of each setting 192 is "false." 194 An implementation MUST ignore the contents for any EXTENDED_SETTINGS 195 identifier it does not understand. 197 3.2. EXTENDED_SETTINGS_ACK Frame 199 The EXTENDED_SETTINGS_ACK frame acknowledges receipt and application 200 of specific values in the peer's SETTINGS frame. It contains a list 201 of EXTENDED_SETTINGS identifiers which the sender has understood and 202 applied. This list MAY be empty. 204 Any EXTENDED_SETTINGS_ACK frame whose length is not a multiple of two 205 bytes MUST be treated as a connection error ([RFC7540] section 5.4.1) 206 of type "FRAME_SIZE_ERROR". 208 4. Settings Synchronization 210 Some values in EXTENDED_SETTINGS benefit from or require an 211 understanding of when the peer has received and applied the changed 212 parameter values. In order to provide such synchronization 213 timepoints, the recipient of a EXTENDED_SETTINGS frame MUST apply the 214 updated parameters as soon as possible upon receipt. The values in 215 the EXTENDED_SETTINGS frame MUST be processed in the order they 216 appear, with no other frame processing between values. Unsupported 217 parameters MUST be ignored. 219 Once all values have been processed, if the REQUEST_ACK flag was set, 220 the recipient MUST immediately emit a EXTENDED_SETTINGS_ACK frame 221 listing the identifiers whose values were understood and applied. 222 (If none of the values were understood, the EXTENDED_SETTINGS_ACK 223 frame will be empty, but MUST still be sent.) Upon receiving an 224 EXTENDED_SETTINGS_ACK frame, the sender of the altered parameters can 225 rely on the setting having been applied. 227 If the sender of an EXTENDED_SETTINGS frame with the "REQUEST_ACK" 228 flag set does not receive an acknowledgement from a peer that has 229 sent the "SETTINGS_EXTENDED_SETTINGS" setting within a reasonable 230 amount of time, it MAY issue a connection error ([RFC7540] 231 Section 5.4.1) of type SETTINGS_TIMEOUT. This error MUST NOT be sent 232 if the peer has not previously advertised support for 233 EXTENDED_SETTINGS. 235 5. Security Considerations 237 Because these frames can be used to request that peers retain 238 potentially-large state, implementations need to use caution in their 239 retention policies. Values which are not understood MUST be 240 discarded in order to protect against increased memory usage. 241 Specifications which make use of EXTENDED_SETTINGS MUST include 242 details about how the contents can be parsed and stored, and SHOULD 243 include details about how the information can be compressed and when 244 it can safely be discarded. 246 6. IANA Considerations 248 This draft establishes one new registry and add three entries across 249 two existing registries. 251 The HTTP/2 "SETTINGS_EXTENDED_SETTINGS" setting is registered in 252 Section 6.2. Two frame types are registered in Section 6.3. 254 6.1. Signature Methods 256 This document establishes a registry for HTTP/2 extended settings. 257 The "HTTP/2 Extended Settings" registry manages a 16-bit space. The 258 "HTTP/2 Extended Settings" registry operates under the "Expert 259 Review" policy [RFC5226] for values in the range from 0x0000 to 260 0xefff, with values between and 0xf000 and 0xffff being reserved for 261 Experimental Use. 263 New registrations are advised to provide the following information: 265 Name: A symbolic name for the setting. Specifying a setting name is 266 optional. 268 Code: The 16-bit code assigned to the setting. 270 Specification: An optional reference to a specification that 271 describes the use of the setting. 273 No entries are registered by this document. 275 6.2. HTTP/2 SETTINGS_HTTP_CERT_AUTH Setting 277 The "SETTINGS_EXTENDED_SETTINGS" setting is registered in the "HTTP/2 278 Settings" registry established in [RFC7540]. 280 Name: SETTINGS_EXTENDED_SETTINGS 282 Code: 0xSETTING-TBD 283 Initial Value: 0 285 Specification: This document. 287 6.3. New HTTP/2 Frames 289 Two new frame types are registered in the "HTTP/2 Frame Types" 290 registry established in [RFC7540]. The entries in the following 291 table are registered by this document. 293 +-----------------------+--------------+-------------------------+ 294 | Frame Type | Code | Specification | 295 +-----------------------+--------------+-------------------------+ 296 | EXTENDED_SETTINGS | 0xFRAME-TBD1 | {{settings-frame}} | 297 | EXTENDED_SETTINGS_ACK | 0xFRAME-TBD2 | {{ack}} | 298 +-----------------------+--------------+-------------------------+ 300 Figure 2 302 7. References 304 7.1. Normative References 306 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 307 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 308 DOI 10.17487/RFC5226, May 2008, 309 . 311 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 312 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 313 DOI 10.17487/RFC7540, May 2015, 314 . 316 7.2. Informative References 318 [I-D.bishop-httpbis-http2-additional-certs] 319 Bishop, M. and M. Thomson, "Secondary Certificate 320 Authentication in HTTP/2", draft-bishop-httpbis-http2- 321 additional-certs-02 (work in progress), October 2016. 323 [I-D.ietf-httpbis-origin-frame] 324 Nottingham, M. and E. Nygren, "The ORIGIN HTTP/2 Frame", 325 draft-ietf-httpbis-origin-frame-01 (work in progress), 326 September 2016. 328 [MS-HTTP2E] 329 "Hypertext Transfer Protocol Version 2 (HTTP/2) 330 Extension", October 2015, 331 . 334 [RFC7838] Nottingham, M., McManus, P., and J. Reschke, "HTTP 335 Alternative Services", RFC 7838, DOI 10.17487/RFC7838, 336 April 2016, . 338 Author's Address 340 Mike Bishop 341 Microsoft 343 Email: michael.bishop@microsoft.com