From 17d2ea66dc0157619723f496f93f32a44c7e9e02 Mon Sep 17 00:00:00 2001 From: Brian Sipos Date: Thu, 14 Mar 2024 14:14:08 -0400 Subject: [PATCH 1/2] Updates for new revision --- .gitlab-ci.yml | 58 ++ spec/CMakeLists.txt | 2 +- spec/dictionary.txt | 39 +- spec/draft-sipos-dtn-udpcl.xml | 1021 +++++++++++++++++++++++--------- spec/sort_dictionary.sh | 6 + 5 files changed, 829 insertions(+), 297 deletions(-) create mode 100644 .gitlab-ci.yml create mode 100755 spec/sort_dictionary.sh diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml new file mode 100644 index 0000000..52170c9 --- /dev/null +++ b/.gitlab-ci.yml @@ -0,0 +1,58 @@ +default: + # All jobs run within a target-like environment + image: docker-remote.artifactory.jhuapl.edu/ubuntu:22.04 + +include: + # Run pipeline only on branches, not MRs + - template: 'Workflows/Branch-Pipelines.gitlab-ci.yml' + +variables: + GIT_SUBMODULE_STRATEGY: recursive + DEBIAN_FRONTEND: "noninteractive" + # for Python/PIP + PIP_CERT: /etc/ssl/certs/ca-certificates.crt + PIP_DEFAULT_TIMEOUT: "300" + # Project-spcific environment + XDG_CACHE_HOME: "$CI_PROJECT_DIR/.cache" + PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip" + +stages: + - build + +cache: + paths: + - .cache/pip + +.prep-install-ca: &prep-install-ca | + apt-get update && apt-get install -y ca-certificates curl + mkdir -p /usr/local/share/ca-certificates + curl -svL http://apllinuxdepot.jhuapl.edu/linux/APL-root-cert/JHUAPL-MS-Root-CA-05-21-2038-B64-text.cer -o /usr/local/share/ca-certificates/JHUAPL-MS-Root-CA-05-21-2038-B64-text.crt + update-ca-certificates + +.prep-install-pip: &prep-install-pip | + apt-get update && apt-get install -y python3 python3-venv python3-pip python3-wheel + pip3 install --upgrade pip + pip3 install pip-tools + +.prep-install-doctools: &prep-install-doctools | + apt-get install -y aspell cmake ruby ruby-dev xmlstarlet yajl-tools xml2rfc + pip3 install xml2rfc + gem install cddl + +ari-doc: + stage: build + rules: + - changes: + - .gitlab-ci.yml + - spec/* + before_script: + - *prep-install-ca + - *prep-install-pip + - *prep-install-doctools + script: + - cmake -S . -B build/default -DCMAKE_INSTALL_DOCDIR=$PWD/build/install + - cmake --build build/default -v + - cmake --install build/default + artifacts: + paths: + - "build/install" diff --git a/spec/CMakeLists.txt b/spec/CMakeLists.txt index 632174b..32035d5 100644 --- a/spec/CMakeLists.txt +++ b/spec/CMakeLists.txt @@ -127,7 +127,7 @@ else() add_custom_command( OUTPUT "${CDDLERRORS_TXT}" DEPENDS "${COMBINED_CDDL}" - COMMAND ${CDDLTOOL} "${COMBINED_CDDL}" generate 2>"${CDDLERRORS_TXT}" 1>&2 || true + COMMAND ${CDDLTOOL} "${COMBINED_CDDL}" generate 10 2>"${CDDLERRORS_TXT}" 1>&2 || true ) add_custom_target( cddlerrors ALL diff --git a/spec/dictionary.txt b/spec/dictionary.txt index 7633510..614b8f4 100644 --- a/spec/dictionary.txt +++ b/spec/dictionary.txt @@ -1,45 +1,56 @@ -ACK Ack +ACK acknowledgement acknowledgements anycast +AQM BCP +BER +BPA BPSec BPv bstr bundleSecurity Burleigh +bursty CAs CBOR -CDDL cddl +CDDL checksums ciphersuite CLA ClientHello +codepoint codepoints connectionless Conv CRC CRLs -Datagram datagram +Datagram datagrams dbus DCCP +de decodable deconflict +DF DNS DTLS -DTN dtn +DTN +ECN +ECT EID EIDs encodings endian extensibility +Heiner IANA ICMP +ICMPv IESG IETF incrementing @@ -49,27 +60,31 @@ IPADDR iPAddress IPsec IPv -Keepalive keepalive +Keepalive kp LLC +middleboxes misconfigured +MPS MRU MRUs MTU -Multicast multicast +Multicast ne ness nodeid OCSP packetization PCH -Pipelining pipelining +Pipelining PKI PKIX +PKTINFO plaintext +PLPMTUD PMTU pre PSK @@ -77,10 +92,12 @@ queueing Responder retransmission retransmissions -Retransmit retransmit +Retransmit retransmitted RKF +routable +Scalable SMI SSL STARTTLS @@ -93,8 +110,8 @@ teardown TLS tstr UDP -UDPCL udpcl +UDPCL uint unhandled unicast @@ -102,10 +119,10 @@ untagged Untrusted URI UTF -Wireshark wireshark +Wireshark xA xBF xC xDF -XPath \ No newline at end of file +XPath diff --git a/spec/draft-sipos-dtn-udpcl.xml b/spec/draft-sipos-dtn-udpcl.xml index 7912c81..17f096b 100644 --- a/spec/draft-sipos-dtn-udpcl.xml +++ b/spec/draft-sipos-dtn-udpcl.xml @@ -1,78 +1,31 @@ - + - - Delay-Tolerant Networking UDP Convergence Layer Protocol + <title abbrev="DTN UDPCLv2"> + Delay-Tolerant Networking UDP Convergence Layer Protocol Version 2 - + - - RKF Engineering Solutions, LLC - + The Johns Hopkins University Applied Physics Laboratory
- 7500 Old Georgetown Road - Suite 1275 - Bethesda + 11100 Johns Hopkins Rd. + Laurel MD - 20814-6198 + 20723 United States of America - BSipos@rkf-eng.com + brian.sipos+ietf@gmail.com
- Transport Delay-Tolerant Networking -This document describes a UDP-based convergence layer (UDPCL) for Delay-Tolerant Networking (DTN). -This version of the UDPCL protocol clarifies requirements of RFC7122, adds discussion of multicast addressing, and updates to the Bundle Protocol (BP) contents, encodings, and convergence layer requirements in BP Version 7. -Specifically, the UDPCL uses CBOR-encoded BPv7 bundles as its service data unit being transported and provides a reliable transport of such bundles. +This document describes a UDP convergence layer (UDPCL) for Delay-Tolerant Networking (DTN). +This version of the UDPCL protocol clarifies requirements of RFC7122, adds discussion of multicast addressing, congestion signaling, and updates to the Bundle Protocol (BP) contents, encodings, and convergence layer requirements in BP version 7. +Specifically, the UDPCL uses CBOR-encoded BPv7 bundles as its service data unit being transported and provides an unreliable transport of such bundles. This version of UDPCL also includes security and extensibility mechanisms. @@ -81,20 +34,20 @@ This version of UDPCL also includes security and extensibility mechanisms.
Introduction -This document describes the UDP-based convergence-layer protocol for Delay-Tolerant Networking. -Delay-Tolerant Networking is an end-to-end architecture providing communications in and/or through highly stressed environments, including those with intermittent connectivity, long and/or variable delays, and high bit error rates. -More detailed descriptions of the rationale and capabilities of these networks can be found in "Delay-Tolerant Network Architecture" . +This document describes the UDP convergence-layer protocol for Delay-Tolerant Networking (DTN). +DTN is an end-to-end architecture providing communications in and/or through highly stressed environments, including those with intermittent connectivity, long and/or variable delays, and high bit error rates. +More detailed descriptions of the rationale and capabilities of these networks can be found in "Delay-Tolerant Networking Architecture" . An important goal of the DTN architecture is to accommodate a wide range of networking technologies and environments. -The protocol used for DTN communications is the Bundle Protocol Version 7 (BPv7) , an application-layer protocol that is used to construct a store-and-forward overlay network. +The protocol used for DTN communications is the Bundle Protocol version 7 (BPv7) , an application-layer protocol that is used to construct a store-and-forward overlay network. BPv7 requires the services of a "convergence-layer adapter" (CLA) to send and receive bundles using the service of some "native" link, network, or Internet protocol. This document describes one such convergence-layer adapter that uses the well-known User Datagram Protocol (UDP). This convergence layer is referred to as UDP Convergence Layer (UDPCL). For the remainder of this document, the abbreviation "BP" without the version suffix refers to BPv7. -The locations of the UDPCL and the BP in the Internet model protocol stack (described in ) are shown in . +The locations of the UDPCL and the Bundle Protocol in the Internet model protocol stack (described in ) are shown in . In particular, when BP is using UDP as its bearer with UDPCL as its convergence layer, both BP and UDPCL reside at the application layer of the Internet model.
@@ -102,7 +55,7 @@ In particular, when BP is using UDP as its bearer with UDPCL as its convergence +-------------------------+ | DTN Application | -\ -+-------------------------| | ++-------------------------+ | | Bundle Protocol (BP) | -> Application Layer +-------------------------+ | | UDP Conv. Layer (UDPCL) | | @@ -125,13 +78,13 @@ This document does not address:
  • -The format of protocol data units of the Bundle Protocol, as those are defined elsewhere in . -This includes the concept of bundle fragmentation or bundle encapsulation. +The format of protocol data units of the Bundle Protocol, as those are defined elsewhere in . +This includes the concept of bundle fragmentation and bundle encapsulation. The UDPCL transfers bundles as opaque data blocks.
  • Mechanisms for locating or identifying other bundle entities (peers) within a network or across an internet. -The mapping of Node ID to potential convergence layer (CL) protocol and network address is left to implementation and configuration of the BP Agent and its various potential routing strategies. +The mapping of a Node ID to a potential convergence layer (CL) protocol and network address is left to implementation and configuration of the BP Agent (BPA) and its various potential routing strategies, as is the mapping of a DNS name and/or address to a choice of an end-entity certificate to authenticate a node to its peers.
  • Logic for routing bundles along a path toward a bundle's endpoint. @@ -139,6 +92,7 @@ This CL protocol is involved only in transporting bundles between adjacent entit
  • Logic for performing rate control and congestion control of bundle transfers, both incoming and outgoing from a UDPCL entity. +The signaling defined in and can support a congestion control mechanism, but it is an implementation matter to choose and configure such a mechanism.
  • Policies or mechanisms for issuing Public Key Infrastructure Using X.509 (PKIX) certificates; provisioning, deploying, or accessing certificates and private keys; deploying or accessing certificate revocation lists (CRLs); or configuring security parameters on an individual entity or across a network. @@ -187,10 +141,10 @@ The relationship between a UDPCL entity and UDPCL sessions is defined as follows
    • -A UDPCL Entity MAY actively perform any number of transfers and should do so whenever the entity has a bundle to forward to another entity in the network. +A UDPCL Entity MAY actively perform any number of transfers and SHOULD do so whenever the entity has a bundle to forward to another entity in the network.
    • -A UDPCL Entity MAY support zero or more passive listening elements that listen for transfers from other entities in the network, including non-unicast transfers. +A UDPCL Entity MAY support zero or more passive listening elements that listen for transfers from other entities in the network, including non-unicast transfers.
    @@ -206,7 +160,7 @@ Because UDP is connectionless, there is no notion of a conversation being "opene
    Transfer:
    This refers to the procedures and mechanisms for conveyance of an individual bundle from one entity to one or more destinations. -This version of UDPCL includes a fragmentation mechanism to allow transfers which are larger than the allowable UDP datagram size. +This version of UDPCL includes a segmentation mechanism to allow transfers which are larger than the allowable UDP datagram size.
    Transmit:
    @@ -251,14 +205,14 @@ This refers to a transfer incoming to an entity as seen from that receiving enti General Protocol Description The service of this protocol is the transmission of DTN bundles via the User Datagram Protocol (UDP). -This document specifies the optional fragmentation of bundles, procedures for DTLS setup and teardown, and a set of messages and entity requirements. +This document specifies the optional segmentation of bundles, procedures for DTLS setup and teardown, and a set of messages and entity requirements. The general operation of the protocol is as follows. -Fundamentally, the UDPCL is a (logically) unidirectional "transmit and forget" protocol which itself maintains no long-term state and provides no feedback to the transmitter. +Fundamentally, the UDPCL is a (logically) unidirectional "transmit and forget" protocol which itself maintains no long-term state and provides no feedback from the receiver to the transmitter. The only long-term state related to UDPCL is used by DTLS in its session keeping (which is bound to a UDP conversation). An entity receiving a bundle from a particular source address-and-port does not imply that the transmitter is willing to accept bundle transfers on that same address-and-port. -It is the obligation of a BP agent and its routing schemes to determine a bundle return path. +It is the obligation of a BP agent and its routing schemes to determine a bundle return path (if such a path even exists).
    Convergence Layer Services @@ -271,15 +225,15 @@ Each of these interactions can be associated with any number of additional metad
    Begin Transmission:
    The principal purpose of the UDPCL is to allow a BP agent to transmit bundle data to one or more other entities. -The receiver of each transfer is identified by an (destination) IPv4 or IPv6 address and a UDP port number (see for details). -The CL does not necessarily perform any transmission queueing, but may block while transmissions are being processed at the UDP layer. +The receiver of each transfer is identified by an (destination) IPv4 or IPv6 address, a UDP port number, and an optional local interface identifier (see for details). +The CL does not necessarily perform any transmission queueing (see ), but might block while transmissions are being processed at the UDP layer. Any queueing of transmissions is the obligation of the BP agent.
    Transmission Started:
    The UDPCL entity indicates to the BP agent when a bundle transmission begins sending UDP datagrams. Once started, there is no notion of a UDPCL transmission failure; a BP agent has to rely on bundle-level status reporting to track bundle progress through the network. -Because of potential queueing or DTLS setup time, this may be delayed from the BP agent providing the bundle-to-transmit. +Because of potential queueing or DTLS setup time, this can be delayed from the BP agent providing the bundle-to-transmit.
    Transmission Finished:
    @@ -288,12 +242,12 @@ This is not a positive indication that any next-hop receiver has either received
    Reception Started:
    -The UDPCL entity indicates to the BP agent when a bundle transfer has begun, which may include information about the total size of a fragmented transfer. +The UDPCL entity indicates to the BP agent when a bundle transfer has begun, which can include information about the total size of a segmented transfer.
    Reception Success:
    The UDPCL entity indicates to the BP agent when a bundle has been fully transferred from a peer entity. -The transmitter of each transfer is identified by an (source) IP address and a UDP port number (see for details). +The transmitter of each transfer is identified by a (source) IP address, a UDP port number, and an optional local interface identifier (see for details).
    Reception Failure:
    @@ -312,7 +266,7 @@ The closure request is on a per-session basis.
    DTLS Session State Changed:
    The UDPCL entity indicates to the BP agent when a DTLS session state changes. -The possible DTLS session states are defined in . +The possible DTLS session states are defined in .
    Begin Sender Listen:
    @@ -334,63 +288,86 @@ The Sender Node ID, if present, is part of this indication. PKIX Environments and CA Policy This specification gives requirements about how to use PKIX certificates issued by a Certificate Authority (CA), but does not define any mechanisms for how those certificates come to be. -The UDPCL uses the exact same mechanisms and makes the same assumptions as TCPCL in . +The UDPCL uses the exact same mechanisms and makes the same assumptions as TCPCL in . + +
    +
    + UDP Conversation Stability + +Unlike the loose UDPCL definition in , the requirements in this document ensure that traffic between two peers with stable IP addresses also use stable UDP port numbers. +This enables the UDPCL to be more compatible with network address translation (NAT) middleboxes and, where necessary, enables the UDPCL to be used along with protocols such as Session Traversal Utilities for NAT (STUN) and Interactive Connectivity Establishment (ICE) . + + +There is a trade-off between stability of UDP conversations and a possible need to protect from off-path data injection, as described in , so the conversation long-term stability (in and ) is recommended while specific cases of short-term consistency , , and are required. + +
    +
    + Path Characterization + +The earlier UDPCL definition in assumed that BP node operators had deep visibility into the IP networks over which bundles would be transferred, specifically that the IP paths between UDPCL sender and receiver had well-characterized parameters for: path maximum transmit unit (PMTU), one-way delay time, one-way throughput limit, and packet loss statistics (both due to congestion and to link errors). + + +In situations where node operators do not have prior information about those parameters, this version of the UDPCL supports mechanisms to measure or estimate them. +These mechanisms are defined in detail under .
    Fragmentation Policies -It is a implementation matter for a sending entity to determine the path maximum transmit unit (PMTU) to be used as a target upper-bound UDP datagram size. -Some techniques to perform MTU discovery are defined in . -All IP packets sent by a UDPCL entity SHOULD have the "don't fragment" bit set to allow detection of PMTU issues. +It is a implementation matter for a sending entity to determine the PMTU to be used as a target upper-bound UDP datagram size. The priority order of fragmentation is the following:
    1. -When possible, bundles too large to fit in one PMTU-sized packet SHOULD be fragmented at the BP layer. +When possible, bundles too large to fit in one PMTU-sized packet MAY be fragmented at the BP layer. Bundle payload fragmentation does not help a large bundle if extension blocks are a major contributor to bundle size, so in some circumstances BP layer fragmentation will not reduce the bundle size sufficiently. -It is outside the scope of UDPCL to manage BP agent fragmentation policies; bundles are received from the BP agent either already fragmented or not. +It is outside the scope of UDPCL to manage BP agent fragmentation policies; encoded bundles are received from the BP agent either already fragmented or not.
    2. -Bundles too large to fit in one PMTU-sized packet SHALL be fragmented as a UDPCL transfer (see ). -Fragmentation at this level treats bundle transfers as opaque data, so it is independent of bundle block sizes or counts. +When a PMTU is available to a peer, bundles too large to fit in one PMTU-sized packet SHALL be segmented as a UDPCL transfer (see ). +Segmentation at this level treats bundle transfers as opaque data, so it is independent of bundle block sizes or counts. +When a PMTU is available, IPv4 packets sent by a UDPCL entity SHOULD have the DF bit set to allow detection of PMTU issues.
    3. -All IP packets larger than expected PMTU SHALL be fragmented by the transmitting entity to fit within one PMTU. +All IPv6 packets and all IPv4 packets which do not have the DF bit set which are larger than the link MTU will be fragmented by the transmitting entity to fit within one link MTU. Because of the issues listed in and , it is best to avoid IP fragmentation as much as possible.
    -A UDPCL entity SHOULD NOT proactively drop an outgoing transfer due to datagram size. -If intermediate network nodes drop IP packets it is an implementation matter to receive network feedback (e.g. ICMP Packet Too Big). +A UDPCL entity SHOULD NOT proactively drop an outgoing transfer due to datagram size. +If intermediate network nodes drop IP packets it is an implementation matter to receive network feedback (e.g. ICMP Fragmentation Needed of or ICMPv6 Packet Too Big of ). +The UDPCL itself provides no transfer acknowledgement mechanism or other protocol-level reception feedback other than the optional procedure, which is why an accurate PMTU for a peer is critical information.
    -
    +
    Error Checking Policies -The core Bundle Protocol specification assumes that bundles are transferring over an erasure channel, i.e., a channel that either delivers packets correctly or -not at all. +The core Bundle Protocol specification assumes that bundles are transferring over an erasure channel, i.e., a channel that either delivers packets correctly or not at all. -A UDP transmitter SHALL NOT disable UDP checksums. -A UDP receiver SHALL NOT disable the checking of received UDP checksums. +A UDP transmitter SHALL NOT disable UDP checksums. +A UDP receiver SHALL NOT disable the checking of received UDP checksums. Even when UDP checksums are enabled, a small probability of UDP packet corruption remains. -In some environments, it may be acceptable for a BP agent to occasionally receive corrupted input. -In general, however, a UDPCL entity SHOULD insure the a bundle's blocks are either covered by a CRC or a BPSec integrity check. +In some environments, it could be acceptable for a BPA to occasionally receive corrupted input for some blocks. +In general, however, a BPA is RECOMMENDED to ensure the a bundle's blocks are covered by a CRC so that next-hop receivers can verify the block contents.
    -
    +
    Congestion Control Policies -The applications using UDPCL for bundle transport SHALL conform to the congestion control requirements of . -The application SHALL either perform active congestion control of bundles or behave as the Low Data-Volume application as defined in . +The applications using UDPCL for bundle transport SHALL conform to the congestion control requirements of . +The application SHALL either perform active congestion control of bundles or behave as the Low Data-Volume application as defined in . + + +When nodes have bidirectional IP capability with a peer, the ECN marking and feedback mechanism of can be used to provide Active Queue Management (AQM) of UDP traffic (and thus BP traffic) to the peer providing feedback. +It is an implementation matter to ensure that traffic patterns which require UDPCL queuing and rate control are paired with a UDPCL entity capable of AQM and peers which provide requisite ECN feedback. -When nodes have bidirectional transfer capability, the bundle deletion reason code "traffic pared" can be used by a receiving agent to signal to the bundle source application that throttling of bundles along that path SHOULD occur. +When nodes have bidirectional BP transfer capability, the bundle deletion reason code "traffic pared" can be used by a receiving agent to signal to the bundle source application that throttling of bundles along that BP path needs to occur.
    @@ -404,136 +381,186 @@ It also discusses behavior within the UDPCL layer, which is illustrated in Breakdown of sub-layers within the UDPCL -+------------------------------------------+ -| Bundle Transfer | Extension Signaling | <- Sequencing / -+------------------------------------------+ fragmentation -| Bundle | Ext. Map | ... | Padding | <- Messaging -+------------------------------------------+ -| UDPCL Packet | <- Packetization -+------------------------------------------+ ++-------------------------------------------+ +| Identified Transfer | Extension Signaling | <- Sequencing / ++-------------------------------------------+ segmentation + \ / + ------ ----------------- + \ / ++-------------------------------------------+ +| Bundle | Extension Map | ... | Padding | <- Messaging ++-------------------------------------------+ +| UDPCL Packet | <- Packetization ++-------------------------------------------+
