idnits 2.17.1 draft-ietf-tsvwg-udp-options-13.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 1621 has weird spacing: '...default mean...' == Line 1649 has weird spacing: '...enabled net.i...' == Line 1650 has weird spacing: '...enabled net....' == Line 1660 has weird spacing: '...default mean...' == Line 1666 has weird spacing: '... params mean...' == (1 more instance...) -- The document date (June 19, 2021) is 1034 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 1333, 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 June 19, 2021 4 Intended updates: 768 5 Expires: December 2021 7 Transport Options for UDP 8 draft-ietf-tsvwg-udp-options-13.txt 10 Status of this Memo 12 This Internet-Draft is submitted in full conformance with the 13 provisions of BCP 78 and BCP 79. This document may not be modified, 14 and derivative works of it may not be created, except to format it 15 for publication as an RFC or to translate it into languages other 16 than English. 18 Internet-Drafts are working documents of the Internet Engineering 19 Task Force (IETF), its areas, and its working groups. Note that 20 other groups may also distribute working documents as Internet- 21 Drafts. 23 Internet-Drafts are draft documents valid for a maximum of six 24 months and may be updated, replaced, or obsoleted by other documents 25 at any time. It is inappropriate to use Internet-Drafts as 26 reference material or to cite them other than as "work in progress." 28 The list of current Internet-Drafts can be accessed at 29 http://www.ietf.org/ietf/1id-abstracts.txt 31 The list of Internet-Draft Shadow Directories can be accessed at 32 http://www.ietf.org/shadow.html 34 This Internet-Draft will expire on December 19, 2021. 36 Copyright Notice 38 Copyright (c) 2021 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (http://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with 46 respect to this document. Code Components extracted from this 47 document must include Simplified BSD License text as described in 48 Section 4.e of the Trust Legal Provisions and are provided without 49 warranty as described in the Simplified BSD License. 51 Abstract 53 Transport protocols are extended through the use of transport header 54 options. This document extends UDP by indicating the location, 55 syntax, and semantics for UDP transport layer options. 57 Table of Contents 59 1. Introduction...................................................3 60 2. Conventions used in this document..............................3 61 3. Background.....................................................3 62 4. The UDP Option Area............................................4 63 5. UDP Options....................................................8 64 5.1. End of Options List (EOL).................................9 65 5.2. No Operation (NOP).......................................10 66 5.3. Option Checksum (OCS)....................................11 67 5.4. Alternate Checksum (ACS).................................12 68 5.5. Fragmentation (FRAG).....................................13 69 5.6. Maximum Segment Size (MSS)...............................17 70 5.7. Maximum Reassembled Segment Size (MRSS)..................18 71 5.8. Unsafe (UNSAFE)..........................................18 72 5.9. Timestamps (TIME)........................................19 73 5.10. Authentication (AUTH)...................................20 74 5.11. Echo request (REQ) and echo response (RES)..............21 75 5.12. Experimental (EXP)......................................22 76 6. Rules for designing new options...............................23 77 7. Option inclusion and processing...............................24 78 8. UDP API Extensions............................................25 79 9. Whose options are these?............Error! Bookmark not defined. 80 10. UDP options FRAG option vs. UDP-Lite.........................27 81 11. Interactions with Legacy Devices.............................27 82 12. Options in a Stateless, Unreliable Transport Protocol........28 83 13. UDP Option State Caching.....................................28 84 14. Updates to RFC 768...........................................29 85 15. Interactions with other RFCs (and drafts)....................29 86 16. Multicast Considerations.....................................30 87 17. Security Considerations......................................30 88 18. IANA Considerations..........................................32 89 19. References...................................................32 90 19.1. Normative References....................................32 91 19.2. Informative References..................................33 93 20. Acknowledgments..............................................35 94 Appendix A. Implementation Information...........................36 96 1. Introduction 98 Transport protocols use options as a way to extend their 99 capabilities. TCP [RFC793], SCTP [RFC4960], and DCCP [RFC4340] 100 include space for these options but UDP [RFC768] currently does not. 101 This document defines an extension to UDP that provides space for 102 transport options including their generic syntax and semantics for 103 their use in UDP's stateless, unreliable message protocol. 105 2. Conventions used in this document 107 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 108 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 109 "OPTIONAL" in this document are to be interpreted as described in 110 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 111 capitals, as shown here. 113 In this document, the characters ">>" preceding an indented line(s) 114 indicates a statement using the key words listed above. This 115 convention aids reviewers in quickly identifying or finding the 116 portions of this RFC covered by these key words. 118 3. Background 120 Many protocols include a default, invariant header and an area for 121 header options that varies from packet to packet. These options 122 enable the protocol to be extended for use in particular 123 environments or in ways unforeseen by the original designers. 124 Examples include TCP's Maximum Segment Size, Window Scale, 125 Timestamp, and Authentication Options [RFC793][RFC5925][RFC7323]. 127 These options are used both in stateful (connection-oriented, e.g., 128 TCP [RFC793], SCTP [RFC4960], DCCP [RFC4340]) and stateless 129 (connectionless, e.g., IPv4 [RFC791], IPv6 [RFC8200]) protocols. In 130 stateful protocols they can help extend the way in which state is 131 managed. In stateless protocols their effect is often limited to 132 individual packets, but they can have an aggregate effect on a 133 sequence of packets as well. This document is intended to provide an 134 out-of-band option area as an alternative to the in-band mechanism 135 currently proposed [Hi15]. 137 UDP is one of the most popular protocols that lacks space for 138 options [RFC768]. The UDP header was intended to be a minimal 139 addition to IP, providing only ports and a data checksum for 140 protection. This document extends UDP to provide a trailer area for 141 options located after the UDP data payload. 143 This extension is possible because UDP includes its own length 144 field, separate from that of the IP header. SCTP includes its own 145 length field, one for each chunk. TCP and DCCP lack this transport 146 length field, inferring it from the IP length. There are a number of 147 suggested reasons why UDP includes this field, notably to support 148 multiple UDP segments in the same IP packet or to indicate the 149 length of the UDP payload as distinct from zero padding required for 150 systems that require writes that are not byte-alighed. These 151 suggestions are not consistent with earlier versions of UDP or with 152 concurrent design of multi-segment multiplexing protocols, however. 154 4. The UDP Option Area 156 The UDP transport header includes demultiplexing and service 157 identification (port numbers), a checksum, and a field that 158 indicates the UDP datagram length (including UDP header). The UDP 159 Length field is typically redundant with the size of the maximum 160 space available as a transport protocol payload (see also discussion 161 in Section 11). 163 For IPv4, IP Total Length field indicates the total IP datagram 164 length (including IP header), and the size of the IP options is 165 indicated in the IP header (in 4-byte words) as the "Internet Header 166 Length" (IHL), as shown in Figure 1 [RFC791]. As a result, the 167 typical (and largest valid) value for UDP Length is: 169 UDP_Length = IPv4_Total_Length - IPv4_IHL * 4 171 For IPv6, the IP Payload Length field indicates the datagram after 172 the base IPv6 header, which includes the IPv6 extension headers and 173 space available for the transport protocol, as shown in Figure 2 174 [RFC8200]. Note that the Next HDR field in IPv6 might not indicate 175 UDP (i.e., 17), e.g., when intervening IP extension headers are 176 present. For IPv6, the lengths of any additional IP extensions are 177 indicated within each extension [RFC8200], so the typical (and 178 largest valid) value for UDP Length is: 180 UDP_Length = IPv6_Payload_Length - sum(extension header lengths) 182 In both cases, the space available for the UDP transport protocol 183 data unit is indicated by IP, either completely in the base header 184 (for IPv4) or adding information in the extensions (for IPv6). In 185 either case, this document will refer to this available space as the 186 "IP transport payload". 188 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 189 |Version| IHL |Type of Service| Total Length | 190 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 191 | Identification |Flags| Fragment Offset | 192 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 193 | Time to Live | Proto=17 (UDP)| Header Checksum | 194 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 195 | Source Address | 196 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 197 | Destination Address | 198 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 199 ... zero or more IP Options (using space as indicated by IHL) ... 200 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 201 | UDP Source Port | UDP Destination Port | 202 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 203 | UDP Length | UDP Checksum | 204 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 206 Figure 1 IPv4 datagram with UDP transport payload 208 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 209 |Version| Traffic Class | Flow Label | 210 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 211 | Payload Length | Next Hdr | Hop Limit | 212 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 213 ... 214 | Source Address (128 bits) | 215 ... 216 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 217 ... 218 | Destination Address (128 bits) | 219 ... 220 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 221 ... zero or more IP Extension headers (each indicating size) ... 222 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 223 | UDP Source Port | UDP Destination Port | 224 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 225 | UDP Length | UDP Checksum | 226 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 228 Figure 2 IPv6 datagram with UDP transport payload 230 As a result of this redundancy, there is an opportunity to use the 231 UDP Length field as a way to break up the IP transport payload into 232 two areas - that intended as UDP user data and an additional 233 "surplus area" (as shown in Figure 3). 235 IP transport payload 236 <-------------------------------------------------> 237 +--------+---------+----------------------+------------------+ 238 | IP Hdr | UDP Hdr | UDP user data | surplus area | 239 +--------+---------+----------------------+------------------+ 240 <------------------------------> 241 UDP Length 243 Figure 3 IP transport payload vs. UDP Length 245 In most cases, the IP transport payload and UDP Length point to the 246 same location, indicating that there is no surplus area. It is 247 important to note that this is not a requirement of UDP [RFC768] 248 (discussed further in Section 11). UDP-Lite used the difference in 249 these pointers to indicate the partial coverage of the UDP Checksum, 250 such that the UDP user data, UDP header, and UDP pseudoheader (a 251 subset of the IP header) are covered by the UDP checksum but 252 additional user data in the surplus area is not covered [RFC3828]. 253 This document uses the surplus area for UDP transport options. 255 The UDP option area is thus defined as the location between the end 256 of the UDP payload and the end of the IP datagram as a trailing 257 options area. This area can occur at any valid byte offset, i.e., it 258 need not be 16-bit or 32-bit aligned. In effect, this document 259 redefines the UDP "Length" field as a "trailer offset". 261 UDP options are defined using a TLV (type, length, and optional 262 value) syntax similar to that of TCP [RFC793]. They are typically a 263 minimum of two bytes in length as shown in Figure 4, excepting only 264 the one byte options "No Operation" (NOP) and "End of Options List" 265 (EOL) described below. 267 +--------+--------+------- 268 | Kind | Length | (remainder of option...) 269 +--------+--------+------- 271 Figure 4 UDP option default format 273 The Kind field is always one byte. The Length field is one byte for 274 all lengths below 255 (including the Kind and Length bytes). A 275 Length of 255 indicates use of the UDP option extended format shown 276 in Figure 5. The Extended Length field is a 16-bit field in network 277 standard byte order. 279 +--------+--------+--------+--------+ 280 | Kind | 255 | Extended Length | 281 +--------+--------+--------+--------+ 282 | (remainder of option...) 283 +--------+--------+--------+--------+ 285 Figure 5 UDP option extended default format 287 >> UDP options MAY begin at any UDP length offset. 289 >> The UDP length MUST be at least as large as the UDP header (8) 290 and no larger than the IP transport payload. Datagrams with length 291 values outside this range MUST be silently dropped as invalid and 292 logged where rate-limiting permits. 294 >> Option Lengths (or Extended Lengths, where applicable) smaller 295 than the minimum for the corresponding Kind and default format MUST 296 be treated as an error. Such errors call into question the remainder 297 of the option area and thus MUST result in all UDP options being 298 silently discarded. 300 >> Any UDP option whose length smaller than 255 MUST use the UDP 301 option default format shown in Figure 4, excepting only EOL and NOP. 303 >> Any UDP option whose length is larger than 254 MUST use the UDP 304 option extended default format shown in Figure 5. 306 I.e., a UDP option always uses the smallest option format, based on 307 the length it uses in each instance. 309 >> Options using the extended option format MUST indicate extended 310 lengths of 255 or higher; smaller extended length values MUST be 311 treated as an error. 313 Others have considered using values of the UDP Length that is larger 314 than the IP transport payload as an additional type of signal. Using 315 a value smaller than the IP transport payload is expected to be 316 backward compatible with existing UDP implementations, i.e., to 317 deliver the UDP Length of user data to the application and silently 318 ignore the additional surplus area data. Using a value larger than 319 the IP transport payload would either be considered malformed (and 320 be silently dropped) or could cause buffer overruns, and so is not 321 considered silently and safely backward compatible. Its use is thus 322 out of scope for the extension described in this document. 324 >> UDP options MUST be interpreted in the order in which they occur 325 in the UDP option area. 327 Note that a receiver can compute the OCS checksum before processing 328 any UDP options, but that computation would assume OCS is used and 329 would not be verified until the OCS option is interpreted. 331 5. UDP Options 333 The following UDP options are currently defined: 335 Kind Length Meaning 336 ---------------------------------------------- 337 0* - End of Options List (EOL) 338 1* - No operation (NOP) 339 2* 4 Option checksum (OCS) 340 3* 6 Alternate checksum (ACS) 341 4* 10/12 Fragmentation (FRAG) 342 5* 4 Maximum segment size (MSS) 343 6* 4 Maximum reassembled segment size (MRSS) 344 7* (varies) Unsafe to ignore (UNSAFE) options 345 8 10 Timestamps (TIME) 346 9 (varies) Authentication (AUTH) 347 10 6 Request (REQ) 348 11 6 Response (RES) 349 12-126 (varies) UNASSIGNED (assignable by IANA) 350 127-253 RESERVED 351 254 (varies) RFC 3692-style experiments (EXP) 352 255 RESERVED 354 These options are defined in the following subsections. Options 0 355 and 1 use the same values as for TCP. 357 >> An endpoint supporting UDP options MUST support those marked with 358 a "*" above: EOL, NOP, OCS, ACS, FRAG, MSS, MRSS, and UNSAFE. This 359 includes both recognizing and being able to generate these options 360 if configured to do so. These are called "must-support" options. 362 >> All other options (without a "*") MAY be implemented, and their 363 use SHOULD be determined either out-of-band or negotiated. 365 >> Receivers supporting UDP options MUST silently ignore unknown 366 options except UNSAFE. That includes options whose length does not 367 indicate the specified value(s). 369 >> Receivers supporting UDP options MUST silently drop the entire 370 datagram containing an UNSAFE option when any UNSAFE option it 371 contains is unknown. See Section 5.8 for further discussion of 372 UNSAFE options. 374 >> Except for NOP, each option SHOULD NOT occur more than once in a 375 single UDP datagram. If an option other than NOP occurs more than 376 once, a receiver MUST interpret only the first instance of that 377 option and MUST ignore all others. 379 >> Only the OCS, AUTH, and ENCR options depend on the contents of 380 the option area. AUTH and ENCR are never used together. AUTH/ENCR 381 are always computed as if their hash and OCS checksum are zero; OCS 382 is always computed as if the OCS checksum is zero and after the 383 AUTH/ENCR hash has been computed. Future options MUST NOT be defined 384 as having a value dependent on the contents of the option area. 385 Otherwise, interactions between those values, OCS, and AUTH/ENCR 386 could be unpredictable. 388 Receivers cannot generally treat unexpected option lengths as 389 invalid, as this would unnecessarily limit future revision of 390 options (e.g., defining a new ACS that is defined by having a 391 different length). The exception is only for lengths that imply a 392 physical impossibility, e.g., smaller than two for conventional 393 options and four for extended length options. Impossible lengths 394 should indicate a malformed option area and all options silently 395 discarded. Lengths other than expected should result in safe options 396 being ignored and that length skipped over, as with any other 397 unknown safe option. 399 >> Option lengths MUST NOT exceed the IP length of the packet. If 400 this occurs, the packet MUST be treated as malformed and dropped, 401 and the event MAY be logged for diagnostics (logging SHOULD be rate 402 limited). 404 >> "Must-support" options other than NOP and EOL MUST come before 405 other options. 407 The requirement that must-support options come before others is 408 intended to allow for endpoints to implement DOS protection, as 409 discussed further in Section 17. 411 5.1. End of Options List (EOL) 413 The End of Options List (EOL) option indicates that there are no 414 more options. It is used to indicate the end of the list of options 415 without needing to pad the options to fill all available option 416 space. 418 +--------+ 419 | Kind=0 | 420 +--------+ 422 Figure 6 UDP EOL option format 424 >> When the UDP options do not consume the entire option area, the 425 last non-NOP option MUST be EOL. 427 >> All bytes in the surplus area after EOL MUST be set to zero on 428 transmit. 430 >> Bytes after EOL in the surplus area MAY be checked as being zero 431 on receipt but MUST be treated as zero regardless of their content 432 and are not passed to the user (e.g., as part of the UDP option 433 area). 435 Requiring the post-option surplus area to be zero prevents side- 436 channel uses of this area, requiring instead that all use of the 437 surplus area be UDP options supported by both endpoints. It is 438 useful to allow for such padding to increase the packet length 439 without affecting the payload length, e.g., for UDP DPLPMTUD [Fa21]. 441 5.2. No Operation (NOP) 443 The No Operation (NOP) option is a one byte placeholder, intended to 444 be used as padding, e.g., to align multi-byte options along 16-bit 445 or 32-bit boundaries. 447 +--------+ 448 | Kind=1 | 449 +--------+ 451 Figure 7 UDP NOP option format 453 >> If options longer than one byte are used, NOP options SHOULD be 454 used at the beginning of the UDP options area to achieve alignment 455 as would be more efficient for active (i.e., non-NOP) options. 457 >> Segments SHOULD NOT use more than seven consecutive NOPs, i.e., 458 to support alignment up to 8-byte boundaries. NOPs are intended to 459 assist with alignment, not as other padding or fill. 461 This issue is discussed further in Section 17. 463 5.3. Option Checksum (OCS) 465 The Option Checksum (OCS) option is conventional Internet checksum 466 [RFC791] that covers all of the surplus area and a pseudoheader 467 composed of the 16-bit length of the surplus area (Figure 8). The 468 primary purpose of OCS is to detect non-standard (i.e., non-option) 469 uses of that area. The surplus area pseudoheader is included to 470 enable traversal of errant middleboxes that incorrectly compute the 471 UDP checksum over the entire IP payload rather than only the UDP 472 payload [Fa18]. 474 The OCS is calculated by computing the Internet checksum over the 475 entire surplus area and surplus length pseudoheader. The OCS 476 protects the option area from errors in a similar way that the UDP 477 checksum protects the UDP user data (when not zero). 479 +--------+--------+ 480 | surplus length | 481 +--------+--------+ 483 Figure 8 UDP surplus length pseudoheader 485 +--------+--------+--------+--------+ 486 | Kind=2 | Len=4 | checksum | 487 +--------+--------+--------+--------+ 488 Figure 9 UDP OCS option format 490 >> The OCS MUST be included when the UDP checksum is nonzero and UDP 491 options are present. 493 UDP checksums can be zero for IPv4 [RFC791], but not typically when 494 used with IPv6 [RFC8200]. Even for IPv6 use, there remains an 495 exception for cases where UDP is a payload already covered by a 496 checksum, as might occur for tunnels [RFC6935], notably to reduce 497 the need for checksum computation that does not provide additional 498 protection, which is why the same exception applies to OCS. 500 >> When present, the OCS SHOULD occur as early as possible, preceded 501 by only NOP options for alignment. 503 >> OCS MUST be half-word coordinated with the start of the UDP 504 options area and include the surplus length pseudoheader similarly 505 coordinated with the start of UDP Header. 507 This Internet checksum is computed over the entire surplus area 508 prefixed by the surplus length pseudoheader (Figure 8) and then 509 adjusting the result before storing it into the OCS checksum field. 511 If the OCS checksum field is aligned to the start of the options 512 area, then the checksum is inserted as-is, otherwise the checksum 513 bytes are swapped before inserting them into the field. The effect 514 of this "coordination" is the same is if the checksum were computed 515 as if the surplus area and pseudoheader were aligned to the UDP 516 header. 518 This feature is intended to potentially help the UDP options 519 traverse devices that incorrectly attempt to checksum the surplus 520 area (as originally proposed as the Checksum Compensation Option, 521 i.e., CCO [Fa18]). 523 The OCS covers the UDP option area as formatted for transmission and 524 immediately upon reception. 526 >> If the OCS fails, all options MUST be ignored and the surplus 527 area silently discarded. 529 >> UDP data that is validated by a correct UDP checksum MUST be 530 delivered to the application layer, even if the OCS fails, unless 531 the endpoints have negotiated otherwise for this segment's socket 532 pair. 534 As a reminder, use of the UDP checksum is optional when the UDP 535 checksum is zero. When not used, the OCS is assumed to be "correct" 536 for the purpose of accepting UDP packets at a receiver (see Section 537 7). 539 The OCS is intended to check for accidental errors, not for attacks. 541 5.4. Alternate Checksum (ACS) 543 The Alternate Checksum (ACS) option provides a stronger alternative 544 to the checksum in the UDP header, using a 32-bit CRC of the 545 conventional UDP payload only (excluding the IP pseudoheader, UDP 546 header, and surplus area). It is an "alternate" to the UDP checksum 547 (covering the UDP payload) - not the OCS (the latter covers the 548 surplus area) Unlike the UDP checksum, ACS does not include the IP 549 pseudoheader or UDP header, thus it does not need to be updated by 550 NATs when IP addresses or UDP ports are rewritten. Its purpose is to 551 detect UDP payload errors that the UDP checksum, when used, might 552 not detect. 554 A CRC32c has been chosen because of its ubiquity and use in other 555 Internet protocols, including iSCSI and SCTP. The option contains 556 the CRC32c in network standard byte order, as described in 557 [RFC3385]. 559 +--------+--------+--------+--------+ 560 | Kind=3 | Len=6 | CRC32c... | 561 +--------+--------+--------+--------+ 562 | CRC32c (cont.) | 563 +--------+--------+ 565 Figure 10 UDP ACS option format 567 When present, the ACS always contains a valid CRC checksum. There 568 are no reserved values, including the value of zero. If the CRC is 569 zero, this must indicate a valid checksum (i.e., it does not 570 indicate that the ACS is not used; instead, the option would simply 571 not be included if that were the desired effect). 573 ACS does not protect the UDP pseudoheader; only the current UDP 574 checksum provides that protection (when used). ACS cannot provide 575 that protection because it would need to be updated whenever the UDP 576 pseudoheader changed, e.g., during NAT address and port translation; 577 because this is not the case, ACS does not cover the pseudoheader. 579 >> Packets with incorrect ACS checksums MUST be passed to the 580 application by default, e.g., with a flag indicating ACS failure. 582 Like all non-UNSAFE UDP options, ACS needs to be silently ignored 583 when failing by default, unless the receiver has been configured to 584 do otherwise. Although all UDP option-aware endpoints support ACS 585 (being in the required set), this silently-ignored behavior ensures 586 that option-aware receivers operate the same as legacy receivers 587 unless overridden. 589 >> Packets with unrecognized ACS lengths MUST be receive the same 590 treatment as packets with incorrect ACS checksums. 592 Ensuring that unrecognized ACS lengths are treated as incorrect 593 checksums enables future variants of ACS to be treated as ACS-like. 595 5.5. Fragmentation (FRAG) 597 The Fragmentation option (FRAG) combines properties of IP 598 fragmentation and the UDP Lite transport protocol [RFC3828]. FRAG 599 provides transport-layer fragmentation and reassembly in which each 600 fragment includes a copy of the same UDP transport ports, enabling 601 the fragments to traverse Network Address (and port) Translation 602 (NAT) devices, in contrast to the behavior of IP fragments. FRAG 603 also allows the UDP checksum to cover only a prefix of the UDP data 604 payload, to avoid repeated checksums of data prior to reassembly. 606 The Fragmentation (FRAG) option supports UDP fragmentation and 607 reassembly, which can be used to transfer UDP messages larger than 608 limited by the IP receive MTU (EMTU_R [RFC1122]). It is typically 609 used with the UDP MSS and MRSS options to enable more efficient use 610 of large messages, both at the UDP and IP layers. FRAG is designed 611 similar to the IPv6 Fragmentation Header [RFC8200], except that the 612 UDP variant uses a 16-bit Offset measured in bytes, rather than 613 IPv6's 13-bit Fragment Offset measured in 8-byte units. This UDP 614 variant avoids creating reserved fields. 616 >> When FRAG is present, it SHOULD come as early as possible in the 617 UDP options list after OCS. 619 >> When FRAG is present, the UDP payload MUST be empty. If the 620 payload is not empty, all UDP options MUST be silently ignored and 621 the payload received sent to the user. 623 Legacy receivers interpret FRAG messages as zero-length payload 624 packets (i.e., UDP Length field is 8, the length of just the UDP 625 header), which would not affect the receiver unless the presence of 626 the packet itself were a signal. 628 The FRAG option has two formats; non-terminal fragments use the 629 shorter variant (Figure 11) and terminal fragments use the longer 630 (Figure 12). The latter includes stand-alone fragments, i.e., when 631 data is contained in the FRAG option but reassembly is not required. 633 +--------+--------+--------+--------+ 634 | Kind=4 | Len=10 | Frag. Start | 635 +--------+--------+--------+--------+ 636 | Identification | 637 +--------+--------+--------+--------+ 638 | Frag. Offset | 639 +--------+--------+ 641 Figure 11 UDP non-terminal FRAG option format 643 In the non-terminal FRAG option format, Frag. Start indicates the 644 location of the beginning of the fragment data, measured from the 645 beginning of the UDP header, which always follows the remainder of 646 the UDP options. Those options are applied to this segment. The 647 fragment data begins at Frag. Start and ends at the end of the IP 648 datagram. Non-terminal fragments never have options after the 649 fragment. 651 The FRAG option does not need a "more fragments" bit because it 652 provides the same indication by using the longer, 12-byte variant, 653 as shown in Figure 12. 655 >> The FRAG option MAY be used on a single fragment, in which case 656 the Frag. Offset would be zero and the option would have the 12-byte 657 format. 659 Use of the single fragment variant can be helpful in supporting use 660 of UNSAFE options without undesirable impact to receivers that do 661 not support either UDP options or the specific UNSAFE options. 663 +--------+--------+--------+--------+ 664 | Kind=4 | Len=12 | Frag. Start | 665 +--------+--------+--------+--------+ 666 | Identification | 667 +--------+--------+--------+--------+ 668 | Frag. Offset | Frag. End | 669 +--------+--------+--------+--------+ 671 Figure 12 UDP terminal FRAG option format 673 The terminal FRAG option format adds a Frag. End pointer, measured 674 from the start of the UDP header, as with Frag. Start. In this 675 variant, UDP options continue after the terminal fragment data. UDP 676 options that occur before the FRAG data are processed on the 677 fragment; UDP options after the FRAG data are processed after 678 reassembly, such that the reassembled data represents the original 679 UDP user data. This allows either pre-reassembly or post-reassembly 680 UDP option effects. 682 >> During fragmentation, the UDP header checksum of each fragment 683 needs to be recomputed based on each datagram's pseudoheader. 685 The Fragment Offset is 16 bits and indicates the location of the UDP 686 payload fragment in bytes from the beginning of the original 687 unfragmented payload. The option Len field indicates whether there 688 are more fragments (Len=10) or no more fragments (Len=12). 690 >> The Identification field is a 32-bit value that MUST be unique 691 over the expected fragment reassembly timeout. 693 >> The Identification field SHOULD be generated in a manner similar 694 to that of the IPv6 Fragment ID [RFC8200]. 696 >> UDP fragments MUST NOT overlap. 698 UDP fragmentation relies on a fragment expiration timer, which can 699 be preset or could use a value computed using the UDP Timestamp 700 option. 702 >> The default UDP reassembly SHOULD be no more than 2 minutes. 704 Implementers are advised to limit the space available for UDP 705 reassembly. 707 >> UDP reassembly space SHOULD be limited to reduce the impact of 708 DOS attacks on resource use. 710 >> UDP reassembly space limits SHOULD NOT be implemented as an 711 aggregate, to avoid cross-socketpair DOS attacks. 713 >> Individual UDP fragments MUST NOT be forwarded to the user. The 714 reassembled datagram is received only after complete reassembly, 715 checksum validation, and continued processing of the remaining UDP 716 options. 718 Any additional UDP options, if used, follow the FRAG option in the 719 final fragment and would be included in the reassembled packet. 720 Processing of those options would commence after reassembly. This is 721 especially important for UNSAFE options, which are interpreted only 722 after FRAG. 724 In general, UDP packets are fragmented as follows: 726 1. Create a datagram with data and UDP options, which we will call 727 "D". Note that the UDP options treat the data area as UDP user 728 data and thus must follow that data. 730 Process these UDP options before the rest of the fragmentation 731 steps below. 733 2. Identify the desired fragment size, which we will call "S". This 734 value should take into account the path MTU (if known) and allow 735 space for per-fragment options (e.g., OCS). 737 3. Fragment "D" into chunks of size no larger than "S"-10 each, with 738 one final chunk no larger than "S"-12. Note that all the non-FRAG 739 options in step #1 MUST appear in the terminal fragment. 741 4. For each chunk of "D" in step #3, create a zero-data UDP packet 742 followed by OCS (if used), FRAG, and any additional UDP options, 743 followed by the FRAG data chunk. 745 The last chunk includes the non-FRAG options noted in step #1 746 after the end of the FRAG data. These UDP options apply to the 747 reassembled data as a whole when received. 749 5. Process the pre-reassembly UDP options of each fragment. 751 Receivers reverse the above sequence. They process all received 752 options in each fragment. When the FRAG option is encountered, the 753 FRAG data is used in reassembly. After all fragments are received, 754 the entire packet is processed with any trailing UDP options 755 applying to the reassembled data. 757 5.6. Maximum Segment Size (MSS) 759 The Maximum Segment Size (MSS, Kind = 5) option is a 16-bit hint of 760 the largest unfragmented UDP segment that an endpoint believes can 761 be received. As with the TCP MSS option [RFC793], the size indicated 762 is the IP layer MTU decreased by the fixed IP and UDP headers only 763 [RFC6691]. The space needed for IP and UDP options need to be 764 adjusted by the sender when using the value indicated. The value 765 transmitted is based on EMTU_R, the largest IP datagram that can be 766 received (i.e., reassembled at the receiver) [RFC1122]. However, as 767 with TCP, this value is only a hint at what the receiver believes; 768 it does not indicate a known path MTU and thus MUST NOT be used to 769 limit transmissions, notably for DPLPMTU probes. 771 +--------+--------+--------+--------+ 772 | Kind=5 | Len=4 | MSS size | 773 +--------+--------+--------+--------+ 775 Figure 13 UDP MSS option format 777 The UDP MSS option MAY be used as a hint for path MTU discovery 778 [RFC1191][RFC8201], but this may be difficult because of known 779 issues with ICMP blocking [RFC2923] as well as UDP lacking automatic 780 retransmission. It is more likely to be useful when coupled with IP 781 source fragmentation to limit the largest reassembled UDP message as 782 indicated by MRSS (see Section 5.7), e.g., when EMTU_R is larger 783 than the required minimums (576 for IPv4 [RFC791] and 1500 for IPv6 784 [RFC8200]). It can also be used with DPLPMTUD [RFC8899] to provide a 785 hint to maximum DPLPMTU, though it MUST NOT prohibit transmission of 786 larger UDP packets (or fragments) used as DPLPMTU probes. 788 5.7. Maximum Reassembled Segment Size (MRSS) 790 The Maximum Reassembled Segment Size (MRSS, Kind=6) option is a 16- 791 bit indicator of the largest reassembled UDP segment that can be 792 received. MRSS is the UDP equivalent of IP's EMTU_R but the two are 793 not related [RFC1122]. Using the FRAG option (Section 5.5), UDP 794 segments can be transmitted as transport fragments, each in their 795 own (presumably not fragmented) IP datagram and be reassembled at 796 the UDP layer. 798 +--------+--------+--------+--------+ 799 | Kind=6 | Len=4 | MRSS size | 800 +--------+--------+--------+--------+ 802 Figure 14 UDP MRSS option format 804 5.8. Unsafe (UNSAFE) 806 The Unsafe option (UNSAFE) extends the UDP option space to allow for 807 options that are not safe to ignore and can be used unidirectionally 808 or without soft-state confirmation of UDP option capability. They 809 are always used only when the entire UDP payload occurs inside a 810 reassembled set of UDP fragments, such that if UDP fragmentation is 811 not supported, the entire fragment would be silently dropped anyway. 813 UNSAFE options are an extended option space, with its own additional 814 option types. These are indicated in the first byte after the option 815 Kind as shown in Figure 15, which is followed by the Length. Length 816 is 1 byte for UKinds whose total length (including Kind, UKind, and 817 Length fields) is less than 255 or 2 bytes for larger lengths (in 818 the similar style as the extended option format). 820 +--------+--------+--------+ 821 | Kind=7 | UKind | Length |... 822 +--------+--------+--------+ 823 1 byte 1 byte 1-3 bytes 825 Figure 15 UDP UNSAFE option format 827 The UNSAFE option format supports extended lengths in the same 828 manner as the other UDP options, i.e., using a Length of 255 and two 829 additional bytes of extended length. 831 >> UNSAFE options MUST be used only as part of UDP fragments, used 832 either per-fragment or after reassembly. 834 >> Receivers supporting UDP options MUST silently drop the entire 835 reassembled datagram if any fragment or the entire datagram includes 836 an UNSAFE option whose UKind is not supported. 838 The following UKind values are defined: 840 UKind Length Meaning 841 ---------------------------------------------- 842 0 RESERVED 843 1 Encryption (ENCR) 844 2-253 (varies) UNASSIGNED (assignable by IANA) 845 254 (varies) RFC 3692-style experiments (UEXP) 846 255 RESERVED 848 ENCR has the same format as AUTH (Section 5.10), except that it 849 encrypts (modifies) the user data. It provides a similar encryption 850 capability as TCP-AO-ENC, in a similar manner [To18ao]. Its fields, 851 coverage, and processing are the same as for AUTH, except that ENCR 852 encrypts only the user data, although it can (optionally) depend on 853 the option area (with certain fields zeroed, as per AUTH, e.g., 854 providing authentication over the option area). Like AUTH, ENCR can 855 be configured to be compatible with NAT traversal. 857 Experimental UKind EXP ExID values indicate the ExID in the 858 following 2 (or 4) bytes, similar to the UDP EXP option as discussed 859 in Section 5.12. Assigned UDP EXP ExIDs and UDP UNSAFE UKind UEXP 860 ExIDs are assigned from the same registry and can be used either in 861 the EXP option (Section 5.12) or within the UKind UEXP. 863 5.9. Timestamps (TIME) 865 The Timestamp (TIME) option exchanges two four-byte timestamp 866 fields. It serves a similar purpose to TCP's TS option [RFC7323], 867 enabling UDP to estimate the round trip time (RTT) between hosts. 868 For UDP, this RTT can be useful for establishing UDP fragment 869 reassembly timeouts or transport-layer rate-limiting [RFC8085]. 871 +--------+--------+------------------+------------------+ 872 | Kind=8 | Len=10 | TSval | TSecr | 873 +--------+--------+------------------+------------------+ 874 1 byte 1 byte 4 bytes 4 bytes 876 Figure 16 UDP TIME option format 878 TS Value (TSval) and TS Echo Reply (TSecr) are used in a similar 879 manner to the TCP TS option [RFC7323]. On transmitted segments using 880 the option, TS Value is always set based on the local "time" value. 882 Received TSval and TSecr values are provided to the application, 883 which can pass the TSval value to be used as TSecr on UDP messages 884 sent in response (i.e., to echo the received TSval). A received 885 TSecr of zero indicates that the TSval was not echoed by the 886 transmitter, i.e., from a previously received UDP packet. 888 >> TIME MAY use an RTT estimate based on nonzero Timestamp values as 889 a hint for fragmentation reassembly, rate limiting, or other 890 mechanisms that benefit from such an estimate. 892 >> TIME SHOULD make this RTT estimate available to the user 893 application. 895 UDP timestamps are modeled after TCP timestamps and have similar 896 expectations. In particular, they are expected to be: 898 o Values are monotonic and non-decreasing except for anticipated 899 number-space rollover events 901 o Values should "increase" (allowing for rollover) according to a 902 typical 'tick' time 904 o A request is defined as "reply=0" and a reply is defined as both 905 fields being non-zero. 907 o A receiver should always respond to a request with the highest 908 TSval received (allowing for rollover), which is not necessarily 909 the most recently received. 911 Rollover can be handled as a special case or more completely using 912 sequence number extension [RFC5925]. 914 5.10. Authentication (AUTH) 916 The Authentication (AUTH) option is intended to allow UDP to provide 917 a similar type of authentication as the TCP Authentication Option 918 (TCP-AO) [RFC5925]. AUTH covers the conventional UDP payload. It 919 uses the same format as specified for TCP-AO, except that it uses a 920 Kind of 9. AUTH supports NAT traversal in a similar manner as TCP-AO 921 [RFC6978]. 923 +--------+--------+--------+--------+ 924 | Kind=9 | Len | Digest... | 925 +--------+--------+--------+--------+ 926 | Digest (con't)... | 927 +--------+--------+--------+--------+ 929 Figure 17 UDP AUTH option format 931 Like TCP-AO, AUTH is not negotiated in-band. Its use assumes both 932 endpoints have populated Master Key Tuples (MKTs), used to exclude 933 non-protected traffic. 935 TCP-AO generates unique traffic keys from a hash of TCP connection 936 parameters. UDP lacks a three-way handshake to coordinate 937 connection-specific values, such as TCP's Initial Sequence Numbers 938 (ISNs) [RFC793], thus AUTH's Key Derivation Function (KDF) uses 939 zeroes as the value for both ISNs. This means that the AUTH reuses 940 keys when socket pairs are reused, unlike TCP-AO. 942 >> Packets with incorrect AUTH HMACs MUST be passed to the 943 application by default, e.g., with a flag indicating AUTH failure. 945 Like all non-UNSAFE UDP options, AUTH needs to be silently ignored 946 when failing. This silently-ignored behavior ensures that option- 947 aware receivers operate the same as legacy receivers unless 948 overridden. 950 In addition to the UDP payload (which is always included), AUTH can 951 be configured to either include or exclude the surplus area, in a 952 similar way as can TCP-AO can optionally exclude TCP options. When 953 UDP options are covered, the OCS option area checksum and AUTH hash 954 areas are zeroed before computing the AUTH hash. It is important to 955 consider that options not yet defined might yield unpredictable 956 results if not confirmed as supported, e.g., if they were to contain 957 other hashes or checksums that depend on the option area contents. 958 This is why such dependencies are not permitted except as defined 959 for OCS and AUTH. 961 Similar to TCP-AO-NAT, AUTH can be configured to support NAT 962 traversal, excluding (by zeroing out) one or both of the UDP ports 963 and corresponding IP addresses [RFC6978]. 965 5.11. Echo request (REQ) and echo response (RES) 967 The echo request (REQ, kind=10) and echo response (RES, kind=11) 968 options provide a means for UDP options to be used to provide 969 packet-level acknowledgements. One such use is described as part of 970 the UDP variant of packetization layer path MTU discovery (PLPMTUD) 971 [Fa21]. The options both have the format indicated in Figure 18. 973 +--------+--------+------------------+ 974 | Kind | Len=6 | nonce | 975 +--------+--------+------------------+ 976 1 byte 1 byte 4 bytes 978 Figure 18 UDP REQ and RES options format 980 5.12. Experimental (EXP) 982 The Experimental option (EXP) is reserved for experiments [RFC3692]. 983 It uses a Kind value of 254. Only one such value is reserved because 984 experiments are expected to use an Experimental ID (ExIDs) to 985 differentiate concurrent use for different purposes, using UDP ExIDs 986 registered with IANA according to the approach developed for TCP 987 experimental options [RFC6994]. 989 +----------+----------+----------+----------+ 990 | Kind=254 | Len | UDP ExID | 991 +----------+----------+----------+----------+ 992 | (option contents, as defined)... | 993 +----------+----------+----------+----------+ 995 Figure 19 UDP EXP option format 997 >> The length of the experimental option MUST be at least 4 to 998 account for the Kind, Length, and the minimum 16-bit UDP ExID 999 identifier (similar to TCP ExIDs [RFC6994]). 1001 The UDP EXP option also includes an extended length format, where 1002 the option LEN is 255 followed by two bytes of extended length. 1004 +----------+----------+----------+----------+ 1005 | Kind=254 | 255 | Extended Length | 1006 +----------+----------+----------+----------+ 1007 | UDP ExID. |(option contents...) | 1008 +----------+----------+----------+----------+ 1010 Figure 20 UDP EXP option format 1012 Assigned UDP EXP ExIDs and UDP UNSAFE UKind UEXP ExIDs are assigned 1013 from the same registry and can be used either in the EXP option or 1014 within the UKind UEXP (Section 5.8). 1016 6. Rules for designing new options 1018 The UDP option Kind space allows for the definition of new options, 1019 however the currently defined options do not allow for arbitrary new 1020 options. The following is a summary of rules for new options and 1021 their rationales: 1023 >> New options MUST NOT depend on or modify option space content. 1024 Only OCS, AUTH, and ENCR depend on the content of the options. 1026 >> UNSAFE options can both depend on and vary user data content 1027 because they are contained only inside UDP fragments and thus are 1028 processed only by UDP option capable receivers. 1030 >> New options MUST NOT declare their order relative to other 1031 options, whether new or old. 1033 >> At the sender, new options MUST NOT modify UDP packet content 1034 anywhere except within their option field, excepting only those 1035 contained within the UNSAFE option; areas that need to remain 1036 unmodified include the IP header, IP options, the UDP body, the UDP 1037 option area (i.e., other options), and the post-option area. 1039 >> Options MUST NOT be modified in transit. This includes those 1040 already defined as well as new options. New options MUST NOT require 1041 or intend optionally for modification of any UDP options, including 1042 their new areas, in transit. 1044 >> New options with fixed lengths smaller than 255 or variable 1045 lengths that are always smaller than 255 MUST use only the default 1046 option format. 1048 Note that only certain of the initially defined options violate 1049 these rules: 1051 o >> Only FRAG and UNSAFE options are permitted to modify the UDP 1052 body. 1054 The following recommendation helps ensure that only valid options 1055 are processed: 1057 o >> OCS SHOULD be the first option, when present. 1059 The following recommendation helps enable efficient zero-copy 1060 processing: 1062 o >> FRAG SHOULD be the first option after OCS, when present. 1064 7. Option inclusion and processing 1066 The following rules apply to option inclusion by senders and 1067 processing by receivers. 1069 >> Senders MAY add any option, as configured by the API. 1071 >> All mandatory options MUST be processed by receivers, if present 1072 (presuming UDP options are supported at that receiver). 1074 >> Non-mandatory options MAY be ignored by receivers, if present, 1075 e.g., based on API settings. 1077 >> All options MUST be processed by receivers in the order 1078 encountered in the options list. 1080 >> All options except UNSAFE options MUST result in the UDP payload 1081 being passed to the application layer, regardless of whether all 1082 options are processed, supported, or succeed. 1084 The basic premise is that, for options-aware endpoints, the sender 1085 decides what options to add and the receiver decides what options to 1086 handle. Simply adding an option does not force work upon a receiver, 1087 with the exception of the mandatory options. 1089 Upon receipt, the receiver checks various properties of the UDP 1090 packet and its options to decide whether to accept or drop the 1091 packet and whether to accept or ignore some its options as follows 1092 (in order): 1094 if the UDP checksum fails then 1095 silently drop (per RFC1122) 1096 if the UDP checksum passes then 1097 if OCS is present and fails then 1098 deliver the UDP payload but ignore all other options 1099 (this is required to emulate legacy behavior) 1100 if OCS is present and passes then 1101 deliver the UDP payload after parsing 1102 and processing the rest of the options, 1103 regardless of whether each is supported or succeeds 1104 (again, this is required to emulate legacy behavior) 1106 The design of the UNSAFE options as used only inside the FRAG area 1107 ensures that the resulting UDP data will be silently dropped in both 1108 legacy and options-aware receivers. 1110 Options-aware receivers can either drop packets with option 1111 processing errors via an override of the default or at the 1112 application layer. 1114 I.e., all options other than OCS are treated the same, in that the 1115 transmitter can add it as desired and the receiver has the option to 1116 require it or not. Only if it is required (e.g., by API 1117 configuration) should the receiver require it being present and 1118 correct. 1120 I.e., for all options other than OCS: 1122 o if the option is not required by the receiver, then packets 1123 missing the option are accepted. 1125 o if the option is required (e.g., by override of the default 1126 behavior at the receiver) and missing or incorrectly formed, 1127 silently drop the packet. 1129 o if the packet is accepted (either because the option is not 1130 required or because it was required and correct), then pass the 1131 option with the packet via the API. 1133 Any options whose length exceeds that of the UDP packet (i.e., 1134 intending to use data that would have been beyond the surplus area) 1135 should be silently ignored (again to model legacy behavior). 1137 8. UDP API Extensions 1139 UDP currently specifies an application programmer interface (API), 1140 summarized as follows (with Unix-style command as an example) 1141 [RFC768]: 1143 o Method to create new receive ports 1145 o E.g., bind(handle, recvaddr(optional), recvport) 1147 o Receive, which returns data octets, source port, and source 1148 address 1150 o E.g., recvfrom(handle, srcaddr, srcport, data) 1152 o Send, which specifies data, source and destination addresses, and 1153 source and destination ports 1155 o E.g., sendto(handle, destaddr, destport, data) 1157 This API is extended to support options as follows: 1159 o Extend the method to create receive ports to include receive 1160 options that are required. Datagrams not containing these 1161 required options MUST be silently dropped and MAY be logged. 1163 o Extend the receive function to indicate the options and their 1164 parameters as received with the corresponding received datagram. 1166 o Extend the send function to indicate the options to be added to 1167 the corresponding sent datagram. 1169 Examples of API instances for Linux and FreeBSD are provided in 1170 Appendix A, to encourage uniform cross-platform implementations. 1172 9. UDP Options are for Transport, Not Transit 1174 UDP options are indicated in an area of the IP payload that is not 1175 used by UDP. That area is really part of the IP payload, not the UDP 1176 payload, and as such, it might be tempting to consider whether this 1177 is a generally useful approach to extending IP. 1179 Unfortunately, the surplus area exists only for transports that 1180 include their own transport layer payload length indicator. TCP and 1181 SCTP include header length fields that already provide space for 1182 transport options by indicating the total length of the header area, 1183 such that the entire remaining area indicated in the network layer 1184 (IP) is transport payload. UDP-Lite already uses the UDP Length 1185 field to indicate the boundary between data covered by the transport 1186 checksum and data not covered, and so there is no remaining area 1187 where the length of the UDP-Lite payload as a whole can be indicated 1188 [RFC3828]. 1190 UDP options are intended for use only by the transport endpoints. 1191 They are no more (or less) appropriate to be modified in-transit 1192 than any other portion of the transport datagram. 1194 UDP options are transport options. Generally, transport datagrams 1195 are not intended to be modified in-transit. UDP options are no 1196 exception and here are specified as "MUST NOT" be altered in 1197 transit. However, the UDP option mechanism provides no specific 1198 protection against in-transit modification of the UDP header, UDP 1199 payload, or UDP option area, except as provided by the options 1200 selected (e.g., OCS or AE). 1202 10. UDP options vs. UDP-Lite 1204 UDP-Lite provides partial checksum coverage, so that packets with 1205 errors in some locations can be delivered to the user [RFC3828]. It 1206 uses a different transport protocol number (136) than UDP (17) to 1207 interpret the UDP Length field as the prefix covered by the UDP 1208 checksum. 1210 UDP (protocol 17) already defines the UDP Length field as the limit 1211 of the UDP checksum, but by default also limits the data provided to 1212 the application as that which precedes the UDP Length. A goal of 1213 UDP-Lite is to deliver data beyond UDP Length as a default, which is 1214 why a separate transport protocol number was required. 1216 UDP options do not use or need a separate transport protocol number 1217 because the data beyond the UDP Length offset (surplus data) is not 1218 provided to the application by default. That data is interpreted 1219 exclusively within the UDP transport layer. 1221 UDP-Lite cannot support UDP options, either as proposed here or in 1222 any other form, because the entire payload of the UDP packet is 1223 already defined as user data and there is no additional field in 1224 which to indicate a separate area for options. The UDP Length field 1225 in UDP-Lite is already used to indicate the boundary between user 1226 data covered by the checksum and user data not covered. 1228 11. Interactions with Legacy Devices 1230 It has always been permissible for the UDP Length to be inconsistent 1231 with the IP transport payload length [RFC768]. Such inconsistency 1232 has been utilized in UDP-Lite using a different transport number. 1233 There are no known systems that use this inconsistency for UDP 1234 [RFC3828]. It is possible that such use might interact with UDP 1235 options, i.e., where legacy systems might generate UDP datagrams 1236 that appear to have UDP options. The UDP OCS provides protection 1237 against such events and is stronger than a static "magic number". 1239 UDP options have been tested as interoperable with Linux, macOS, and 1240 Windows Cygwin, and worked through NAT devices. These systems 1241 successfully delivered only the user data indicated by the UDP 1242 Length field and silently discarded the surplus area. 1244 One reported embedded device passes the entire IP datagram to the 1245 UDP application layer. Although this feature could enable 1246 application-layer UDP option processing, it would require that 1247 conventional UDP user applications examine only the UDP payload. 1249 This feature is also inconsistent with the UDP application interface 1250 [RFC768] [RFC1122]. 1252 It has been reported that Alcatel-Lucent's "Brick" Intrusion 1253 Detection System has a default configuration that interprets 1254 inconsistencies between UDP Length and IP Length as an attack to be 1255 reported. Note that other firewall systems, e.g., CheckPoint, use a 1256 default "relaxed UDP length verification" to avoid falsely 1257 interpreting this inconsistency as an attack. 1259 12. Options in a Stateless, Unreliable Transport Protocol 1261 There are two ways to interpret options for a stateless, unreliable 1262 protocol -- an option is either local to the message or intended to 1263 affect a stream of messages in a soft-state manner. Either 1264 interpretation is valid for defined UDP options. 1266 It is impossible to know in advance whether an endpoint supports a 1267 UDP option. 1269 >> All UDP options other than UNSAFE ones MUST be ignored if not 1270 supported or upon failure (e.g., ACS). 1272 >> All UDP options that fail MUST result in the UDP data still being 1273 sent to the application layer by default, to ensure equivalence with 1274 legacy devices. 1276 >> UDP options that rely on soft-state exchange MUST allow for 1277 message reordering and loss. 1279 The above requirements prevent using any option that cannot be 1280 safely ignored unless it is hidden inside the FRAG area (i.e., 1281 UNSAFE options). Legacy systems also always need to be able to 1282 interpret the transport payload fragments as individual transport 1283 datagrams. 1285 13. UDP Option State Caching 1287 Some TCP connection parameters, stored in the TCP Control Block, can 1288 be usefully shared either among concurrent connections or between 1289 connections in sequence, known as TCP Sharing [RFC2140][To21cb]. 1290 Although UDP is stateless, some of the options proposed herein may 1291 have similar benefit in being shared or cached. We call this UCB 1292 Sharing, or UDP Control Block Sharing, by analogy. Just as TCB 1293 sharing is not a standard because it is consistent with existing TCP 1294 specifications, UCB sharing would be consistent with existing UDP 1295 specifications, including this one. Both are implementation issues 1296 that are outside the scope of their respective specifications, and 1297 so UCB sharing is outside the scope of this document. 1299 14. Updates to RFC 768 1301 This document updates RFC 768 as follows: 1303 o This document defines the meaning of the IP payload area beyond 1304 the UDP length but within the IP length. 1306 o This document extends the UDP API to support the use of options. 1308 15. Interactions with other RFCs (and drafts) 1310 This document clarifies the interaction between UDP length and IP 1311 length that is not explicitly constrained in either UDP or the host 1312 requirements [RFC768] [RFC1122]. 1314 Teredo extensions (TE) define use of a similar surplus area for 1315 trailers [RFC6081]. TE defines the UDP length pointing beyond 1316 (larger) than the location indicated by the IP length rather than 1317 shorter (as used herein): 1319 "..the IPv6 packet length (i.e., the Payload Length value in 1320 the IPv6 header plus the IPv6 header size) is less than or 1321 equal to the UDP payload length (i.e., the Length value in 1322 the UDP header minus the UDP header size)" 1324 As a result, UDP options are not compatible with TE, but that is 1325 also why this document does not update TE. Additionally, it is not 1326 at all clear how TE operates, as it requires network processing of 1327 the UDP length field to understand the total message including TE 1328 trailers. 1330 TE updates Teredo NAT traversal [RFC4380]. The NAT traversal 1331 document defined "consistency" of UDP length and IP length as: 1333 "An IPv6 packet is deemed valid if it conforms to [RFC2460]: 1334 the protocol identifier should indicate an IPv6 packet and 1335 the payload length should be consistent with the length of 1336 the UDP datagram in which the packet is encapsulated." 1338 IPv6 is clear on the meaning of this consistency, in which the 1339 pseudoheader used for UDP checksums is based on the UDP length, not 1340 inferred from the IP length, using the same text in the current 1341 specification [RFC8200]: 1343 "The Upper-Layer Packet Length in the pseudo-header is the 1344 length of the upper-layer header and data (e.g., TCP header 1345 plus TCP data). Some upper-layer protocols carry their own 1346 length information (e.g., the Length field in the UDP header); 1347 for such protocols, that is the length used in the pseudo- 1348 header." 1350 This document is consistent the UDP profile for Robust Header 1351 Compression (ROHC)[RFC3095], noted here: 1353 "The Length field of the UDP header MUST match the Length 1354 field(s) of the preceding subheaders, i.e., there must not 1355 be any padding after the UDP payload that is covered by the 1356 IP Length." 1358 ROHC compresses UDP headers only when this match succeeds. It does 1359 not prohibit UDP headers where the match fails; in those cases, ROHC 1360 default rules (Section 5.10) would cause the UDP header to remain 1361 uncompressed. Upon receipt of a compressed UDP header, Section A.1.3 1362 of that document indicates that the UDP length is "INFERRED"; in 1363 uncompressed packets, it would simply be explicitly provided. 1365 This issue of handling UDP header compression is more explicitly 1366 described in more recent specifications, e.g., Sec. 10.10 of Static 1367 Context Header Compression [RFC8724]. 1369 16. Multicast Considerations 1371 UDP options are primarily intended for unicast use. Using these 1372 options over multicast IP requires careful consideration, e.g., to 1373 ensure that the options used are safe for different endpoints to 1374 interpret differently (e.g., either to support or silently ignore) 1375 or to ensure that all receivers of a multicast group confirm support 1376 for the options in use. 1378 17. Security Considerations 1380 There are a number of security issues raised by the introduction of 1381 options to UDP. Some are specific to this variant, but others are 1382 associated with any packet processing mechanism; all are discussed 1383 in this section further. 1385 The use of UDP packets with inconsistent IP and UDP Length fields 1386 has the potential to trigger a buffer overflow error if not properly 1387 handled, e.g., if space is allocated based on the smaller field and 1388 copying is based on the larger. However, there have been no reports 1389 of such vulnerability and it would rely on inconsistent use of the 1390 two fields for memory allocation and copying. 1392 UDP options are not covered by DTLS (datagram transport-layer 1393 security). Despite the name, neither TLS [RFC8446] (transport layer 1394 security, for TCP) nor DTLS [RFC6347] (TLS for UDP) protect the 1395 transport layer. Both operate as a shim layer solely on the payload 1396 of transport packets, protecting only their contents. Just as TLS 1397 does not protect the TCP header or its options, DTLS does not 1398 protect the UDP header or the new options introduced by this 1399 document. Transport security is provided in TCP by the TCP 1400 Authentication Option (TCP-AO [RFC5925]) or in UDP by the 1401 Authentication (AUTH) option (Section 5.10) and UNSAFE Encryption 1402 (ENCR) option (5.8). Transport headers are also protected as payload 1403 when using IP security (IPsec) [RFC4301]. 1405 UDP options use the TLV syntax similar to that of TCP. This syntax 1406 is known to require serial processing and may pose a DOS risk, e.g., 1407 if an attacker adds large numbers of unknown options that must be 1408 parsed in their entirety. Implementations concerned with the 1409 potential for this vulnerability MAY implement only the required 1410 options and MAY also limit processing of TLVs, either in number of 1411 options or total length, or both. Because required options come 1412 first and at most once each (with the exception of NOPs, which 1413 should never need to come in sequences of more than seven in a row), 1414 this limits their DOS impact. Note that TLV formats for options does 1415 require serial processing, but any format that allows future 1416 options, whether ignored or not, could introduce a similar DOS 1417 vulnerability. 1419 UDP security should never rely solely on transport layer processing 1420 of options. UNSAFE options are the only type that share fate with 1421 the UDP data, because of the way that data is hidden in the surplus 1422 area until after those options are processed. All other options 1423 default to being silently ignored at the transport layer but may be 1424 dropped either if that default is overridden (e.g., by 1425 configuration) or discarded at the application layer (e.g., using 1426 information about the options processed that are passed along with 1427 the packet). 1429 UDP fragmentation introduces its own set of security concerns, which 1430 can be handled in a manner similar to IP fragmentation. In 1431 particular, the number of packets pending reassembly and effort used 1432 for reassembly is typically limited. In addition, it may be useful 1433 to assume a reasonable minimum fragment size, e.g., that non- 1434 terminal fragments should never be smaller than 500 bytes. 1436 18. IANA Considerations 1438 Upon publication, IANA is hereby requested to create a new registry 1439 for UDP Option Kind numbers, similar to that for TCP Option Kinds. 1440 Initial values of this registry are as listed in Section 5. 1441 Additional values in this registry are to be assigned from the 1442 UNASSIGNED values in Section 5 by IESG Approval or Standards Action 1443 [RFC8126]. Those assignments are subject to the conditions set forth 1444 in this document, particularly (but not limited to) those in Section 1445 6. 1447 Upon publication, IANA is hereby requested to create a new registry 1448 for UDP Experimental Option Experiment Identifiers (UDP ExIDs) for 1449 use in a similar manner as TCP ExIDs [RFC6994]. UDP ExIDs can be 1450 used in either the UDP EXP option or the UDP UNSAFE option when 1451 using UKind=UEXP. This registry is initially empty. Values in this 1452 registry are to be assigned by IANA using first-come, first-served 1453 (FCFS) rules [RFC8126]. Options using these ExIDs are subject to the 1454 same conditions as new options, i.e., they too are subject to the 1455 conditions set forth in this document, particularly (but not limited 1456 to) those in Section 6. 1458 Upon publication, IANA is hereby requested to create a new registry 1459 for UDP UNSAFE UKind numbers. There are no initial assignments in 1460 this registry. Values in this registry are to be assigned from the 1461 UNASSIGNED values in Section 5.8 by IESG Approval or Standards 1462 Action [RFC8126]. Those assignments are subject to the conditions 1463 set forth in this document, particularly (but not limited to) those 1464 in Section 6. 1466 19. References 1468 19.1. Normative References 1470 [RFC768] Postel, J., "User Datagram Protocol," RFC 768, August 1471 1980. 1473 [RFC791] Postel, J., "Internet Protocol," RFC 791, Sept. 1981. 1475 [RFC1122] Braden, R., Ed., "Requirements for Internet Hosts -- 1476 Communication Layers," RFC 1122, Oct. 1989. 1478 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1479 Requirement Levels," BCP 14, RFC 2119, March 1997. 1481 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1482 2119 Key Words," RFC 2119, May 2017. 1484 19.2. Informative References 1486 [Fa18] Fairhurst, G., T. Jones, R. Zullo, "Checksum Compensation 1487 Options for UDP Options", draft-fairhurst-udp-options-cco, 1488 Oct. 2018. 1490 [Fa21] Fairhurst, G., T. Jones, "Datagram PLPMTUD for UDP 1491 Options," draft-fairhurst-tsvwg-udp-options-dplpmtud, Apr. 1492 2021. 1494 [Hi15] Hildebrand, J., B. Trammel, "Substrate Protocol for User 1495 Datagrams (SPUD) Prototype," draft-hildebrand-spud- 1496 prototype-03, Mar. 2015. 1498 [RFC793] Postel, J., "Transmission Control Protocol" RFC 793, 1499 September 1981. 1501 [RFC1191] Mogul, J., S. Deering, "Path MTU discovery," RFC 1191, 1502 November 1990. 1504 [RFC2140] Touch, J., "TCP Control Block Interdependence," RFC 2140, 1505 Apr. 1997. 1507 [RFC2923] Lahey, K., "TCP Problems with Path MTU Discovery," RFC 1508 2923, September 2000. 1510 [RFC3095] Bormann, C. (Ed), et al., "RObust Header Compression 1511 (ROHC): Framework and four profiles: RTP, UDP, ESP, and 1512 uncompressed," RFC 3095, July 2001. 1514 [RFC3385] Sheinwald, D., J. Satran, P. Thaler, V. Cavanna, "Internet 1515 Protocol Small Computer System Interface (iSCSI) Cyclic 1516 Redundancy Check (CRC)/Checksum Considerations," RFC 3385, 1517 Sep. 2002. 1519 [RFC3692] Narten, T., "Assigning Experimental and Testing Numbers 1520 Considered Useful," RFC 3692, Jan. 2004. 1522 [RFC3828] Larzon, L-A., M. Degermark, S. Pink, L-E. Jonsson (Ed.), 1523 G. Fairhurst (Ed.), "The Lightweight User Datagram 1524 Protocol (UDP-Lite)," RFC 3828, July 2004. 1526 [RFC4301] Kent, S. and K. Seo, "Security Architecture for the 1527 Internet Protocol", RFC 4301, Dec. 2005. 1529 [RFC4340] Kohler, E., M. Handley, and S. Floyd, "Datagram Congestion 1530 Control Protocol (DCCP)", RFC 4340, March 2006. 1532 [RFC4380] Huitema, C., "Teredo: Tunneling IPv6 over UDP through 1533 Network Address Translations (NATs)," RFC 4380, Feb. 2006. 1535 [RFC4960] Stewart, R. (Ed.), "Stream Control Transmission Protocol", 1536 RFC 4960, September 2007. 1538 [RFC5925] Touch, J., A. Mankin, R. Bonica, "The TCP Authentication 1539 Option," RFC 5925, June 2010. 1541 [RFC6081] Thaler, D., "Teredo Extensions," RFC 6081, Jan 2011. 1543 [RFC6347] Rescorla, E., N. Modadugu, "Datagram Transport Layer 1544 Security Version 1.2," RFC 6347, Jan. 2012. 1546 [RFC6691] Borman, D., "TCP Options and Maximum Segment Size (MSS)," 1547 RFC 6691, July 2012. 1549 [RFC6935] Eubanks, M., P. Chimento, M. Westerlund, "IPv6 and UDP 1550 Checksums for Tunneled Packets," RFC 6935, April 2013. 1552 [RFC6978] Touch, J., "A TCP Authentication Option Extension for NAT 1553 Traversal", RFC 6978, July 2013. 1555 [RFC6994] Touch, J., "Shared Use of Experimental TCP Options," RFC 1556 6994, Aug. 2013. 1558 [RFC7323] Borman, D., R. Braden, V. Jacobson, R. Scheffenegger 1559 (Ed.), "TCP Extensions for High Performance," RFC 7323, 1560 Sep. 2014. 1562 [RFC8085] Eggert, L., G. Fairhurst, G. Shepherd, "UDP Usage 1563 Guidelines," RFC 8085, Feb. 2017. 1565 [RFC8126] Cotton, M., B. Leiba, T. Narten, "Guidelines for Writing 1566 an IANA Considerations Section in RFCs," RFC 8126, June 1567 2017. 1569 [RFC8200] Deering, S., R. Hinden, "Internet Protocol Version 6 1570 (IPv6) Specification," RFC 8200, Jul. 2017. 1572 [RFC8201] McCann, J., S. Deering, J. Mogul, R. Hinden (Ed.), "Path 1573 MTU Discovery for IP version 6," RFC 8201, Jul. 2017. 1575 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 1576 Version 1.3," RFC 8446, Aug. 2018. 1578 [RFC8724] Minaburo, A., L. Toutain, C. Gomez, D. Barthel, JC., 1579 "SCHC: Generic Framework for Static Context Header 1580 Compression and Fragmentation," RFC 8724, Apr. 2020. 1582 [RFC8899] Fairhurst, G., T. Jones, M. Tuxen, I. Rungeler, T. Volker, 1583 "Packetization Layer Path MTU Discovery for Datagram 1584 Transports," RFC 8899, Sep. 2020. 1586 [To18ao] Touch, J., "A TCP Authentication Option Extension for 1587 Payload Encryption," draft-touch-tcp-ao-encrypt, Jul. 1588 2018. 1590 [To21cb] Touch, J., M. Welzl, S. Islam, J. You, "TCP Control Block 1591 Interdependence," draft-touch-tcpm-2140bis, Apr. 2021. 1593 20. Acknowledgments 1595 This work benefitted from feedback from Bob Briscoe, Ken Calvert, 1596 Ted Faber, Gorry Fairhurst (including OCS for misbehaving middlebox 1597 traversal), C. M. Heard (including combining previous FRAG and LITE 1598 options into the new FRAG), Tom Herbert, Mark Smith, and Raffaele 1599 Zullo, as well as discussions on the IETF TSVWG and SPUD email 1600 lists. 1602 This work was partly supported by USC/ISI's Postel Center. 1604 This document was prepared using 2-Word-v2.0.template.dot. 1606 Authors' Addresses 1608 Joe Touch 1609 Manhattan Beach, CA 90266 USA 1611 Phone: +1 (310) 560-0334 1612 Email: touch@strayalpha.com 1614 Appendix A. Implementation Information 1616 The following information is provided to encourage interoperable API 1617 implementations. 1619 System-level variables (sysctl): 1621 Name default meaning 1622 ---------------------------------------------------- 1623 net.ipv4.udp_opt 0 UDP options available 1624 net.ipv4.udp_opt_ocs 1 Default include OCS 1625 net.ipv4.udp_opt_acs 0 Default include ACS 1626 net.ipv4.udp_opt_mss 0 Default include MSS 1627 net.ipv4.udp_opt_time 0 Default include TIME 1628 net.ipv4.udp_opt_frag 0 Default include FRAG 1629 net.ipv4.udp_opt_ae 0 Default include AE 1631 Socket options (sockopt), cached for outgoing datagrams: 1633 Name meaning 1634 ---------------------------------------------------- 1635 UDP_OPT Enable UDP options (at all) 1636 UDP_OPT_OCS Enable UDP OCS option 1637 UDP_OPT_ACS Enable UDP ACS option 1638 UDP_OPT_MSS Enable UDP MSS option 1639 UDP_OPT_TIME Enable UDP TIME option 1640 UDP_OPT_FRAG Enable UDP FRAG option 1641 UDP_OPT_AE Enable UDP AE option 1643 Send/sendto parameters: 1645 Connection parameters (per-socketpair cached state, part UCB): 1647 Name Initial value 1648 ---------------------------------------------------- 1649 opts_enabled net.ipv4.udp_opt 1650 ocs_enabled net.ipv4.udp_opt_ocs 1652 The following option is included for debugging purposes, and MUST 1653 NOT be enabled otherwise. 1655 System variables 1657 net.ipv4.udp_opt_junk 0 1658 System-level variables (sysctl): 1660 Name default meaning 1661 ---------------------------------------------------- 1662 net.ipv4.udp_opt_junk 0 Default use of junk 1664 Socket options (sockopt): 1666 Name params meaning 1667 ------------------------------------------------------ 1668 UDP_JUNK - Enable UDP junk option 1669 UDP_JUNK_VAL fillval Value to use as junk fill 1670 UDP_JUNK_LEN length Length of junk payload in bytes 1672 Connection parameters (per-socketpair cached state, part UCB): 1674 Name Initial value 1675 ---------------------------------------------------- 1676 junk_enabled net.ipv4.udp_opt_junk 1677 junk_value 0xABCD 1678 junk_len 4