Internet DRAFT - draft-pardue-capsule-ext-guidance

draft-pardue-capsule-ext-guidance







Network Working Group                                          L. Pardue
Internet-Draft                                                Cloudflare
Intended status: Standards Track                        23 November 2023
Expires: 26 May 2024


            Guidance for HTTP Capsule Protocol Extensibility
                  draft-pardue-capsule-ext-guidance-00

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 26 May 2024.

Copyright Notice

   Copyright (c) 2023 IETF Trust and the persons identified as the
   document authors.  All rights reserved.



Pardue                     Expires 26 May 2024                  [Page 1]

Internet-Draft             TODO - Abbreviation             November 2023


   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 . . . . . . . .   3
   4.  Security Considerations . . . . . . . . . . . . . . . . . . .   4
   5.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   5
   6.  References  . . . . . . . . . . . . . . . . . . . . . . . . .   5
     6.1.  Normative References  . . . . . . . . . . . . . . . . . .   5
     6.2.  Informative References  . . . . . . . . . . . . . . . . .   5
   Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . .   6
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .   6

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 26 May 2024                  [Page 2]

Internet-Draft             TODO - Abbreviation             November 2023


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
   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].

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.





Pardue                     Expires 26 May 2024                  [Page 3]

Internet-Draft             TODO - Abbreviation             November 2023


   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.

4.  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



Pardue                     Expires 26 May 2024                  [Page 4]

Internet-Draft             TODO - Abbreviation             November 2023


   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].

5.  IANA Considerations

   There are no IANA considerations.

6.  References

6.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>.

   [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>.

6.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>.




Pardue                     Expires 26 May 2024                  [Page 5]

Internet-Draft             TODO - Abbreviation             November 2023


   [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>.

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: lucaspardue.24.7@gmail.com























Pardue                     Expires 26 May 2024                  [Page 6]