| Internet-Draft | TODO - Abbreviation | November 2023 |
| Pardue | Expires 26 May 2024 | [Page] |
This document updates RFC 9297 with further guidance for extensibility of the HTTP Capsule Protocol.¶
This note is to be removed before publishing as an RFC.¶
The latest revision of this draft can be found at https://LPardue.github.io/draft-pardue-capsule-ext-guidance/draft-pardue-capsule-ext-guidance.html. Status information for this document may be found at https://datatracker.ietf.org/doc/draft-pardue-capsule-ext-guidance/.¶
Source for this draft and an issue tracker can be found at https://github.com/LPardue/draft-pardue-capsule-ext-guidance.¶
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 https://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 26 May 2024.¶
Copyright (c) 2023 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 (https://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 Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶
The Capsule Protocol [CAPSULE] is a sequence of type-length-value tuples that definitions of new HTTP upgrade tokens can choose to use. It allows endpoints to reliably communicate request-related information end-to-end on HTTP request streams, even in the presence of HTTP intermediaries.¶
Clients can indicate in requests that they want the data stream to use the Capsule Protocol by providing an upgrade token and/or a Capsule-Protocol header field; see Section 3 of [CAPSULE]. Servers confirm Capsule Protocol usage by returning a response in the 2xx (Successful) range, possibly including a Capsule-Protocol header field.¶
The process of initiating the Capsule Protocol for any given data stream identifies the purpose of usage and the Capsule types that endpoints can send or receive.¶
This document updates RFC 9297 with further guidance for extensibility of the Capsule Protocol.¶
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶
In order to support extensibility, Section 3.2 of [CAPSULE] requires that:¶
Endpoints that receive a Capsule with an unknown Capsule Type MUST silently drop that Capsule and skip over it to parse the next Capsule.¶
The first ambiguity in this text comes from the term "endpoint". It relates to the resource that the Capsule Protocol negotiation applies to, not the general HTTP endpoint. In other words, known or unknown types are scoped only to the request stream Capsule Protocol usage, nothing else.¶
For example, proxying UDP in HTTP [UDP-PROXYING] makes use of the updgrade token "connect-udp" to enable the Connect Protocol. It describes how DATAGRAM capsules (Section 3.5 of [CAPSULE]) can be used. Use of other capsule types on that data stream is undefined, the expectation being that they are ignored on receipt.¶
Similarly, proxing IP in HTTP [IP-PROXYING] makes use of the upgrade token "connect-ip" to enable the Connect Protocol. It defines ADDRESS_ASSIGN, ADDRESS_REQUEST, and ROUTE_ADVERTISEMENT capsules (Section 4.7 of [IP-PROXYING]) and describes how these can be used together with DATAGRAM capsules.¶
An HTTP server could support both UDP and IP proxying and it's implementation would be able to understand all four capsule types. However, use of ADDRESS_ASSIGN, for example, on a "connect-udp" data stream is undefined by [UDP-PROXYING].¶
The second ambiguity with the text in Section 3.2 of [CAPSULE] comes from ambiguity of intent. Silent dropping of unknown types new can be safely used by extensions without prior arrangement or negotiation.¶
However, some extensions might be built on the assumption a capsule is processed by the recipient. For example to send a capsule that elicits some response message or behavioural change. Such extensions can benefit from some form of explicit negotiation.¶
There are several approaches to negotiating the use of new capsule types within the scope of a request stream Capsule Protocol. This document does not mandate any specific method but advises protocol designers to use negotiation patterns that fit the end-to-end nature of the Capsule Protocol, where endpoints generate and process capsules.¶
Specifically SETTINGS negotiation (Section 5.5 of [HTTP/2] and Section 9 of [HTTP/3]) could be used to extend a connection, changing the scope of Capsule Protocol knowledge for all request streams or a set of upgrade tokens. However, the SETTINGS are not an end-to-end mechanism and therefore this method of negotiation does not work when intermediaries are involved.¶
Negotiation of new capsule types via new upgrade tokens is an end-to-end mechanism. However, while HTTP/1.x clients can offer several token values in the Upgrade mechanism (Section 7.8 of [HTTP]), extended CONNECT ([EXT-CONNECT2] and [EXTCONNECT3]) does not support this possibility. While HTTP/2 or HTTP/3 clients could use multiple separate requests in order to attempt the selection of a most-preferred upgrade token, this requires additional round trips which might introduce undesirable delays.¶
Header fields provide an end-to-end negotiation mechanism. The Capsule-Protocol header field is itself extensible and parameters could, in theory, be used to negotiate extensions. However, Capsule-Protocol requires that unknown parameters are ignored, so extension designers ought to use an offer-echo pattern that confirms the recipient did process the parameter. Also note that use of Capsule-Protocol is optional and the upgrade tokens can mandate use of the Capsule Protocol without this header field. In such cases, a new header field can be defined to support extension negotiation.¶
The ability to send capsule types that the peer may not know, and is therefore required to ignore, can be abused to cause a peer to expend additional processing time. This could become a burden when used unnecessarily or to excess.¶
An endpoint that does not monitor such behavior exposes itself to a risk of denial-of-service attack. Implementations SHOULD track the use of unknown capsule types and set limits on their use. An endpoint MAY treat activity that is suspicious as a reason to close a connection, but false positives will result in disrupting valid connections and requests. For guidance on closing connections see Section 9.6 of [HTTP/1.1], Section 5.5 of [HTTP/2], and Section 9 of [HTTP/3].¶
There are no IANA considerations.¶
David Schinazi and Tommy Pauly are capsule enthusiasts that suggested some ideas leading to the genesis of this document¶