-
- IP Addressing +
+ IP Header The earlier UDPCL specification in did not include guidance on IP addressing, interface sourcing, or potential use of multicast, though the architecture of explicitly includes multicast and anycast as expected network modes. -The BP agent determines the mapping from destination EID to next-hop CL parameters, including transfer destination address and transfer source interface. -Some EIDs represent unicast destinations and others non-unicast destinations as defined in . -The unicast-ness of an EID does not necessarily correspond with the unicast-ness, as some bundle routing schemes involve attempting multiple parallel paths to a unicast endpoint. +For each forwarding transfer the BP agent determines the mapping from destination EID to next-hop CL parameters, including next-hop destination address and source interface. +Some EIDs represent singleton destinations and others non-singleton destinations as defined in . +The singleton-ness of an EID does not necessarily correspond with the unicast-ness of its forwarding, as some bundle routing schemes involve attempting multiple parallel paths to a singleton endpoint and some involve forwarding non-singleton-destination traffic to known individual BP neighbors along unicast paths. -For unicast transfers to a single node, the destination address SHALL be a non-multicast IPv4 or IPv6 address (which does include link-local addresses). -For unicast transfers, the source interface address MAY be supplied by the BP agent or otherwise determined by the operating system IP routing. -When performing unicast transfers, a UDPCL entity SHOULD require DTLS use (see ) or restrict the network to one protected by IPsec or some other under-layer security mechanism (e.g., a virtual private network). +For unicast transfers to a single node, the destination address SHALL be a non-multicast IPv4 or IPv6 address (which includes link-local addresses). +For unicast transfers, the source interface address MAY be supplied by the BP agent or otherwise determined by the operating system IP routing. +When performing unicast transfers, a UDPCL entity SHOULD require DTLS use (see ) or restrict the network to one protected by IPsec or some other under-layer security mechanism (e.g., a virtual private network). -For multicast transfers to one or more nodes, the destination address SHALL be a multicast IPv4 or IPv6 address. +For multicast transfers to any number of nodes, the destination address SHALL be a multicast IPv4 or IPv6 address. +The well-known multicast addresses defined in SHALL be used as a default in the absence of any network-specific configuration. For multicast transfers, the source interface address MUST be supplied by the BP agent rather than inferred by the UDPCL entity. +For multicast transfers the UDPCL does not define any security mechanism. + + +When supported by an implementation, the UDPCL SHOULD accept and provide information on the local interface from which a transmission is sent or to which a reception was received. +For IPv6 this corresponds with the IPV6_PKTINFO ancillary data API of ; for IPv4 this is an implementation-specific detail supported by IP_PKTINFO ancillary data on some operating systems. +Identifying an interface for transmission or reception allows a BPA to provide fine-grained control and visibility when UDPCL is used for IP multicast or when link-local addressing is in use. + + +The IPv4 header bit don't fragment (DF) is used as discussed in . + + +The IPv4 and IPv6 header field for Explicit Congestion Notification (ECN) is used as discussed in and .
UDP Header -Destination port number 4556 has been assigned by IANA as the Registered Port number for the UDP convergence layer and SHALL be used as a default. -Other destination port numbers MAY be used per local configuration. +UDP port number 4556 has been assigned by IANA as the Registered Port number for the UDPCL and SHALL be used as a default for both source and destination. +Other source or destination port numbers MAY be used per local configuration. Determining a passive entity's destination port number (if different from the registered UDPCL port number) is up to the implementation. -Any source port number MAY be used for UDPCL transfers. -Typically an operating system assigned number in the UDP Ephemeral range (49152-65535) is used. -For repeated messaging to the same destination address-and-port, the active entity SHOULD reuse the same source address-and-port. -Reusing source address-and-port allows simplifies network monitoring and analysis and also enables bi-directional messaging as defined in . +If the default source port is not used, typically an operating system assigned number in the UDP Ephemeral range (49152-65535) is used. +For repeated messaging to the same destination address-and-port, the active entity SHOULD reuse the same source address-and-port. +For feedback messaging, the passive entity SHALL respond to the same address-and-port that solicited the feedback and use the same source address-and-port which was listed on. +Reusing source address-and-port allows simplifies network monitoring and analysis and also enables bi-directional messaging as defined in , , and .
-
+
UDPCL Packets The lowest layer of UDPCL communication are individual-datagram packets. -To exchange UDPCL data, an active entity SHALL transmit a UDP datagram to a listening passive entity in accordance with , typically by using the services provided by the operating system. +To exchange UDPCL data, an active entity SHALL transmit a UDP datagram to a listening passive entity in accordance with , typically by using the services provided by the operating system. For backward compatibility with , UDPCL has no explicit message type identifier. - + -Each UDP datagram SHALL contain one or more UDPCL message as defined in . -Each type of message defines additional restrictions on how it may be used in a packet. - +Each UDP datagram SHALL contain one or more UDPCL message as defined in . +Each type of message defines additional restrictions on how it can be used in a packet. + The following are special cases of UDPCL packet uses. - +
Unframed Transfer:
-An unframed transfer packet SHALL consist of a single encoded BPv6 or BPv7 bundle with no padding. +An unframed transfer packet SHALL consist of a single encoded BPv6 or BPv7 bundle with no padding. This provides backward compatibility with and a allows a trivial use of UDPCL which is just embedding an encoded bundle in a UDP datagram. -
-
Keepalive
+ +
Keepalive:
-A keepalive packet SHALL consist of exactly four octets of padding with no preceding message. +A keepalive packet SHALL consist of exactly four octets of padding with no preceding message. This behavior maintains backward compatibility with . -
+ +
DTLS Record:
+
+ +In addition to the UDPCL-specific messaging, immediately after a DTLS Initiation (see ) the DTLS handshake sequence will begin. +Packets with a leading octet value of 0x16 SHALL be treated as a DTLS handshake record in accordance with . + + +If the datagram with the DTLS Initiation extension is not received by an entity, the entity SHOULD still detect the DTLS handshake records and start the handshake sequence at that point. +Packets with a leading octet value of 0x14--0x1A or 0x20--0x3F SHALL be treated as a DTLS sequencing failure; DTLS non-handshake records SHOULD never be seen by the UDPCL messaging layer. + +
+
+ Redundant Transmission + +Because the UDPCL uses unreliable UDP as its transmission layer, an entity with information about the loss characteristics of the path to a peer entity can intentionally perform duplicate transmissions to improve the chances that the packet, message, or whole transfer will arrive at the receiver. +It is an implementation matter to determine when to perform redundant transmission, and could be based on the interface, peer network or address, or properties of the UDPCL packet itself. + + +The number of duplicate transmissions for a packet is referred to as its Redundancy Factor. +A Redundancy Factor of one means to perform no duplicate transmission. +A larger Redundancy Factor will result in more network resources used (and possibly wasted). + + +The time interval between original and each duplicate transmission is referred to as its Redundancy Delay. +A larger Redundancy Delay will result in more entity resources used keeping packet contents in memory for retransmission. +To avoid a receiver mishandling redundant packets containing Transfer items (see ) the Redundancy Delay SHOULD be no longer than the receiver's transfer timeout, if known, or one minute (60 seconds). + + +For paths where losses over time are bursty, a low redundancy factor but high redundancy delay will ensure that the duplicated packets are transmitted over a longer span of time and (hopefully) do not have a correlated probability of loss. + + +To avoid unnecessary processing on the receiver's BP Agent, when redundant transmission used the method of SHALL be used even for single-segment transfers so that the UDPCL entity can discard any duplicate receptions. +If redundant transmission is used with an unframed transfer the UDPCL has no ability to discard any duplicate receptions and all duplicates will be seen by the receiving BP Agent. + +
UDPCL Messages The middle layer of UDPCL communication are unframed, but self-delimited, messages. -Specific message types MAY be concatenated together into a single packet, each message type indicates any restrictions on how it can be used within a packet. +Specific message types MAY be concatenated together into a single packet, each message type indicates any restrictions on how it can be used within a packet. For backward compatibility with , UDPCL has no explicit message type identifier. The message type is inferred by the inspecting the data contents according to the following rules: -
-
BPv6 Bundle:
+
+
Bundle:
-All encoded BP version 6 bundles begin with the version identifier octet 0x06 in accordance with . -A message with a leading octet value of 0x06 SHALL be treated as a BPv6 bundle. -Multiple BPv6 Bundles SHOULD NOT be present in one UDPCL packet to maintain compatibility with . -
-
BPv7 Bundle:
-
- -All encoded BP version 7 bundles begin with a CBOR array head in accordance with . -A message with a leading octet value indicating CBOR array (major type 4) SHALL be treated as a BPv7 bundle. - -BPv7 bundles transmitted via UDPCL SHALL NOT include any leading CBOR tag. -If the BP agent provides bundles with such tags the transmitting UDPCL entity SHALL remove them. +When sent outside of an explicit, identified transfer (see ) an encoded bundle is treated as a separate message type. +This is for compatibility with but comes at the expense of the UDPCL not being able to de-duplicate any redundant transfers. +
+
BPv6 Bundle:
+
+All encoded BP version 6 bundles begin with the version identifier octet 0x06 in accordance with . +A message with a leading octet value of 0x06 SHALL be treated as a BPv6 bundle. +Multiple BPv6 Bundles SHOULD NOT be present in one UDPCL packet to maintain compatibility with . +
+
BPv7 Bundle:
+
+ +All encoded BP version 7 bundles begin with a CBOR array head in accordance with . +A message with a leading octet value indicating CBOR array (major type 4) SHALL be treated as a BPv7 bundle. + + +BPv7 bundles transmitted via UDPCL SHALL NOT include any leading CBOR tag. +If the BP agent provides bundles with such tags the transmitting UDPCL entity SHALL remove them. + +
+
Extension Map:
-All UDPCL extensions SHALL be contained in a CBOR map in accordance with the definitions of . -The encoded Extension Map SHALL NOT have any CBOR tags. -A message with a leading octet value indicating CBOR map (major type 5) SHALL be treated as an Extension Map. +All UDPCL extensions SHALL be contained in a CBOR map in accordance with the definitions of . +The encoded Extension Map SHALL NOT have any CBOR tags. +A message with a leading octet value indicating CBOR map (major type 5) SHALL be treated as an Extension Map.
Padding:
-Padding data SHALL be a sequence of octets all with value 0x00. -A message with a leading octet value of 0x00 SHALL be treated as padding. +Padding data SHALL be a sequence of octets all with value 0x00. +A message with a leading octet value of 0x00 SHALL be treated as padding. Padding is used to ensure a UDP datagram is exactly a desired size. -Because padding has no intrinsic length indication, if present it SHALL be the last contents of any UDPCL packet. -A receiving UDPCL entity SHALL ignore all padding, including any trailing non-zero octets. - -
-
DTLS Record:
-
- -In addition to the UDPCL specific messaging, immediately after a DTLS Initiation (see ) the DTLS handshake sequence will begin. -Data with a leading octet value of 0x16 SHALL be treated as a DTLS handshake record in accordance with . - - -If the datagram with the DTLS Initiation extension is not received by an entity, the entity SHOULD still detect the DTLS handshake records and start the handshake sequence at that point. -Data with a leading octet value of 0x17--0x19 SHALL be treated as a DTLS sequencing failure; DTLS non-handshake records should never be seen by the UDPCL messaging layer. +Because padding has no intrinsic length indication, if present it SHALL be the last contents of any UDPCL packet. +A receiving UDPCL entity SHALL ignore all padding, including any trailing non-zero octets.
-A summary of how a receiving UDPCL entity can interpret the first octet of a datagram is listed in . +A summary of how a receiving UDPCL entity can interpret the first octet of a UDPCL packet is listed in . When inspecting using CBOR major types, the range of values is caused by the CBOR head encoding of . @@ -542,32 +569,39 @@ When inspecting using CBOR major types, the range of values is caused by the CBO + - + + + - - + + + + + +
Octet Value Message ContentMessage Extent
0x00Padding (remainder of packet)PaddingRemainder of packet
0x06 BPv6 BundleEnd of self-delimited bundle encoding
0x16--0x19DTLS Record (remainder of packet)0x14--0x1A or 0x20--0x3FDTLS RecordRemainder of packet
0x80--0x9F BPv7 Bundle (CBOR array)End of array item (self-delimited bundle encoding)
0xA0--0xBF Extension Map (CBOR map)End of map item
others unused
@@ -576,13 +610,13 @@ When inspecting using CBOR major types, the range of values is caused by the CBO UDPCL Extension Items Extensions to UDPCL are encoded per-datagram in a single CBOR map as defined in . -Each UDPCL extension item SHALL be identified by a unique Extension ID used as a key in the Extension Map. -Extension ID values SHALL be a CBOR int item no longer than 16-bits. +Each UDPCL extension item SHALL be identified by a unique Extension ID used as a key in the Extension Map. +Extension ID values SHALL be a CBOR int item which fits within a signed 16-bit integer. Extension ID assignments are listed in . -Unless prohibited by particular extension type requirements, a single Extension Map MAY contain any combination of extension items. -Receivers SHALL ignore extension items with unknown Extension ID and continue to process known extension items. +Unless prohibited by particular extension type requirements, a single Extension Map MAY contain any combination of extension items. +Receivers SHALL ignore extension items with unknown Extension ID and continue to process known extension items.
Extension Map structure CDDL @@ -592,74 +626,74 @@ Receivers SHALL ignore extension items with unknown Extension ID and continue to ; being present (or not present) in the same map. udpcl-ext-map = $udpcl-ext-map .within udpcl-ext-map-structure $udpcl-ext-map = { - * $$udpcl-ext-item + + $$udpcl-ext-item } udpcl-ext-map-structure = { - * ext-key => any + + ext-key => any } -ext-key = (int .size 2) .ne 0 +ext-key = ((-32768 .. 32767) .within int) .ne 0
The following subsections define the initial UDPCL extension types. -
- DTLS Initiation (STARTTLS) +
+ Extension Support -This extension item indicates that the transmitter is about to begin a DTLS handshake sequence in accordance with . +This extension allows an entity to signal its support for receiving specific UDPCL extension types. -The DTLS Initiation value SHALL be an untagged null value. -There are no DTLS parameters actually transmitted as part of this extension, it only serves to indicate to the recipient that the next datagram will be a DTLS ClientHello. -Although the datagram containing this extension is not retransmitted, the DTLS handshake itself will retransmit ClientHello messages until confirmation is received. +The Extension Support value SHALL be a CBOR array of int items. +Each item SHALL represent an extension type code which is able to be handled by the entity sending the Extension Support. + + +The minimum set of Extension Support SHOULD contain values 1 through 8 inclusive, which are the extension types defined in this document.
- DTLS Initiation CDDL + Extension Support CDDL $$udpcl-ext-item //= ( - 5: null + 1: [ + ext-key ] )
-If the entity is configured to enable exchanging messages according to DTLS 1.2 or any successors which are compatible with that DTLS ClientHello, the first message in any sequence to a unicast recipient SHALL be an Extension Map with the DTLS Initiation item. -The RECOMMENDED policy is to enable DTLS for all unicast recipients, even if security policy does not allow or require authentication. -This follows the opportunistic security model of , though an active attacker could interfere with the exchange in such cases (see ). +This extension type is expected to be used along with for announcing presence to (potential) peer entities. -The Extension Map containing a DTLS Initiation item SHALL NOT contain any other items. -A DTLS Initiation item SHALL NOT be present in any message transmitted within a DTLS session. -A receiver of a DTLS Initiation item within a DTLS session SHALL ignore it. -Between transmitting a DTLS Initiation item and finishing a DTLS handshake (either success or failure) an entity SHALL NOT transmit any other UDP datagrams in that same conversation. +If an entity receives an extension type which it cannot handle, that entity MAY send an Extension Support item in response. +The enveloping UDPCL packet SHALL use the source address-and-port that sent the unhandled extension type as the destination of the packet.
- Bundle Transfer + Transfer -This extension item allows CL-layer fragmentation of bundle transfers as defined in . +This extension item allows CL-layer segmentation of bundle transfers as defined in . -The Transfer value SHALL be an untagged CBOR array of four items. +The Transfer value SHALL be an untagged CBOR array of two or four items. The items are defined in the following order:
Transfer ID:
-This field SHALL be a CBOR uint item no larger than 32-bits, which is used to correlate multiple fragments. +This field SHALL be a CBOR uint item no larger than 32-bits, which is used to correlate multiple segments.
Total Length:
-This field SHALL be a CBOR uint item no larger than 32-bits, which is used to indicate the total length (in octets) of the transfer. -If multiple Transfer items for the same Transfer ID are received with differing Total Length values, the receiver SHALL treat the transfer as being malformed and refuse to handle any further fragments associated with the transfer. +This optional field SHALL be a CBOR uint item no larger than 32-bits, which is used to indicate the total length (in octets) of the transfer. +If multiple Transfer items for the same Transfer ID are received with differing Total Length values, the receiver SHALL treat the transfer as being malformed and refuse to handle any further segments associated with the transfer. +If a transfer requires only a single segment, this field SHALL be omitted and the total length treated as the size of the Segment Data.
-
Fragment Offset:
+
Segment Offset:
-This field SHALL be a CBOR uint item no larger than 32-bits, which is used to indicate the offset (in octets) into the transfer for the start of this fragment. +This optional field SHALL be a CBOR uint item no larger than 32-bits, which is used to indicate the offset (in octets) into the transfer for the start of this segment. +If a transfer requires only a single segment, this field SHALL be omitted and the segment offset treated as zero.
-
Fragment Data:
+
Segment Data:
-This field SHALL be a CBOR bstr item no larger than 2^32-1 octets, in which the fragment data is contained. -The bstr itself indicates the length of the fragment data. +This field SHALL be a CBOR bstr item no larger than 2^32-1 octets, in which the segment data is contained. +The bstr itself indicates the length of the segment data.
@@ -668,13 +702,22 @@ The bstr itself indicates the length of the fragment data. $$udpcl-ext-item //= ( 2: [ transfer-id: uint .size 4, - total-length: uint .size 4, - fragment-offset: uint .size 4, - fragment-data: bstr, + ?( + total-length: uint .size 4, + segment-offset: uint .size 4, + ), + segment-data: bstr, ] )
+ +Multiple Transfer items MAY be present in the same UDPCL packet by concatenating multiple Extension Map into one packet. + + +A transmitting entity SHALL use the same source and destination address-and-port for all UDPCL packets comprising a single segmented transfer. +This is more strict than the requirements of to ensure consistent reassembly behavior in . +
Sender Listen @@ -685,13 +728,13 @@ Although the packet containing this extension is not retransmitted, the time int There is no positive indication that packets are no longer accepted; the Sender Listen just stops being transmitted. -The Sender Listen value SHALL be an untagged uint value representing the interval of time (in milliseconds) that the entity is willing to accept UDPCL packets on the source address-and-port used for the associated transmitted message. -After transmitting a Sender Listen, the entity SHALL listen for and accept datagrams on the source address-and-port used for the associated transmitted message. -As long as the entity is still willing to accept packets, at the end of one accept interval the entity SHALL transmit another Sender Listen item. +The Sender Listen value SHALL be an untagged uint value representing the interval of time (in milliseconds) that the entity is willing to accept UDPCL packets on the source address-and-port used for the associated transmitted message. +After transmitting a Sender Listen, the entity SHALL listen for and accept datagrams on the source address-and-port used for the associated transmitted message. +As long as the entity is still willing to accept packets, at the end of one accept interval the entity SHALL transmit another Sender Listen item. This repetition continues until the entity is no longer willing to listen for packets. -A receiving entity SHOULD treat a peer as no longer listening after an implementation-defined timeout since the last received Sender Listen item. +A receiving entity SHOULD treat a peer as no longer listening after an implementation-defined timeout since the last received Sender Listen item. A RECOMMENDED Sender Listen timeout is three (3) times the associated time duration; this allows a single dropped datagram to not interrupt a continuous sequence.
@@ -704,20 +747,19 @@ time-duration = uint
-Unlike the generic source port requirement in , when repeated Sender Listen are transmitted in a sequence a consistent source address-and-port SHALL be used. +Unlike the generic source port requirement in , when repeated Sender Listen are transmitted in a sequence a consistent source address-and-port SHALL be used. -The Sender Listen interval SHOULD be no shorter than 1 second and no longer than 60 seconds. +The Sender Listen interval SHOULD be no shorter than 1 second and no longer than 60 seconds. -An entity SHOULD include a Sender Node ID item along with a Sender Listen item if the conditions of are met. -An entity MAY include any other extension type along with a Sender Listen item. -An entity SHALL NOT transmit a Sender Listen item before or along with a DTLS Initiate if DTLS is desired for a conversation. +An entity SHOULD include an and item along with a Sender Listen item if the conditions of those extension types are met. +An entity MAY include any other extension type along with a Sender Listen item. +An entity SHALL NOT transmit a Sender Listen item before or along with a DTLS Initiate if DTLS is desired for a conversation. This extension is not a neighbor discovery mechanism and does not indicate an entity listening generally on a particular UDP port. Sender Listen applies only to UDP datagrams from the the peer address-and-port. -An entity SHALL NOT include a Sender Listen item in a message transmitted to a multicast address.
@@ -727,8 +769,8 @@ This extension item indicates the Node ID of the transmitter. For DTLS-secured sessions (see ) this extension can be used to disambiguate an end-entity certificate which has multiple NODE-ID values. -The Sender Node ID value SHALL be an untagged tstr value containing a Node ID. -Every Node ID SHALL be a URI consistent with the requirements of and the URI schemes of the IANA "Bundle Protocol URI Scheme Type" registry . +The Sender Node ID value SHALL be an untagged tstr value containing a Node ID. +Every Node ID SHALL be a URI consistent with the requirements of and the URI schemes of the IANA "Bundle Protocol URI Scheme Type" registry .
Sender Node ID CDDL @@ -740,21 +782,208 @@ nodeid = tstr
-An entity SHOULD NOT include a Sender Node ID item if a DTLS session has already been established and the presented end-entity certificate contains a single NODE-ID. +An entity SHOULD NOT include a Sender Node ID item if a DTLS session has already been established and the presented end-entity certificate contains a single NODE-ID. In this case there is no ambiguity about which Node ID is identified by the certificate. -If an entity receives a peer Node ID which is not authenticated (by the procedure of ) that Node ID SHOULD NOT be used by a BP agent for any discovery or routing functions. +If an entity receives a peer Node ID which is not authenticated (by the procedure of ) that Node ID SHOULD NOT be used by a BP agent for any discovery or routing functions. Trusting an unauthenticated Node ID can lead to the threat described in .
+
+ DTLS Initiation (STARTTLS) + +This extension item indicates that the transmitter is about to begin a DTLS handshake sequence in accordance with . + + +The DTLS Initiation value SHALL be an untagged null value. +There are no DTLS parameters actually transmitted as part of this extension, it only serves to indicate to the recipient that the next datagram will be a DTLS ClientHello. +Although the datagram containing this extension is not retransmitted, the DTLS handshake itself will retransmit ClientHello messages until confirmation is received. + +
+ DTLS Initiation CDDL + +$$udpcl-ext-item //= ( + 5: null +) + +
+ +If the entity is configured to enable exchanging messages according to DTLS 1.3 or any successors which are compatible with that DTLS ClientHello, the first message in any sequence to a unicast recipient SHALL be an Extension Map with the DTLS Initiation item. +The RECOMMENDED policy is to enable DTLS for all unicast recipients, even if security policy does not allow or require authentication. +This follows the opportunistic security model of , though an active attacker could interfere with the exchange in such cases (see ). + + +The Extension Map containing a DTLS Initiation item SHALL NOT contain any other items. +A DTLS Initiation item SHALL NOT be present in any message transmitted within a DTLS session. +A receiver of a DTLS Initiation item within a DTLS session SHALL ignore it. +Between transmitting a DTLS Initiation item and finishing a DTLS handshake (either success or failure) an entity SHALL NOT transmit any other UDP datagrams in that same conversation. + +
+
+ Peer Probe + +This extension item provides the Probe Packet functionality of in order to support path MTU discovery mechanism of . + + +The Peer Probe value SHALL be an array of three items. +The items are defined in the following order: + +
+
Nonce:
+
+The first item SHALL be a uint nonce for correlating with extensions. +
+
Sequence Number:
+
+The second item SHALL be a uint sequence number for the specific Probe packet. +
+
Confirmation Delay:
+
+The second item SHALL be a uint representing the desired confirmation delay time (in milliseconds). +
+
+
+ Peer Probe CDDL + +$$udpcl-ext-item //= ( + 6: [ + nonce, + seqno, + confirm-delay + ], +) +; A correlator nonce for confirmations +nonce = uint +seqno = uint +confirm-delay = uint + +
+ +When the Peer Probe item is present in a UDPCL packet, the Extension Map SHALL be the only message in the packet and it SHALL be followed by padding to a specific total size. +A transmitting entity SHALL use the same source and destination address-and-port for all UDPCL packets containing a Peer Probe with the same nonce value. +This is more strict than the requirements of to ensure consistent confirmation behavior defined below. + + +The nonce value SHALL be used to correlate multiple Probe packets into a single sequence. +If an entity receives multiple unique nonce values from the same source address-and-port and the number of unique nonce values exceeds an upper limit, the receiving entity SHALL ignore the Probe. +The upper limit is implementation defined but SHOULD be no less than one unique nonce at-a-time. + + +If the confirmation delay time is above an upper limit the receiving entity SHALL ignore the Probe. +The upper limit is implementation defined but SHOULD be no shorter than one minute (60 seconds). + + +If an entity receives multiple instances of Peer Probe with the same nonce and sequence number values, the duplicates SHALL NOT be ignored. +This makes the last duplicate transmission of the last probe the basis of Peer Confirmation timing. + + +After an entity receives and validates a packet with a Peer Probe extension item it SHALL wait for the indicated confirmation delay time before sending a item. +The enveloping UDPCL packet SHALL use the source address-and-port that sent the last Probe item as the destination of the Confirmation. +Once the Peer Confirmation packet is sent, the entity SHALL remove state associated with the Peer Probe items being confirmed. +This bounds the state on a confirming entity and makes each Peer Confirmation with the same nonce value incremental and not additive (i.e., there will never be two Confirmations with the same nonce covering the same sequence numbers, except for duplicate transmissions). + +
+
+ Peer Confirmation + +This extension item provides the Confirmation functionality of in order to support path MTU discovery mechanism of . + + +The Peer Confirmation value SHALL be an array of two items. +The items are defined in the following order: + +
+
Nonce:
+
+The first item SHALL be a uint nonce for correlating with items. +
+
Seen Sequence Range:
+
+The second item SHALL be an array of pairs of uint values representing the range of sequence numbers of received Probe packets with the same nonce value. +
+
+ +The encoding of ranges is a compressed form in which each pair of values indicates: + +
    +
  1. +The non-zero offset from the previous one-past-end-of-interval, or the offset from zero if there is no preceding interval +
    2. +
  2. +The length of this interval, which is inclusive of the first and last contained sequence number so will always be positive +
    3. +
