idnits 2.17.1 draft-ietf-taps-transports-usage-udp-03.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 : ---------------------------------------------------------------------------- == There are 4 instances of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (May 24, 2017) is 2528 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Outdated reference: A later version (-08) exists of draft-ietf-6man-rfc1981bis-06 == Outdated reference: A later version (-09) exists of draft-ietf-taps-transports-usage-04 ** Obsolete normative reference: RFC 2460 (Obsoleted by RFC 8200) ** Obsolete normative reference: RFC 2553 (Obsoleted by RFC 3493) -- Obsolete informational reference (is this intentional?): RFC 4566 (Obsoleted by RFC 8866) Summary: 2 errors (**), 0 flaws (~~), 5 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Engineering Task Force G. Fairhurst 3 Internet-Draft T. Jones 4 Intended status: Informational University of Aberdeen 5 Expires: November 23, 2017 May 24, 2017 7 Features of the User Datagram Protocol (UDP) and Lightweight UDP (UDP- 8 Lite) Transport Protocols 9 draft-ietf-taps-transports-usage-udp-03 11 Abstract 13 This is an informational document that describes the transport 14 protocol interface primitives provided by the User Datagram Protocol 15 (UDP) and the Lightweight User Datagram Protocol (UDP-Lite) transport 16 protocols. It identifies the datagram services exposed to 17 applications and how an application can configure and use the 18 features offered by the Internet datagram transport service. The 19 resulting road map to documentation may be of help to users of the 20 UDP and UDP-Lite protocols. 22 Status of this Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at http://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on November 23, 2017. 39 Copyright Notice 41 Copyright (c) 2017 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents (http://trustee.ietf.org/ 46 license-info) in effect on the date of publication of this document. 47 Please review these documents carefully, as they describe your rights 48 and restrictions with respect to this document. Code Components 49 extracted from this document must include Simplified BSD License text 50 as described in Section 4.e of the Trust Legal Provisions and are 51 provided without warranty as described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2 56 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 57 3. UDP and UDP-Lite Primitives . . . . . . . . . . . . . . . . . 3 58 3.1. Primitives Provided by UDP . . . . . . . . . . . . . . . . 3 59 3.1.1. Excluded Primitives . . . . . . . . . . . . . . . . . 10 60 3.2. Primitives Provided by UDP-Lite . . . . . . . . . . . . . 10 61 4. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 11 62 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 63 6. Security Considerations . . . . . . . . . . . . . . . . . . . 11 64 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 11 65 7.1. Normative References . . . . . . . . . . . . . . . . . . . 11 66 7.2. Informative References . . . . . . . . . . . . . . . . . . 13 67 Appendix A. Multicast Primitives . . . . . . . . . . . . . . . . . 14 68 Appendix B. Revision Notes . . . . . . . . . . . . . . . . . . . . 17 69 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 19 71 1. Introduction 73 This document presents defined interactions between transport 74 protocols and applications in the form of 'primitives' (function 75 calls) for the User Datagram Protocol (UDP) [RFC0768] and the 76 Lightweight User Datagram Protocol (UDP-Lite) [RFC3828]. In this 77 usage, the word application refers to any program built on the 78 datagram interface, and including tunnels and other upper layer 79 protocols that use UDP and UDP-LIte. 81 The de facto standard application programming interface (API) for TCP 82 /IP applications is the "socket" interface [POSIX]. An application 83 can use the recv() and send() POSIX functions as well as the 84 recvfrom() and sendto() and recvmsg() and sendmsg() functions. The 85 UDP and UDP-Lite sockets API differs from that for TCP in several key 86 ways. (Examples of usage of this API are provided in [STEVENS].) 88 Additional functions in the sockets API are provided by socket 89 options, examples include: 91 o SO_REUSEADDR specifies the rules for validating addresses supplied 92 to bind() should allow reuse of local addresses 94 o SO_REUSEPORT specifies that the rules for validating ports 95 supplied to bind() should allow reuse of a local port 97 o IP_RECVTTL returns the IP Time To Live (TTL) field from IP header 98 of a received datagram. 100 Some platforms also offer applications the ability to directly 101 assemble and transmit IP packets through "raw sockets" or similar 102 facilities. The raw socket API is a second, more cumbersome method 103 of using UDP. The use of this API is discussed in the RFC series in 104 the UDP Guidelines [RFC8085]. 106 The list of transport service features and primitives in this 107 document is strictly based on the parts of protocol specifications in 108 RFC-series that relate to what the transport protocol provides to an 109 application that uses it and how the application interacts with the 110 transport protocol. Primitives can be invoked by an application or a 111 transport protocol; the latter type is called an "event". 113 The description in the next section follows the methodology defined 114 by the IETF TAPS working group [I-D.ietf-taps-transports-usage]. 115 Specifically, it provides the first pass of this process, which 116 discusses the relevant RFC text describing primitives for each 117 protocol. 119 The presented road map to documentation of the transport interface 120 may also help developers working with UDP and UDP-Lite. 122 2. Terminology 124 This document is intended as a contribution to the Transport Services 125 (TAPS) working group to assist in analysis of the UDP and UDP-Lite 126 transport interface. It uses common terminology defined in "Usage of 127 Transport Features Provided by IETF Transport Protocols" [I-D.ietf- 128 taps-transports-usage]. This document also refers to the terminology 129 of RFC 2119 [RFC2119], but does not itself define new terms using 130 this terminology. 132 3. UDP and UDP-Lite Primitives 134 This section summarizes the relevant text parts of the RFCs 135 describing the UDP and UDP-Lite protocols, focusing on what the 136 transport protocols provide to the application (in and how the 137 transport is used (based on abstract API descriptions, where they are 138 available). 140 This section describes unicast usage, but UDP and UDP-Lite also 141 support IPv4 broadcast and IPv4/IPv6 multicast [RFC8085]. Many 142 primitives also apply when the transports are used with IP broadcast 143 and multicast. Appendix describes where to find documentation for 144 network-layer primitives required to use UDP 145 or UDP-Lite with IP multicast. 147 3.1. Primitives Provided by UDP 148 The User Datagram Protocol (UDP) [RFC0768] States: "This User 149 Datagram Protocol (UDP) is defined to make available a datagram mode 150 of packet-switched computer communication in the environment of an 151 interconnected set of computer networks." It "provides a procedure 152 for application programs to send messages to other programs with a 153 minimum of protocol mechanism (..)". 155 The User Interface section of RFC768 states that the user interface 156 to an application should be able to create receive, source and 157 destination ports and addresses, and provide operations to receive 158 data based on ports with an indication of source port and address. 159 Operations should be provided that allows datagrams be sent 160 specifying the source and destination ports and addresses to be sent. 162 UDP has been defined for IPv6 [RFC2460], together with API extensions 163 for a Basic Socket Interface Extensions for IPv6 [RFC3493]. 164 [RFC6935] and [RFC6936] defines an update to the UDP transport 165 specified in RFC 2460. This enables use of a zero UDP checksum mode 166 with a tunnel protocol, providing that the method satisfies the 167 requirements in the corresponding applicability statement [RFC6936]. 169 UDP offers only a basic transport interface. UDP datagrams may be 170 directly sent and received, without exchanging messages between the 171 endpoints to setup a connection (i.e., no handshake is performed by 172 the transport protocol prior to communication). Using the sockets 173 API, applications can receive packets from more than one IP source 174 address on a single UDP socket. Common support allows specification 175 of the local IP address, destination IP address, local port and 176 destination port values. Any or all of these can be indicated, with 177 defaults supplied by the local system when these are not specified. 178 The local endpoint is set using the BIND call and set on the remote 179 endpoint using the CONNECT call. The CLOSE function has local 180 significance only. It does not impact the status of the remote 181 endpoint. 183 Neither UDP nor UDP-Lite provide congestion control, retransmission, 184 nor do they have support to optimise fragmentation and other 185 transport functions. This means that applications using UDP need to 186 provide additional functions on top of the UDP transport API 187 [RFC8085]. Some transport functions require parameters to be passed 188 through the API to control the network layer (IPv4 or IPv6). These 189 additional primitives could be considered a part of the network layer 190 (e.g., control of the setting of the Don't Fragment (DF) flag on a 191 transmitted IPv4 datagram), but are nonetheless essential to allow a 192 user of the UDP API to implement functions that are normally 193 associated with the transport layer (such as probing for the path 194 maximum transmission size). This document includes such primitives. 196 Guidance on the use of the services provided by UDP is provided in 197 the UDP Guidelines [RFC8085]. This also states "many operating 198 systems also allow a UDP socket to be connected, i.e., to bind a UDP 199 socket to a specific pair of addresses and ports. This is similar to 200 the corresponding TCP sockets API functionality. However, for UDP, 201 this is only a local operation that serves to simplify the local send 202 /receive functions and to filter the traffic for the specified 203 addresses and ports. Binding a UDP socket does not establish a 204 connection - UDP does not notify the remote endpoint when a local UDP 205 socket is bound. Binding a socket also allows configuring options 206 that affect the UDP or IP layers, for example, use of the UDP 207 checksum or the IP Timestamp Option. On some stacks, a bound socket 208 also allows an application to be notified when Internet Control 209 Message (ICMP) error messages are received for its transmissions 210 [RFC1122]." 212 The POSIX Base Specifications [POSIX] define an API that offers 213 mechanisms for an application to receive asynchronous data events at 214 the socket layer. Calls such as "poll", "select" or "queue" allow an 215 application to be notified when data has arrived at a socket or when 216 a socket has flushed its buffers. 218 A callback-driven API to the network interface can be structured on 219 top of these calls. Implicit connection setup allows an application 220 to delegate connection life management to the transport API. The 221 transport API uses protocol primitives to offer the automated service 222 to the application via the sockets API. By combining UDP primitives 223 (CONNECT.UDP, SEND.UDP), a higher level API could offer a similar 224 service. 226 The following datagram primitives are specified: 228 CONNECT: The CONNECT primitive allows the association of source and 229 destination port sets to a socket to enable creation of a 230 'connection' for UDP traffic. This UDP connection allows an 231 application to be notified of errors received from the network 232 stack and provides a shorthand access to the send and receive 233 primitives. Since UDP is itself connectionless, no datagrams are 234 sent because this primitive is executed. A further connect call 235 can be used to change the association. 237 Two forms of usage may be identified for the CONNECT primitive: 239 1. bind(): A bind operation sets the local port, either 240 implicitly, triggered by a "sendto" operation on an unbound, 241 unconnected socket using an ephemeral port. Or by an explicit 242 "bind" to use a configured or well-known port. 244 2. bind(); connect(): A bind operation that is followed by a 245 CONNECT primitive. The bind operation establishes the use of 246 a known local port for datagrams, rather than using an 247 ephemeral port. The connect operation specifies a known 248 address port combination to be used by default for future 249 datagrams. This form is used either after receiving a 250 datagram from an endpoint that causes the creation of a 251 connection, or can be triggered by third party configuration 252 or a protocol trigger (such as reception of a UDP Service 253 Description Protocol, SDP [RFC4566], record). 255 LISTEN: The roles of a client and a server are often not appropriate 256 for UDP, where connections can be peer-to-peer. The listening 257 functions are performed using one of the forms of the CONNECT 258 primitive described above. 260 SEND: The SEND primitive hands over a provided number of bytes that 261 UDP should send to the other side of a UDP connection in a UDP 262 datagram. The primitive can be used by an application to directly 263 send datagrams to an endpoint defined by an address/port pair. If 264 a connection has been created, then the address/port pair is 265 inferred from the current connection for the socket. Connecting a 266 socket allows network errors to be returned to the application as 267 a notification on the send primitive. Messages passed to the send 268 primitive that cannot be sent atomically in a datagram will not be 269 sent by the network layer, generating an error. 271 RECEIVE: The RECEIVE primitive allocates a receiving buffer to 272 accommodate a received datagram. The primitive returns the number 273 of bytes provided from a received UDP datagram. Section 4.1.3.5 274 of the requirements of Internet hosts [RFC1122] states "When a UDP 275 datagram is received, its specific-destination address MUST be 276 passed up to the application layer." 278 CHECKSUM_ENABLED: The optional CHECKSUM primitive controls whether a 279 sender enables the UDP checksum when sending datagrams ( [RFC0768] 280 and [RFC6935] [RFC6936] [RFC8085]). When unset, this overrides the 281 default UDP behaviour, disabling the checksum on sending. Section 282 4.1.3.4 of the requirements for Internet hosts [RFC1122] states 283 "An application MAY optionally be able to control whether a UDP 284 checksum will be generated, but it MUST default to checksumming 285 on." 287 REQUIRE_CHECKSUM: The optional REQUIRE_CHECKSUM primitive determines 288 whether UDP datagrams received with a zero checksum are permitted 289 or discarded, UDP defaults to requiring checksums. Section 290 4.1.3.4 of the requirements for Internet hosts [RFC1122] states 291 "An application MAY optionally be able to control whether UDP 292 datagrams without checksums should be discarded or passed to the 293 application." Section 3.1 of the specification for UDP-Lite 294 [RFC3828] requires that the checksum field is non-zero, and hence 295 the UDP-Lite API must discard all datagrams received with a zero 296 checksum. 298 SET_IP_OPTIONS: The SET_IP_OPTIONS primitive request the network- 299 layer to send a datagram with the specified IP options. Section 300 4.1.3.2 of the requirements for Internet hosts[RFC1122] states 301 that an "application MUST be able to specify IP options to be sent 302 in its UDP datagrams, and UDP MUST pass these options to the IP 303 layer." 305 GET_IP_OPTIONS: The GET_IP_OPTIONS primitive retrieves the IP options 306 of a datagram received at the network-layer. Section 4.1.3.2 of 307 the requirements for Internet hosts[RFC1122] states that a UDP 308 receiver "MUST pass any IP option that it receives from the IP 309 layer transparently to the application layer". 311 SET_DF: The SET_DF primitive allows the network-layer to fragment 312 packets using the Fragment Offset in IPv4 [RFC6864] and a host to 313 use Fragment Headers in IPv6 [RFC2460]. The SET_DF primitive sets 314 the Don't Fragment (DF) flag in the IPv4 packet header that 315 carries a UDP datagram, which allows routers to fragment IPv4 316 packets. Although some specific applications rely on 317 fragmentation support, in general, a UDP application should 318 implement a method that avoids IP fragmentation (section 4 of 319 [RFC8085]). NOTE: In many other IETF transports (e.g., TCP, SCTP) 320 the transport provides the support needed to use DF. However, when 321 using UDP, the application is responsible for the techniques 322 needed to discover the effective path maximum transmission unit 323 (PMTU) allowed on the network path, coordinating with the network 324 layer. The acceptable maximum packet size can be determined using 325 Packetization-Layer-Path MTU Discovery (PLPMTUD) [RFC4821] or Path 326 MTU Discovery [RFC1191] [I-D.ietf-6man-rfc1981bis]. 328 GET_MMS_S: The GET_MMS_S primitive retrieves a network-layer value 329 that indicates the maximum message size (MMS) that may be sent at 330 the transport layer using a non-fragmented IP packet from the 331 configured interface. This value is specified in section 6.1 of 332 [RFC1191] and section 5.1 of [I-D.ietf-6man-rfc1981bis]. It is 333 calculated from Effective Maximum Transmit Unit for Sending 334 (EMTU_S), and the link MTU for the given source IP address. This 335 takes into account the size of the IP header plus space reserved 336 by the IP layer for additional headers (if any). UDP applications 337 should use this value as part of a method to avoid sending UDP 338 datagrams that would result in IP packets that exceed the 339 effective PMTU allowed across the network path. The effective 340 PMTU (specified in Section 1 of [RFC1191]) is equivalent to the 341 EMTU_S (specified in [RFC1122]). The specification of PLPMTUD 342 [RFC4821] states: "If PLPMTUD updates the MTU for a particular 343 path, all Packetization Layer sessions that share the path 344 representation (as described in Section 5.2) SHOULD be notified to 345 make use of the new MTU and make the required congestion control 346 adjustments". 348 GET_MMS_R: The GET_MMS_R primitive retrieves a network-layer value 349 that indicates the maximum message size (MMS) that may be received 350 at the transport layer from the configured interface. This value 351 is specified in section 3.1 of [RFC1191]. It is calculated from 352 Effective Maximum Transmit Unit for Receiving (EMTU_R), and the 353 link MTU for the given source IP address, and takes into account 354 the size of the IP header plus space reserved by the IP layer for 355 additional headers (if any). 357 SET_TTL: The SET_TTL primitive sets the hop limit (TTL field) in the 358 network-layer that is used in the IPv4 header of a packet that 359 carries an UDP datagram. This is used to limit the scope of 360 unicast datagrams. Section 3.2.2.4 of the requirements for 361 Internet hosts [RFC1122] states an "incoming Time Exceeded message 362 MUST be passed to the transport layer". 364 GET_TTL: The GET_TTL primitive retrieves the value of the TTL field 365 in a network packet received at the network-layer. Section 366 3.2.2.4 of the requirements for Internet hosts [RFC1122] states 367 that a UDP receiver "MAY pass the received ToS up to the 368 application layer" When used for applications such as the 369 Generalized TTL Security Mechanism (GTSM) [RFC5082], this needs 370 the UDP receiver API to pass the received value of this field to 371 the application. 373 SET_IPV6_UNICAST_HOPS: The SET_IPV6_UNICAST_HOPS primitive sets the 374 network-layer hop limit field in an IPv6 packet header [RFC2460] 375 carrying a UDP datagram. For IPv6 unicast datagrams, this is 376 functionally equivalent to the SET_TTL IPv4 function. 378 GET_IPV6_UNICAST_HOPS: The GET_IPV6_UNICAST_HOPS primitive is a 379 network-layer function that reads the hop count in the IPv6 header 380 [RFC2460] information of a received UDP datagram. For IPv6 381 unicast datagrams, this is functionally equivalent to the GET_TTL 382 IPv4 function. 384 SET_DSCP: The SET_DSCP primitive is a network-layer function that 385 sets the Differentiated Services (diffserv) Code Point, DSCP, (or 386 the legacy Type of Service, ToS) value [RFC2474] to be used in the 387 field of an IP header of a packet that carries a UDP datagram. 388 Section 2.4 of the requirements for Internet hosts[RFC1123] states 389 that "Applications MUST select appropriate ToS values when they 390 invoke transport layer services, and these values MUST be 391 configurable.". The application should be able to change the ToS 392 during the connection lifetime, and the ToS value should be passed 393 to the IP layer unchanged. Section 4.1.4 of [RFC1122] also states 394 that on reception the "UDP MAY pass the received ToS value up to 395 the application layer". The Differentiated Services (diffuser) 396 model [RFC2475] [RFC3260] replaces this field in the IP Header 397 assigning the six most significant bits to carry the 398 Differentiated Services Code Point (DSCP) field [RFC2474]. 399 Preserving the intention of the hist requirements [RFC1122] to 400 allow the application to specify the "Type of Service", this 401 should be interpreted to mean that an API should allow the 402 application to set the DSCP. Section 3.1.6 of the UDP Guidelines 403 [RFC8085] describes the way UDP applications should use this 404 field. Normally a UDP socket will assign a single DSCP value to 405 all datagrams in a flow, but a sender is allowed to use different 406 DSCP values for datagrams within the same flow in certain 407 cases[RFC8085]. There are guidelines for WebRTC that illustrate 408 this use [RFC7657]. 410 SET_ECN: The SET_ECN primitive is a network-layer function that sets 411 the ECN field in the IP Header of a UDP datagram. The ECN field 412 defaults to a value of 00. When the use of the ToS field was 413 redefined by diffserv [RFC3260], 2 bits of the field were assigned 414 to support Explicit Congestion Notification (ECN) [RFC3168]. 415 Section 3.1.5 of the UDP Guidelines [RFC8085] describes the way 416 UDP applications should use this field. NOTE: In many other IETF 417 transports (e.g., TCP) the transport provides the support needed 418 to use ECN, when using UDP, the application or higher layer 419 protocol is itself responsible for the techniques needed to use 420 ECN. 422 GET_ECN: The GET_ECN primitive is a network-layer function that 423 returns the value of the ECN field in the IP Header of a received 424 UDP datagram. Section 3.1.5 of the UDP Guidelines [RFC8085] 425 states that a UDP receiver "MUST check the ECN field at the 426 receiver for each UDP datagram that it receives on this port", 427 requiring the UDP receiver API to pass to pass the received ECN 428 field up to the application layer to enable appropriate congestion 429 feedback. 431 ERROR_REPORT The ERROR_REPORT event informs an application of "soft 432 errors", including the arrival of an ICMP or ICMPv6 error message. 433 Section 4.1.4 of the host requirements [RFC1122] states "UDP MUST 434 pass to the application layer all ICMP error messages that it 435 receives from the IP layer." For example, this event is required 436 to implement ICMP-based Path MTU Discovery [RFC1191] [I-D.ietf- 437 6man-rfc1981bis]. UDP applications must perform a CONNECT to 438 receive ICMP errors. 440 CLOSE: The close primitive closes a connection. No further datagrams 441 can be sent or received. Since UDP is itself connectionless, no 442 datagrams are sent when this primitive is executed. 444 3.1.1. Excluded Primitives 446 Section 3.4 of the host requirements [RFC1122] also describes 447 "GET_MAXSIZES, GET_SRCADDR (Section 3.3.4.3) and ADVISE_DELIVPROB:". 448 These mechanisms are no longer used. It also specifies use of the 449 Source Quench ICMP message, which has since been deprecated 450 [RFC6633]. 452 The IPV6_V6ONLY function defined in Section 5.3 of the basic socket 453 interface for IPv6 [RFC3493] restricts the use of information from 454 the name resolver to only allow communication of AF_INET6 sockets to 455 use IPv6 only. This is not considered part of the transport service. 457 3.2. Primitives Provided by UDP-Lite 459 The Lightweight User Datagram Protocol (UDP-Lite) [RFC3828] provides 460 similar services to UDP. It changed the semantics of the UDP "payload 461 length" field to that of a "checksum coverage length" field. UDP- 462 Lite requires the pseudo-header checksum to be computed at the sender 463 and checked at a receiver. Apart from the length and coverage 464 changes, UDP-Lite is semantically identical to UDP. 466 The sending interface of UDP-Lite differs from that of UDP by the 467 addition of a single (socket) option that communicates the checksum 468 coverage length. This specifies the intended checksum coverage, with 469 the remaining unprotected part of the payload called the "error- 470 insensitive part". 472 The receiving interface of UDP-Lite differs from that of UDP by the 473 addition of a single (socket) option that specifies the minimum 474 acceptable checksum coverage. The UDP-Lite Management Information 475 Base (MIB) [RFC5097] further defines the checksum coverage method. 476 Guidance on the use of services provided by UDP-Lite is provided in 477 the UDP Guidelines [RFC8085]. 479 UDP-Lite requires use of the UDP or UDP-Lite checksum, and hence it 480 is not permitted to use the "DISABLE_CHECKSUM:" function to disable 481 use of a checksum, nor is it possible to disable receiver checksum 482 processing using the "REQUIRE_CHECKSUM:" function . All other 483 primitives and functions for UDP are permitted. 485 In addition, the following are defined: 487 SET_CHECKSUM_COVERAGE: The SET_CHECKSUM_COVERAGE primitive sets the 488 coverage area for a sent datagram. UDP-Lite traffic uses this 489 primitive to set the coverage length provided by the UDP checksum. 490 Section 3.3 of the UDP-Lite MIB [RFC5097] states that 491 "Applications that wish to define the payload as partially 492 insensitive to bit errors ... Should do this by an explicit 493 system call on the sender side." The default is to provide the 494 same coverage as for UDP. 496 SET_MIN_COVERAGE The SET_MIN_COVERAGE primitive sets the minimum 497 acceptable coverage protection for received datagrams. UDP-Lite 498 traffic uses this primitive to set the coverage length that is 499 checked on receive (section 1.1 of the UDP-Lite MIB [RFC5097] 500 describes the corresponding MIB entry as 501 udpliteEndpointMinCoverage). Section 3.3 of the UDP-Lite 502 specification [RFC3828] states that "applications that wish to 503 receive payloads that were only partially covered by a checksum 504 should inform the receiving system by an explicit system call". 505 The default is to require only minimal coverage of the datagram 506 payload. 508 4. Acknowledgements 510 This work was partially funded by the European Union's Horizon 2020 511 research and innovation programme under grant agreement No. 644334 512 (NEAT). The views expressed are solely those of the author(s). Thanks 513 to all who have commented or contributed, including Joe Touch, Ted 514 Hardie and Aaron Falk. 516 5. IANA Considerations 518 This memo includes no request to IANA. 520 The authors request the section to be removed during conversion into 521 an RFC by the RFC Editor. 523 6. Security Considerations 525 Security considerations for the use of UDP and UDP-Lite are provided 526 in the referenced RFCs. Security guidance for application usage is 527 provided in the UDP-Guidelines [RFC8085]. 529 7. References 531 7.1. Normative References 533 [I-D.ietf-6man-rfc1981bis] 534 <>, J., <>, S., <>, J. and R. Hinden, "Path MTU Discovery 535 for IP version 6", Internet-Draft draft-ietf-6man- 536 rfc1981bis-06, April 2017. 538 [I-D.ietf-taps-transports-usage] 539 Welzl, M., Tuexen, M. and N. Khademi, "On the Usage of 540 Transport Features Provided by IETF Transport Protocols", 541 Internet-Draft draft-ietf-taps-transports-usage-04, April 542 2017. 544 [RFC0768] Postel, J., "User Datagram Protocol", STD 6, RFC 768, DOI 545 10.17487/RFC0768, August 1980, . 548 [RFC1122] Braden, R., Ed., "Requirements for Internet Hosts - 549 Communication Layers", STD 3, RFC 1122, DOI 10.17487/ 550 RFC1122, October 1989, . 553 [RFC1123] Braden, R., Ed., "Requirements for Internet Hosts - 554 Application and Support", STD 3, RFC 1123, DOI 10.17487/ 555 RFC1123, October 1989, . 558 [RFC1191] Mogul, J.C. and S.E. Deering, "Path MTU discovery", RFC 559 1191, DOI 10.17487/RFC1191, November 1990, . 562 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 563 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 564 RFC2119, March 1997, . 567 [RFC2460] Deering, S. and R. Hinden, "Internet Protocol, Version 6 568 (IPv6) Specification", RFC 2460, DOI 10.17487/RFC2460, 569 December 1998, . 571 [RFC2553] Gilligan, R., Thomson, S., Bound, J. and W. Stevens, 572 "Basic Socket Interface Extensions for IPv6", RFC 2553, 573 DOI 10.17487/RFC2553, March 1999, . 576 [RFC3168] Ramakrishnan, K., Floyd, S. and D. Black, "The Addition of 577 Explicit Congestion Notification (ECN) to IP", RFC 3168, 578 DOI 10.17487/RFC3168, September 2001, . 581 [RFC3493] Gilligan, R., Thomson, S., Bound, J., McCann, J. and W. 582 Stevens, "Basic Socket Interface Extensions for IPv6", RFC 583 3493, DOI 10.17487/RFC3493, February 2003, . 586 [RFC3828] Larzon, L-A., Degermark, M., Pink, S., Jonsson, L-E.Ed., 587 and G. Fairhurst, Ed., "The Lightweight User Datagram 588 Protocol (UDP-Lite)", RFC 3828, DOI 10.17487/RFC3828, July 589 2004, . 591 [RFC6864] Touch, J., "Updated Specification of the IPv4 ID Field", 592 RFC 6864, DOI 10.17487/RFC6864, February 2013, . 595 [RFC6935] Eubanks, M., Chimento, P. and M. Westerlund, "IPv6 and UDP 596 Checksums for Tunneled Packets", RFC 6935, DOI 10.17487/ 597 RFC6935, April 2013, . 600 [RFC6936] Fairhurst, G. and M. Westerlund, "Applicability Statement 601 for the Use of IPv6 UDP Datagrams with Zero Checksums", 602 RFC 6936, DOI 10.17487/RFC6936, April 2013, . 605 [RFC8085] Eggert, L., Fairhurst, G. and G. Shepherd, "UDP Usage 606 Guidelines", BCP 145, RFC 8085, DOI 10.17487/RFC8085, 607 March 2017, . 609 7.2. Informative References 611 [POSIX] "IEEE Std. 1003.1-2001, , "Standard for Information 612 Technology - Portable Operating System Interface (POSIX)", 613 Open Group Technical Standard: Base Specifications Issue 614 6, ISO/IEC 9945:2002", December 2001. 616 [RFC2474] Nichols, K., Blake, S., Baker, F. and D. Black, 617 "Definition of the Differentiated Services Field (DS 618 Field) in the IPv4 and IPv6 Headers", RFC 2474, DOI 619 10.17487/RFC2474, December 1998, . 622 [RFC2475] Blake, S., Black, D., Carlson, M., Davies, E., Wang, Z. 623 and W. Weiss, "An Architecture for Differentiated 624 Services", RFC 2475, DOI 10.17487/RFC2475, December 1998, 625 . 627 [RFC3260] Grossman, D., "New Terminology and Clarifications for 628 Diffserv", RFC 3260, DOI 10.17487/RFC3260, April 2002, 629 . 631 [RFC3376] Cain, B., Deering, S., Kouvelas, I., Fenner, B. and A. 632 Thyagarajan, "Internet Group Management Protocol, Version 633 3", RFC 3376, DOI 10.17487/RFC3376, October 2002, . 636 [RFC3678] Thaler, D., Fenner, B. and B. Quinn, "Socket Interface 637 Extensions for Multicast Source Filters", RFC 3678, DOI 638 10.17487/RFC3678, January 2004, . 641 [RFC3810] Vida, R.Ed., and L. Costa, Ed., "Multicast Listener 642 Discovery Version 2 (MLDv2) for IPv6", RFC 3810, DOI 643 10.17487/RFC3810, June 2004, . 646 [RFC4566] Handley, M., Jacobson, V. and C. Perkins, "SDP: Session 647 Description Protocol", RFC 4566, DOI 10.17487/RFC4566, 648 July 2006, . 650 [RFC4604] Holbrook, H., Cain, B. and B. Haberman, "Using Internet 651 Group Management Protocol Version 3 (IGMPv3) and Multicast 652 Listener Discovery Protocol Version 2 (MLDv2) for Source- 653 Specific Multicast", RFC 4604, DOI 10.17487/RFC4604, 654 August 2006, . 656 [RFC4821] Mathis, M. and J. Heffner, "Packetization Layer Path MTU 657 Discovery", RFC 4821, DOI 10.17487/RFC4821, March 2007, 658 . 660 [RFC5082] Gill, V., Heasley, J., Meyer, D., Savola, P.Ed., and C. 661 Pignataro, "The Generalized TTL Security Mechanism 662 (GTSM)", RFC 5082, DOI 10.17487/RFC5082, October 2007, 663 . 665 [RFC5097] Renker, G. and G. Fairhurst, "MIB for the UDP-Lite 666 protocol", RFC 5097, DOI 10.17487/RFC5097, January 2008, 667 . 669 [RFC5790] Liu, H., Cao, W. and H. Asaeda, "Lightweight Internet 670 Group Management Protocol Version 3 (IGMPv3) and Multicast 671 Listener Discovery Version 2 (MLDv2) Protocols", RFC 5790, 672 DOI 10.17487/RFC5790, February 2010, . 675 [RFC6633] Gont, F., "Deprecation of ICMP Source Quench Messages", 676 RFC 6633, DOI 10.17487/RFC6633, May 2012, . 679 [RFC7657] Black, D.Ed., and P. Jones, "Differentiated Services 680 (Diffserv) and Real-Time Communication", RFC 7657, DOI 681 10.17487/RFC7657, November 2015, . 684 [STEVENS] "Stevens, W., Fenner, B., and A. Rudoff, "UNIX Network 685 Programming, The sockets Networking API", Addison- 686 Wesley.", 2004. 688 Appendix A. Multicast Primitives 689 This appendix describes primitives that are used when UDP and UDP- 690 Lite support IPv4/IPv6 Multicast. Guidance on the use of UDP and 691 UDP-Lite for multicast services is provided in the UDP 692 Guidelines[RFC8085]. 694 IP multicast may be supported using the Any Source Multicast (ASM) 695 model or by the Source-Specific Multicast (SSM) model. The latter 696 requires use of a Multicast Source Filter (MSF) when specifying an IP 697 multicast group destination address. 699 Use of multicast requires additional primitives at the transport API 700 that need to be called to coordinate operation of the IPv4 and IPv6 701 network layer protocols. For example, to receive datagrams sent to a 702 group, an endpoint must first become a member of a multicast group at 703 the network layer. Local multicast reception is signalled for IPv4 704 by the Internet Group Management Protocol (IGMP) [RFC3376] [RFC4604]. 705 IPv6 uses the equivalent Multicast Listener Discovery (MLD) protocol 706 [RFC3810] [RFC5790], carried over ICMPv6. A lightweight version of 707 these protocols has also been specified [RFC5790]. 709 The following are defined: 711 JoinLocalGroup: 1 of the basic socket extensions for IPv6 [RFC3493] 712 provides a function that allows receivi9ng traffic from a local 713 IPv4 multicast group. 715 IPV6_MULTICAST_IF: Section 5.2 of the basic socket extensions for 716 IPv6 [RFC2553] states that this sets the interface that will be 717 used for outgoing multicast packets. 719 IP_MULTICAST_TTL: This sets the time to live field t to use for 720 outgoing IPv4 multicast packets. This is used to limit scope of 721 multicast datagrams. Methods such as GTSM [RFC5082], set this 722 value to ensure link-local transmission. GTSM also requires the 723 UDP receiver API to pass the received value of this field to the 724 application. 726 IPV6_MULTICAST_HOPS: Section 5.2 of the basic socket extensions for 727 IPv6 [RFC2553] states that sets the hop count to use for outgoing 728 multicast IPv6 packets. (This is equivalent to IP_MULTICAST_TTL 729 used for IPv4 multicast). 731 IPV6_MULTICAST_LOOP: Section 5.2 of the basic socket extensions for 732 IPv6 [RFC2553] states that this sets whether a copy of a datagram 733 is looped back by the IP layer for local delivery when the 734 datagram is sent to a group to which the sending host itself 735 belongs). 737 IPV6_JOIN_GROUP: Section 5.2 of the basic socket extensions for IPv6 738 [RFC2553] provides a function that allows an endpoint to join an 739 IPv6 multicast group. 741 SIOCGIPMSFILTER: Section 8.1 of the socket interface for MSF 742 [RFC3678] provides a function that allows reading the multicast 743 source filters. 745 SIOCSIPMSFILTER: Section 8.1 of the socket interface for MSF 746 [RFC3678] provides a function that allows setting/modifying the 747 multicast source filters. 749 IPV6_LEAVE_GROUP: Section 5.2 of the basic socket extensions for IPv6 750 [RFC2553] provides a function that allows leaving an IPv6 751 multicast group. 753 LeaveHostGroup: Section 7.1 of the basic socket extensions for IPv6 754 [RFC3493] provides a function that allows leaving an IPv4 755 multicast group. 757 LeaveLocalGroup: Section 7.1 of the basic socket extensions for IPv6 758 [RFC3493] provides a function that allows leaving a local IPv4 759 multicast group. 761 Section 4.1.1 of the Socket Interface Extensions for MSF [RFC3678] 762 updates the multicast interface to add support for MSF for IPv4 and 763 IPv6 required by IGMPv3. Three sets of API functionality are defined: 765 1. IPv4 Basic (Delta-based) API. "Each function call specifies a 766 single source address which should be added to or removed from 767 the existing filter for a given multicast group address on which 768 to listen." 770 2. IPv4 Advanced (Full-state) API. "This API allows an application 771 to define a complete source-filter comprised of zero or more 772 source addresses, and replace the previous filter with a new 773 one." 775 3. Protocol-Independent Basic MSF (Delta-based) API 777 4. Protocol-Independent Advanced MSF (Full-state) API 779 It specifies the following primitives: 781 IP_ADD_MEMBERSHIP: This is used to join an ASM group. 783 IP_BLOCK_SOURCE: This MSF can block data from a given multicast 784 source to a given ASM or SSM group. 786 IP_UNBLOCK_SOURCE: This updates an MSF to undo a previous call to 787 IP_UNBLOCK_SOURCE for an ASM or SSM group. 789 IP_DROP_MEMBERSHIP: This is used to leave an ASM or SSM group. (In 790 SSM, this drops all sources that have been joined for a particular 791 group and interface. The operations are the same as if the socket 792 had been closed.) 794 Section 4.1.2 of the socket interface for MSF [RFC3678] updates the 795 interface to add IPv4 MSF support to IGMPv3 using ASM: 797 IP_ADD_SOURCE_MEMBERSHIP: This is used to join an SSM group. 799 IP_DROP_SOURCE_MEMBERSHIP: This is used to leave an SSM group. 801 Section 4.1.2 of the socket interface for MSF [RFC3678] defines the 802 Advanced (Full-state) API: 804 setipv4sourcefilter This is used to join an IPv4 multicast group, or 805 to enable multicast from a specified source. 807 getipv4sourcefilter: This is used to leave an IPv4 multicast group, 808 or to filter multicast from a specified source. 810 Section 5.1 of the socket interface for MSF [RFC3678] specifies 811 Protocol-Independent Multicast API functions: 813 MCAST_JOIN_GROUP This is used to join an ASM group. 815 MCAST_JOIN_SOURCE_GROUP This is used to join an SSM group. 817 MCAST_BLOCK_SOURCE: This is used to block a source in an ASM group. 819 MCAST_UNBLOCK_SOURCE: This removes a previous MSF set by 820 MCAST_BLOCK_SOURCE. 822 MCAST_LEAVE_GROUP: This leaves a SSM group. 824 MCAST_LEAVE_GROUP: This leaves an ASM or SSM group. 826 Section 5.2 of the socket interface for MSF [RFC3678] specifies the 827 Protocol-Independent Advanced MSF (Full-state) API applicable for 828 both IPv4 and IPv6: 830 setsourcefilter This is used to join an IPv4 or IPv6 multicast group, 831 or to enable multicast from a specified source. 833 getsourcefilter: This is used to leave an IPv4 or IPv6 multicast 834 group, or to filter multicast from a specified source. 836 The Lightweight IGMPv3 (LW_IGMPv3) and MLDv2 protocol [RFC5790] 837 updates this interface (in Section 7.2 of RFC5790). 839 Appendix B. Revision Notes 841 Note to RFC-Editor: please remove this entire section prior to 842 publication. 844 Individual draft -00: 846 o This is the first version. Comments and corrections are welcome 847 directly to the authors or via the IETF TAPS working group mailing 848 list. 850 Individual draft -01: 852 o Includes ability of a UDP receiver to disallow zero checksum 853 datagrams. 855 o Fixes to references and some connect on UDP usage. 857 Individual draft -02: 859 o Fixes to address issues noted by WG. 861 o Completed Multicast section to specify modern APIs. 863 o Noted comments on API usage for UDP. 865 o Feedback from various reviewers. 867 Individual draft -03: 869 o Removes pass 2 and 3 of the TAPS analysis from this revision. 870 These are expected to be incorporated into a combined draft of the 871 TAPS WG. 873 o Fixed Typos. 875 TAPS WG draft -00: 877 o Expected to progress with draft-ietf-taps-transports-usage of the 878 TAPS WG. 880 TAPS WG draft -01: 882 o No intentional changes were made to the specification of 883 primitives, this update is editorial 885 o Reorganised text to eliminate the appendices. 887 o Editorial changes were make to complete the document for a WGLC. 889 o Rephrasing to eliminate using references as nouns, and to make 890 text more consistent. 892 o One appendix was incorporated. 894 o This appendix was moved to the end (for later deletion by the RFC- 895 Ed). 897 TAPS WG draft -02: 899 o Updated to align with latest taps-transport-usage ID. 901 o Revised to clarify MTU usage and track work in IPv6 PMTU 903 o Usage of DF clarified. 905 TAPS WG draft -03 907 o edit to MMS entries. 909 Authors' Addresses 911 Godred Fairhurst 912 University of Aberdeen 913 School of Engineering 914 Fraser Noble Building 915 Fraser Noble Building Aberdeen, AB24 3UE 916 UK 918 Email: gorry@erg.abdn.ac.uk 920 Tom Jones 921 University of Aberdeen 922 School of Engineering 923 Fraser Noble Building 924 Aberdeen, AB24 3UE 925 UK 927 Email: tom@erg.abdn.ac.uk