WebTransport A. Frindell Internet-Draft Meta Intended status: Informational 10 July 2023 Expires: 11 January 2024 Devious Baton Protocol for Exercising WebTransport draft-frindell-webtrans-devious-baton-00 Abstract This document describes a simple protocol that can be used to exercise the functionality provided by WebTransport. The protocol passes a "baton" between endpoints, using both unidirectional and bidirectional streams. 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://afrind.github.io/draft-frindell-webtrans-devious-baton/draft- frindell-webtrans-devious-baton.html. Status information for this document may be found at https://datatracker.ietf.org/doc/draft- frindell-webtrans-devious-baton/. Discussion of this document takes place on the WebTransport Working Group mailing list (mailto:webtransport@ietf.org), which is archived at https://mailarchive.ietf.org/arch/browse/webtransport/. Subscribe at https://www.ietf.org/mailman/listinfo/webtransport/. Source for this draft and an issue tracker can be found at https://github.com/afrind/draft-frindell-webtrans-devious-baton. 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." Frindell Expires 11 January 2024 [Page 1] Internet-Draft devious-baton July 2023 This Internet-Draft will expire on 11 January 2024. Copyright Notice 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. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 2. Conventions and Definitions . . . . . . . . . . . . . . . . . 3 3. Session Establishment . . . . . . . . . . . . . . . . . . . . 3 3.1. Query Parameters . . . . . . . . . . . . . . . . . . . . 3 3.2. Protocol Version . . . . . . . . . . . . . . . . . . . . 4 4. Protocol Behavior . . . . . . . . . . . . . . . . . . . . . . 4 4.1. Setup . . . . . . . . . . . . . . . . . . . . . . . . . . 4 4.2. Processing a Baton Message . . . . . . . . . . . . . . . 4 4.3. Baton message . . . . . . . . . . . . . . . . . . . . . . 5 4.4. Datagrams . . . . . . . . . . . . . . . . . . . . . . . . 6 4.5. Session Closure . . . . . . . . . . . . . . . . . . . . . 6 4.6. Error Handling . . . . . . . . . . . . . . . . . . . . . 6 4.6.1. Stream Error Codes . . . . . . . . . . . . . . . . . 6 4.6.2. Session Error Codes . . . . . . . . . . . . . . . . . 7 5. Security Considerations . . . . . . . . . . . . . . . . . . . 7 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 7. Normative References . . . . . . . . . . . . . . . . . . . . 7 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 8 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 8 1. Introduction WebTransport offers applications the ability to send and receive data over bidirectional and unidirectional streams, as well as send and received datagrams. The Devious Baton protocol is an application that can be used to test the full suite of functionality in a WebTransport implementation and demonstrate interoperability. Frindell Expires 11 January 2024 [Page 2] Internet-Draft devious-baton July 2023 The protocol works by passing a "baton" -- a one byte integer -- between endpoints using streams. A receiving endpoint increments the baton value modulo 256 and sends it to the peer until the baton's value reaches 0. 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. Client: The endpoint that initiates the WebTransport session Server: The endpoint that did not initiate the WebTransport session Devious Baton Session: A single WebTransport session initiated as described in Section 3 3. Session Establishment The client initiates a WebTransport session as defined in [OVERVIEW]. The protocol can be used by any endpoint, but for interoperability it is RECOMMENDED that the URL path be /webtransport/devious-baton. 3.1. Query Parameters The behavior of the protocol can be configured by parameters indicated by the client. These parameters are transmitted in query parameters in the session establishment URL. Sending parameters is optional but omission of a parameter requires the server to interpret that as the default value. The server MUST support the following optional query parameters: * version - an integer specifying the draft version of Devious Baton the client intends to use If the version is invalid or the server does not support the specified version, it MUST reject the WebTransport session with a 4xx status code. The default value is 0. * baton - an integer between 1 and 255, inclusive, which the server will use as the initial baton value for all batons. Frindell Expires 11 January 2024 [Page 3] Internet-Draft devious-baton July 2023 If the baton value is invalid, the server MUST reject the WebTransport session with a 4xx status code. There is no default - if unspecified the server chooses a random baton value between 1 and 255, inclusive. * count - a positive integer specifying how many batons will be sent in parallel The default value is 1. If the client asks for more batons than the server is capable of sending, the server MUST reject the WebTransport session with a 4xx status code. 3.2. Protocol Version This draft defines Devious Baton protocol version 0. 4. Protocol Behavior 4.1. Setup Upon successful negotiation of a WebTransport session to the Devious Baton endpoint, the server opens a unidirectional stream for each baton. If there is insufficient stream credit to open a unidirectional stream, the server MUST close the WebTransport session with the DA_YAMN session error code. The server sends a Baton message with the initial baton value on each stream and closes it. 4.2. Processing a Baton Message When either endpoint receives a Baton message on a stream, it takes the following actions: * If the value of the baton is 0, the endpoint decrements the number of active batons by one. * If the value of the baton is not 0, the endpoint MUST send a new Baton message with a baton value equal to the incoming baton value + 1 modulo 256. The new Baton message is sent on a stream, decribed below. * After sending the Baton message, the endpoint MUST send a FIN on the stream. The endpoint selects the outgoing Baton message stream based on how the incoming Baton message arrived. Frindell Expires 11 January 2024 [Page 4] Internet-Draft devious-baton July 2023 * If the incoming Baton message arrived on a unidirectional stream, the endpoint opens a bidirectional stream and sends the outgoing Baton message on it. * If the Baton message arrived on a peer-initiated bidirectional stream, the endpoint sends the outgoing Baton message on that stream. * If the Baton message arrived on a self-initiated bidirectional stream, the endpoint opens a unidirectional stream and sends the outgoing Baton message on it. If an endpoint receives a baton message with an unexpected value, it MAY close the WebTransport session with the SUS session error code. If the endpoint has insufficient stream credit to open the correct type of stream, it MUST close the WebTransport session with the DA_YAMN session error code. If the endpoint has insufficient flow control credit to send the Baton message, it SHOULD send as much as limits allow, and wait for additional credit. The endpoint SHOULD close the WebTransport session with the BORED session error code if the peer takes too long to grant credit. 4.3. Baton message Baton Message { padding length(i) padding(...) baton(1) } To allow for exercising of long streams and flow control, the Baton message begins with an aribtrary amount of padding. padding length specifies the number of bytes of padding. The padding field contains padding length octets of padding. The receiver ignores the bytes themselves so they can be any value, for example 0 or random data. baton contains the current value of the baton. It is a single byte to enforce the modulo 256 arithmetic. Frindell Expires 11 January 2024 [Page 5] Internet-Draft devious-baton July 2023 4.4. Datagrams When a client endpoint receives a Baton message with a baton value = 1 modulo 7, it sends a datagram with an identical Baton message. When a server endpoint receives a Baton message with a baton value = 0 modulo 7, it sends a datagram with an identical Baton message. Note that a Baton message in a datagram MUST use a padding value small enough such that the entire Baton message fits in a single datagram. 4.5. Session Closure Each endpoint tracks the number of active batons. It is initally equal to the client's count parameter. Each time a baton exchange completes or is reset, the number of active batons is decreased by 1. When the number of active batons reaches 0, the endpoint MUST close the WebTransport session with no error. To close a Devious Baton Session with an error, the endpoint initiating the close sends a CLOSE_WEBTRANSPORT_SESSION capsule with the specified session error code. To close the session without an error, the endpoint initiating the close sends a FIN on the CONNECT stream. 4.6. Error Handling If an endpoint receives a gracefully closed stream or datagram with an incomplete Baton message, it MUST close the WebTransport session with the BRUH session error code. Either endpoint can send a STOP_SENDING or RESET_STREAM on an open stream. STOP_SENDING MUST use the IDC stream error code. Upon receipt of a STOP_SENDING on a stream, or a RESET_STREAM on a bidirectional stream, the endpoint MUST send a RESET_STREAM for that stream with the WHATEVER stream error code unless it has already closed the stream. A RESET_STREAM sent spontaneously MUST use the I_LIED stream error code. If an endpoint gets tired of waiting for the next Baton message, it MAY close the WebTransport session with the BORED error code. 4.6.1. Stream Error Codes The following error codes can be sent in RESET_STREAM and STOP_SENDING frames. Frindell Expires 11 January 2024 [Page 6] Internet-Draft devious-baton July 2023 +==========+======+================================+ | Name | Code | Description | +==========+======+================================+ | IDC | 0x01 | I don't care about this stream | +----------+------+--------------------------------+ | WHATEVER | 0x02 | The peer asked for this | +----------+------+--------------------------------+ | I_LIED | 0x03 | Spontaneous reset | +----------+------+--------------------------------+ Table 1: Stream Error Codes 4.6.2. Session Error Codes The following error codes can be sent in the CLOSE_WEBTRANSPORT_SESSION capsule. +=========+======+=================================+ | Name | Code | Description | +=========+======+=================================+ | DA_YAMN | 0x01 | There is insufficient stream | | | | credit to continue the protocol | +---------+------+---------------------------------+ | BRUH | 0x02 | Received a malformed Baton | | | | message | +---------+------+---------------------------------+ | SUS | 0x03 | Received an unexpected Baton | | | | message | +---------+------+---------------------------------+ | BORED | 0x04 | Got tired of waiting for the | | | | next message | +---------+------+---------------------------------+ Table 2: Session Error Codes 5. Security Considerations There are not believed to be any further security considerations beyond those presented in QUIC Transport. 6. IANA Considerations This document has no IANA actions. 7. Normative References Frindell Expires 11 January 2024 [Page 7] Internet-Draft devious-baton July 2023 [OVERVIEW] Vasiliev, V., "The WebTransport Protocol Framework", Work in Progress, Internet-Draft, draft-ietf-webtrans-overview- 05, 24 January 2023, . [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . Acknowledgments Martin Thomson, Christian Huitema and Lucas Pardue contributed ideas to this protocol. David Schinazi suggested the name Devious Baton. Error code naming inspiration by middle schoolers everywhere, but specifically James Frindell. Author's Address Alan Frindell Meta Email: afrind@meta.com Frindell Expires 11 January 2024 [Page 8]