+
+ Peer Confirmation CDDL + +$$udpcl-ext-item //= ( + 7: [ + nonce, + seen-range + ], +) +; Range of sequence numbers seen +seen-range = [ + seen-interval-pair ] +seen-interval-pair = ( + offset: uint, + length: uint .gt 0, +) + +
+ +When an entity receives a packet with a Peer Confirmation extension item it SHALL wait for the same confirmation delay used in each Probe item for multiple Confirmation items with the same nonce. +Upon reception of all Confirmation items within the waiting delay, the entity SHALL treat the largest value of the seen range as the PMTU to the corresponding peer entity. + +
+
+ ECN Counts + +This extension item provides the ECN Feedback functionality of in order to support congestion control feedback of . + + +The ECN Counts value SHALL be an array of three items. +The items are defined in the following order: + +
+
ECT(0) Count:
+
+The first item SHALL be a uint count of packets marked with ECT(0) received from the peer, wrapped to 32-bits. +
+
ECT(1) Count:
+
+The second item SHALL be a uint count of packets marked with ECT(1) received from the peer, wrapped to 32-bits. +
+
CE Count:
+
+The third item SHALL be a uint count of packets marked with CE received from the peer, wrapped to 32-bits. +
+
+
+ ECN Counts CDDL + +$$udpcl-ext-item //= ( + 8: [ + ect0: ecn-count, + ect1: ecn-count, + ce: ecn-count + ], +) +; Wraps around at 32-bits +ecn-count = uint .size 4 + +
+ +Because this extension type will only be used for feedback to a specific transmitting peer, it SHALL NOT be present in any UDPCL packet with an IP multicast destination. + +
- Explicit Transfers + Identified Transfers -This version of UDPCL supports CL-layer fragmentation of bundles larger than the PMTU would otherwise allow. -Policies related to fragmentation at, above, or below the UDPCL layer are defined in . -The entire fragmented bundle is referred to as a Transfer and individual fragments of a transfer are encoded as Transfer extension items in accordance with . +This version of UDPCL supports CL-layer identification of bundles and segmentation of bundles larger than the PMTU would otherwise allow. +Policies related to segmentation at or fragmentation above, or below the UDPCL layer are defined in . +The entire segmented bundle is referred to as a Transfer and individual segments of a transfer are encoded as Transfer extension items in accordance with . This mechanism also allows a bundle transfer to be transmitted along with additional extension items, which the unframed bundle-in-datagram data does not. @@ -768,45 +997,164 @@ A Transfer ID does not attempt to address uniqueness of the bundle data itself a Each invocation of UDPCL by the BP agent, requesting transmission of a bundle (fragmentary or otherwise), can cause the initiation of a single UDPCL transfer. -Because UDPCL operation is connectionless, Transfer IDs from each entity SHALL be unique for the operating duration of the entity. -In practice, the ID needs only be unique for the longest receiver reassembly time window; but because that information is not part of the protocol there is no way for an transmitting entity to know the reassembly time window of any receiver (see ). -When there are bidirectional bundle transfers between UDPCL entities, an entity SHOULD NOT rely on any relation between Transfer IDs originating from each side of the conversation. +Because UDPCL operation is connectionless, Transfer IDs from each entity SHALL be unique for the operating duration of the entity. +In practice, the ID needs only be unique for the longest receiver de-duplication and reassembly time window; but because that information is not part of the protocol there is no way for an transmitting entity to know the reassembly time window of any receiver (see ). +When there are bidirectional bundle transfers between UDPCL entities, an entity SHOULD NOT rely on any relation between Transfer IDs originating from each side of the conversation. -Although there is not a strict requirement for Transfer ID initial values or ordering (see ), in the absence of any other mechanism for generating Transfer IDs an entity SHALL use the following algorithm: +Although there is not a strict requirement for Transfer ID initial values or ordering (see ), in the absence of any other mechanism for generating Transfer IDs an entity SHALL use the following algorithm: the initial Transfer ID from each entity is zero; subsequent Transfer ID values are incremented from the prior Transfer ID value by one; upon exhaustion of the entire 32-bit Transfer ID space, the subsequent Transfer ID value is zero.
-
- Fragmentation and Reassembly +
+ Segmentation and Reassembly + +The full data content of a transfer SHALL be an unframed (BPv6 or BPv7) bundle as defined in . +A receiving entity SHALL discard any reassembled transfer which does not properly contain a bundle as defined in . + -The full data content of a transfer SHALL be an unframed (BPv6 or BPv7) bundle as defined in . -A receiving entity SHALL discard any reassembled transfer which does not properly contain a bundle. +A transmitting entity MAY produce a Transfer with a single segment (i.e., a Segment Data size identical to the Total Length) in which case the redundant Transfer fields are omitted. +A transmitting entity SHALL NOT produce Transfer segments with overlapping span. +A transmitting entity SHOULD transmit Transfer segments in order of Segment Offset; this makes the behavior deterministic. -A transmitting entity MAY produce a Transfer with a single fragment (i.e., a Fragment Data size identical to the Total Length). -A transmitting entity SHALL NOT produce Transfer fragments with overlapping span. -A transmitting entity SHOULD transmit Transfer fragments in order of Fragment Offset; this makes the behavior deterministic. +A receving entity SHALL maintain transfer reassembly state based on the tuple of packet source address-and-port and the Transfer ID sent by that source. +This relies on the stability of source port numbers at least for the duration of a single transfer, as required by . +See for options and implications of source port number use. Because of the nature of UDP transport, there is no guaranteed order or timing of received Transfer items. -A receiving entity SHALL consider a transport as finished when Fragment Data has been received which fully covers the Total Length of the transfer. +A receiving entity SHALL consider a transport as finished when Segment Data has been received which fully covers the Total Length of the transfer. -A receiving entity SHALL discard any Transfer item containing different CBOR types than defined in this document. -A receiving entity SHALL discard any Transfer item containing a fragment with an overlapping span. -Because there is no feedback indication at the UDPCL layer, a transmitter has no indication when a transfer is discarded by the receiver. +A receiving entity SHALL discard any Transfer item containing different CBOR types than defined in this document. +A receiving entity SHALL discard any Transfer item containing a segment with a span overlapping any other in the reassembly state. +That includes overlapping span because of a redundant transmission (see ). +Because there is no feedback indication at the UDPCL layer, a transmitter has no indication when a Transfer item is discarded by the receiver. -A receiving entity SHOULD discard unfinished transfer state after an implementation-defined timeout since the last received fragment. -Entities SHOULD choose a transfer timeout interval no longer than one minute (60 seconds). -Discarding an unfinished transfer causes no indication to the transmitting entity, but does indicate this to the BP agent. -This timeout is purely receiver-side and represents the maximum allowed time between sequential received datagrams (in any order), which should be short if the datagrams take a similar network path. +A receiving entity SHOULD discard unfinished reassembly state after an implementation-defined timeout since the last received segment. +This timeout is purely receiver-side and represents the maximum allowed time between sequential received datagrams (in any order), which will be short if the datagrams take a similar network path. +A receiving entity SHALL NOT discard reassembly state upon successful completion of a transfer, in case the transmitting entity is sending redundant packets () which need to be discarded. +Entities SHOULD choose a transfer timeout interval no longer than one minute (60 seconds). +Discarding an unfinished transfer causes no indication to the transmitting entity, but does indicate this to the receiving BP agent.
+
+ Path Characterization Procedures + +The procedures defined in this section allow pairs of UDPCL entities to characterize IP path parameters between them when those parameters are either unknown or for troubleshooting when actual network performance deviates from expectations. + + +These procedures not mandated to be used operationally, but when the associated characterization is desired these are the procedures which SHALL be used. + +
+ Packetization Layer Path MTU Discovery + +This version of UDPCL is compatible with the requirements of Packetization Layer Path MTU Discovery (PLPMTUD) from . +Specifically the UDPCL supports the requirements of by using the extension item to perform the probe behavior and extension item for the confirmation behavior. +Because the Peer Confirmation acknowledges a possibly large range of Peer Probe packets, this makes the UDPCL less sensitive to large or time-variable path delays than if each Probe was separately acknowledged. + + +The use of PLPMTUD is especially helpful when DTLS is used to secure UDPCL conversations, as the DTLS confidentiality mechanism and associated record layer reduces the maximum packet size (MPS) by an amount depending upon the negotiated ciphersuite. + + +In case one or more Peer Probe items are sent but no corresponding Peer Confirmation is ever received, this might indicate that the peer has not implemented or enabled PLPMTUD and SHOULD NOT be treated as an indication that the peer is unreachable. + +
+
+ Delay Time Estimation + +The round-trip time (RTT) between two entities can be estimated by sending a sequence of small sized items, each in its own UDPCL packet, with a small or zero Confirmation Delay and measuring the time taken to receive the corresponding item. + + +The sequence MAY be as short as a single packet to get a point estimate of RTT. +Otherwise, the inter-packet interval at the sender SHALL be larger than the Confirmation Delay contained in each item. +This will cause each probe packet to correspond with a single related confirmation packet allowing either a time-series estimation or an average-over-time estimation of RTT. + + +Because there is no explicit time tagging of the acknowledgement, the one-way delay can be assumed to be one half of the RTT total. + +
+
+ Throughput and Loss Estimation + +The one-way packet loss between two entities can be estimated by sending a sequence of equally-sized items, each in its own UDPCL packet, over some short time interval and observing how many of the probes have been seen in one or more corresponding item. +For relatively low loss rates, a BER can be estimated by assuming each lost packet is caused by an equivalent to a single random error. + + +Similarly, a sequence of relatively large-sized (for the expected throughput order-of-magnitude) items, each in its own UDPCL packet, and the total volume indicated by corresponding items over some time interval can be used to estimate the one-way throughput limit. + + +For both cases above, the Probe packets can be combined with ECN markings as described in to ensure that losses or throughput limits are not related to intermediate queuing congestion. + +
+
+ Congestion Control Feedback + +AQM can be performed using "classic" ECN of or with more advanced methods such as the ECN Protocol for Low Latency, Low Loss, and Scalable Throughput (L4S) of . +These mechanisms allow for endpoints to implement internet-friendly congestion control with a small amount of application-level feedback of ECN data. +The ECN Counts extension of allows a UDPCL entity to both signal that it is ECN capable and to report ECN feedback in a way compatible with both and . + + +Because the information base defined below counts ECN values based on UDP conversation, the feedback occurs at the level of the entire conversation and not an individual message or bundle transfer within. +When present, any sending queues of a UDPCL entity SHALL be organized around the UDP conversation. + + +When an entity has enabled a congestion control mechanism, it SHALL mark outgoing IP packets with an ECN field of either ECT(0) or ECT(1) codepoint if they contain bundle data (either from an unframed transfer or an identified transfer ). +This marking is the signal that the sending entity is ECN capable and desires to receive ECN feedback. + + +When an entity has enabled ECN feedback and receives a UDPCL packet with a unicast IP destination and an ECN field other than the Not-ECT codepoint, the ECN field of the IP packet SHALL be used to update the entry of the ECN Feedback information table corresponding to its UDP Conversation. +When a new entry is needed in the ECN Feedback information table, the counts SHALL be initialized to zero. + + +When an entity has ECN feedback for a peer, it SHALL send ECN Counts extension items to that peer. +The ECN Counts extension MAY be sent periodically by a timer or when count values are increased above some threshold. +When triggered by timer, the minimum interval SHOULD be no shorter than 1 second. +When triggered by count change, the minimum increase SHOULD be no a change in CE Count being TBD% of the sum of the changes of ECT(0) Count and ECT(1) Count. + + +The information base for ECN Feedback information is a logical table containing the columns of . + + + ECN Feedback Information Columns + + + + + + + + + + + + + + + + + + + + + + + + +
NameDescription
UDP ConversationThis is the four-tuple of address-and-port for the remote and local UDP endpoints.
ECT(0) Count +This is the total number of IP packets received in the UDP Conversation with the ECN field containing the ECT(0) codepoint. +
ECT(1) Count +This is the total number of IP packets received in the UDP Conversation with the ECN field containing the ECT(0) codepoint. +
CE Count +This is the total number of IP packets received in the UDP Conversation with the ECN field containing the CE codepoint. +
+
+
UDPCL Security @@ -815,10 +1163,10 @@ When DTLS is used within the UDPCL it affects the entire conversation. There is no concept of a plaintext message being sent in a conversation after a DTLS session is established. -Once established, the lifetime of a DTLS session SHALL be bound by the DTLS session ticket lifetime or either peer sending a Closure Alert record. +Once established, the lifetime of a DTLS session SHALL be bound by the DTLS session ticket lifetime or either peer sending a Closure Alert record. -Subsequent DTLS session attempts to the same passive entity MAY attempt to use the DTLS session resumption feature. +Subsequent DTLS session attempts to the same passive entity MAY attempt to use the DTLS session resumption feature. There is no guarantee that the passive entity will accept the request to resume a DTLS session, and the active entity cannot assume any resumption outcome.
@@ -828,37 +1176,37 @@ The UDPCL uses DTLS for certificate exchange in both directions to identify each Each certificate can potentially identify multiple entities and there is no problem using such a certificate as long as the identifiers are sufficient to meet authentication policy (as described in later sections) for the entity which presents it. -The types and priorities of identities used by DTLS in UDPCL is the same as those for TLS in TCPCL as defined in . +The types and priorities of identities used by DTLS in UDPCL is the same as those for TLS in TCPCL as defined in .
Certificate Profile for UDPCL -All end-entity certificates used by a UDPCL entity SHALL conform to the profile defined in . +All end-entity certificates used by a UDPCL entity SHALL conform to the profile defined in .
DTLS Handshake The signaling for DTLS Initiation is described in . -After sending or receiving an Extension Map containing a DTLS Initiation item, an entity SHALL begin the handshake procedure of . +After sending or receiving an Extension Map containing a DTLS Initiation item, an entity SHALL begin the handshake procedure of . By convention, this protocol uses the entity which sent the DTLS Initiation (the active peer) as the "client" role of the DTLS handshake request. -Upon receiving an unexpected ClientHello record outside of a DTLS session, an entity SHALL begin the DTLS handshake procedure as if a DTLS Initiation had been received. +Upon receiving an unexpected ClientHello record outside of a DTLS session, an entity SHALL begin the DTLS handshake procedure as if a DTLS Initiation had been received. This allows recovering from a dropped packet containing DTLS Initiation.
DTLS Authentication -The function and mechanism of DTLS authentication in UDPCL is the same as for TLS in TCPCL as defined in , with the exception that Node ID Authentication is based on an optional Sender Node ID extension (see ) used to disambiguate when an end-entity certificate contains multiple NODE-ID values. +The function and mechanism of DTLS authentication in UDPCL is the same as for TLS in TCPCL as defined in , with the exception that Node ID Authentication is based on an optional Sender Node ID extension (see ) used to disambiguate when an end-entity certificate contains multiple NODE-ID values.
Policy Recommendations -The policy recommendations given here are are the same as those for TCPCL in . +The policy recommendations given here are are the same as those for TCPCL in . They are restated in this document for clarity. @@ -957,7 +1305,7 @@ This can be avoided by always using DTLS, even if authentication is not availabl Threat: Passive Leak of Bundle Data UDPCL can be used to provide point-to-point unicast transport security, but does not provide multicast security, security of data-at-rest, and does not guarantee end-to-end bundle security. -In those cases the bundle security mechanisms defined in are to be used instead. +In those cases the bundle security mechanisms defined in are to be used instead. When used without DTLS security, the UDPCL exposes all bundle data to passive eavesdroppers. @@ -1029,10 +1377,24 @@ Determining when a DNS-ID/IPADDR-ID authentication can be trusted to validate a One mitigation to arbitrary entities with valid PKIX certificates impersonating arbitrary Node IDs is the use of the PKIX Extended Key Usage key purpose "id-kp-bundleSecurity" of . -When this Extended Key Usage is present in the certificate, it represents a stronger assertion that the private key holder should in fact be trusted to operate as a DTN Node. +When this Extended Key Usage is present in the certificate, it represents a stronger assertion that the private key holder is trusted to operate as a DTN Node.
-
+
+ Threat: Off-Path Packet Injection + +As described in , when each endpoint of a UDP conversation uses a stable port number the conversation can be more easily snooped and off-path packets can be injected to spoof UDPCL traffic. +When the requirements in are followed UDPCL traffic will use predictable, well-known port numbers and will be subject to this threat. + + +One direct mitigation of this threat is to use DTLS to ensure that off-path attackers cannot inject packets without being discovered and those packets rejected at the destination. + + +Another mitigation is for a UDPCL entity to use the well-known UDPCL port for passive listening but choose an ephemeral port to bind to when acting as the active peer. +This will enable some amount of obfuscation while maintaining stable UDP conversations, but could also make legitimate traffic analysis and troubleshooting more difficult. + +
+
Threat: Denial of Service The behaviors described in this section all amount to a potential denial-of-service to a UDPCL entity. @@ -1043,8 +1405,8 @@ An entity can send a large amount of data to a UDPCL entity, requiring the recei The victim entity can block UDP packets from network peers which are thought to be incorrectly behaving within network. -An entity can also send only one fragment of a seemingly valid transfer and never send the remaining fragments, which will cause resources on the receiver to be wasted on transfer reassembly state. -The victim entity can either block packets from network peers or intentionally keep a short unfinished transfer timeout (see ). +An entity can also send only one segment of a seemingly valid transfer and never send the remaining segments, which will cause resources on the receiver to be wasted on transfer reassembly state. +The victim entity can either block packets from network peers or intentionally keep a short unfinished transfer timeout (see ). The keepalive mechanism can be abused to waste throughput within a network link which would otherwise be usable for bundle transmissions. @@ -1068,7 +1430,7 @@ The following subsections give examples of alternate DTLS uses.
DTLS Without Authentication - In environments where PKI is available but there are restrictions on the issuance of certificates (including the contents of certificates), it may be possible to make use of DTLS in a way which authenticates only the passive entity of a UDPCL transfer or which does not authenticate either entity. + In environments where PKI is available but there are restrictions on the issuance of certificates (including the contents of certificates), it can be possible to make use of DTLS in a way which authenticates only the passive entity of a UDPCL transfer or which does not authenticate either entity. Using DTLS in a way which does not successfully authenticate some claim of both peer entities of a UDPCL transfer is outside of the scope of this document but does have similar properties to the opportunistic security model of .
@@ -1094,12 +1456,70 @@ Even when UDPCL is not DTLS secured and there is a on-path attacker altering UDP Registration procedures referred to in this section are defined in . -
- Port Number +
+ IP Multicast Addresses + +This document allocates new routable multicast addresses for use with the UDPCL. + + +Within the port registry of , the sub-registry titled "Internetwork Control Block" has been updated to include the following address. + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue
Address(es):TBA-IP4
Description:All BP Nodes
References:[This specification]
+ +Within the port registry of , the sub-registry titled "Variable Scope Multicast Addresses" has been updated to include the following address. + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue
Address(es):TBA-IP6
Description:All BP Nodes
References:[This specification]
+
+
+ UDP Port Number Within the port registry of , UDP port number 4556 has been previously assigned as the default port for the UDP convergence layer in . This assignment to UDPCL is unchanged, but the assignment reference is updated to this specification. There is no UDPCL version indication on-the-wire but this specification is a superset of and is fully backward compatible. + + The related assignment for DCCP port 4556 (registered by ) is unchanged. @@ -1132,7 +1552,7 @@ The related assignment for DCCP port 4556 (registered by - + @@ -1167,37 +1587,57 @@ Expert(s) are encouraged to be biased towards approving registrations unless the - + - + - + + + + + + - + - + - + - + + + + + + + + + + + + + + + + - + @@ -1205,12 +1645,6 @@ Expert(s) are encouraged to be biased towards approving registrations unless the
Reference:This specification.[This specification]
Port Number:
negative-32768 to -1 Private/Experimental UseThis specification.[This specification]
0 ReservedThis specification.[This specification]
1Extension Support of [this specification]
2 Transfer of this specification. of [this specification]
3 Sender Listen of this specification. of [this specification]
4 Sender Node ID of this specification. of [this specification]
5 DTLS Initiation (STARTTLS) of this specification. of [this specification]
6Peer Probe of [this specification]
7Peer Confirmation of [this specification]
8ECN Counts of [this specification]
6-655359 to 32767 Unassigned
-
- Acknowledgments - -TBD - -
@@ -1265,25 +1699,31 @@ TBD + - + - - + + + + Informative References + + + @@ -1293,9 +1733,10 @@ TBD - + + - + UDPCL Example Implementation @@ -1328,16 +1769,26 @@ The areas in which changes from have been made to exist
  • Made explicit references to UDP- and IP-related RFCs.
  • Made more strict Keepalive and Padding requirements.
    • -
  • Defined UDPCL security and made mandatory-to-implement.
    • +
  • Added Extension Map message type and initial extension types.
    • +
  • Defined UDPCL security and made it mandatory-to-implement but optional to use.
The areas in which extensions from have been made as new behaviors are:
  • Added BPv7 bundle as a possible UDPCL payload.
    • -
  • Added Extension Map message type and initial extension types.
    • -
  • Defined semantics for UDPCL multicast addressing.
    • +
  • Added discussion about optional explicit redundancy in transmission.
    • +
  • Added discussion about optional path MTU discovery.
    • +
  • Added discussion about optional congestion control feedback.
    • +
  • Defined semantics for IP multicast addressing.
    • +
  • Defined recommendations for UDP port use and re-use (port stability).
+
+ Acknowledgments + +Much pre-draft review was performed to make the document clear and readable by Sarah Heiner of JHU/APL. + +
diff --git a/spec/sort_dictionary.sh b/spec/sort_dictionary.sh new file mode 100755 index 0000000..101d7be --- /dev/null +++ b/spec/sort_dictionary.sh @@ -0,0 +1,6 @@ +#!/bin/bash +set -e +SELFDIR=$(readlink -f $(dirname "${BASH_SOURCE[0]}")) + +cat ${SELFDIR}/dictionary.txt | sort | uniq >${SELFDIR}/dictionary-sort.txt +mv ${SELFDIR}/dictionary-sort.txt ${SELFDIR}/dictionary.txt From b866569a09f9ef8062c574b60fbe9f2bc0aebc5d Mon Sep 17 00:00:00 2001 From: Brian Sipos Date: Wed, 31 Jul 2024 13:00:57 -0400 Subject: [PATCH 2/2] Using pages deploy action directly --- .github/workflows/rfc-check.yml | 70 +++++++++++++++++++++------------ 1 file changed, 44 insertions(+), 26 deletions(-) diff --git a/.github/workflows/rfc-check.yml b/.github/workflows/rfc-check.yml index 0ab2865..77224a4 100644 --- a/.github/workflows/rfc-check.yml +++ b/.github/workflows/rfc-check.yml @@ -1,41 +1,59 @@ name: RFC XML Check on: [push] + +# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages permissions: - contents: write + contents: read + pages: write + id-token: write + +# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. +# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. +concurrency: + group: "pages" + cancel-in-progress: false jobs: build: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v3 - - name: dependencies - run: | - sudo apt-get install -y aspell cmake python3 python3-pip python3-setuptools python3-wheel ruby xmlstarlet - sudo pip3 install xml2rfc - sudo gem install cddl - - name: xml2rfc - run: | - cmake -S . -B build -DCMAKE_INSTALL_DOCDIR=$PWD/build/install - cmake --build build -v - cmake --install build - - uses: actions/upload-artifact@v3 - with: - name: spec - path: build/install + - uses: actions/checkout@v3 + - name: dependencies + run: | + sudo apt-get install -y aspell cmake python3 python3-pip python3-setuptools python3-wheel ruby xmlstarlet + sudo pip3 install --upgrade pip + sudo pip3 install xml2rfc + sudo gem install cddl + - name: xml2rfc + run: | + cmake -S . -B build -DCMAKE_INSTALL_DOCDIR=$PWD/build/install + cmake --build build -v + cmake --install build + - uses: actions/upload-artifact@v3 + with: + name: spec + path: build/install deploy: if: github.ref == 'refs/heads/main' runs-on: ubuntu-latest needs: build + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} steps: - - uses: actions/checkout@v3 - - uses: actions/download-artifact@v3 - with: - name: spec - path: build/install - - name: Deploy 🚀 - uses: JamesIves/github-pages-deploy-action@4.1.0 - with: - branch: gh-pages # The branch the action should deploy to. - folder: build/install # The folder the action should deploy. + - uses: actions/checkout@v3 + - uses: actions/download-artifact@v3 + with: + name: spec + path: build/install + - name: Setup Pages + uses: actions/configure-pages@v3 + - name: Upload artifact + uses: actions/upload-pages-artifact@v2 + with: + path: build/install + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v2