idnits 2.17.1 draft-ietf-tsvwg-udp-options-10.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- == The document has an IETF Trust Provisions of 28 Dec 2009, Section 6.c(i) Publication Limitation clause. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 1580 has weird spacing: '...default mean...' == Line 1608 has weird spacing: '...enabled net.i...' == Line 1609 has weird spacing: '...enabled net....' == Line 1620 has weird spacing: '...default mean...' == Line 1626 has weird spacing: '... params mean...' == (1 more instance...) -- The document date (May 1, 2021) is 1083 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'RFC2460' is mentioned on line 1304, but not defined ** Obsolete undefined reference: RFC 2460 (Obsoleted by RFC 8200) -- Duplicate reference: RFC2119, mentioned in 'RFC8174', was also mentioned in 'RFC2119'. -- Obsolete informational reference (is this intentional?): RFC 793 (Obsoleted by RFC 9293) -- Obsolete informational reference (is this intentional?): RFC 2140 (Obsoleted by RFC 9040) -- Obsolete informational reference (is this intentional?): RFC 4960 (Obsoleted by RFC 9260) -- Obsolete informational reference (is this intentional?): RFC 6347 (Obsoleted by RFC 9147) -- Obsolete informational reference (is this intentional?): RFC 6691 (Obsoleted by RFC 9293) Summary: 1 error (**), 0 flaws (~~), 9 warnings (==), 7 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 TSVWG J. Touch 2 Internet Draft Independent consultant 3 Intended status: Standards Track May 1, 2021 4 Intended updates: 768 5 Expires: November 2021 7 Transport Options for UDP.txt 9 Status of this Memo draft-ietf-tsvwg-udp-options-10 11 This Internet-Draft is submitted in full conformance with the 12 provisions of BCP 78 and BCP 79. This document may not be modified, 13 and derivative works of it may not be created, except to format it 14 for publication as an RFC or to translate it into languages other 15 than English. 17 Internet-Drafts are working documents of the Internet Engineering 18 Task Force (IETF), its areas, and its working groups. Note that 19 other groups may also distribute working documents as Internet- 20 Drafts. 22 Internet-Drafts are draft documents valid for a maximum of six 23 months and may be updated, replaced, or obsoleted by other documents 24 at any time. It is inappropriate to use Internet-Drafts as 25 reference material or to cite them other than as "work in progress." 27 The list of current Internet-Drafts can be accessed at 28 http://www.ietf.org/ietf/1id-abstracts.txt 30 The list of Internet-Draft Shadow Directories can be accessed at 31 http://www.ietf.org/shadow.html 33 This Internet-Draft will expire on November 1, 2021. 35 Copyright Notice 37 Copyright (c) 2021 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (http://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with 45 respect to this document. Code Components extracted from this 46 document must include Simplified BSD License text as described in 47 Section 4.e of the Trust Legal Provisions and are provided without 48 warranty as described in the Simplified BSD License. 50 Abstract 52 Transport protocols are extended through the use of transport header 53 options. This document extends UDP by indicating the location, 54 syntax, and semantics for UDP transport layer options. 56 Table of Contents 58 1. Introduction...................................................3 59 2. Conventions used in this document..............................3 60 3. Background.....................................................3 61 4. The UDP Option Area............................................4 62 5. UDP Options....................................................8 63 5.1. End of Options List (EOL).................................9 64 5.2. No Operation (NOP).......................................10 65 5.3. Option Checksum (OCS)....................................10 66 5.4. Alternate Checksum (ACS).................................12 67 5.5. Fragmentation (FRAG).....................................13 68 5.6. Maximum Segment Size (MSS)...............................17 69 5.7. Maximum Reassembled Segment Size (MRSS)..................17 70 5.8. Unsafe (UNSAFE)..........................................18 71 5.9. Timestamps (TIME)........................................19 72 5.10. Authentication and Encryption (AE)......................20 73 5.11. Echo request (REQ) and echo response (RES)..............21 74 5.12. Experimental (EXP)......................................21 75 6. Rules for designing new options...............................22 76 7. Option inclusion and processing...............................23 77 8. UDP API Extensions............................................25 78 9. Whose options are these?......................................25 79 10. UDP options FRAG option vs. UDP-Lite.........................26 80 11. Interactions with Legacy Devices.............................27 81 12. Options in a Stateless, Unreliable Transport Protocol........27 82 13. UDP Option State Caching.....................................28 83 14. Updates to RFC 768...........................................28 84 15. Interactions with other RFCs (and drafts)....................28 85 16. Multicast Considerations.....................................30 86 17. Security Considerations......................................30 87 18. IANA Considerations..........................................31 88 19. References...................................................32 89 19.1. Normative References....................................32 90 19.2. Informative References..................................32 91 20. Acknowledgments..............................................34 92 Appendix A. Implementation Information...........................36 94 1. Introduction 96 Transport protocols use options as a way to extend their 97 capabilities. TCP [RFC793], SCTP [RFC4960], and DCCP [RFC4340] 98 include space for these options but UDP [RFC768] currently does not. 99 This document defines an extension to UDP that provides space for 100 transport options including their generic syntax and semantics for 101 their use in UDP's stateless, unreliable message protocol. 103 2. Conventions used in this document 105 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 106 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 107 "OPTIONAL" in this document are to be interpreted as described in 108 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 109 capitals, as shown here. 111 In this document, the characters ">>" preceding an indented line(s) 112 indicates a statement using the key words listed above. This 113 convention aids reviewers in quickly identifying or finding the 114 portions of this RFC covered by these key words. 116 3. Background 118 Many protocols include a default, invariant header and an area for 119 header options that varies from packet to packet. These options 120 enable the protocol to be extended for use in particular 121 environments or in ways unforeseen by the original designers. 122 Examples include TCP's Maximum Segment Size, Window Scale, 123 Timestamp, and Authentication Options [RFC793][RFC5925][RFC7323]. 125 These options are used both in stateful (connection-oriented, e.g., 126 TCP [RFC793], SCTP [RFC4960], DCCP [RFC4340]) and stateless 127 (connectionless, e.g., IPv4 [RFC791], IPv6 [RFC8200]) protocols. In 128 stateful protocols they can help extend the way in which state is 129 managed. In stateless protocols their effect is often limited to 130 individual packets, but they can have an aggregate effect on a 131 sequence of packets as well. This document is intended to provide an 132 out-of-band option area as an alternative to the in-band mechanism 133 currently proposed [Hi15]. 135 UDP is one of the most popular protocols that lacks space for 136 options [RFC768]. The UDP header was intended to be a minimal 137 addition to IP, providing only ports and a data checksum for 138 protection. This document extends UDP to provide a trailer area for 139 options located after the UDP data payload. 141 This extension is possible because UDP includes its own length 142 field, separate from that of the IP header. SCTP includes its own 143 length field, one for each chunk. TCP and DCCP lack this transport 144 length field, inferring it from the IP length. There are a number of 145 suggested reasons why UDP includes this field, notably to support 146 multiple UDP segments in the same IP packet or to indicate the 147 length of the UDP payload as distinct from zero padding required for 148 systems that require writes that are not byte-alighed. These 149 suggestions are not consistent with earlier versions of UDP or with 150 concurrent design of multi-segment multiplexing protocols, however. 152 4. The UDP Option Area 154 The UDP transport header includes demultiplexing and service 155 identification (port numbers), a checksum, and a field that 156 indicates the UDP datagram length (including UDP header). The UDP 157 Length field is typically redundant with the size of the maximum 158 space available as a transport protocol payload (see also discussion 159 in Section 11). 161 For IPv4, IP Total Length field indicates the total IP datagram 162 length (including IP header), and the size of the IP options is 163 indicated in the IP header (in 4-byte words) as the "Internet Header 164 Length" (IHL), as shown in Figure 1 [RFC791]. As a result, the 165 typical (and largest valid) value for UDP Length is: 167 UDP_Length = IPv4_Total_Length - IPv4_IHL * 4 169 For IPv6, the IP Payload Length field indicates the datagram after 170 the base IPv6 header, which includes the IPv6 extension headers and 171 space available for the transport protocol, as shown in Figure 2 172 [RFC8200]. Note that the Next HDR field in IPv6 might not indicate 173 UDP (i.e., 17), e.g., when intervening IP extension headers are 174 present. For IPv6, the lengths of any additional IP extensions are 175 indicated within each extension [RFC8200], so the typical (and 176 largest valid) value for UDP Length is: 178 UDP_Length = IPv6_Payload_Length - sum(extension header lengths) 180 In both cases, the space available for the UDP transport protocol 181 data unit is indicated by IP, either completely in the base header 182 (for IPv4) or adding information in the extensions (for IPv6). In 183 either case, this document will refer to this available space as the 184 "IP transport payload". 186 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 187 |Version| IHL |Type of Service| Total Length | 188 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 189 | Identification |Flags| Fragment Offset | 190 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 191 | Time to Live | Proto=17 (UDP)| Header Checksum | 192 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 193 | Source Address | 194 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 195 | Destination Address | 196 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 197 ... zero or more IP Options (using space as indicated by IHL) ... 198 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 199 | UDP Source Port | UDP Destination Port | 200 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 201 | UDP Length | UDP Checksum | 202 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 204 Figure 1 IPv4 datagram with UDP transport payload 206 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 207 |Version| Traffic Class | Flow Label | 208 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 209 | Payload Length | Next Hdr | Hop Limit | 210 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 211 ... 212 | Source Address (128 bits) | 213 ... 214 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 215 ... 216 | Destination Address (128 bits) | 217 ... 218 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 219 ... zero or more IP Extension headers (each indicating size) ... 220 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 221 | UDP Source Port | UDP Destination Port | 222 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 223 | UDP Length | UDP Checksum | 224 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 226 Figure 2 IPv6 datagram with UDP transport payload 228 As a result of this redundancy, there is an opportunity to use the 229 UDP Length field as a way to break up the IP transport payload into 230 two areas - that intended as UDP user data and an additional 231 "surplus area" (as shown in Figure 3). 233 IP transport payload 234 <-------------------------------------------------> 235 +--------+---------+----------------------+------------------+ 236 | IP Hdr | UDP Hdr | UDP user data | surplus area | 237 +--------+---------+----------------------+------------------+ 238 <------------------------------> 239 UDP Length 241 Figure 3 IP transport payload vs. UDP Length 243 In most cases, the IP transport payload and UDP Length point to the 244 same location, indicating that there is no surplus area. It is 245 important to note that this is not a requirement of UDP [RFC768] 246 (discussed further in Section 11). UDP-Lite used the difference in 247 these pointers to indicate the partial coverage of the UDP Checksum, 248 such that the UDP user data, UDP header, and UDP pseudoheader (a 249 subset of the IP header) are covered by the UDP checksum but 250 additional user data in the surplus area is not covered [RFC3828]. 251 This document uses the surplus area for UDP transport options. 253 The UDP option area is thus defined as the location between the end 254 of the UDP payload and the end of the IP datagram as a trailing 255 options area. This area can occur at any valid byte offset, i.e., it 256 need not be 16-bit or 32-bit aligned. In effect, this document 257 redefines the UDP "Length" field as a "trailer offset". 259 UDP options are defined using a TLV (type, length, and optional 260 value) syntax similar to that of TCP [RFC793]. They are typically a 261 minimum of two bytes in length as shown in Figure 4, excepting only 262 the one byte options "No Operation" (NOP) and "End of Options List" 263 (EOL) described below. 265 +--------+--------+------- 266 | Kind | Length | (remainder of option...) 267 +--------+--------+------- 269 Figure 4 UDP option default format 271 The Kind field is always one byte. The Length field is one byte for 272 all lengths below 255 (including the Kind and Length bytes). A 273 Length of 255 indicates use of the UDP option extended format shown 274 in Figure 5. The Extended Length field is a 16-bit field in network 275 standard byte order. 277 +--------+--------+--------+--------+ 278 | Kind | 255 | Extended Length | 279 +--------+--------+--------+--------+ 280 | (remainder of option...) 281 +--------+--------+--------+--------+ 283 Figure 5 UDP option extended default format 285 >> UDP options MAY begin at any UDP length offset. 287 >> The UDP length MUST be at least as large as the UDP header (8) 288 and no larger than the IP transport payload. Datagrams with length 289 values outside this range MUST be silently dropped as invalid and 290 logged where rate-limiting permits. 292 >> Option Lengths (or Extended Lengths, where applicable) smaller 293 than the minimum for the corresponding Kind and default format MUST 294 be treated as an error. Such errors call into question the remainder 295 of the option area and thus MUST result in all UDP options being 296 silently discarded. 298 >> Any UDP option whose length is only smaller than 255 MUST always 299 use the UDP option default format shown in Figure 4, excepting only 300 EOL and NOP. 302 >> Any UDP option whose length can be larger than 254 MUST always 303 use the UDP option extended default format shown in Figure 5, 304 including UNSAFE and EXP. 306 I.e., a UDP option always uses only the default format or the 307 extended default format, depending on whether its length is only 308 ever smaller than 255 or not. 310 Others have considered using values of the UDP Length that is larger 311 than the IP transport payload as an additional type of signal. Using 312 a value smaller than the IP transport payload is expected to be 313 backward compatible with existing UDP implementations, i.e., to 314 deliver the UDP Length of user data to the application and silently 315 ignore the additional surplus area data. Using a value larger than 316 the IP transport payload would either be considered malformed (and 317 be silently dropped) or could cause buffer overruns, and so is not 318 considered silently and safely backward compatible. Its use is thus 319 out of scope for the extension described in this document. 321 >> UDP options MUST be interpreted in the order in which they occur 322 in the UDP option area. 324 5. UDP Options 326 The following UDP options are currently defined: 328 Kind Length Meaning 329 ---------------------------------------------- 330 0* - End of Options List (EOL) 331 1* - No operation (NOP) 332 2* 3 Option checksum (OCS) 333 3* 6 Alternate checksum (ACS) 334 4* 10/12 Fragmentation (FRAG) 335 5* 4 Maximum segment size (MSS) 336 6* 4 Maximum reassembled segment size (MRSS) 337 7* (varies) Unsafe to ignore (UNSAFE) options 338 8 10 Timestamps (TIME) 339 9 (varies) Authentication and Encryption (AE) 340 10 6 Request (REQ) 341 11 6 Response (RES) 342 12-126 (varies) UNASSIGNED (assignable by IANA) 343 127-253 RESERVED 344 254 (varies) RFC 3692-style experiments (EXP) 345 255 RESERVED 347 These options are defined in the following subsections. Options 0 348 and 1 use the same values as for TCP. 350 >> An endpoint supporting UDP options MUST support those marked with 351 a "*" above: EOL, NOP, OCS, ACS, FRAG, MSS, MRSS, and UNSAFE. This 352 includes both recognizing and being able to generate these options 353 if configured to do so. These are called "must-support" options. 355 >> All other options (without a "*") MAY be implemented, and their 356 use SHOULD be determined either out-of-band or negotiated. 358 >> Receivers supporting UDP options MUST silently ignore unknown 359 options except UNSAFE. That includes options whose length does not 360 indicate the specified value(s). 362 >> Receivers supporting UDP options MUST silently drop the entire 363 datagram containing an UNSAFE option when any UNSAFE option it 364 contains is unknown. See Section 5.8 for further discussion of 365 UNSAFE options. 367 >> Except for NOP, each option SHOULD NOT occur more than once in a 368 single UDP datagram. If an option other than NOP occurs more than 369 once, a receiver MUST interpret only the first instance of that 370 option and MUST ignore all others. 372 >> Only the OCS and AE options depend on the contents of the option 373 area. AE is always computed as if the AE hash and OCS checksum are 374 zero; OCS is always computed as if the OCS checksum is zero and 375 after the AE hash has been computed. Future options MUST NOT be 376 defined as having a value dependent on the contents of the option 377 area. Otherwise, interactions between those values, OCS, and AE 378 could be unpredictable. 380 Receivers cannot treat unexpected option lengths as invalid, as this 381 would unnecessarily limit future revision of options (e.g., defining 382 a new ACS that is defined by having a different length). 384 >> Option lengths MUST NOT exceed the IP length of the packet. If 385 this occurs, the packet MUST be treated as malformed and dropped, 386 and the event MAY be logged for diagnostics (logging SHOULD be rate 387 limited). 389 >> Options with fixed lengths MUST use the default option format. 391 >> Options with variable lengths MUST use the default option format 392 where their total length is 254 bytes or less. 394 >> Options using the extended option format MUST indicate extended 395 lengths of 255 or higher; smaller extended length values MUST be 396 treated as an error. 398 >> "Must-support" options other than NOP and EOL MUST come before 399 other options. 401 The requirement that must-support options come before others is 402 intended to allow for endpoints to implement DOS protection, as 403 discussed further in Section 17. 405 5.1. End of Options List (EOL) 407 The End of Options List (EOL) option indicates that there are no 408 more options. It is used to indicate the end of the list of options 409 without needing to pad the options to fill all available option 410 space. 412 +--------+ 413 | Kind=0 | 414 +--------+ 416 Figure 6 UDP EOL option format 418 >> When the UDP options do not consume the entire option area, the 419 last non-NOP option MUST be EOL. 421 >> All bytes in the surplus area after EOL MUST be zero. If these 422 bytes are non-zero, the entire surplus area MUST be silently ignored 423 and only the UDP data passed to the user with an adjusted UDP length 424 to indicate that no options were present. 426 Requiring the post-option surplus area to be zero prevents side- 427 channel uses of this area, requiring instead that all use of the 428 surplus area be UDP options supported by both endpoints. It is 429 useful to allow for such padding to increase the packet length 430 without affecting the payload length, e.g., for UDP DPLPMTUD [Fa21]. 432 5.2. No Operation (NOP) 434 The No Operation (NOP) option is a one byte placeholder, intended to 435 be used as padding, e.g., to align multi-byte options along 16-bit 436 or 32-bit boundaries. 438 +--------+ 439 | Kind=1 | 440 +--------+ 442 Figure 7 UDP NOP option format 444 >> If options longer than one byte are used, NOP options SHOULD be 445 used at the beginning of the UDP options area to achieve alignment 446 as would be more efficient for active (i.e., non-NOP) options. 448 >> Segments SHOULD NOT use more than three consecutive NOPs. NOPs 449 are intended to assist with alignment, not other padding or fill. 451 [NOTE: Tom Herbert suggested we declare "more than 3 consecutive 452 NOPs" a fatal error to reduce the potential of using NOPs as a DOS 453 attack, but IMO there are other equivalent ways (e.g., using 454 RESERVED or other UNASSIGNED values) and the "no more than 3" 455 creates its own DOS vulnerability) 457 5.3. Option Checksum (OCS) 459 The Option Checksum (OCS) option is conventional Internet checksum 460 [RFC791] that covers all of the surplus area and a pseudoheader 461 composed of the 16-bit length of the surplus area (Figure 8). The 462 primary purpose of OCS is to detect non-standard (i.e., non-option) 463 uses of that area. The surplus area pseudoheader is included to 464 enable traversal of errant middleboxes that incorrectly compute the 465 UDP checksum over the entire IP payload rather than only the UDP 466 payload [Fa18]. 468 The OCS is calculated by computing the Internet checksum over the 469 surplus area and surplus length pseudoheader. The OCS protects the 470 option area from errors in a similar way that the UDP checksum 471 protects the UDP user data (when not zero). 473 +--------+--------+ 474 | surplus length | 475 +--------+--------+ 477 Figure 8 UDP surplus length pseudoheader 479 +--------+--------+--------+ 480 | Kind=2 | checksum | 481 +--------+--------+--------+ 483 Figure 9 UDP OCS option format 485 >> The OCS MUST be included when the UDP checksum is nonzero and UDP 486 options are present. 488 >> When present, the OCS SHOULD occur as early as possible, preceded 489 by only NOP options for alignment and the FRAG option if present. 491 >> OCS MUST be half-word coordinated with the start of the UDP 492 options area and include the surplus length pseudoheader similarly 493 coordinated with the start of UDP Header. 495 This Internet checksum is computed over the surplus area (including 496 EOL, if present) prefixed by the surplus length pseudoheader (Figure 497 8) and then adjusting the result before storing it into the OCS 498 checksum field. If the OCS checksum field is aligned to the start of 499 the options area, then the checksum is inserted as-is, otherwise the 500 checksum bytes are swapped before inserting them into the field. The 501 effect of this "coordination" is the same is if the checksum were 502 computed as if the surplus area and pseudoheader were aligned to the 503 UDP header. 505 This feature is intended to potentially help the UDP options 506 traverse devices that incorrectly attempt to checksum the surplus 507 area (as originally proposed as the Checksum Compensation Option, 508 i.e., CCO [Fa18]). 510 The OCS covers the UDP option area as formatted for transmission and 511 immediately upon reception. 513 >> If the OCS fails, all options MUST be ignored and the surplus 514 area silently discarded. 516 >> UDP data that is validated by a correct UDP checksum MUST be 517 delivered to the application layer, even if the OCS fails, unless 518 the endpoints have negotiated otherwise for this segment's socket 519 pair. 521 As a reminder, use of the UDP checksum is optional when the UDP 522 checksum is zero. When not used, the OCS is assumed to be "correct" 523 for the purpose of accepting UDP packets at a receiver (see Section 524 7). 526 The OCS is intended to check for accidental errors, not for attacks. 528 5.4. Alternate Checksum (ACS) 530 The Alternate Checksum (ACS) option provides a stronger alternative 531 to the checksum in the UDP header, using a 32-bit CRC of the 532 conventional UDP payload only (excluding the IP pseudoheader, UDP 533 header, and surplus area). It is an "alternate" to the UDP checksum 534 (covering the UDP payload) - not the OCS (the latter covers the 535 surplus area) Unlike the UDP checksum, ACS does not include the IP 536 pseudoheader or UDP header, thus it does not need to be updated by 537 NATs when IP addresses or UDP ports are rewritten. Its purpose is to 538 detect UDP payload errors that the UDP checksum, when used, might 539 not detect. 541 A CRC32c has been chosen because of its ubiquity and use in other 542 Internet protocols, including iSCSI and SCTP. The option contains 543 the CRC32c in network standard byte order, as described in 544 [RFC3385]. 546 +--------+--------+--------+--------+ 547 | Kind=3 | Len=6 | CRC32c... | 548 +--------+--------+--------+--------+ 549 | CRC32c (cont.) | 550 +--------+--------+ 552 Figure 10 UDP ACS option format 554 When present, the ACS always contains a valid CRC checksum. There 555 are no reserved values, including the value of zero. If the CRC is 556 zero, this must indicate a valid checksum (i.e., it does not 557 indicate that the ACS is not used; instead, the option would simply 558 not be included if that were the desired effect). 560 ACS does not protect the UDP pseudoheader; only the current UDP 561 checksum provides that protection (when used). ACS cannot provide 562 that protection because it would need to be updated whenever the UDP 563 pseudoheader changed, e.g., during NAT address and port translation; 564 because this is not the case, ACS does not cover the pseudoheader. 566 >> Packets with incorrect ACS checksums MUST be passed to the 567 application by default, e.g., with a flag indicating ACS failure. 569 Like all non-UNSAFE UDP options, ACS need to be silently ignored 570 when failing. Although all UDP option-aware endpoints support ACS 571 (being in the required set), this silently-ignored behavior ensures 572 that option-aware receivers operate the same as legacy receivers 573 unless overridden. 575 5.5. Fragmentation (FRAG) 577 The Fragmentation option (FRAG) combines properties of IP 578 fragmentation and the UDP Lite transport protocol [RFC3828]. FRAG 579 provides transport-layer fragmentation and reassembly in which each 580 fragment includes a copy of the same UDP transport ports, enabling 581 the fragments to traverse Network Address (and port) Translation 582 (NAT) devices, in contrast to the behavior of IP fragments. FRAG 583 also allows the UDP checksum to cover only a prefix of the UDP data 584 payload, to avoid repeated checksums of data prior to reassembly. 586 The Fragmentation (FRAG) option supports UDP fragmentation and 587 reassembly, which can be used to transfer UDP messages larger than 588 limited by the IP receive MTU (EMTU_R [RFC1122]). It is typically 589 used with the UDP MSS option to enable more efficient use of large 590 messages, both at the UDP and IP layers. FRAG is designed similar to 591 the IPv6 Fragmentation Header [RFC8200], except that the UDP variant 592 uses a 16-bit Offset measured in bytes, rather than IPv6's 13-bit 593 Fragment Offset measured in 8-byte units. This UDP variant avoids 594 creating reserved fields. 596 >> When FRAG is present, it MUST come first in the UDP options list. 598 >> When FRAG is present, the UDP payload MUST be empty. If the 599 payload is not empty, all UDP options MUST be silently ignored and 600 the payload received to the user. 602 Legacy receivers interpret FRAG messages as zero-length payload 603 packets (i.e., UDP Length field is 8, the length of just the UDP 604 header), which would not affect the receiver unless the presence of 605 the packet itself were a signal. 607 The FRAG option has two formats; non-terminal fragments use the 608 shorter variant (Figure 11) and terminal fragments use the longer 609 (Figure 12). The latter includes stand-alone fragments, i.e., when 610 data is contained in the FRAG option but reassembly is not required. 612 +--------+--------+--------+--------+ 613 | Kind=4 | Len=10 | Offset | 614 +--------+--------+--------+--------+ 615 | Identification | 616 +--------+--------+--------+--------+ 617 | Frag. Offset | 618 +--------+--------+ 620 Figure 11 UDP non-terminal FRAG option format 622 The FRAG option does not need a "more fragments" bit because it 623 provides the same indication by using the longer, 12-byte variant, 624 which also includes an Internet checksum over the entire reassembled 625 UDP payload (omitting the IP pseudoheader and UDP header, as well as 626 UDP options), as shown in Figure 12. 628 >> The FRAG option MAY be used on a single fragment, in which case 629 the Offset would be zero and the option would have the 12-byte 630 format, including the reassembly checksum. 632 Use of the single fragment variant can be helpful in supporting use 633 of UNSAFE options without undesirable impact to receivers that do 634 not support either UDP options or the specific UNSAFE options. 636 >> The reassembly checksum SHOULD be used, but MAY be unused in the 637 same situations when the UDP checksum is unused (e.g., for transit 638 tunnels or applications that have their own integrity checks 639 [RFC8200]), and by the same mechanism (set the field to 0x0000). 641 +--------+--------+--------+--------+ 642 | Kind=4 | Len=12 | Offset | 643 +--------+--------+--------+--------+ 644 | Identification | 645 +--------+--------+--------+--------+ 646 | Frag. Offset | Reassy. Checksum| 647 +--------+--------+--------+--------+ 649 Figure 12 UDP terminal FRAG option format 651 >> During fragmentation, the UDP header checksum of each fragment 652 needs to be recomputed based on each datagram's pseudoheader. 654 Unlike the UDP checksum, the reassembly checksum does not need to be 655 updated if the UDP header changes because it covers only the 656 reassembled data. FRAG uses a comparatively weak checksum upon 657 reassembly because the fragments are already checked individually. 659 >> After reassembly is complete and validated using the checksum of 660 the terminal FRAG option, the UDP header checksum of the resulting 661 datagram needs to be recomputed based on the datagram's 662 pseudoheader. 664 The Fragment Offset is 16 bits and indicates the location of the UDP 665 payload fragment in bytes from the beginning of the original 666 unfragmented payload. The Len field indicates whether there are more 667 fragments (Len=10) or no more fragments (Len=12). 669 >> The Identification field is a 32-bit value that MUST be unique 670 over the expected fragment reassembly timeout. 672 >> The Identification field SHOULD be generated in a manner similar 673 to that of the IPv6 Fragment ID [RFC8200]. 675 >> UDP fragments MUST NOT overlap. 677 UDP fragmentation relies on a fragment expiration timer, which can 678 be preset or could use a value computed using the UDP Timestamp 679 option. 681 >> The default UDP reassembly SHOULD be no more than 2 minutes. 683 Implementers are advised to limit the space available for UDP 684 reassembly. 686 >> UDP reassembly space SHOULD be limited to reduce the impact of 687 DOS attacks on resource use. 689 >> UDP reassembly space limits SHOULD NOT be implemented as an 690 aggregate, to avoid cross-socketpair DOS attacks. 692 >> Individual UDP fragments MUST NOT be forwarded to the user. The 693 reassembled datagram is received only after complete reassembly, 694 checksum validation, and continued processing of the remaining UDP 695 options. 697 Any additional UDP options, if used, follow the FRAG option in the 698 final fragment and would be included in the reassembled packet. 699 Processing of those options would commence after reassembly. This is 700 especially important for UNSAFE options, which are interpreted only 701 after FRAG. 703 >> UDP options MUST NOT follow the FRAG header in non-terminal 704 fragments. Any data following the FRAG header in non-terminal 705 fragments MUST be silently dropped. All other options that apply to 706 a reassembled packet MUST follow the FRAG header in the terminal 707 fragment. 709 In general, UDP packets are fragmented as follows: 711 1. Create a datagram with data and any non-FRAG UDP options, which 712 we will call "D". Note that the options apply to the entire data 713 area and must follow the data. These options are processed before 714 the rest of the fragmentation steps below. 716 2. Identify the desired fragment size, which we will call "S". This 717 value should take into account the path MTU (if known) and allow 718 space for per-fragment options (e.g., OCS). 720 3. Fragment "D" into chunks of size no larger than "S"-10 each, with 721 one final chunk no larger than "S"-12. Note that all the non-FRAG 722 options in step #1 MUST appear in the terminal fragment. 724 4. For each chunk of "D" in step #3, create a zero-data UDP packet 725 followed by the per-fragment options, with the final option being 726 the FRAG option followed by the FRAG data chunk. 728 The last chunk includes the non-FRAG options noted in step #1 729 after the end of the FRAG data. These UDP options apply to the 730 reassembled data as a whole when received. 732 5. Process the UDP options of each fragment, e.g., computing its 733 OCS. 735 <> 738 Receivers reverse the above sequence. They process all received 739 options in each fragment. When the FRAG option is encountered, the 740 FRAG data is used in reassembly. After all fragments are received, 741 the entire packet is processed with any trailing UDP options 742 applying to the reassembled data. 744 5.6. Maximum Segment Size (MSS) 746 The Maximum Segment Size (MSS, Kind = 5) option is a 16-bit hint of 747 the largest unfragmented UDP segment that an endpoint believes can 748 be received. As with the TCP MSS option [RFC793], the size indicated 749 is the IP layer MTU decreased by the fixed IP and UDP headers only 750 [RFC6691]. The space needed for IP and UDP options need to be 751 adjusted by the sender when using the value indicated. The value 752 transmitted is based on EMTU_R, the largest IP datagram that can be 753 received (i.e., reassembled at the receiver) [RFC1122]. However, as 754 with TCP, this value is only a hint at what the receiver believes; 755 it does not indicate a known path MTU and thus MUST NOT be used to 756 limit transmissions, notably for DPLPMTU probes. 758 +--------+--------+--------+--------+ 759 | Kind=5 | Len=4 | MSS size | 760 +--------+--------+--------+--------+ 762 Figure 13 UDP MSS option format 764 The UDP MSS option MAY be used as a hint for path MTU discovery 765 [RFC1191][RFC8201], but this may be difficult because of known 766 issues with ICMP blocking [RFC2923] as well as UDP lacking automatic 767 retransmission. It is more likely to be useful when coupled with IP 768 source fragmentation to limit the largest reassembled UDP message as 769 indicated by MRSS (see Section 5.7), e.g., when EMTU_R is larger 770 than the required minimums (576 for IPv4 [RFC791] and 1500 for IPv6 771 [RFC8200]). It can also be used with DPLPMTUD [RFC8899] to provide a 772 hint to maximum DPLPMTU, though it MUST NOT prohibit transmission of 773 larger UDP packets (or fragments) used as DPLPMTU probes. 775 5.7. Maximum Reassembled Segment Size (MRSS) 777 The Maximum Reassembled Segment Size (MRSS, Kind=6) option is a 16- 778 bit indicator of the largest reassembled UDP segment that can be 779 received. MRSS is the UDP equivalent of IP's EMTU_R but the two are 780 not related [RFC1122]. Using the FRAG option (Section 5.5), UDP 781 segments can be transmitted as fragments in multiple IP datagrams 782 and be reassembled larger than the IP layer allows. 784 +--------+--------+--------+--------+ 785 | Kind=6 | Len=4 | MRSS size | 786 +--------+--------+--------+--------+ 788 Figure 14 UDP MRSS option format 790 5.8. Unsafe (UNSAFE) 792 The Unsafe option (UNSAFE) extends the UDP option space to allow for 793 options that are not safe to ignore and can be used unidirectionally 794 or without soft-state confirmation of UDP option capability. They 795 are always used only when the entire UDP payload occurs inside a 796 reassembled set of UDP fragments, such that if UDP fragmentation is 797 not supported, the entire fragment would be silently dropped anyway. 799 UNSAFE options are an extended option space, with its own additional 800 option types. These are indicated in the first byte after the option 801 Kind as shown in Figure 15, which is followed by the Length. Length 802 is 1 byte for UKinds whose total length (including Kind, UKind, and 803 Length fields) is less than 255 or 2 bytes for larger lengths (in 804 the similar style as the extended option format). 806 +--------+--------+--------+ 807 | Kind=7 | UKind | Length |... 808 +--------+--------+--------+ 809 1 byte 1 byte 1-2 bytes 811 Figure 15 UDP UNSAFE option format 813 >> UNSAFE options MUST be used only as part of UDP fragments, used 814 either per-fragment or after reassembly. 816 >> Receivers supporting UDP options MUST silently drop the entire 817 reassembled datagram if any fragment or the entire datagram includes 818 an UNSAFE option whose UKind is not supported. 820 The following UKind values are defined: 822 UKind Length Meaning 823 ---------------------------------------------- 824 0 RESERVED 825 1-253 (varies) UNASSIGNED (assignable by IANA) 826 254 (varies) RFC 3692-style experiments (UEXP) 827 255 RESERVED 829 Experimental UKind EXP ExID values indicate the ExID in the 830 following 2 (or 4) bytes, similar to the UDP EXP option as discussed 831 in Section 5.12. Assigned UDP EXP ExIDs and UDP UNSAFE UKind UEXP 832 ExIDs are assigned from the same registry and can be used either in 833 the EXP option (Section 5.12) or within the UKind UEXP. 835 5.9. Timestamps (TIME) 837 The Timestamp (TIME) option exchanges two four-byte timestamp 838 fields. It serves a similar purpose to TCP's TS option [RFC7323], 839 enabling UDP to estimate the round trip time (RTT) between hosts. 840 For UDP, this RTT can be useful for establishing UDP fragment 841 reassembly timeouts or transport-layer rate-limiting [RFC8085]. 843 +--------+--------+------------------+------------------+ 844 | Kind=8 | Len=10 | TSval | TSecr | 845 +--------+--------+------------------+------------------+ 846 1 byte 1 byte 4 bytes 4 bytes 848 Figure 16 UDP TIME option format 850 TS Value (TSval) and TS Echo Reply (TSecr) are used in a similar 851 manner to the TCP TS option [RFC7323]. On transmitted segments using 852 the option, TS Value is always set based on the local "time" value. 853 Received TSval and TSecr values are provided to the application, 854 which can pass the TSval value to be used as TSecr on UDP messages 855 sent in response (i.e., to echo the received TSval). A received 856 TSecr of zero indicates that the TSval was not echoed by the 857 transmitter, i.e., from a previously received UDP packet. 859 >> TIME MAY use an RTT estimate based on nonzero Timestamp values as 860 a hint for fragmentation reassembly, rate limiting, or other 861 mechanisms that benefit from such an estimate. 863 >> TIME SHOULD make this RTT estimate available to the user 864 application. 866 UDP timestamps are modeled after TCP timestamps and have similar 867 expectations. In particular, they are expected to be: 869 o Values are monotonic and non-decreasing except for anticipated 870 number-space rollover events 872 o Values should "increase" (allowing for rollover) according to a 873 typical 'tick' time 875 o A request is defined as "reply=0" and a reply is defined as both 876 fields being non-zero. 878 o A receiver should always respond to a request with the highest 879 TSval received (allowing for rollover), which is not necessarily 880 the most recently received. 882 Rollover can be handled as a special case or more completely using 883 sequence number extension [RFC5925]. 885 5.10. Authentication and Encryption (AE) 887 The Authentication and Encryption (AE) option is intended to allow 888 UDP to provide a similar type of authentication as the TCP 889 Authentication Option (TCP-AO) [RFC5925]. AE the conventional UDP 890 payload and may also cover the surplus area, depending on 891 configuration. It uses the same format as specified for TCP-AO, 892 except that it uses a Kind of 9. AE supports NAT traversal in a 893 similar manner as TCP-AO [RFC6978]. AE can also be extended to 894 provide a similar encryption capability as TCP-AO-ENC, in a similar 895 manner [To18ao]. 897 +--------+--------+--------+--------+ 898 | Kind=9 | Len | Digest... | 899 +--------+--------+--------+--------+ 900 | Digest (con't)... | 901 +--------+--------+--------+--------+ 903 Figure 17 UDP AE option format 905 Like TCP-AO, AE is not negotiated in-band. Its use assumes both 906 endpoints have populated Master Key Tuples (MKTs), used to exclude 907 non-protected traffic. 909 TCP-AO generates unique traffic keys from a hash of TCP connection 910 parameters. UDP lacks a three-way handshake to coordinate 911 connection-specific values, such as TCP's Initial Sequence Numbers 912 (ISNs) [RFC793], thus AE's Key Derivation Function (KDF) uses zeroes 913 as the value for both ISNs. This means that the AE reuses keys when 914 socket pairs are reused, unlike TCP-AO. 916 >> Packets with incorrect AE HMACs MUST be passed to the application 917 by default, e.g., with a flag indicating AE failure. 919 Like all non-UNSAFE UDP options, AE needs to be silently ignored 920 when failing. This silently-ignored behavior ensures that option- 921 aware receivers operate the same as legacy receivers unless 922 overridden. 924 In addition to the UDP payload (which is always included), AE can be 925 configured to either include or exclude the surplus area, in a 926 similar way as can TCP-AO can optionally exclude TCP options. When 927 UDP options are covered, the OCS option area checksum and AE hash 928 areas are zeroed before computing the AE hash. It is important to 929 consider that options not yet defined might yield unpredictable 930 results if not confirmed as supported, e.g., if they were to contain 931 other hashes or checksums that depend on the option area contents. 932 This is why such dependencies are not permitted except as defined 933 for OCS and UDP-AE. 935 Similar to TCP-AO-NAT, AE can be configured to support NAT 936 traversal, excluding (by zeroing out) one or both of the UDP ports 937 and corresponding IP addresses [RFC6978]. 939 5.11. Echo request (REQ) and echo response (RES) 941 The echo request (REQ, kind=10) and echo response (RES, kind=11) 942 options provide a means for UDP options to be used to provide 943 packet-level acknowledgements. One such use is described as part of 944 the UDP variant of packetization layer path MTU discovery (PLPMTUD) 945 [Fa21]. The options both have the format indicated in Figure 18. 947 +--------+--------+------------------+ 948 | Kind | Len=6 | nonce | 949 +--------+--------+------------------+ 950 1 byte 1 byte 4 bytes 952 Figure 18 UDP REQ and RES options format 954 5.12. Experimental (EXP) 956 The Experimental option (EXP) is reserved for experiments [RFC3692]. 957 It uses a Kind value of 254. Only one such value is reserved because 958 experiments are expected to use an Experimental ID (ExIDs) to 959 differentiate concurrent use for different purposes, using UDP ExIDs 960 registered with IANA according to the approach developed for TCP 961 experimental options [RFC6994]. 963 +----------+----------+----------+----------+ 964 | Kind=254 | Len | UDP ExID | 965 +----------+----------+----------+----------+ 966 | (option contents, as defined)... | 967 +----------+----------+----------+----------+ 969 Figure 19 UDP EXP option format 971 >> The length of the experimental option MUST be at least 4 to 972 account for the Kind, Length, and the minimum 16-bit UDP ExID 973 identifier (similar to TCP ExIDs [RFC6994]). 975 Assigned UDP EXP ExIDs and UDP UNSAFE UKind UEXP ExIDs are assigned 976 from the same registry and can be used either in the EXP option or 977 within the UKind UEXP (Section 5.8). 979 6. Rules for designing new options 981 The UDP option Kind space allows for the definition of new options, 982 however the currently defined options do not allow for arbitrary new 983 options. For example, FRAG needs to come first if present; new 984 options cannot declare that they need to precede it. The following 985 is a summary of rules for new options and their rationales: 987 >> New options MUST NOT depend on option space content, excepting 988 only those contained within the UNSAFE option. Only OCS and AE 989 depend on the content of the options themselves and their order is 990 fixed (on transmission, AE is computed first using a zero-checksum 991 OCS if present, and OCS is computed last before transmission, over 992 the entire option area, including AE). 994 >> UNSAFE options can both depend on and vary option space content 995 because they are contained only inside UDP fragments and thus are 996 processed only by UDP option capable receivers. 998 >> New options MUST NOT declare their order relative to other 999 options, whether new or old. 1001 >> At the sender, new options MUST NOT modify UDP packet content 1002 anywhere except within their option field, excepting only those 1003 contained within the UNSAFE option; areas that need to remain 1004 unmodified include the IP header, IP options, the UDP body, the UDP 1005 option area (i.e., other options), and the post-option area. 1007 >> Options MUST NOT be modified in transit. This includes those 1008 already defined as well as new options. New options MUST NOT require 1009 or intend optionally for modification of any UDP options, including 1010 their new areas, in transit. 1012 >> New options with fixed lengths smaller than 255 or variable 1013 lengths that are always smaller than 255 MUST use only the default 1014 option format. 1016 Note that only certain of the initially defined options violate 1017 these rules: 1019 o >> FRAG MUST be first, if present, and MUST be processed when 1020 encountered (e.g., even before security options). 1022 o >> Only FRAG and UNSAFE options are permitted to modify the UDP 1023 body or option areas. 1025 o >> OCS SHOULD be the first option, except in the presence of 1026 FRAG, in which case it SHOULD be the first option after FRAG. 1028 7. Option inclusion and processing 1030 The following rules apply to option inclusion by senders and 1031 processing by receivers. 1033 >> Senders MAY add any option, as configured by the API. 1035 >> All mandatory options MUST be processed by receivers, if present 1036 (presuming UDP options are supported at that receiver). 1038 >> Non-mandatory options MAY be ignored by receivers, if present, 1039 e.g., based on API settings. 1041 >> All options MUST be processed by receivers in the order 1042 encountered in the options list. 1044 >> All options except UNSAFE options MUST result in the UDP payload 1045 being passed to the application layer, regardless of whether all 1046 options are processed, supported, or succeed. 1048 The basic premise is that, for options-aware endpoints, the sender 1049 decides what options to add and the receiver decides what options to 1050 handle. Simply adding an option does not force work upon a receiver, 1051 with the exception of the mandatory options. 1053 Upon receipt, the receiver checks various properties of the UDP 1054 packet and its options to decide whether to accept or drop the 1055 packet and whether to accept or ignore some its options as follows 1056 (in order): 1058 if the UDP checksum fails then 1059 silently drop (per RFC1122) 1060 if the UDP checksum passes then 1061 if OCS is present and fails then 1062 deliver the UDP payload but ignore all other options 1063 (this is required to emulate legacy behavior) 1064 if OCS is present and passes then 1065 deliver the UDP payload after parsing 1066 and processing the rest of the options, 1067 regardless of whether each is supported or succeeds 1068 (again, this is required to emulate legacy behavior) 1070 The design of the UNSAFE options as used only inside the FRAG area 1071 ensures that the resulting UDP data will be silently dropped in both 1072 legacy and options-aware receivers. 1074 Options-aware receivers can either drop packets with option 1075 processing errors via an override of the default or at the 1076 application layer. 1078 I.e., all options other than OCS are treated the same, in that the 1079 transmitter can add it as desired and the receiver has the option to 1080 require it or not. Only if it is required (e.g., by API 1081 configuration) should the receiver require it being present and 1082 correct. 1084 I.e., for all options other than OCS: 1086 o if the option is not required by the receiver, then packets 1087 missing the option are accepted. 1089 o if the option is required (e.g., by override of the default 1090 behavior at the receiver) and missing or incorrectly formed, 1091 silently drop the packet. 1093 o if the packet is accepted (either because the option is not 1094 required or because it was required and correct), then pass the 1095 option with the packet via the API. 1097 Any options whose length exceeds that of the UDP packet (i.e., 1098 intending to use data that would have been beyond the surplus area) 1099 should be silently ignored (again to model legacy behavior). 1101 8. UDP API Extensions 1103 UDP currently specifies an application programmer interface (API), 1104 summarized as follows (with Unix-style command as an example) 1105 [RFC768]: 1107 o Method to create new receive ports 1109 o E.g., bind(handle, recvaddr(optional), recvport) 1111 o Receive, which returns data octets, source port, and source 1112 address 1114 o E.g., recvfrom(handle, srcaddr, srcport, data) 1116 o Send, which specifies data, source and destination addresses, and 1117 source and destination ports 1119 o E.g., sendto(handle, destaddr, destport, data) 1121 This API is extended to support options as follows: 1123 o Extend the method to create receive ports to include receive 1124 options that are required. Datagrams not containing these 1125 required options MUST be silently dropped and MAY be logged. 1127 o Extend the receive function to indicate the options and their 1128 parameters as received with the corresponding received datagram. 1130 o Extend the send function to indicate the options to be added to 1131 the corresponding sent datagram. 1133 Examples of API instances for Linux and FreeBSD are provided in 1134 Appendix A, to encourage uniform cross-platform implementations. 1136 9. Whose options are these? 1138 UDP options are indicated in an area of the IP payload that is not 1139 used by UDP. That area is really part of the IP payload, not the UDP 1140 payload, and as such, it might be tempting to consider whether this 1141 is a generally useful approach to extending IP. 1143 Unfortunately, the surplus area exists only for transports that 1144 include their own transport layer payload length indicator. TCP and 1145 SCTP include header length fields that already provide space for 1146 transport options by indicating the total length of the header area, 1147 such that the entire remaining area indicated in the network layer 1148 (IP) is transport payload. UDP-Lite already uses the UDP Length 1149 field to indicate the boundary between data covered by the transport 1150 checksum and data not covered, and so there is no remaining area 1151 where the length of the UDP-Lite payload as a whole can be indicated 1152 [RFC3828]. 1154 UDP options are intended for use only by the transport endpoints. 1155 They are no more (or less) appropriate to be modified in-transit 1156 than any other portion of the transport datagram. 1158 UDP options are transport options. Generally, transport datagrams 1159 are not intended to be modified in-transit. UDP options are no 1160 exception and here are specified as "MUST NOT" be altered in 1161 transit. However, the UDP option mechanism provides no specific 1162 protection against in-transit modification of the UDP header, UDP 1163 payload, or UDP option area, except as provided by the options 1164 selected (e.g., OCS or AE). 1166 10. UDP options FRAG option vs. UDP-Lite 1168 UDP-Lite provides partial checksum coverage, so that packets with 1169 errors in some locations can be delivered to the user [RFC3828]. It 1170 uses a different transport protocol number (136) than UDP (17) to 1171 interpret the UDP Length field as the prefix covered by the UDP 1172 checksum. 1174 UDP (protocol 17) already defines the UDP Length field as the limit 1175 of the UDP checksum, but by default also limits the data provided to 1176 the application as that which precedes the UDP Length. A goal of 1177 UDP-Lite is to deliver data beyond UDP Length as a default, which is 1178 why a separate transport protocol number was required. 1180 UDP options do not use or need a separate transport protocol number 1181 because the data beyond the UDP Length offset (surplus data) is not 1182 provided to the application by default. That data is interpreted 1183 exclusively within the UDP transport layer. 1185 The UDP FRAG options option supports a similar service to UDP-Lite. 1186 The main difference is that UDP-Lite provides the un-checksummed 1187 user data to the application by default, whereas the UDP FRAG option 1188 can safely provide that service only between endpoints that 1189 negotiate that capability in advance. An endpoint that does not 1190 implement UDP options would silently discard this non-checksummed 1191 user data, along with the UDP options as well. 1193 UDP-Lite cannot support UDP options, either as proposed here or in 1194 any other form, because the entire payload of the UDP packet is 1195 already defined as user data and there is no additional field in 1196 which to indicate a separate area for options. The UDP Length field 1197 in UDP-Lite is already used to indicate the boundary between user 1198 data covered by the checksum and user data not covered. 1200 11. Interactions with Legacy Devices 1202 It has always been permissible for the UDP Length to be inconsistent 1203 with the IP transport payload length [RFC768]. Such inconsistency 1204 has been utilized in UDP-Lite using a different transport number. 1205 There are no known systems that use this inconsistency for UDP 1206 [RFC3828]. It is possible that such use might interact with UDP 1207 options, i.e., where legacy systems might generate UDP datagrams 1208 that appear to have UDP options. The UDP OCS provides protection 1209 against such events and is stronger than a static "magic number". 1211 UDP options have been tested as interoperable with Linux, macOS, and 1212 Windows Cygwin, and worked through NAT devices. These systems 1213 successfully delivered only the user data indicated by the UDP 1214 Length field and silently discarded the surplus area. 1216 One reported embedded device passes the entire IP datagram to the 1217 UDP application layer. Although this feature could enable 1218 application-layer UDP option processing, it would require that 1219 conventional UDP user applications examine only the UDP payload. 1220 This feature is also inconsistent with the UDP application interface 1221 [RFC768] [RFC1122]. 1223 It has been reported that Alcatel-Lucent's "Brick" Intrusion 1224 Detection System has a default configuration that interprets 1225 inconsistencies between UDP Length and IP Length as an attack to be 1226 reported. Note that other firewall systems, e.g., CheckPoint, use a 1227 default "relaxed UDP length verification" to avoid falsely 1228 interpreting this inconsistency as an attack. 1230 (TBD: test with UDP checksum offload and UDP fragmentation offload) 1232 12. Options in a Stateless, Unreliable Transport Protocol 1234 There are two ways to interpret options for a stateless, unreliable 1235 protocol -- an option is either local to the message or intended to 1236 affect a stream of messages in a soft-state manner. Either 1237 interpretation is valid for defined UDP options. 1239 It is impossible to know in advance whether an endpoint supports a 1240 UDP option. 1242 >> All UDP options other than UNSAFE ones MUST be ignored if not 1243 supported or upon failure (e.g., ACS). 1245 >> All UDP options that fail MUST result in the UDP data still being 1246 sent to the application layer by default, to ensure equivalence with 1247 legacy devices. 1249 >> UDP options that rely on soft-state exchange MUST allow for 1250 message reordering and loss. 1252 The above requirements prevent using any option that cannot be 1253 safely ignored unless it is hidden inside the FRAG area (i.e., 1254 UNSAFE options). Legacy systems also always need to be able to 1255 interpret the transport payload fragments as individual transport 1256 datagrams. 1258 13. UDP Option State Caching 1260 Some TCP connection parameters, stored in the TCP Control Block, can 1261 be usefully shared either among concurrent connections or between 1262 connections in sequence, known as TCP Sharing [RFC2140][To20cb]. 1263 Although UDP is stateless, some of the options proposed herein may 1264 have similar benefit in being shared or cached. We call this UCB 1265 Sharing, or UDP Control Block Sharing, by analogy. 1267 [TBD: extend this section to indicate which options MAY vs. MUST NOT 1268 be shared and how, e.g., along the lines of To20cb] 1270 14. Updates to RFC 768 1272 This document updates RFC 768 as follows: 1274 o This document defines the meaning of the IP payload area beyond 1275 the UDP length but within the IP length. 1277 o This document extends the UDP API to support the use of options. 1279 15. Interactions with other RFCs (and drafts) 1281 This document clarifies the interaction between UDP length and IP 1282 length that is not explicitly constrained in either UDP or the host 1283 requirements [RFC768] [RFC1122]. 1285 Teredo extensions (TE) define use of a similar surplus area for 1286 trailers [RFC6081]. TE defines the UDP length pointing beyond 1287 (larger) than the location indicated by the IP length rather than 1288 shorter (as used herein): 1290 "..the IPv6 packet length (i.e., the Payload Length value in 1291 the IPv6 header plus the IPv6 header size) is less than or 1292 equal to the UDP payload length (i.e., the Length value in 1293 the UDP header minus the UDP header size)" 1295 As a result, UDP options are not compatible with TE, but that is 1296 also why this document does not update TE. Additionally, it is not 1297 at all clear how TE operates, as it requires network processing of 1298 the UDP length field to understand the total message including TE 1299 trailers. 1301 TE updates Teredo NAT traversal [RFC4380]. The NAT traversal 1302 document defined "consistency" of UDP length and IP length as: 1304 "An IPv6 packet is deemed valid if it conforms to [RFC2460]: 1305 the protocol identifier should indicate an IPv6 packet and 1306 the payload length should be consistent with the length of 1307 the UDP datagram in which the packet is encapsulated." 1309 IPv6 is clear on the meaning of this consistency, in which the 1310 pseudoheader used for UDP checksums is based on the UDP length, not 1311 inferred from the IP length, using the same text in the current 1312 specification [RFC8200]: 1314 "The Upper-Layer Packet Length in the pseudo-header is the 1315 length of the upper-layer header and data (e.g., TCP header 1316 plus TCP data). Some upper-layer protocols carry their own 1317 length information (e.g., the Length field in the UDP header); 1318 for such protocols, that is the length used in the pseudo- 1319 header." 1321 This document is consistent the UDP profile for Robust Header 1322 Compression (ROHC)[RFC3095], noted here: 1324 "The Length field of the UDP header MUST match the Length 1325 field(s) of the preceding subheaders, i.e., there must not 1326 be any padding after the UDP payload that is covered by the 1327 IP Length." 1329 ROHC compresses UDP headers only when this match succeeds. It does 1330 not prohibit UDP headers where the match fails; in those cases, ROHC 1331 default rules (Section 5.10) would cause the UDP header to remain 1332 uncompressed. Upon receivep of a compressed UDP header, Section 1333 A.1.3 of that document indicates that the UDP length is "INFERRED"; 1334 in uncompressed packets, it would simply be explicitly provided. 1336 This issue of handling UDP header compression is more explicitly 1337 described in more recent specifications, e.g., Sec. 10.10 of Static 1338 Context Header Compression [RFC8724]. 1340 16. Multicast Considerations 1342 UDP options are primarily intended for unicast use. Using these 1343 options over multicast IP requires careful consideration, e.g., to 1344 ensure that the options used are safe for different endpoints to 1345 interpret differently (e.g., either to support or silently ignore) 1346 or to ensure that all receivers of a multicast group confirm support 1347 for the options in use. 1349 17. Security Considerations 1351 The use of UDP packets with inconsistent IP and UDP Length fields 1352 has the potential to trigger a buffer overflow error if not properly 1353 handled, e.g., if space is allocated based on the smaller field and 1354 copying is based on the larger. However, there have been no reports 1355 of such vulnerability and it would rely on inconsistent use of the 1356 two fields for memory allocation and copying. 1358 UDP options are not covered by DTLS (datagram transport-layer 1359 security). Despite the name, neither TLS [RFC8446] (transport layer 1360 security, for TCP) nor DTLS [RFC6347] (TLS for UDP) protect the 1361 transport layer. Both operate as a shim layer solely on the payload 1362 of transport packets, protecting only their contents. Just as TLS 1363 does not protect the TCP header or its options, DTLS does not 1364 protect the UDP header or the new options introduced by this 1365 document. Transport security is provided in TCP by the TCP 1366 Authentication Option (TCP-AO [RFC5925]) or in UDP by the 1367 Authentication Extension option (Section 5.10). Transport headers 1368 are also protected as payload when using IP security (IPsec) 1369 [RFC4301]. 1371 UDP options use the TLV syntax similar to that of TCP. This syntax 1372 is known to require serial processing and may pose a DOS risk, e.g., 1373 if an attacker adds large numbers of unknown options that must be 1374 parsed in their entirety. Implementations concerned with the 1375 potential for this vulnerability MAY implement only the required 1376 options and MAY also limit processing of TLVs. Because required 1377 options come first and at most once each (with the exception of 1378 NOPs, which should never need to come in sequences of more than 1379 three in a row), this limits their DOS impact. 1381 UDP security should never rely solely on transport layer processing 1382 of options. UNSAFE options are the only type that share fate with 1383 the UDP data, because of the way that data is hidden in the surplus 1384 area until after those options are processed. All other options 1385 default to being silently ignored at the transport layer but may be 1386 dropped either if that default is overridden (e.g., by 1387 configuration) or discarded at the application layer (e.g., using 1388 information about the options processed that are passed along with 1389 the packet). 1391 UDP fragmentation introduces its own set of security concerns, which 1392 can be handled in a manner similar to IP fragmentation. In 1393 particular, the number of packets pending reassembly and effort used 1394 for reassembly is typically limited. In addition, it may be useful 1395 to assume a reasonable minimum fragment size, e.g., that non- 1396 terminal fragments should never be smaller than 500 bytes. 1398 18. IANA Considerations 1400 Upon publication, IANA is hereby requested to create a new registry 1401 for UDP Option Kind numbers, similar to that for TCP Option Kinds. 1402 Initial values of this registry are as listed in Section 5. 1403 Additional values in this registry are to be assigned from the 1404 UNASSIGNED values in Section 5 by IESG Approval or Standards Action 1405 [RFC8126]. Those assignments are subject to the conditions set forth 1406 in this document, particularly (but not limited to) those in Section 1407 6. 1409 Upon publication, IANA is hereby requested to create a new registry 1410 for UDP Experimental Option Experiment Identifiers (UDP ExIDs) for 1411 use in a similar manner as TCP ExIDs [RFC6994]. UDP ExIDs can be 1412 used in either the UDP EXP option or the UDP UNSAFE option when 1413 using UKind=UEXP. This registry is initially empty. Values in this 1414 registry are to be assigned by IANA using first-come, first-served 1415 (FCFS) rules [RFC8126]. Options using these ExIDs are subject to the 1416 same conditions as new options, i.e., they too are subject to the 1417 conditions set forth in this document, particularly (but not limited 1418 to) those in Section 6. 1420 Upon publication, IANA is hereby requested to create a new registry 1421 for UDP UNSAFE UKind numbers. There are no initial assignments in 1422 this registry. Values in this registry are to be assigned from the 1423 UNASSIGNED values in Section 5.8 by IESG Approval or Standards 1424 Action [RFC8126]. Those assignments are subject to the conditions 1425 set forth in this document, particularly (but not limited to) those 1426 in Section 6. 1428 19. References 1430 19.1. Normative References 1432 [RFC768] Postel, J., "User Datagram Protocol," RFC 768, August 1433 1980. 1435 [RFC791] Postel, J., "Internet Protocol," RFC 791, Sept. 1981. 1437 [RFC1122] Braden, R., Ed., "Requirements for Internet Hosts -- 1438 Communication Layers," RFC 1122, Oct. 1989. 1440 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1441 Requirement Levels," BCP 14, RFC 2119, March 1997. 1443 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1444 2119 Key Words," RFC 2119, May 2017. 1446 19.2. Informative References 1448 [Fa18] Fairhurst, G., T. Jones, R. Zullo, "Checksum Compensation 1449 Options for UDP Options", draft-fairhurst-udp-options-cco, 1450 Oct. 2018. 1452 [Fa21] Fairhurst, G., T. Jones, "Datagram PLPMTUD for UDP 1453 Options," draft-fairhurst-tsvwg-udp-options-dplpmtud, Apr. 1454 2021. 1456 [Hi15] Hildebrand, J., B. Trammel, "Substrate Protocol for User 1457 Datagrams (SPUD) Prototype," draft-hildebrand-spud- 1458 prototype-03, Mar. 2015. 1460 [RFC793] Postel, J., "Transmission Control Protocol" RFC 793, 1461 September 1981. 1463 [RFC1191] Mogul, J., S. Deering, "Path MTU discovery," RFC 1191, 1464 November 1990. 1466 [RFC2140] Touch, J., "TCP Control Block Interdependence," RFC 2140, 1467 Apr. 1997. 1469 [RFC2923] Lahey, K., "TCP Problems with Path MTU Discovery," RFC 1470 2923, September 2000. 1472 [RFC3095] Bormann, C. (Ed), et al., "RObust Header Compression 1473 (ROHC): Framework and four profiles: RTP, UDP, ESP, and 1474 uncompressed," RFC 3095, July 2001. 1476 [RFC3385] Sheinwald, D., J. Satran, P. Thaler, V. Cavanna, "Internet 1477 Protocol Small Computer System Interface (iSCSI) Cyclic 1478 Redundancy Check (CRC)/Checksum Considerations," RFC 3385, 1479 Sep. 2002. 1481 [RFC3692] Narten, T., "Assigning Experimental and Testing Numbers 1482 Considered Useful," RFC 3692, Jan. 2004. 1484 [RFC3828] Larzon, L-A., M. Degermark, S. Pink, L-E. Jonsson (Ed.), 1485 G. Fairhurst (Ed.), "The Lightweight User Datagram 1486 Protocol (UDP-Lite)," RFC 3828, July 2004. 1488 [RFC4301] Kent, S. and K. Seo, "Security Architecture for the 1489 Internet Protocol", RFC 4301, Dec. 2005. 1491 [RFC4340] Kohler, E., M. Handley, and S. Floyd, "Datagram Congestion 1492 Control Protocol (DCCP)", RFC 4340, March 2006. 1494 [RFC4380] Huitema, C., "Teredo: Tunneling IPv6 over UDP through 1495 Network Address Translations (NATs)," RFC 4380, Feb. 2006. 1497 [RFC4960] Stewart, R. (Ed.), "Stream Control Transmission Protocol", 1498 RFC 4960, September 2007. 1500 [RFC5925] Touch, J., A. Mankin, R. Bonica, "The TCP Authentication 1501 Option," RFC 5925, June 2010. 1503 [RFC6081] Thaler, D., "Teredo Extensions," RFC 6081, Jan 2011. 1505 [RFC6347] Rescorla, E., N. Modadugu, "Datagram Transport Layer 1506 Security Version 1.2," RFC 6347, Jan. 2012. 1508 [RFC6691] Borman, D., "TCP Options and Maximum Segment Size (MSS)," 1509 RFC 6691, July 2012. 1511 [RFC6978] Touch, J., "A TCP Authentication Option Extension for NAT 1512 Traversal", RFC 6978, July 2013. 1514 [RFC6994] Touch, J., "Shared Use of Experimental TCP Options," RFC 1515 6994, Aug. 2013. 1517 [RFC7323] Borman, D., R. Braden, V. Jacobson, R. Scheffenegger 1518 (Ed.), "TCP Extensions for High Performance," RFC 7323, 1519 Sep. 2014. 1521 [RFC8085] Eggert, L., G. Fairhurst, G. Shepherd, "UDP Usage 1522 Guidelines," RFC 8085, Feb. 2017. 1524 [RFC8126] Cotton, M., B. Leiba, T. Narten, "Guidelines for Writing 1525 an IANA Considerations Section in RFCs," RFC 8126, June 1526 2017. 1528 [RFC8200] Deering, S., R. Hinden, "Internet Protocol Version 6 1529 (IPv6) Specification," RFC 8200, Jul. 2017. 1531 [RFC8201] McCann, J., S. Deering, J. Mogul, R. Hinden (Ed.), "Path 1532 MTU Discovery for IP version 6," RFC 8201, Jul. 2017. 1534 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 1535 Version 1.3," RFC 8446, Aug. 2018. 1537 [RFC8724] Minaburo, A., L. Toutain, C. Gomez, D. Barthel, JC., 1538 "SCHC: Generic Framework for Static Context Header 1539 Compression and Fragmentation," RFC 8724, Apr. 2020. 1541 [RFC8899] Fairhurst, G., T. Jones, M. Tuxen, I. Rungeler, T. Volker, 1542 "Packetization Layer Path MTU Discovery for Datagram 1543 Transports," RFC 8899, Sep. 2020. 1545 [To18ao] Touch, J., "A TCP Authentication Option Extension for 1546 Payload Encryption," draft-touch-tcp-ao-encrypt, Jul. 1547 2018. 1549 [To20cb] Touch, J., M. Welzl, S. Islam, J. You, "TCP Control Block 1550 Interdependence," draft-touch-tcpm-2140bis, Apr. 2020. 1552 20. Acknowledgments 1554 This work benefitted from feedback from Bob Briscoe, Ken Calvert, 1555 Ted Faber, Gorry Fairhurst (including OCS for misbehaving middlebox 1556 traversal), C. M. Heard (including combining previous FRAG and LITE 1557 options into the new FRAG), Tom Herbert, Mark Smith, and Raffaele 1558 Zullo, as well as discussions on the IETF TSVWG and SPUD email 1559 lists. 1561 This work was partly supported by USC/ISI's Postel Center. 1563 This document was prepared using 2-Word-v2.0.template.dot. 1565 Authors' Addresses 1567 Joe Touch 1568 Manhattan Beach, CA 90266 USA 1570 Phone: +1 (310) 560-0334 1571 Email: touch@strayalpha.com 1573 Appendix A. Implementation Information 1575 The following information is provided to encourage interoperable API 1576 implementations. 1578 System-level variables (sysctl): 1580 Name default meaning 1581 ---------------------------------------------------- 1582 net.ipv4.udp_opt 0 UDP options available 1583 net.ipv4.udp_opt_ocs 1 Default include OCS 1584 net.ipv4.udp_opt_acs 0 Default include ACS 1585 net.ipv4.udp_opt_mss 0 Default include MSS 1586 net.ipv4.udp_opt_time 0 Default include TIME 1587 net.ipv4.udp_opt_frag 0 Default include FRAG 1588 net.ipv4.udp_opt_ae 0 Default include AE 1590 Socket options (sockopt), cached for outgoing datagrams: 1592 Name meaning 1593 ---------------------------------------------------- 1594 UDP_OPT Enable UDP options (at all) 1595 UDP_OPT_OCS Enable UDP OCS option 1596 UDP_OPT_ACS Enable UDP ACS option 1597 UDP_OPT_MSS Enable UDP MSS option 1598 UDP_OPT_TIME Enable UDP TIME option 1599 UDP_OPT_FRAG Enable UDP FRAG option 1600 UDP_OPT_AE Enable UDP AE option 1602 Send/sendto parameters: 1604 Connection parameters (per-socketpair cached state, part UCB): 1606 Name Initial value 1607 ---------------------------------------------------- 1608 opts_enabled net.ipv4.udp_opt 1609 ocs_enabled net.ipv4.udp_opt_ocs 1611 The following option is included for debugging purposes, and MUST 1612 NOT be enabled otherwise. 1614 System variables 1616 net.ipv4.udp_opt_junk 0 1618 System-level variables (sysctl): 1620 Name default meaning 1621 ---------------------------------------------------- 1622 net.ipv4.udp_opt_junk 0 Default use of junk 1624 Socket options (sockopt): 1626 Name params meaning 1627 ------------------------------------------------------ 1628 UDP_JUNK - Enable UDP junk option 1629 UDP_JUNK_VAL fillval Value to use as junk fill 1630 UDP_JUNK_LEN length Length of junk payload in bytes 1632 Connection parameters (per-socketpair cached state, part UCB): 1634 Name Initial value 1635 ---------------------------------------------------- 1636 junk_enabled net.ipv4.udp_opt_junk 1637 junk_value 0xABCD 1638 junk_len 4