Guidance for HTTP Capsule Protocol Extensibility
draft-pardue-capsule-ext-guidance-01
This document is an Internet-Draft (I-D).
Anyone may submit an I-D to the IETF.
This I-D is not endorsed by the IETF and has no formal standing in the
IETF standards process.
| Document | Type | Active Internet-Draft (individual) | |
|---|---|---|---|
| Author | Lucas Pardue | ||
| Last updated | 2024-10-21 | ||
| RFC stream | (None) | ||
| Intended RFC status | (None) | ||
| Formats | |||
| Additional resources |
GitHub Repository
|
||
| Stream | Stream state | (No stream defined) | |
| Consensus boilerplate | Unknown | ||
| RFC Editor Note | (None) | ||
| IESG | IESG state | I-D Exists | |
| Telechat date | (None) | ||
| Responsible AD | (None) | ||
| Send notices to | (None) |
draft-pardue-capsule-ext-guidance-01
Network Working Group L. Pardue
Internet-Draft Cloudflare
Intended status: Standards Track 21 October 2024
Expires: 24 April 2025
Guidance for HTTP Capsule Protocol Extensibility
draft-pardue-capsule-ext-guidance-01
Abstract
This document updates RFC 9297 with further guidance for
extensibility of the HTTP Capsule Protocol.
About This Document
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.
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 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 24 April 2025.
Copyright Notice
Copyright (c) 2024 IETF Trust and the persons identified as the
document authors. All rights reserved.
Pardue Expires 24 April 2025 [Page 1]
Internet-Draft HTTP Capsule Extension Guidance October 2024
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.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Conventions and Definitions . . . . . . . . . . . . . . . . . 3
3. The Extensibility of Capsule Type Usage . . . . . . . . . . . 3
3.1. Negotiating Additional Capsule Type Usage . . . . . . . . 4
4. Generic CAPSULE_ERROR code for HTTP/2 and HTTP/3 . . . . . . 5
5. Security Considerations . . . . . . . . . . . . . . . . . . . 5
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 5
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 5
7.1. Normative References . . . . . . . . . . . . . . . . . . 5
7.2. Informative References . . . . . . . . . . . . . . . . . 6
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 7
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 7
1. Introduction
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.
Pardue Expires 24 April 2025 [Page 2]
Internet-Draft HTTP Capsule Extension Guidance October 2024
2. Conventions and Definitions
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.
3. The Extensibility of Capsule Type Usage
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
upgrade 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, proxying 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 [CAPSULE] document requires updated text to resolve this
ambuguity. Should this document be adopted, consensus on the
resolution can be established.
Pardue Expires 24 April 2025 [Page 3]
Internet-Draft HTTP Capsule Extension Guidance October 2024
3.1. Negotiating Additional Capsule Type Usage
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 that 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.
Pardue Expires 24 April 2025 [Page 4]
Internet-Draft HTTP Capsule Extension Guidance October 2024
4. Generic CAPSULE_ERROR code for HTTP/2 and HTTP/3
Section 3.3 of [CAPSULE] describes error handling for all HTTP
versions. It defined the H3_DATAGRAM_ERROR code for HTTP/3, with the
description "Datagram or Capsule Protocol parse error". Subsequent
work that relies on using the Capsule protocol has identified that
there are situations where using H3_DATAGRAM_ERROR can be confusing,
such as where DATAGRAM capsules are expressly not allowed, but some
other processing error related to capsules occurs. Furthermore,
there is no registered HTTP/2 error code to articulate capsule-
related errors (instead, this is delegated to HTTP/2 generic
malformed handling defined in Section 8.1.1 of [HTTP/2]).
This document registers two generic error codes, CAPSULE_ERROR and
H3_CAPSULE_ERROR (values TBD), for HTTP/2 and HTTP/3 respectively.
This can be used as a general-purpose error for anything related to
Capsule protocol handling, when a more-specific error is not
available or is not preferred.
5. Security Considerations
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].
6. IANA Considerations
TODO: register error codes
7. References
7.1. Normative References
[CAPSULE] Schinazi, D. and L. Pardue, "HTTP Datagrams and the
Capsule Protocol", RFC 9297, DOI 10.17487/RFC9297, August
2022, <https://www.rfc-editor.org/rfc/rfc9297>.
Pardue Expires 24 April 2025 [Page 5]
Internet-Draft HTTP Capsule Extension Guidance October 2024
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/rfc/rfc2119>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.
7.2. Informative References
[EXT-CONNECT2]
McManus, P., "Bootstrapping WebSockets with HTTP/2",
RFC 8441, DOI 10.17487/RFC8441, September 2018,
<https://www.rfc-editor.org/rfc/rfc8441>.
[EXTCONNECT3]
Hamilton, R., "Bootstrapping WebSockets with HTTP/3",
RFC 9220, DOI 10.17487/RFC9220, June 2022,
<https://www.rfc-editor.org/rfc/rfc9220>.
[HTTP] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
Ed., "HTTP Semantics", STD 97, RFC 9110,
DOI 10.17487/RFC9110, June 2022,
<https://www.rfc-editor.org/rfc/rfc9110>.
[HTTP/1.1] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
Ed., "HTTP/1.1", STD 99, RFC 9112, DOI 10.17487/RFC9112,
June 2022, <https://www.rfc-editor.org/rfc/rfc9112>.
[HTTP/2] Thomson, M., Ed. and C. Benfield, Ed., "HTTP/2", RFC 9113,
DOI 10.17487/RFC9113, June 2022,
<https://www.rfc-editor.org/rfc/rfc9113>.
[HTTP/3] Bishop, M., Ed., "HTTP/3", RFC 9114, DOI 10.17487/RFC9114,
June 2022, <https://www.rfc-editor.org/rfc/rfc9114>.
[IP-PROXYING]
Pauly, T., Ed., Schinazi, D., Chernyakhovsky, A.,
Kühlewind, M., and M. Westerlund, "Proxying IP in HTTP",
RFC 9484, DOI 10.17487/RFC9484, October 2023,
<https://www.rfc-editor.org/rfc/rfc9484>.
[UDP-PROXYING]
Schinazi, D., "Proxying UDP in HTTP", RFC 9298,
DOI 10.17487/RFC9298, August 2022,
<https://www.rfc-editor.org/rfc/rfc9298>.
Pardue Expires 24 April 2025 [Page 6]
Internet-Draft HTTP Capsule Extension Guidance October 2024
Acknowledgments
David Schinazi and Tommy Pauly are capsule enthusiasts that suggested
some ideas leading to the genesis of this document
Author's Address
Lucas Pardue
Cloudflare
Email: lucas@lucaspardue.com
Pardue Expires 24 April 2025 [Page 7]