idnits 2.17.1 draft-herbert-udp-space-hdr-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. 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 : ---------------------------------------------------------------------------- ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 131: '...d. Padding bytes MUST be set to zero o...' RFC 2119 keyword, line 132: '...ransmission, and MUST be verified to b...' RFC 2119 keyword, line 218: '... option in the [UDPOPT], MUST NOT be in a surplus space trailer....' RFC 2119 keyword, line 279: '... then a sender MUST NOT send packets...' RFC 2119 keyword, line 289: '... The sender MUST insert up to three ...' (16 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 8, 2019) is 1753 days in the past. Is this intentional? Checking references for intended status: Full Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'RFC768' is mentioned on line 399, but not defined == Missing Reference: 'RFC6936' is mentioned on line 487, but not defined == Outdated reference: A later version (-32) exists of draft-ietf-tsvwg-udp-options-07 Summary: 1 error (**), 0 flaws (~~), 4 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 INTERNET-DRAFT T. Herbert 3 Intended Status: Standard Intel 4 Expires: January 2020 6 July 8, 2019 8 UDP Surplus Header 9 draft-herbert-udp-space-hdr-01 11 Abstract 13 This specification defines the UDP Surplus Header that is an 14 extensible and generic format applied to the UDP surplus space. The 15 UDP surplus space comprises the bytes between the end of the UDP 16 datagram, as indicated by the UDP Length field, and the end of the IP 17 packet, as indicated by IP packet or payload length. The UDP Surplus 18 Header can be either a protocol trailer of the UDP datagram, or a 19 protocol header which effectively serves as an extended UDP header. 21 Status of this Memo 23 This Internet-Draft is submitted to IETF in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF), its areas, and its working groups. Note that 28 other groups may also distribute working documents as 29 Internet-Drafts. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 The list of current Internet-Drafts can be accessed at 37 http://www.ietf.org/1id-abstracts.html 39 The list of Internet-Draft Shadow Directories can be accessed at 40 http://www.ietf.org/shadow.html 42 Copyright and License Notice 44 Copyright (c) 2019 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents 49 (http://trustee.ietf.org/license-info) in effect on the date of 50 publication of this document. Please review these documents 51 carefully, as they describe your rights and restrictions with respect 52 to this document. Code Components extracted from this document must 53 include Simplified BSD License text as described in Section 4.e of 54 the Trust Legal Provisions and are provided without warranty as 55 described in the Simplified BSD License. 57 Table of Contents 59 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 60 2 UDP Surplus Header format . . . . . . . . . . . . . . . . . . . 3 61 2.1 Protocol trailer format . . . . . . . . . . . . . . . . . . 4 62 2.2 Protocol header format (Extended UDP header) . . . . . . . . 6 63 3 Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 64 3.1 Sender operation . . . . . . . . . . . . . . . . . . . . . . 7 65 3.2 Receiver operation . . . . . . . . . . . . . . . . . . . . . 8 66 3.2.1 Error handling . . . . . . . . . . . . . . . . . . . . . 9 67 4 Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . 9 68 5 Security Considerations . . . . . . . . . . . . . . . . . . . . 11 69 6 IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 11 70 7 References . . . . . . . . . . . . . . . . . . . . . . . . . . 11 71 7.1 Normative References . . . . . . . . . . . . . . . . . . . 11 72 7.2 Informative References . . . . . . . . . . . . . . . . . . 11 73 Appendix A: Checksum processing . . . . . . . . . . . . . . . . . 12 74 A.1 Transmit Checksum processing . . . . . . . . . . . . . . . . 12 75 A.1.1 TX checksum for USH trailer . . . . . . . . . . . . . . 12 76 A.1.2 TX checksum for USH header . . . . . . . . . . . . . . . 13 77 A.2 Receive Checksum handling . . . . . . . . . . . . . . . . . 13 78 A.2.1 Simultaneous verification . . . . . . . . . . . . . . . 13 79 A.2.2 RX checksum for USH trailer . . . . . . . . . . . . . . 14 80 A.2.3 RX checksum for USH header . . . . . . . . . . . . . . . 14 81 Appendix B: Protocol headers versus versus protocol trailers . . . 15 82 Appendix C: Protocol field alignment . . . . . . . . . . . . . . . 15 83 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 16 85 1 Introduction 87 As defined in [RFC768], the UDP header contains a UDP Length field. 88 The UDP Length is not required to correlate with the IP payload 89 length of a packet such that there may be bytes between the end of 90 the UDP datagram and the end of the IP packet. This space is referred 91 to as the UDP surplus space. 93 This specification defines the UDP Surplus Header (USH) to provide a 94 common format for the UDP surplus space. The USH is comprised of a 95 four byte base header and some variable amount of data. The base 96 header contains a type field that determines how the header data is 97 interpreted. This allows different formats and uses of the UDP 98 surplus space. UDP options [UDPOPT] are one example of a type where 99 the header data contains a list of options. 101 There are two use cases of USH: 103 1) Protocol trailer (section 2.1) 105 2) Protocol header or Extended UDP Header (section 2.2) 107 The motivations for USH, include the motivations for protocol header 108 format in USH, are described in section 4. 110 2 UDP Surplus Header format 112 The common format of the UDP Surplus Header (USH) is shown below: 114 0 1 2 3 115 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 116 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 117 | Padding (0 to 3 bytes) | 118 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 119 | Type | TSLength | Checksum | 120 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 121 | | 122 ~ Type Specific Data ~ 123 | | 124 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 126 The fields are: 128 o Padding: Aligns the UDP Surplus Header to four bytes. The number 129 of padding bytes required is: 3 - ((udp_length - 1) % 4), where 130 the udp_length is the length of the UDP datagram as specified in 131 the UDP Length field. Padding bytes MUST be set to zero on 132 transmission, and MUST be verified to be zero when received. 134 o Type: Indicates the format of the UDP surplus space and how the 135 Type Specific Data is interpreted. Defined Type values are: 137 o 0: Reserved 139 o 1: UDP options 141 o 2-127: Reserved 143 o 128-255: Available for private use or experimentation 145 o TSLength: Length of the type specific data in units of four byte 146 words. The length of the type specific data is thus zero to 1020 147 bytes. 149 o Checksum: The standard one's complement checksum that covers the 150 UDP surplus area. The coverage starts from the first byte of 151 Padding, or the Type field if no padding is present, through the 152 end of the IP packet. If the number of Padding bytes is odd then 153 a zero byte is logically prepended to surplus area for the 154 checksum calculation. 156 o Type Specific Data: Variable length data that is considered part 157 of the UDP Surplus Header. This data is interpreted per the 158 value of the Type field. 160 2.1 Protocol trailer format 162 When used as a protocol trailer, the UDP Surplus Header immediately 163 follows the UDP data. The logical protocol layering is: 165 +-+-+-+-+-+-+-+-+-+-+-+ 166 | UDP header | 167 +-+-+-+-+-+-+-+-+-+-+-+ 168 | UDP data | 169 / +-+-+-+-+-+-+-+-+-+-+-+ \ 170 Surplus | | USH base header | | 171 space | +-+-+-+-+-+-+-+-+-+-+-+ | USH 172 | | Type specific data | | 173 \ +-+-+-+-+-+-+-+-+-+-+-+ / 175 The packet format of UDP Surplus Header as a protocol trailer is: 177 0 1 2 3 178 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 179 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\ 180 | Source port | Destination port | | 181 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ UDP 182 | Length | Checksum | | 183 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+/ 184 | | 185 ~ UDP data ~ 186 | | 187 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 188 | | Padding | 189 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 190 | Type | TSLength | Checksum |\ 191 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 192 | | | 193 ~ Type Specific Data ~ USH 194 | | | 195 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ / 197 Notes: 199 - The offset of the UDP Surplus Header from the start of the UDP 200 header, including possible padding for the USH, is equal the UDP 201 Length. 203 - The number of padding bytes is 3 - ((udp_length - 1) % 4), where 204 udp_length is equal to the UDP Length field. The offset of the 205 Type field of the USH is 4 * ((udp_length - 1) / 4 + 1). 207 - If the size of the USH header (four plus four times TSLength) is 208 less than the size of the UDP surplus space in a packet, then 209 the USH is considered to be malformed (see section 3.2). 211 - The UDP checksum covers the UDP header and UDP data. The USH 212 checksum covers the entire UDP surplus space. 214 - A legacy receiver, one that does not understand the UDP Surplus 215 Header, will ignore the contents of the UDP surplus space and 216 process the UDP data as normal. Protocol data that cannot 217 correctly be ignored by a receiver, such as the fragmentation 218 option in the [UDPOPT], MUST NOT be in a surplus space trailer. 220 2.2 Protocol header format (Extended UDP header) 222 The UDP Surplus Header can be used as a protocol header. Effectively, 223 this creates an extended UDP header format. The logical protocol 224 layering is: 226 +-+-+-+-+-+-+-+-+-+-+-+ \ 227 | UDP header | | 228 / +-+-+-+-+-+-+-+-+-+-+-+ | Extended 229 | | UDP space header | | UDP header 230 Surplus | +-+-+-+-+-+-+-+-+-+-+-+ | 231 space | | Type specific data | | 232 | +-+-+-+-+-+-+-+-+-+-+-+ / 233 | | UDP data | 234 \ +-+-+-+-+-+-+-+-+-+-+-+ 236 The packet format containing an extended UDP header is: 238 0 1 2 3 239 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 240 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\ 241 | Source port | Destination port | | 242 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ UDP 243 | Length | Checksum | | 244 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+/ 245 | Type | TSLength | Checksum |\ 246 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 247 | | | 248 ~ Type Specific Data ~ USH 249 | | | 250 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ / 251 | | 252 ~ UDP data ~ 253 | | 254 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 256 Notes: 258 - Since the UDP header is aligned and a multiple of four bytes, no 259 padding for USH is necessary. 261 - The UDP length is fixed to be eight so that all bytes beyond the 262 UDP header are contained in the surplus space. 264 - The UDP checksum covers the eight bytes of UDP header and the 265 checksum pseudo header. The USH checksum covers the entire 266 surplus space which includes the UDP Surplus Header and UDP 267 data. 269 - The UDP data length is the IP payload length minus the size of 270 the UDP header and the size of the UDP Surplus Header. That is: 272 UDP_data_length = IP_payload_length - 12 - (4 * TSLength) 274 - If a legacy receiver, one that does not understand the UDP 275 Surplus Header, receives a packet in protocol header format it 276 will process it as a UDP datagram containing zero length data. 277 Presumably, most applications will ignore such packets, however 278 if an application applies semantics to zero length datagrams 279 then a sender MUST NOT send packets with an extended UDP header 280 to legacy receivers. 282 3 Operation 284 3.1 Sender operation 286 A sender sets a UDP Surplus Header in the surplus space when sending 287 an IP packet. The UDP surplus header immediately follows the UDP 288 packet at the offset of UDP Length from the start of the UDP header. 289 The sender MUST insert up to three bytes of padding to align the 290 offset of the Type field in the UDP Surplus Header to four bytes. 291 Padding bytes MUST be set to zero. 293 If the USH is being used as a protocol trailer then the UDP Surplus 294 Header follows the UDP data. If a protocol header is being set then 295 the UDP Surplus Header follows the eight byte UDP header and the UDP 296 data follows the UDP Surplus Header. 298 The IP Length field in the IPv4 header or Total Length field in the 299 IPv6 header MUST be set to include the UDP datagram and the UDP 300 surplus space. The UDP Length field MUST be set to size of the UDP 301 header (eight) plus the size of the UDP data in the protocol trailer 302 use case, and MUST be set to the size of the UDP header (eight) in 303 the protocol header use case. 305 The TSLength field MUST be set to reflect the length of the Type 306 Specific Data. The Type Specific Data MUST be padded if necessary to 307 align its length to four bytes. 309 The USH Checksum MUST be set. To compute the checksum: 311 1) Set the Checksum field to zero. Compute the standard one's 312 complement two byte checksum starting from the Type field 313 through the end of the IP packet (end of the surplus space). If 314 the length of the surplus space is odd then a zero byte is 315 logically appended for the purposes of the calculation. 317 2) Set the value of the Checksum field to the bitwise "not" of the 318 checksum computed in the previous step. 320 3.2 Receiver operation 322 The processing for a UDP packet with surplus space is: 324 1) Check for minimum length to contain a UDP Surplus Header. If 325 the UDP surplus space length is less than 3 - ((udp_length - 1) 326 % 4) + 4, then the UDP Surplus Header is considered invalid. 328 2) Check padding bytes. If the UDP Length is not a multiple of 329 four bytes then verify that the padding bytes following the UDP 330 payload are set to zero. The required number of padding bytes 331 is 3 - ((udp_length - 1) % 4). If the padding bytes are not 332 zero, the UDP Surplus Header is considered invalid. 334 3) Check the TSLength field. If the length determined from the 335 TSLength field plus the starting offset of the Type Specific 336 Data exceeds the length of the IP packet then the UDP Surplus 337 Header is considered invalid. 339 4) Verify the checksum. Compute the one's complement checksum 340 starting from the Type field through the end of the IP packet 341 (the end of the surplus area). If the result of the computation 342 is checksum zero (~0 or -0) then the checksum is verified. If 343 the checksum is not verified then the UDP Surplus Header is 344 considered invalid. 346 5) Check the Type. If the Type is unknown to the receiver then the 347 surplus header is considered invalid. 349 6) Process the Type Specific Data per the Type in the UDP Surplus 350 Header. If an error condition is encountered in the course of 351 processing the Type Specific Data then the receiver SHOULD 352 consider that the UDP Surplus Header is invalid. 354 7) In the protocol trailer use case, if there are additional bytes 355 beyond the UDP Surplus Header, a receiver SHOULD ignore those 356 bytes (with the exception that the excess bytes MUST be 357 included in the USH Checksum computation). 359 8) If the UDP Surplus Header is validated and processed, deliver 360 the UDP data to the application. 362 In the case of a protocol trailer, the surplus area is 363 discarded and the UDP data, which follows the UDP header and 364 has length of UDP Length minus eight, is delivered to the 365 application. 367 In the case of protocol header, the UDP data delivered to the 368 application immediately follows the UDP Surplus Header and has 369 length of IP_payload_length - 12 - (4 * TSLength). 371 3.2.1 Error handling 373 If an error is encountered when processing the UDP space or UDP 374 Surplus Header such that the UDP Surplus Header is considered 375 invalid, then the following actions should be taken: 377 - In the protocol trailer case (UDP Length greater than eight), 378 the UDP surplus area SHOULD be ignored per protocol processing 379 convention. An implementation MAY allow configuration that would 380 discard such packets. An implementation MUST either process the 381 surplus space or ignore the whole space. In particular, the UDP 382 Surplus Header MUST NOT be partially processed lest that leads 383 to indeterminate results of processing an accepted packet. 385 - In the case of a protocol header (a UDP packet having exactly a 386 length of eight), the receiver SHOULD discard packets with 387 malformed UDP surplus space or UDP Surplus Header. A receiver 388 MAY deliver the packet to the application in the unlikely 389 scenario that the application applies semantics to zero length 390 UDP datagrams and there is the possibility that the surplus 391 space is a legacy use case (i.e. the sender set surplus space 392 but doesn't use the UDP Surplus Header format). 394 4 Motivation 396 This section describes the motivations for the UDP Surplus Header and 397 motivation for protocol headers. 399 o While the UDP surplus area was implicitly created by [RFC768], 400 the space was never specifically reserved by IETF action. 401 Prescribing a format enables interoperable and backwards 402 compatible use of this space within the context of defined 403 protocol specifications. 405 o A common header allows different uses and extensibility of the 406 UDP surplus space within a common framework. This is achieved by 407 inclusion of a Type field and Type Specific Data in the UDP 408 Surplus Header. For instance, legacy uses of surplus space could 409 be adapted to use the format and brought into conformance. 411 o Since the UDP surplus space was never reserved, there is a 412 possibility that the UDP surplus space is already being used by 413 some implementations. Disambiguating these "legacy" use cases 414 from a newly defined standard format is essential. The required 415 Checksum field, and to a lesser extent the Type and TSLength 416 fields, help disambiguate uses of the surplus area from legacy 417 or accidental uses of the surplus area. Use of the extended UDP 418 header format also reduces the chances of misinterpreting legacy 419 uses. 421 o The USH checksum is checksum offload friendly. See appendix A 422 for discussion on checksum offload and USH. 424 o The required checksum in the UDP Surplus Header properly 425 compensates for those devices that incorrectly compute UDP 426 checksum over the length of the IP payload as opposed to just 427 the UDP length. 429 o A fixed checksum, as opposed to placing a checksum in options, 430 avoids the problem that a checksum can't protect against 431 corruption of the type field for the option containing the 432 checksum. 434 o Protocols headers, such as those used in the Extended UDP Header 435 format, are more implementation friendly than protocol trailers. 436 See Appendix B for more discussion. 438 o Maintaining four byte alignment, as is common in IP protocols, 439 is beneficial to implementations on several hardware 440 architectures. See Appendix C for more discussion. 442 5 Security Considerations 444 The UDP Surplus Header does not address nor introduce any new 445 security considerations. The Type Specific Data in a UDP Surplus 446 Header may contain security protocol mechanisms or require 447 additional security considerations. Security considerations for 448 Type Specific Data is out of scope for this document. 450 6 IANA Considerations 452 IANA is requested to create a registry for the UDP Surplus 453 Header Types. 455 7 References 457 7.1 Normative References 459 7.2 Informative References 461 [UDPOPT] Touch, J., "Transport Options for UDP", draft-ietf-tsvwg- 462 udp-options-07 464 Appendix A: Checksum processing 466 This appendix is informational and does not constitute a normative 467 part of this document. 469 Checksum offload is a ubiquitous feature of Network Interface Cards 470 (NICs) that offloads checksum computation to hardware for 471 performance. This section suggests some implementation techniques to 472 best leverage checksum offload when UDP surplus space is being used. 474 Note that the USH checksum ensures that the checksum computed over 475 the UDP surplus space sums to zero in one's complement arithmetic. 476 This has the intended consequence that the UDP checksum calculation 477 over just the UDP length results in the same value when the UDP 478 checksum is computed over the UDP length and surplus space as well. 479 This property can be exploited for efficient and interoperable 480 processing. 482 A.1 Transmit Checksum processing 484 A UDP packet with a UDP Surplus Header has two checksum that may need 485 to be set on transmission: the UDP checksum and the USH checksum. The 486 UDP checksum is optional for IPv4 and is required for IPv6 except in 487 very narrow circumstances described in [RFC6936]. The USH checksum is 488 always required to be set. 490 Most devices only offload one checksum on transmit, so a design 491 objective is to offload the checksum that covers the most bytes and 492 hence provides the most benefit to offload. The checksum that is not 493 offloaded is computed by the host CPU. Generally, the checksum that 494 covers the UDP data is the one covers the most data and should be 495 offloaded. That is, when USH is a protocol trailer the UDP checksum 496 should be offloaded, and when the USH is a protocol header (i.e. 497 extended UDP header) the USH checksum should be offloaded. 499 In generic checksum offload, for each packet the host indicates to 500 the device the starting offset where the checksum calculation begins 501 and the offset of the field to write the resultant checksum. The 502 extent of the checksum coverage is assumed to be the end of the 503 packet. In particular, this means that even if the UDP checksum is 504 being offloaded, the UDP surplus space is included in the device's 505 computation. Ensuring that the surplus space sums to zero in one's 506 complement arithmetic avoids any ambiguity with checksum offload. 508 A.1.1 TX checksum for USH trailer 510 The recommended procedure for setting checksums when the UDP Surplus 511 Header is a trailer is: 513 1) On the host set the USH checksum using the normal procedures 514 for setting the checksum (section 3.1). 516 2) Arrange for the UDP checksum to be offloaded to the device. 517 This is done by indicating the checksum start offset to be the 518 first byte of UDP header, indicating the checksum field offset 519 to be the offset of the UDP checksum field, and initializing 520 the UDP checksum field to the "bitwise not" of the appropriate 521 IP pseudo header. 523 Step 1) ensures that the surplus area sums to zero in one's 524 complement arithmetic, so that in step 2) the value that the device 525 sets in the UDP checksum field will be correct regardless of whether 526 the device includes the surplus area in its computation or not. 528 Note that the USH padding must be set to zero so it does not affect 529 the checksum computed in step 1). The USH checksum on transmission 530 can be correctly computed by starting the checksum computation from 531 the offset of USH Type field. 533 A.1.2 TX checksum for USH header 535 The recommended procedure for setting checksums when the UDP Surplus 536 Header is a header is: 538 1) Set the UDP checksum on the host. This is normal procedures to 539 set the UDP checksum for a UDP datagram with length of eight. 541 2) Arrange to offload the USH checksum. The USH checksum field is 542 initialized to zero, the offset to start the checksum 543 calculation is set to the offset of the Type field in the USH, 544 and the checksum field offset is set to the offset of the USH 545 checksum field. 547 A.2 Receive Checksum handling 549 In the most generic form of receive checksum offload, a device 550 performs a running checksum calculation across a packet as it is 551 received. That is, it performs a running ones complement addition 552 over two byte words as they are received. The device then provides 553 the computed value, referred to as the "checksum complete" value, to 554 the host in the meta data (receive descriptor) for the packet. The 555 host can use this value to verify one or more packet checksums 556 contained in the packet. 558 A.2.1 Simultaneous verification 560 If a device provides a checksum complete value and the UDP checksum 561 is set, then both the UDP checksum and USH checksum can be 562 simultaneously verified: 564 1) Pull up checksum to start of the UDP header. That is the 565 checksum complete value is computed from the start of the UDP 566 header through the end of the IP packet. 568 2) Verify the UDP checksum taking into account the pseudo header. 569 If the UDP checksum is verified, then the USH checksum is also 570 verified. 572 If the simultaneous verification fails then further work might be 573 needed if checksum failure of the surplus space does not result in 574 the packet being dropped. For instance, if the surplus space is to be 575 ignored in the trailer use case. 577 A.2.2 RX checksum for USH trailer 579 The recommended procedure for independently verifying the UDP and USH 580 checksums when the UDP Surplus Header is a protocol trailer is: 582 1) Compute the one's complement checksum across the UDP surplus 583 space. If checksum zero is the result, then the USH checksum is 584 verified. 586 2) Perform one's complement subtraction of the value derived in 587 step 1) from the checksum complete value. The result is the 588 checksum complete value across just the UDP header and UDP 589 data. 591 3) Compute the IP pseudo header for the UDP checksum and one's 592 complement add the result to that of step 2). If the result is 593 checksum zero then the UDP checksum is verified. 595 If the UDP checksum is zero (unset) then only the USH checksum needs 596 to be verified so steps 2) and 3) can be omitted. 598 A.2.3 RX checksum for USH header 600 The recommended procedure for independently verifying the UDP and USH 601 checksums when the UDP Surplus Header is a protocol header is: 603 1) Compute the one's complement checksum across the UDP header. 605 2) Compute the IP pseudo header for the UDP checksum and one's 606 complement add the result to that of step 1). If the result is 607 checksum zero then the checksum of the UDP header (zero length 608 datagram) is verified. 610 3) Perform one's complement subtraction of the value derived in 611 step 1) from the checksum complete value. The result is the 612 checksum complete value across just the UDP surplus space. If 613 zero is the result, then the USH checksum is valid. 615 If the UDP checksum is zero (unset) then only the USH checksum needs 616 to be verified, so step 2) can be omitted. 618 Appendix B: Protocol headers versus versus protocol trailers 620 This appendix is informational and does not constitute a normative 621 part of this document. 623 Protocol headers by definition are data at the precede the payload of 624 a packet, whereas protocol trailers follow the payload. By nearly 625 universal convention, IP protocols specify protocol headers (e.g. IP, 626 TCP, UDP, Extension headers) and not protocol trailers. A notable 627 exception to this is ESP where the integrity check value is placed 628 after the payload data. 630 Both software and hardware implementations are designed and optimized 631 for processing protocol headers. 633 A common technique in software implementations is to "pull up" all 634 the headers in a packet into a contiguous buffer as various protocol 635 layers are processed. To process a protocol trailer, such as a UDP 636 Surplus Header in the trailer use case, an alternate mechanism is 637 needed. This may result in copying data from the end of the packet 638 into a contiguous buffer. Another disadvantage of protocol trailers 639 is that when they are processed a cache miss is almost certain. This 640 will be especially noticeable with hardware techniques that attempt 641 to pre-populate the CPU data cache with some number of header bytes 642 (such as data Direct Data I/O). 644 High performance hardware devices that perform Deep Packet Inspection 645 (DPI) will be even more sensitive to protocol trailers. Often such 646 devices have a fixed length parsing buffer of X bytes (where X is 647 commonly 64, 128, or 256 bytes). When a device receives a packet, the 648 first X bytes of the packet are preloaded into the parsing buffer 649 before processing commences. Protocol processing is performed on the 650 bytes in the parsing buffer. If the protocol headers extend beyond 651 the parsing buffer then either the device won't process the headers 652 (which may mean they drop the packet) or the packet is relegated to a 653 slow path. Neither behavior is desirable. Given that protocol 654 trailers follow packet payload, it will be common that the protocol 655 trailers for a packet are not contained with parsing buffer. 657 Appendix C: Protocol field alignment 658 This appendix is informational and does not constitute a normative 659 part of this document. 661 It is often convenient to access multi-byte protocol fields in a 662 protocol header in memory using CPU instructions to access a field as 663 a word (two bytes) or double word (four bytes). When such accesses 664 are done, the data being accessed can be "aligned" or "unaligned". An 665 aligned data access happens when the address of the operation modulo 666 the size of the operand is zero, and conversely an unaligned access 667 occurs when the when the address of the operation modulo the size of 668 the operand is non-zero. On certain CPU architectures including 669 SPARC, older versions of ARM, some cases of RISC-V, and even a corner 670 case in x86, an unaligned access may incur a substantial performance 671 penalty compared to an aligned access. For instance, an unaligned 672 access may result in a software trap and handling the memory access 673 in software. 675 By convention, most IETF protocols are structured to ensure that 676 multi-byte fields have an offset within the respective protocol 677 header that is properly aligned per their field size. Additionally, 678 most IP protocols are defined to have length that is a multiple of 679 four bytes. These conventions, along with some implementation 680 techniques, have mostly allowed software implementations to be 681 reusable across different architectures without the sustaining 682 performance hit of unaligned accesses. 684 The Padding field in UDP Surplus Header is important to maintain the 685 benefits of aligned protocol headers. 687 Author's Address 689 Tom Herbert 690 Intel 691 Santa Clara, CA 692 USA 694 Email: tom@quantonium.net