idnits 2.17.1 draft-fairhurst-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 : ---------------------------------------------------------------------------- No issues found here. 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 (October 05, 2016) is 2759 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Outdated reference: A later version (-09) exists of draft-ietf-taps-transports-usage-01 == Outdated reference: A later version (-19) exists of draft-ietf-tsvwg-rfc5405bis-07 ** 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 1981 (Obsoleted by RFC 8201) -- Obsolete informational reference (is this intentional?): RFC 4566 (Obsoleted by RFC 8866) Summary: 2 errors (**), 0 flaws (~~), 4 warnings (==), 3 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: April 8, 2017 October 05, 2016 7 Features of the User Datagram Protocol (UDP) and Lightweight UDP (UDP- 8 Lite) Transport Protocols 9 draft-fairhurst-taps-transports-usage-udp-03 11 Abstract 13 This document describes how the User Datagram Protocol (UDP) and the 14 Lightweight User Datagram Protocol (UDP-Lite) transport protocols 15 expose services to applications and how an application can configure 16 and use the features offered by the transport service. The document 17 is intended as a contribution to the Transport Services (TAPS) 18 working group to assist in analysis of the UDP and UDP-Lite transport 19 interface. 21 Status of This Memo 23 This Internet-Draft is submitted 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). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 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 This Internet-Draft will expire on April 8, 2017. 38 Copyright Notice 40 Copyright (c) 2016 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 2 56 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 57 3. UDP and UDP-Lite Primitives . . . . . . . . . . . . . . . . . 3 58 3.1. Primitives Provided by UDP . . . . . . . . . . . . . . . 3 59 3.1.1. Excluded Primitives . . . . . . . . . . . . . . . . . 8 60 3.2. Primitives Provided by UDP-Lite . . . . . . . . . . . . . 9 61 4. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 10 62 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 63 6. Security Considerations . . . . . . . . . . . . . . . . . . . 10 64 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 65 7.1. Normative References . . . . . . . . . . . . . . . . . . 10 66 7.2. Informative References . . . . . . . . . . . . . . . . . 11 67 Appendix A. Revision Notes . . . . . . . . . . . . . . . . . . . 13 68 Appendix B. Notes Based on Typical Usage . . . . . . . . . . . . 14 69 Appendix C. UDP Multicast . . . . . . . . . . . . . . . . . . . 14 70 C.1. Multicast Primitives . . . . . . . . . . . . . . . . . . 15 71 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 17 73 1. Terminology 75 This document uses common terminology defined in 76 [I-D.ietf-taps-transports-usage]. This document also refers to the 77 terminology of [RFC2119], but does not itself define new terms using 78 this terminology. 80 2. Introduction 82 This document presents defined interactions between transport 83 protocols and applications in the form of 'primitives' (function 84 calls). Primitives can be invoked by an application or a transport 85 protocol; the latter type is called an "event". The list of 86 transport service features and primitives in this document is 87 strictly based on the parts of protocol specifications that relate to 88 what the protocol provides to an application using it and how the 89 application interacts with it. It does not cover parts of a protocol 90 that are explicitly stated as optional to implement. 92 This follows the methodology defined in 93 [I-D.ietf-taps-transports-usage], specifically it provides the first 94 pass of this process. It discusses the relevant RFC text describing 95 primitives for each protocol. This also provides documentation that 96 may help users of UDP and UDP-Lite. 98 3. UDP and UDP-Lite Primitives 100 This summarizes the relevant text parts of the RFCs describing the 101 UDP and UDP-Lite protocols, focusing on what the transport protocols 102 provide to the application and how the transport is used (based on 103 abstract API descriptions, where they are available). 105 3.1. Primitives Provided by UDP 107 The User Datagram Protocol (UDP) [RFC0768] States: "This User 108 Datagram Protocol (UDP) is defined to make available a datagram mode 109 of packet-switched computer communication in the environment of an 110 interconnected set of computer networks." It "provides a procedure 111 for application programs to send messages to other programs with a 112 minimum of protocol mechanism (..)". 114 The User Interface section of [RFC0768] specifies that the user 115 interface to an application should be able to create receive ports, 116 source and destination ports and addresses, and provide operations to 117 receive data based on ports with an indication of source port and 118 address. Operations should be provided that allows datagrams be sent 119 specifying the source and destination ports and addresses to be sent. 121 UDP for IPv6 is defined by [RFC2460], and API extensions to support 122 this in [RFC3493]. [RFC6935] and [RFC6936] defines an update to the 123 UDP transport specified in RFC 2460. This enables use of a zero UDP 124 checksum mode with a tunnel protocol, providing that the method 125 satisfies the requirements in [RFC6936]. 127 UDP offers only a basic transport interface. UDP datagrams may be 128 directly sent and received, without exchanging messages between the 129 endpoints to setup a connection (i.e., there is no handshake prior to 130 communication). Using the sockets API, applications can receive 131 packets from more than one IP source address on a single UDP socket. 132 Common support allows specification of the local IP address, 133 destination IP address, local port and destination port values. Any 134 or all of these can be indicated, with defaults supplied by the local 135 system when these are not specified. The local endpoint is set using 136 the BIND call and set on the remote endpoint using the CONNECT call. 137 The CLOSE function has local significance only. This does not impact 138 the status of the remote endpoint. 140 UDP and UDP-Lite do not provide congestion control, retransmission, 141 nor support to optimise fragmentation etc. This means that 142 applications using UDP need to provide additional functions on top of 143 the UDP transport API. This requires parameters to be passed through 144 the API to control the network layer (IPv4 or IPv6). These 145 additional primitives could be considered a part of the network layer 146 (e.g., control of the setting of the Don't Fragment flag on a 147 transmitted datagram), but are nonetheless essential to allow a user 148 of the UDP API to implement functions that are normally associated 149 with the transport layer (such as probing for Path maximum 150 transmission size). Although this adds complexity to the analysis of 151 the API, this document includes such primitives. 153 [I-D.ietf-tsvwg-rfc5405bis] also states "many operating systems also 154 allow a UDP socket to be connected, i.e., to bind a UDP socket to a 155 specific pair of addresses and ports. This is similar to the 156 corresponding TCP sockets API functionality. However, for UDP, this 157 is only a local operation that serves to simplify the local send/ 158 receive functions and to filter the traffic for the specified 159 addresses and ports. Binding a UDP socket does not establish a 160 connection - UDP does not notify the remote end when a local UDP 161 socket is bound. Binding a socket also allows configuring options 162 that affect the UDP or IP layers, for example, use of the UDP 163 checksum or the IP Timestamp option. On some stacks, a bound socket 164 also allows an application to be notified when ICMP error messages 165 are received for its transmissions [RFC1122]." 167 The [POSIX] API offers mechanisms for an application to receive 168 asynchronous data events at the socket layer. Calls such as poll, 169 select or queue allow an application to be notified when data has 170 arrived at a socket or a socket has flushed its buffers. It is 171 possible to structure a callback-driven API to the network interface 172 on top of these calls. There are protocols that allow a macro 173 interface to network primitives, [RFC6458] describes implicit 174 association setup for sending datagram messages using SCTP. Implicit 175 connection setup allows an application to delegate connection life 176 management to the transport API. The transport API uses protocol 177 primitives to offer the automated service to the application via the 178 socket API. By combining UDP primitives (CONNECT.UDP, SEND.UDP), a 179 higher level API could offer a similar service. 181 Guidance on the use of services provided by UDP is provided in 182 [I-D.ietf-tsvwg-rfc5405bis]. 184 The following primitives are specified: 186 CONNECT: The CONNECT primitive allows the association of source and 187 port sets to a socket to enable creation of a 'connection' for UDP 188 traffic. This UDP connection allows an application to be notified 189 of errors received from the network stack and provides a shorthand 190 access to the send and receive primitives. Since UDP is itself 191 connectionless, no datagrams are sent because this primitive is 192 executed. A further connect call can be used to change the 193 association to a source/port pair. 195 Two forms of usage may be identified for the CONNECT primitive: 197 1. bind(): A bind operation sets the local port, either 198 implicitly, triggered by a send to operation on an unbound, 199 unconnected socket using an ephemeral port. Or by an explicit 200 bind to makes use of a configured or well-known port. 202 2. bind(); connect(): A bind operation followed by a CONNECT 203 primitive. The bind operation establishes the use of a known 204 local port for datagrams, rather than using an ephemeral port. 205 The connect operation specifies a known address port 206 combination to be used by default for future datagrams. This 207 form is used either after receiving a datagram from an 208 endpoint causing the creation of a connection or can be 209 triggered by third party configuration or a protocol trigger 210 (such as reception of a UDP Service Description Protocol, SDP 211 [RFC4566], record). 213 LISTEN: The roles of a client and a server are often not appropriate 214 for UDP, where connections can be peer-to-peer. The listening 215 functions are performed using one of the forms of CONNECT 216 primitive described above. 218 SEND: The SEND primitive hands over a provided number of bytes that 219 UDP should send to the other side of a UDP connection in a UDP 220 datagram. The primitive can be used by an application to directly 221 send datagrams to an endpoint defined by an address/port pair. If 222 a connection has been created, then the address/port pair is 223 inferred from the current connection for the socket. A connection 224 created on the socket will allow network errors to be returned to 225 the application as a notification on the send primitive. Messages 226 passed to the send primitive that cannot be sent atomically in a 227 datagram will not be sent by the network layer, generating an 228 error. 230 RECEIVE: The RECEIVE primitive allocates a receiving buffer to 231 accommodate a received datagram. The primitive returns the number 232 of bytes provided from a received UDP datagram. Section 4.1.3.5 233 of [RFC1122] states "When a UDP datagram is received, its 234 specific-destination address MUST be passed up to the application 235 layer." 237 DISABLE_CHECKSUM: The CHECKSUM function controls whether a sender 238 disables the UDP checksum when sending datagrams. [RFC0768] and 239 IPv6 [RFC6935] [RFC6936] [I-D.ietf-tsvwg-rfc5405bis]. When set it 240 overrides the default UDP behaviour disabling the checksum on 241 sending. Section 4.1.3.4 of [RFC1122] states "An application MAY 242 optionally be able to control whether a UDP checksum will be 243 generated, but it MUST default to checksumming on." 245 REQUIRE_CHECKSUM: The REQUIRE_CHECKSUM function determines whether 246 UDP datagrams received with a zero checksum are permitted or 247 discarded. Section 4.1.3.4 of [RFC1122] states "An application 248 MAY optionally be able to control whether UDP datagrams without 249 checksums should be discarded or passed to the application." 250 Section 3.1 of [RFC3828] requires that the checksum field is non- 251 zero, and hence UDP-Lite need to discard all datagrams received 252 with a zero checksum. 254 SET_IP_OPTIONS: The SET_IP_OPTIONS function enables a datagram to be 255 sent with the specified IP options. Section 4.1.3.2 of[RFC1122] 256 states that an "application MUST be able to specify IP options to 257 be sent in its UDP datagrams, and UDP MUST pass these options to 258 the IP layer." 260 GET_IP_OPTIONS: The GET_IP_OPTIONS function is a network-layer 261 function that enables a receiver to read the IP options of a 262 received datagram. Section 4.1.3.2 of[RFC1122] states that a UDP 263 receiver "MUST pass any IP option that it receives from the IP 264 layer transparently to the application layer". 266 SET_DF: The SET_DF function is a network-layer function that sets 267 the Don't Fragment (DF) flag to be used in the field of an IP 268 header of a packet that carries a UDP datagram. A UDP application 269 should implement a method that avoids IP fragmentation ( section 4 270 of [I-D.ietf-tsvwg-rfc5405bis]). It can use Packetization-Layer- 271 Path MTU Discovery (PLPMTUD) [RFC4821] or Path MTU Discovery 272 [RFC1191]. NOTE: In many other IETF transports (e.g. TCP) the 273 transport provides the support needed to use DF, when using UDP, 274 the application is responsible for the techniques needed to 275 discover the path MTU, coordinating with the network layer. 277 GET_INTERFACE_MTU: The GET_INTERFACE_MTU function a network-layer 278 function that indicates the largest unfragmented IP packet that 279 may be sent. A UDP endpoint can subtract the size of all network 280 and transport headers to determine the maximum size of 281 unfragmented UDP payload. UDP applications should use this value 282 as part of a method to avoid sending UDP datagrams that would 283 result in IP packets that exceed the effective path maximum 284 transmission unit (PMTU) allowed on the network path. The 285 effective PMTU specified in Section 1 of [RFC1191] is equivalent 286 to the "effective MTU for sending" specified in [RFC1122]. 287 [RFC4821] states: "If PLPMTUD updates the MTU for a particular 288 path, all Packetization Layer sessions that share the path 289 representation (as described in Section 5.2) SHOULD be notified to 290 make use of the new MTU and make the required congestion control 291 adjustments." 293 SET_TTL: The SET_TTL function a network-layer function that sets the 294 hop limit (TTL field) to be used in the field of an IPv4 header of 295 a packet that carries an UDP datagram. This is used to limit the 296 scope of unicast datagrams. Section 3.2.2.4 of [RFC1122] states 297 an "incoming Time Exceeded message MUST be passed to the transport 298 layer". 300 GET_TTL: The GET_TTL function is a network-layer function that reads 301 the value of the TTL field from the IPv4 header of a received UDP 302 datagram. Section 3.2.2.4 of [RFC1122] states that a UDP receiver 303 "MAY pass the received TOS up to the application layer" When used 304 for applications such as the Generalized TTL Security Mechanism 305 (GTSM) [RFC5082], this needs the UDP receiver API to pass the 306 received value of this field to the application. 308 SET_IPV6_UNICAST_HOPS: The SET_IPV6_UNICAST_HOPS function is a 309 network-layer function that sets the hop limit field to be used in 310 the field of an IPv6 header of a packet that carries a UDP 311 datagram. For IPv6 unicast datagrams, this is functionally 312 equivalent to the SET_TTL IPv4 function. 314 GET_IPV6_UNICAST_HOPS: The GET_IPV6_UNICAST_HOPS function is a 315 network-layer function that reads the value from the hop count 316 field in the IPv6 header from the IP header information of a 317 received UDP datagram. For IPv6 unicast datagrams, this is 318 functionally equivalent to the GET_TTL IPv4 function. 320 SET_DSCP: The SET_DSCP function is a network-layer function that 321 sets the DSCP (or legacy TOS) value to be used in the field of an 322 IP header of a packet that carries a UDP Datagram. Section 2.4 of 323 [RFC1122] states that "Applications MUST select appropriate TOS 324 values when they invoke transport layer services, and these values 325 MUST be configurable.". The application should be able to change 326 the TOS during the connection lifetime, and the TOS value should 327 be passed to the IP layer unchanged. Section 4.1.4 of [RFC1122] 328 also states that on reception the "UDP MAY pass the received TOS 329 value up to the application layer". [RFC2475] [RFC3260] replaces 330 this field in the IP Header assigning the six most significant 331 bits to carry the Differentiated Services Code Point (DSCP) field. 332 Preserving the intention of [RFC1122] to allow the application to 333 specify the "Type of Service", this should be interpreted to mean 334 that an API should allow the application to set the DSCP. 335 Section 3.1.6 of [I-D.ietf-tsvwg-rfc5405bis] describes the way UDP 336 applications should use this field. Normally a UDP socket will 337 assign a single DSCP value to all Datagrams in a flow, but it is 338 allowed to use different DSCP values for datagrams within the same 339 flow in some cases, as described in [I-D.ietf-tsvwg-rfc5405bis]. 340 Guidelines for WebRTC that illustrate this use are provided in 341 [RFC7657]. 343 SET_ECN: The SET_ECN function is a network-layer function that sets 344 the ECN field in the IP Header of a UDP Datagram. When use of the 345 TOS field was redefined [RFC3260], 2 bits of the field were 346 assigned to support Explicit Congestion Notification (ECN) 347 [RFC3168]. Section 3.1.5 [I-D.ietf-tsvwg-rfc5405bis] describes 348 the way UDP applications should use this field. NOTE: In many 349 other IETF transports (e.g. TCP) the transport provides the 350 support needed to use ECN, when using UDP, the application itself 351 is responsible for the techniques needed to use ECN. 353 GET_ECN: The GET_ECN function is a network-layer function that 354 returns the value of the ECN field in the IP Header of a received 355 UDP Datagram. Section 3.1.5 [I-D.ietf-tsvwg-rfc5405bis] states 356 that a UDP receiver "MUST check the ECN field at the receiver for 357 each UDP datagram that it receives on this port", requiring the 358 UDP receiver API to pass to pass the received ECN field up to the 359 application layer to enable appropriate congestion feedback. 361 ERROR_REPORT The ERROR_REPORT event informs an application of "soft 362 errors", including the arrival of an ICMP or ICMPv6 error message. 363 Section 4.1.4 of [RFC1122] states "UDP MUST pass to the 364 application layer all ICMP error messages that it receives from 365 the IP layer." For example, this event is required to implement 366 ICMP-based Path MTU Discovery [RFC1191] [RFC1981]. 368 CLOSE: The close primitive closes a connection. No further 369 datagrams may be sent/received. Since UDP is itself 370 connectionless, no datagrams are sent because this command is 371 executed. 373 3.1.1. Excluded Primitives 375 Section 3.4 of [RFC1122] also describes "GET_MAXSIZES: - replaced, 376 GET_SRCADDR (Section 3.3.4.3) and ADVISE_DELIVPROB:". These 377 mechanisms are no longer used. It also specifies use of the Source 378 Quench ICMP message, which has since been deprecated [RFC6633]. The 379 IPV6_V6ONLY function defined in Section 5.3 of [RFC3493] restricts 380 the use of information from the name resolver to only allow 381 communication of AF_INET6 sockets to use IPv6 only. This is not 382 considered part of the transport service. 384 3.2. Primitives Provided by UDP-Lite 386 The Lightweight User Datagram Protocol (UDP-Lite) [RFC3828] provides 387 similar services to UDP. It changed the semantics of the UDP 388 "payload length" field to that of a "checksum coverage length" field. 389 UDP-Lite requires the pseudo-header checksum to be computed at the 390 sender and checked at a receiver. Apart from the length and coverage 391 changes, UDP-Lite is semantically identical to UDP. 393 The sending interface of UDP-Lite differs from that of UDP by the 394 addition of a single (socket) option that communicates the checksum 395 coverage length. This specifies the intended checksum coverage, with 396 the remaining unprotected part of the payload called the "error- 397 insensitive part". 399 The receiving interface of UDP-Lite differs from that of UDP by the 400 addition of a single (socket) option that specifies the minimum 401 acceptable checksum coverage. 403 The UDP-Lite Management Information Base (MIB) further defines the 404 checksum coverage method [RFC5097]. Guidance on the use of services 405 provided by UDP-Lite is provided in [I-D.ietf-tsvwg-rfc5405bis]. 407 UDP-Lite requires use of the UDP or UDP-Lite checksum, and hence it 408 is not permitted to use the "DISABLE_CHECKSUM:" function to disable 409 use of a checksum, nor is it possible to disable receiver checksum 410 processing using the "REQUIRE_CHECKSUM:" function . All other 411 primitives and functions for UDP are permitted. 413 In addition, the following are defined: 415 SET_CHECKSUM_COVERAGE: The SET_CHECKSUM_COVERAGE function sets the 416 coverage area for a sent datagram. UDP-Lite traffic uses this 417 primitive to set the coverage length provided by the UDP checksum. 418 Section 3.3 of [RFC5097] states that "Applications that wish to 419 define the payload as partially insensitive to bit errors ... 420 Should do this by an explicit system call on the sender side." 421 The default is to provide the same coverage as for UDP. 423 SET_MIN_COVERAGE The SET_MIN_COVERAGE function sets the minimum a 424 acceptable coverage protection for received datagrams. UDP-Lite 425 traffic uses this primitive to set the coverage length that is 426 checked on receive (section 1.1 of [RFC5097] describes the 427 corresponding MIB entry as udpliteEndpointMinCoverage). 428 Section 3.3 of [RFC3828] states that "applications that wish to 429 receive payloads that were only partially covered by a checksum 430 should inform the receiving system by an explicit system call". 432 The default is to require only minimal coverage of the datagram 433 payload. 435 4. Acknowledgements 437 This work was partially funded by the European Union's Horizon 2020 438 research and innovation programme under grant agreement No. 644334 439 (NEAT). The views expressed are solely those of the author(s). 440 Thanks to all who have commented or contributed, including Joe Touch, 441 Ted Hardie, Aaron Falk. 443 5. IANA Considerations 445 This memo includes no request to IANA. 447 If there are no requirements for IANA, the section will be removed 448 during conversion into an RFC by the RFC Editor. 450 6. Security Considerations 452 Security considerations for the use of UDP and UDP-Lite are provided 453 in the referenced RFCs. Security guidance for application usage is 454 provide in the UDP-Guidelines [I-D.ietf-tsvwg-rfc5405bis]. 456 7. References 458 7.1. Normative References 460 [I-D.ietf-taps-transports-usage] 461 Welzl, M., Tuexen, M., and N. Khademi, "On the Usage of 462 Transport Service Features Provided by IETF Transport 463 Protocols", draft-ietf-taps-transports-usage-01 (work in 464 progress), July 2016. 466 [I-D.ietf-tsvwg-rfc5405bis] 467 Eggert, L., Fairhurst, G., and G. Shepherd, "UDP Usage 468 Guidelines", draft-ietf-tsvwg-rfc5405bis-07 (work in 469 progress), November 2015. 471 [RFC0768] Postel, J., "User Datagram Protocol", STD 6, RFC 768, 472 DOI 10.17487/RFC0768, August 1980, 473 . 475 [RFC1122] Braden, R., Ed., "Requirements for Internet Hosts - 476 Communication Layers", STD 3, RFC 1122, 477 DOI 10.17487/RFC1122, October 1989, 478 . 480 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 481 Requirement Levels", BCP 14, RFC 2119, 482 DOI 10.17487/RFC2119, March 1997, 483 . 485 [RFC2460] Deering, S. and R. Hinden, "Internet Protocol, Version 6 486 (IPv6) Specification", RFC 2460, DOI 10.17487/RFC2460, 487 December 1998, . 489 [RFC2553] Gilligan, R., Thomson, S., Bound, J., and W. Stevens, 490 "Basic Socket Interface Extensions for IPv6", RFC 2553, 491 DOI 10.17487/RFC2553, March 1999, 492 . 494 [RFC3168] Ramakrishnan, K., Floyd, S., and D. Black, "The Addition 495 of Explicit Congestion Notification (ECN) to IP", 496 RFC 3168, DOI 10.17487/RFC3168, September 2001, 497 . 499 [RFC3493] Gilligan, R., Thomson, S., Bound, J., McCann, J., and W. 500 Stevens, "Basic Socket Interface Extensions for IPv6", 501 RFC 3493, DOI 10.17487/RFC3493, February 2003, 502 . 504 [RFC3828] Larzon, L-A., Degermark, M., Pink, S., Jonsson, L-E., Ed., 505 and G. Fairhurst, Ed., "The Lightweight User Datagram 506 Protocol (UDP-Lite)", RFC 3828, DOI 10.17487/RFC3828, July 507 2004, . 509 [RFC6935] Eubanks, M., Chimento, P., and M. Westerlund, "IPv6 and 510 UDP Checksums for Tunneled Packets", RFC 6935, 511 DOI 10.17487/RFC6935, April 2013, 512 . 514 7.2. Informative References 516 [POSIX] "IEEE Std. 1003.1-2001, , "Standard for Information 517 Technology - Portable Operating System Interface (POSIX)", 518 Open Group Technical Standard: Base Specifications Issue 519 6, ISO/IEC 9945:2002", December 2001. 521 [RFC1191] Mogul, J. and S. Deering, "Path MTU discovery", RFC 1191, 522 DOI 10.17487/RFC1191, November 1990, 523 . 525 [RFC1981] McCann, J., Deering, S., and J. Mogul, "Path MTU Discovery 526 for IP version 6", RFC 1981, DOI 10.17487/RFC1981, August 527 1996, . 529 [RFC2475] Blake, S., Black, D., Carlson, M., Davies, E., Wang, Z., 530 and W. Weiss, "An Architecture for Differentiated 531 Services", RFC 2475, DOI 10.17487/RFC2475, December 1998, 532 . 534 [RFC3260] Grossman, D., "New Terminology and Clarifications for 535 Diffserv", RFC 3260, DOI 10.17487/RFC3260, April 2002, 536 . 538 [RFC3678] Thaler, D., Fenner, B., and B. Quinn, "Socket Interface 539 Extensions for Multicast Source Filters", RFC 3678, 540 DOI 10.17487/RFC3678, January 2004, 541 . 543 [RFC4566] Handley, M., Jacobson, V., and C. Perkins, "SDP: Session 544 Description Protocol", RFC 4566, DOI 10.17487/RFC4566, 545 July 2006, . 547 [RFC4821] Mathis, M. and J. Heffner, "Packetization Layer Path MTU 548 Discovery", RFC 4821, DOI 10.17487/RFC4821, March 2007, 549 . 551 [RFC5082] Gill, V., Heasley, J., Meyer, D., Savola, P., Ed., and C. 552 Pignataro, "The Generalized TTL Security Mechanism 553 (GTSM)", RFC 5082, DOI 10.17487/RFC5082, October 2007, 554 . 556 [RFC5097] Renker, G. and G. Fairhurst, "MIB for the UDP-Lite 557 protocol", RFC 5097, DOI 10.17487/RFC5097, January 2008, 558 . 560 [RFC5790] Liu, H., Cao, W., and H. Asaeda, "Lightweight Internet 561 Group Management Protocol Version 3 (IGMPv3) and Multicast 562 Listener Discovery Version 2 (MLDv2) Protocols", RFC 5790, 563 DOI 10.17487/RFC5790, February 2010, 564 . 566 [RFC6458] Stewart, R., Tuexen, M., Poon, K., Lei, P., and V. 567 Yasevich, "Sockets API Extensions for the Stream Control 568 Transmission Protocol (SCTP)", RFC 6458, 569 DOI 10.17487/RFC6458, December 2011, 570 . 572 [RFC6633] Gont, F., "Deprecation of ICMP Source Quench Messages", 573 RFC 6633, DOI 10.17487/RFC6633, May 2012, 574 . 576 [RFC6936] Fairhurst, G. and M. Westerlund, "Applicability Statement 577 for the Use of IPv6 UDP Datagrams with Zero Checksums", 578 RFC 6936, DOI 10.17487/RFC6936, April 2013, 579 . 581 [RFC7657] Black, D., Ed. and P. Jones, "Differentiated Services 582 (Diffserv) and Real-Time Communication", RFC 7657, 583 DOI 10.17487/RFC7657, November 2015, 584 . 586 [STEVENS] "Stevens, W., Fenner, B., and A. Rudoff, "UNIX Network 587 Programming, The sockets Networking API", Addison- 588 Wesley.", 2004. 590 Appendix A. Revision Notes 592 Note to RFC-Editor: please remove this entire section prior to 593 publication. 595 Individual draft -00: 597 o This is the first version. Comments and corrections are welcome 598 directly to the authors or via the IETF TAPS working group mailing 599 list. 601 Individual draft -01: 603 o Includes ability of a UDP receiver to disallow zero checksum 604 datagrams. 606 o Fixes to references and some connect on UDP usage. 608 Individual draft -02: 610 o Fixes to address issues noted by WG. 612 o Completed Multicast section to specify modern APIs. 614 o Noted comments on API usage for UDP. 616 o Feedback from various reviewers. 618 Individual draft -03: 620 o Removes pass 2 and 3 of the TAPS analysis from this revision. 621 These are expected to be incorporated into a combined draft of the 622 TAPS WG. 624 o Fixed Typos. 626 Appendix B. Notes Based on Typical Usage 628 This appendix contains notes to assist in a later revision. 630 The de facto standard application programming interface (API) for 631 TCP/IP applications is the "sockets" interface[POSIX]. Some 632 platforms also offer applications the ability to directly assemble 633 and transmit IP packets through "raw sockets" or similar facilities. 634 This is a second, more cumbersome method of using UDP. The use of 635 this API is discussed in the RFC series in 636 [I-D.ietf-tsvwg-rfc5405bis]. 638 The UDP sockets API differs from that for TCP in several key ways. 639 Because application programmers are typically more familiar with the 640 TCP sockets API, this section discusses these differences. [STEVENS] 641 provides usage examples of the UDP sockets API. 643 This section provides notes on some topics relating to implemented 644 UDP APIs. 646 A UDP application can use the recv() and send() POSIX functions as 647 well as the recvfrom() and sendto() and recvmsg and sendmsg() 648 functions. 650 SO_REUSEADDR specifies that the rules used in validating addresses 651 supplied to bind() should allow reuse of local addresses. 653 SO_REUSEPORT specifies that the rules used in validating ports 654 supplied to bind() should allow reuse of a local port 656 Accessing TTL From applications: If the IP_RECVTTL option is enabled 657 on a SOCK_DGRAM socket, the recvmsg(2) call will return the IP TTL 658 (time to live) field for a UDP datagram. The msg_control field in 659 the msghdr structure points to a buffer that contains a cmsghdr 660 structure followed by the TTL. 662 Appendix C. UDP Multicast 664 UDP and UDP-Lite Multicast may be considered in later versions of 665 this document. This appendix contains notes to assist in this later 666 revision. 668 A host must request the ability to broadcast before it can send/ 669 receive ipv4 broadcast traffic. A host must become a member of a 670 multicast group at the network layer before it can receive datagrams 671 sent to the group. 673 C.1. Multicast Primitives 675 UDP and UDP-Lite support IPv4 broadcast and IPv4/IPv6 Multicast. Use 676 of multicast requires additional functions at the transport API that 677 must be called to coordinate operation of the IPv4 and IPv6 network 678 layer protocols. 680 Guidance on the use of UDP and UDP-Lite for multicast services is 681 provided in [I-D.ietf-tsvwg-rfc5405bis]. 683 The following are defined: 685 JoinLocalGroup: 1 of [RFC3493] provides a function that allows 686 joining of a local IPv4 multicast group. 688 IPV6_MULTICAST_IF: Section 5.2 of [RFC2553] states that this sets 689 the interface to use for outgoing multicast packets. 691 IP_MULTICAST_TTL: This sets the hop limit to use for outgoing 692 multicast packets. This is used to limit scope of multicast 693 datagrams. When used for applications such as GTSM, this needs 694 the UDP receiver API to pass the received value of this field to 695 the application. (This is equivalent to IPV6_MULTICAST_HOPS for 696 IPv6 multicast and TTL/IPV6_UNICAST_HOPS for unicast datagrams). 698 IPV6_MULTICAST_HOPS: Section 5.2 of [RFC2553] states that this sets 699 the hop limit to use for outgoing multicast packets. When used 700 for applications such as GTSM, this needs the UDP receiver API to 701 pass the received value of this field to the application. (This 702 is equivalent to IP_MULTICAST_TTL for IPv4 multicast and TTL/ 703 IPV6_UNICAST_HOPS for unicast datagrams). 705 IPV6_MULTICAST_LOOP: Section 5.2 of [RFC2553] states that this sets 706 whether a copy of a datagram is looped back by the IP layer for 707 local delivery when the datagram is sent to a group to which the 708 sending host itself belongs). 710 IPV6_JOIN_GROUP: Section 5.2 of [RFC2553] provides a function that 711 allows joining of an IPv6 multicast group. 713 SIOCGIPMSFILTER: Section 8.1 of [RFC3678] provides a function that 714 allows reading the multicast source filters. 716 SIOCSIPMSFILTER: Section 8.1 of [RFC3678] provides a function that 717 allows setting/modifying the multicast source filters. 719 IPV6_LEAVE_GROUP: Section 5.2 of [RFC2553] provides a function that 720 allows leaving of a multicast group. 722 LeaveHostGroup: Section 7.1 of [RFC3493] provides a function that 723 allows joining of an IPv4 multicast group. 725 LeaveLocalGroup: Section 7.1 of [RFC3493] provides a function that 726 allows joining of a local IPv4 multicast group. 728 Section 4.1.1 of [RFC3678] updates the interface to add support for 729 Multicast Source Filters (MSF) to IGMPv3 for Any Source Multicast 730 (ASM): 732 This identifies three sets of API functionality: 734 1. IPv4 Basic (Delta-based) API. "Each function call specifies a 735 single source address which should be added to or removed from 736 the existing filter for a given multicast group address on which 737 to listen." 739 2. IPv4 Advanced (Full-state) API. "This API allows an application 740 to define a complete source-filter comprised of zero or more 741 source addresses, and replace the previous filter with a new 742 one." 744 3. Protocol-Independent Basic MSF (Delta-based) API 746 4. Protocol-Independent Advanced MSF (Full-state) API 748 It specifies the following primitives: 750 IP_ADD_MEMBERSHIP: This is used to join an ASM group. 752 IP_BLOCK_SOURCE: This is a MSF that can be used to block data from a 753 given multicast source to a given group for ASM or SSM. 755 IP_UNBLOCK_SOURCE: This updates an MSF to undo a previous call to 756 IP_UNBLOCK_SOURCE for ASM or SSM. 758 IP_DROP_MEMBERSHIP: This is used to leave an ASM or SSM group. (In 759 SSM this drops all sources that have been joined for a particular 760 group and interface. The operations are the same as if the socket 761 had been closed.) 763 Section 4.1.2 of [RFC3678] updates the interface to add Multicast 764 Source Filter (MSF) support for IGMPv3 with Any Source Multicast 765 (ASM) using IPv4: 767 IP_ADD_SOURCE_MEMBERSHIP: This is used to join an SSM group. 769 IP_DROP_SOURCE_MEMBERSHIP: This is used to leave an SSM group. 771 Section 4.1.2 of [RFC3678] defines the Advanced (Full-state) API: 773 setipv4sourcefilter This is used to join an IPv4 multicast group, or 774 to enable multicast from a specified source. 776 getipv4sourcefilter: This is used to leave an IPv4 multicast group, 777 or to filter multicast from a specified source. 779 Section 5.1 of [RFC3678] specifies Protocol-Independent Multicast API 780 functions: 782 MCAST_JOIN_GROUP This is used to join an ASM group. 784 MCAST_JOIN_SOURCE_GROUP This is used to join an SSM group. 786 MCAST_BLOCK_SOURCE: This is used to block a source in an ASM group. 788 MCAST_UNBLOCK_SOURCE: This removes a previous MSF set by 789 MCAST_BLOCK_SOURCE: 791 MCAST_LEAVE_GROUP: This leaves a SSM group. 793 MCAST_LEAVE_GROUP: This leaves a ASM or SSM group. 795 Section 5.2 of [RFC3678] specifies the Protocol-Independent Advanced 796 MSF (Full-state) API applicable for both IPv4 and IPv6 multicast: 798 setsourcefilter This is used to join an IPv4 or IPv6 multicast 799 group, or to enable multicast from a specified source. 801 getsourcefilter: This is used to leave an IPv4 or IPv6 multicast 802 group, or to filter multicast from a specified source. 804 Section 7.2 of [RFC5790] updates the interface to specify support for 805 Lightweight IGMPv3 (LW_IGMPv3) and MLDv2. 807 According to the MSF API definition [RFC3678], "an LW-IGMPv3 host 808 should implement either the IPv4 Basic MSF API or the Protocol- 809 Independent Basic MSF API, and an LW-MLDv2 host should implement the 810 Protocol- Independent Basic MSF API. Other APIs, IPv4 Advanced MSF 811 API and Protocol-Independent Advanced MSF API, are optional to 812 implement in an LW-IGMPv3/LW-MLDv2 host." 814 Authors' Addresses 815 Godred Fairhurst 816 University of Aberdeen 817 School of Engineering 818 Fraser Noble Building 819 Fraser Noble Building Aberdeen AB24 3UE 820 UK 822 Email: gorry@erg.abdn.ac.uk 824 Tom Jones 825 University of Aberdeen 826 School of Engineering 827 Fraser Noble Building 828 Aberdeen AB24 3UE 829 UK 831 Email: tom@erg.abdn.ac.uk