idnits 2.17.1 draft-ietf-taps-transports-usage-udp-07.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 (September 19, 2017) is 2403 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-08 -- Obsolete informational reference (is this intentional?): RFC 4566 (Obsoleted by RFC 8866) Summary: 0 errors (**), 0 flaws (~~), 3 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: March 23, 2018 September 19, 2017 7 Features of the User Datagram Protocol (UDP) and Lightweight UDP (UDP- 8 Lite) Transport Protocols 9 draft-ietf-taps-transports-usage-udp-07 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. RFCxxxx 19 documents the usage of transport features provided by IETF transport 20 protocols, describing the way UDP, UDP-Lite and other transport 21 protocols expose their services to applications and how an 22 application can configure and use the features that make up these 23 services. This document provides input to and context for that 24 document, as well as offering a road map to documentation that may be 25 of help to users of the UDP and UDP-Lite protocols. 27 XXX RFC-Ed Note - please replace RFCxxxx with the published RFC 28 number for I-D.ietf-taps-transports-usage, when these documents are 29 both published XXX. 31 Status of This Memo 33 This Internet-Draft is submitted in full conformance with the 34 provisions of BCP 78 and BCP 79. 36 Internet-Drafts are working documents of the Internet Engineering 37 Task Force (IETF). Note that other groups may also distribute 38 working documents as Internet-Drafts. The list of current Internet- 39 Drafts is at https://datatracker.ietf.org/drafts/current/. 41 Internet-Drafts are draft documents valid for a maximum of six months 42 and may be updated, replaced, or obsoleted by other documents at any 43 time. It is inappropriate to use Internet-Drafts as reference 44 material or to cite them other than as "work in progress." 46 This Internet-Draft will expire on March 23, 2018. 48 Copyright Notice 50 Copyright (c) 2017 IETF Trust and the persons identified as the 51 document authors. All rights reserved. 53 This document is subject to BCP 78 and the IETF Trust's Legal 54 Provisions Relating to IETF Documents 55 (https://trustee.ietf.org/license-info) in effect on the date of 56 publication of this document. Please review these documents 57 carefully, as they describe your rights and restrictions with respect 58 to this document. Code Components extracted from this document must 59 include Simplified BSD License text as described in Section 4.e of 60 the Trust Legal Provisions and are provided without warranty as 61 described in the Simplified BSD License. 63 Table of Contents 65 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 66 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 67 3. UDP and UDP-Lite Primitives . . . . . . . . . . . . . . . . . 4 68 3.1. Primitives Provided by UDP . . . . . . . . . . . . . . . 4 69 3.1.1. Excluded Primitives . . . . . . . . . . . . . . . . . 11 70 3.2. Primitives Provided by UDP-Lite . . . . . . . . . . . . . 11 71 4. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 12 72 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 73 6. Security Considerations . . . . . . . . . . . . . . . . . . . 12 74 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 13 75 7.1. Normative References . . . . . . . . . . . . . . . . . . 13 76 7.2. Informative References . . . . . . . . . . . . . . . . . 14 77 Appendix A. Multicast Primitives . . . . . . . . . . . . . . . . 16 78 Appendix B. Revision Notes . . . . . . . . . . . . . . . . . . . 19 79 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 22 81 1. Introduction 83 This document presents defined interactions between transport 84 protocols and applications in the form of 'primitives' (function 85 calls) for the User Datagram Protocol (UDP) [RFC0768] and the 86 Lightweight User Datagram Protocol (UDP-Lite) [RFC3828]. In this 87 usage, the word application refers to any program built on the 88 datagram interface, and including tunnels and other upper layer 89 protocols that use UDP and UDP-LIte. 91 UDP is widely implemented and deployed. It is used for a wide range 92 of applicatons. A special class of applications can derive benefit 93 from having partially damaged payloads delivered, rather than 94 discarded, when using paths that include error-prone links. 95 Applications that can tolerate payload corruption can choose to use 96 UDP-Lite instead of UDP and use the application programming interface 97 (API) to control checksum protection. Conversely, UDP applications 98 could choose to use UDP-Lite, but this is currently less widely 99 deployed and users could encounter paths that do not support UDP- 100 LIte. These topics are discussed more in section 3.4 of the UDP 101 Usage Guidelines [RFC8085]. 103 The IEEE standard API for TCP/IP applications is the "socket" 104 interface [POSIX]. An application can use the recv() and send() 105 POSIX functions as well as the recvfrom() and sendto() and recvmsg() 106 and sendmsg() functions. The UDP and UDP-Lite sockets API differs 107 from that for TCP in several key ways. (Examples of usage of this 108 API are provided in [STEVENS].) In UDP and UDP-Lite, each datagram 109 is a self-contained message of a specified length, and options at the 110 transport layer can be used to set properties for all subsequent 111 datagrams sent using a socket or changed for each datagram. For 112 datagrams, this can require the application to use the API to set IP- 113 level information (the IP Time To Live (TTL), Differentiated Services 114 (DiffServ) Code Point, IP fragmentation, etc) for the datagrams it 115 sends and receives. In contrast, when using TCP and other 116 connection-oriented transports, the IP-level information normally 117 either remains the same for the duration of a connection or is 118 controlled by the transport protocol rather than the application. 120 Socket options are used in the socket API to provide additional 121 functions For example, the IP_RECVTTL socket option is used by some 122 UDP multicast applications to return the IP TTL field from IP header 123 of a received datagram. 125 Some platforms also offer applications the ability to directly 126 assemble and transmit IP packets through "raw sockets" or similar 127 facilities. The raw socket API is a second, more cumbersome, method 128 to send UDP datagrams. The use of this API is discussed in the RFC 129 series in the UDP Guidelines [RFC8085]. 131 The list of transport service features and primitives in this 132 document is strictly based on the parts of protocol specifications in 133 RFC-series that relate to what the transport protocol provides to an 134 application that uses it and how the application interacts with the 135 transport protocol. Primitives can be invoked by an application or a 136 transport protocol; the latter type is called an "event". 138 The description in Section 3 follows the methodology defined by the 139 IETF TAPS working group in [I-D.ietf-taps-transports-usage]. 140 Specifically, this document provides the first pass of this process, 141 which discusses the relevant RFC text describing primitives for each 142 protocol. [I-D.ietf-taps-transports-usage] uses this input to 143 document the usage of transport features provided by IETF transport 144 protocols, describing the way UDP, UDP-Lite and other transport 145 protocols expose their services to applications and how an 146 application can configure and use the features that make up these 147 services. 149 The presented road map to documentation of the transport interface 150 may also help developers working with UDP and UDP-Lite. 152 2. Terminology 154 This document provides details for the Pass 1 analysis of UDP and 155 UDP-Lite that is used in "Usage of Transport Features Provided by 156 IETF Transport Protocols" [I-D.ietf-taps-transports-usage]. It uses 157 common terminology defined in that document and also quotes RFCs that 158 use the terminology of RFC 2119 [RFC2119]. 160 3. UDP and UDP-Lite Primitives 162 The User Datagram Protocol (UDP) [RFC0768][RFC8200] and UDP-Lite 163 protocols [RFC3828] are IETF standards track transport protocols. 164 These protocols provide unidirectional, datagram services, supporting 165 transmit and receive operations that preserve message boundaries. 167 This section summarises the relevant text parts of the RFCs 168 describing the UDP and UDP-Lite protocols, focusing on what the 169 transport protocols provide to the application and how the transport 170 is used (based on abstract API descriptions, where they are 171 available). It describes how UDP is used with IPv4 or IPv6 to send 172 unicast or anycast datagrams and the use to send broadcast datagrams 173 for IPv4. A set of network-layer primitives required to use UDP or 174 UDP-Lite with IP multicast (for IPv4 and IPv6) have been specified in 175 the RFC series. Appendix A describes where to find documentation for 176 network-layer primitives required to use UDP or UDP-Lite with IP 177 multicast (for IPv4 and IPv6). 179 3.1. Primitives Provided by UDP 181 The User Datagram Protocol (UDP) [RFC0768] States: "This User 182 Datagram Protocol (UDP) is defined to make available a datagram mode 183 of packet-switched computer communication in the environment of an 184 interconnected set of computer networks." It "provides a procedure 185 for application programs to send messages to other programs with a 186 minimum of protocol mechanism (..)". 188 The User Interface section of RFC768 states that the user interface 189 to an application should allow "the creation of new receive ports, 190 receive operations on the receive ports that return the data octets 191 and an indication of source port and source address, and an operation 192 that allows a datagram to be sent, specifying the data, source and 193 destination ports and addresses to be sent". 195 UDP has been defined for IPv6 [RFC8200], together with API extensions 196 for a Basic Socket Interface Extensions for IPv6 [RFC3493]. 197 [RFC6935] and [RFC6936] define an update to the UDP transport 198 originally specified in RFC2460. This enables use of a zero UDP 199 checksum mode with a tunnel protocol, providing that the method 200 satisfies the requirements in the corresponding applicability 201 statement [RFC6936]. 203 UDP offers only a basic transport interface. UDP datagrams may be 204 directly sent and received, without exchanging messages between the 205 endpoints to setup a connection (i.e., no handshake is performed by 206 the transport protocol prior to communication). Using the sockets 207 API, applications can receive packets from more than one IP source 208 address on a single UDP socket. Common support allows specification 209 of the local IP address, destination IP address, local port and 210 destination port values. Any or all of these can be indicated, with 211 defaults supplied by the local system when these are not specified. 212 The local endpoint is set using the BIND call and set on the remote 213 endpoint using the CONNECT call. The CLOSE function has local 214 significance only. It does not impact the status of the remote 215 endpoint. 217 Neither UDP nor UDP-Lite provide congestion control, retransmission, 218 nor do they provide mechanisms for application-level packetisation 219 that would avoid IP fragmentation and other transport functions. 220 This means that applications using UDP need to provide additional 221 functions on top of the UDP transport API [RFC8085]. Some transport 222 functions require parameters to be passed through the API to control 223 the network layer (IPv4 or IPv6). These additional primitives could 224 be considered a part of the network layer (e.g., control of the 225 setting of the Don't Fragment (DF) flag on a transmitted IPv4 226 datagram), but are nonetheless essential to allow a user of the UDP 227 API to implement functions that are normally associated with the 228 transport layer (such as probing for the path maximum transmission 229 size). This document includes such primitives. 231 Guidance on the use of the services provided by UDP is provided in 232 the UDP Guidelines [RFC8085]. This also states "many operating 233 systems also allow a UDP socket to be connected, i.e., to bind a UDP 234 socket to a specific pair of addresses and ports. This is similar to 235 the corresponding TCP sockets API functionality. However, for UDP, 236 this is only a local operation that serves to simplify the local 237 send/receive functions and to filter the traffic for the specified 238 addresses and ports. Binding a UDP socket does not establish a 239 connection - UDP does not notify the remote endpoint when a local UDP 240 socket is bound. Binding a socket also allows configuring options 241 that affect the UDP or IP layers, for example, use of the UDP 242 checksum or the IP Timestamp Option. On some stacks, a bound socket 243 also allows an application to be notified when Internet Control 244 Message (ICMP) error messages are received for its transmissions 245 [RFC1122]." 247 The POSIX Base Specifications [POSIX] define an API that offers 248 mechanisms for an application to receive asynchronous data events at 249 the socket layer. Calls such as "poll", "select" or "queue" allow an 250 application to be notified when data has arrived at a socket or when 251 a socket has flushed its buffers. 253 A callback-driven API to the network interface can be structured on 254 top of these calls. Implicit connection setup allows an application 255 to delegate connection life management to the transport API. The 256 transport API uses protocol primitives to offer the automated service 257 to the application via the sockets API. By combining UDP primitives 258 (CONNECT.UDP, SEND.UDP), a higher level API could offer a similar 259 service. 261 The following datagram primitives are specified: 263 CONNECT: The CONNECT primitive allows the association of source and 264 destination port sets to a socket to enable creation of a 265 'connection' for UDP traffic. This UDP connection allows an 266 application to be notified of errors received from the network 267 stack and provides a shorthand access to the send and receive 268 primitives. Since UDP is itself connectionless, no datagrams are 269 sent because this primitive is executed. A further connect call 270 can be used to change the association. 272 The roles of a client and a server are often not appropriate for 273 UDP, where connections can be peer-to-peer. The listening 274 functions are performed using one of the forms of the CONNECT 275 primitive: 277 1. bind(): A bind operation sets the local port, either 278 implicitly, triggered by a "sendto" operation on an unbound 279 unconnected socket using an ephemeral port. Or by an explicit 280 "bind" to use a configured or well-known port. 282 2. bind(); connect(): A bind operation that is followed by a 283 CONNECT primitive. The bind operation establishes the use of 284 a known local port for datagrams, rather than using an 285 ephemeral port. The connect operation specifies a known 286 address port combination to be used by default for future 287 datagrams. This form is used either after receiving a 288 datagram from an endpoint that causes the creation of a 289 connection, or can be triggered by third party configuration 290 or a protocol trigger (such as reception of a UDP Service 291 Description Protocol, SDP [RFC4566], record). 293 SEND: The SEND primitive hands over a provided number of bytes that 294 UDP should send to the other side of a UDP connection in a UDP 295 datagram. The primitive can be used by an application to directly 296 send datagrams to an endpoint defined by an address/port pair. If 297 a connection has been created, then the address/port pair is 298 inferred from the current connection for the socket. Connecting a 299 socket allows network errors to be returned to the application as 300 a notification on the send primitive. Messages passed to the send 301 primitive that cannot be sent atomically in an IP packet will not 302 be sent by the network layer, generating an error. 304 RECEIVE: The RECEIVE primitive allocates a receiving buffer to 305 accommodate a received datagram. The primitive returns the number 306 of bytes provided from a received UDP datagram. Section 4.1.3.5 307 of the requirements of Internet hosts [RFC1122] states "When a UDP 308 datagram is received, its specific-destination address MUST be 309 passed up to the application layer." 311 CHECKSUM_ENABLED: The optional CHECKSUM_ENABLED primitive controls 312 whether a sender enables the UDP checksum when sending datagrams ( 313 [RFC0768] and [RFC6935] [RFC6936] [RFC8085]). When unset, this 314 overrides the default UDP behaviour, disabling the checksum on 315 sending. Section 4.1.3.4 of the requirements for Internet hosts 316 [RFC1122] states "An application MAY optionally be able to control 317 whether a UDP checksum will be generated, but it MUST default to 318 checksumming on." 320 REQUIRE_CHECKSUM: The optional REQUIRE_CHECKSUM primitive determines 321 whether UDP datagrams received with a zero checksum are permitted 322 or discarded, UDP defaults to requiring checksums. 323 Section 4.1.3.4 of the requirements for Internet hosts [RFC1122] 324 states "An application MAY optionally be able to control whether 325 UDP datagrams without checksums should be discarded or passed to 326 the application." Section 3.1 of the specification for UDP-Lite 327 [RFC3828] requires that the checksum field is non-zero, and hence 328 the UDP-Lite API must discard all datagrams received with a zero 329 checksum. 331 SET_IP_OPTIONS: The SET_IP_OPTIONS primitive requests the network- 332 layer to send a datagram with the specified IP options. 333 Section 4.1.3.2 of the requirements for Internet hosts[RFC1122] 334 states that an "application MUST be able to specify IP options to 335 be sent in its UDP datagrams, and UDP MUST pass these options to 336 the IP layer." 338 GET_IP_OPTIONS: The GET_IP_OPTIONS primitive retrieves the IP 339 options of a datagram received at the network-layer. 340 Section 4.1.3.2 of the requirements for Internet hosts[RFC1122] 341 states that a UDP receiver "MUST pass any IP option that it 342 receives from the IP layer transparently to the application 343 layer". 345 SET_DF: The SET_DF primitive allows the network-layer to fragment 346 packets using the Fragment Offset in IPv4 [RFC6864] and a host to 347 use Fragment Headers in IPv6 [RFC8200]. The SET_DF primitive sets 348 the Don't Fragment (DF) flag in the IPv4 packet header that 349 carries a UDP datagram, which allows routers to fragment IPv4 350 packets. Although some specific applications rely on 351 fragmentation support, in general, a UDP application should 352 implement a method that avoids IP fragmentation (section 4 of 353 [RFC8085]). NOTE: In many other IETF transports (e.g., TCP, SCTP) 354 the transport provides the support needed to use DF. However, 355 when using UDP, the application is responsible for the techniques 356 needed to discover the effective Path Maximum Transmission Unit 357 (PMTU) allowed on the network path, coordinating with the network 358 layer. Classical PMTU Discovery (PMTUD) [RFC1191] relies upon the 359 network path returning ICMP Fragmentation Needed or ICMPv6 Packet 360 Too Big messages to the sender. When these ICMP messages are not 361 delivered (or filtered) a sender is unable to learn the actual 362 path MTU, and UDP Datagrams larger than the PMTU will be "black 363 holed". To avoid this, an application can instead implement 364 Packetization Layer Path MTU Discovery (PLPMTUD) [RFC4821] that 365 does not rely upon network support for ICMPv6 messages and is 366 therefore considered more robust than standard PMTUD, as 367 recommended in [RFC8085] and [RFC8201]. 369 GET_MMS_S: The GET_MMS_S primitive retrieves a network-layer value 370 that indicates the maximum message size (MMS) that may be sent at 371 the transport layer using a non-fragmented IP packet from the 372 configured interface. This value is specified in section 6.1 of 373 [RFC1191] and section 5.1 of [RFC8201]. It is calculated from 374 Effective Maximum Transmit Unit for Sending (EMTU_S), and the link 375 MTU for the given source IP address. This takes into account the 376 size of the IP header plus space reserved by the IP layer for 377 additional headers (if any). UDP applications should use this 378 value as part of a method to avoid sending UDP datagrams that 379 would result in IP packets that exceed the effective PMTU allowed 380 across the network path. The effective PMTU (specified in 381 Section 1 of [RFC1191]) is equivalent to the EMTU_S (specified in 383 [RFC1122]). The specification of PLPMTUD [RFC4821] states: "If 384 PLPMTUD updates the MTU for a particular path, all Packetization 385 Layer sessions that share the path representation (as described in 386 Section 5.2) SHOULD be notified to make use of the new MTU and 387 make the required congestion control adjustments". 389 GET_MMS_R: The GET_MMS_R primitive retrieves a network-layer value 390 that indicates the maximum message size (MMS) that may be received 391 at the transport layer from the configured interface. This value 392 is specified in section 3.1 of [RFC1191]. It is calculated from 393 Effective Maximum Transmit Unit for Receiving (EMTU_R), and the 394 link MTU for the given source IP address, and takes into account 395 the size of the IP header plus space reserved by the IP layer for 396 additional headers (if any). 398 SET_TTL: The SET_TTL primitive sets the hop limit (TTL field) in the 399 network-layer that is used in the IPv4 header of a packet that 400 carries an UDP datagram. This is used to limit the scope of 401 unicast datagrams. Section 3.2.2.4 of the requirements for 402 Internet hosts [RFC1122] states an "incoming Time Exceeded message 403 MUST be passed to the transport layer". 405 GET_TTL: The GET_TTL primitive retrieves the value of the TTL field 406 in an IP packet received at the network layer. An application 407 using the Generalized TTL Security Mechanism (GTSM) [RFC5082] can 408 use this information to trust datagrams with a TTL value within 409 the expected range, as described in Section 3 of RFC5082. 411 SET_MIN_TTL: The SET_MIN_TTL primitive restricts Datagrams delivered 412 to the application to those received with an IP TTL value greater 413 than or equal to passed parameter. This primitive can be used to 414 implement applications such as Generalized TTL Security Mechanism 415 (GTSM) [RFC5082] to as described in Section 3 of RFC5082, but this 416 RFC does not specify this method. 418 SET_IPV6_UNICAST_HOPS: The SET_IPV6_UNICAST_HOPS primitive sets the 419 network-layer hop limit field in an IPv6 packet header [RFC8200] 420 carrying a UDP datagram. For IPv6 unicast datagrams, this is 421 functionally equivalent to the SET_TTL IPv4 function. 423 GET_IPV6_UNICAST_HOPS: The GET_IPV6_UNICAST_HOPS primitive is a 424 network-layer function that reads the hop count in the IPv6 header 425 [RFC8200] information of a received UDP datagram. This is 426 specified in section 6.3 of RFC3542. For IPv6 unicast datagrams, 427 this is functionally equivalent to the GET_TTL IPv4 function. 429 SET_DSCP: The SET_DSCP primitive is a network-layer function that 430 sets the DSCP, (or the legacy Type of Service, ToS) value 432 [RFC2474] to be used in the field of an IP header of a packet that 433 carries a UDP datagram. Section 2.4 of the requirements for 434 Internet hosts[RFC1123] states that "Applications MUST select 435 appropriate ToS values when they invoke transport layer services, 436 and these values MUST be configurable.". The application should 437 be able to change the ToS during the connection lifetime, and the 438 ToS value should be passed to the IP layer unchanged. 439 Section 4.1.4 of [RFC1122] also states that on reception the "UDP 440 MAY pass the received ToS value up to the application layer". The 441 DiffServ model [RFC2475] [RFC3260] replaces this field in the IP 442 Header assigning the six most significant bits to carry the DSCP 443 field [RFC2474]. Preserving the intention of the host 444 requirements [RFC1122] to allow the application to specify the 445 "Type of Service", this should be interpreted to mean that an API 446 should allow the application to set the DSCP. Section 3.1.6 of 447 the UDP Guidelines [RFC8085] describes the way UDP applications 448 should use this field. Normally a UDP socket will assign a single 449 DSCP value to all datagrams in a flow, but a sender is allowed to 450 use different DSCP values for datagrams within the same flow in 451 certain cases[RFC8085]. There are guidelines for WebRTC that 452 illustrate this use [RFC7657]. 454 SET_ECN: The SET_ECN primitive is a network-layer function that sets 455 the Explicit Congestion Notification (ECN) field in the IP Header 456 of a UDP datagram. The ECN field defaults to a value of 00. When 457 the use of the ToS field was redefined by DiffServ [RFC3260], 2 458 bits of the field were assigned to support ECN [RFC3168]. 459 Section 3.1.5 of the UDP Guidelines [RFC8085] describes the way 460 UDP applications should use this field. NOTE: In many other IETF 461 transports (e.g., TCP) the transport provides the support needed 462 to use ECN, when using UDP, the application or higher layer 463 protocol is itself responsible for the techniques needed to use 464 ECN. 466 GET_ECN: The GET_ECN primitive is a network-layer function that 467 returns the value of the ECN field in the IP Header of a received 468 UDP datagram. Section 3.1.5 of the UDP Guidelines [RFC8085] 469 states that a UDP receiver "MUST check the ECN field at the 470 receiver for each UDP datagram that it receives on this port", 471 requiring the UDP receiver API to pass to pass the received ECN 472 field up to the application layer to enable appropriate congestion 473 feedback. 475 ERROR_REPORT The ERROR_REPORT event informs an application of "soft 476 errors", including the arrival of an ICMP or ICMPv6 error message. 477 Section 4.1.4 of the host requirements [RFC1122] states "UDP MUST 478 pass to the application layer all ICMP error messages that it 479 receives from the IP layer." For example, this event is required 480 to implement ICMP-based Path MTU Discovery [RFC1191] [RFC8201]. 481 UDP applications must perform a CONNECT to receive ICMP errors. 483 CLOSE: The close primitive closes a connection. No further 484 datagrams can be sent or received. Since UDP is itself 485 connectionless, no datagrams are sent when this primitive is 486 executed. 488 3.1.1. Excluded Primitives 490 Section 3.4 of the host requirements [RFC1122] also describes 491 "GET_MAXSIZES, GET_SRCADDR (Section 3.3.4.3) and ADVISE_DELIVPROB:". 492 These mechanisms are no longer used. It also specifies use of the 493 Source Quench ICMP message, which has since been deprecated 494 [RFC6633]. 496 The IPV6_V6ONLY function is a network-layer primitive that applies to 497 all transport services, defined in Section 5.3 of the basic socket 498 interface for IPv6 [RFC3493]. This restricts the use of information 499 from the name resolver to only allow communication of AF_INET6 500 sockets to use IPv6 only. This is not considered part of the 501 transport service. 503 3.2. Primitives Provided by UDP-Lite 505 The Lightweight User Datagram Protocol (UDP-Lite) [RFC3828] provides 506 similar services to UDP. It changed the semantics of the UDP 507 "payload length" field to that of a "checksum coverage length" field. 508 UDP-Lite requires the pseudo-header checksum to be computed at the 509 sender and checked at a receiver. Apart from the length and coverage 510 changes, UDP-Lite is semantically identical to UDP. 512 The sending interface of UDP-Lite differs from that of UDP by the 513 addition of a single (socket) option that communicates the checksum 514 coverage length. This specifies the intended checksum coverage, with 515 the remaining unprotected part of the payload called the "error- 516 insensitive part". 518 The receiving interface of UDP-Lite differs from that of UDP by the 519 addition of a single (socket) option that specifies the minimum 520 acceptable checksum coverage. The UDP-Lite Management Information 521 Base (MIB) [RFC5097] further defines the checksum coverage method. 522 Guidance on the use of services provided by UDP-Lite is provided in 523 the UDP Guidelines [RFC8085]. 525 UDP-Lite requires use of the UDP or UDP-Lite checksum, and hence it 526 is not permitted to use the "DISABLE_CHECKSUM:" function to disable 527 use of a checksum, nor is it possible to disable receiver checksum 528 processing using the "REQUIRE_CHECKSUM:" function . All other 529 primitives and functions for UDP are permitted. 531 In addition, the following are defined: 533 SET_CHECKSUM_COVERAGE: The SET_CHECKSUM_COVERAGE primitive sets the 534 coverage area for a sent datagram. UDP-Lite traffic uses this 535 primitive to set the coverage length provided by the UDP checksum. 536 Section 3.3 of the UDP-Lite MIB [RFC5097] states that 537 "Applications that wish to define the payload as partially 538 insensitive to bit errors ... Should do this by an explicit 539 system call on the sender side." The default is to provide the 540 same coverage as for UDP. 542 SET_MIN_COVERAGE The SET_MIN_COVERAGE primitive sets the minimum 543 acceptable coverage protection for received datagrams. UDP-Lite 544 traffic uses this primitive to set the coverage length that is 545 checked on receive. (Section 1.1 of the UDP-Lite MIB [RFC5097] 546 describes the corresponding MIB entry as 547 udpliteEndpointMinCoverage.) Section 3.3 of the UDP-Lite 548 specification [RFC3828] states that "applications that wish to 549 receive payloads that were only partially covered by a checksum 550 should inform the receiving system by an explicit system call". 551 The default is to require only minimal coverage of the datagram 552 payload. 554 4. Acknowledgements 556 This work was partially funded by the European Union's Horizon 2020 557 research and innovation programme under grant agreement No. 644334 558 (NEAT). Thanks to all who have commented or contributed, including 559 Joe Touch, Ted Hardie, Aaron Falk, Tommy Pauly, and Francis Dupont. 561 5. IANA Considerations 563 This memo includes no request to IANA. 565 The authors request the section to be removed during conversion into 566 an RFC by the RFC Editor. 568 6. Security Considerations 570 Security considerations for the use of UDP and UDP-Lite are provided 571 in the referenced RFCs. Security guidance for application usage is 572 provided in the UDP-Guidelines [RFC8085]. 574 7. References 576 7.1. Normative References 578 [I-D.ietf-taps-transports-usage] 579 Welzl, M., Tuexen, M., and N. Khademi, "On the Usage of 580 Transport Features Provided by IETF Transport Protocols", 581 draft-ietf-taps-transports-usage-08 (work in progress), 582 August 2017. 584 [RFC0768] Postel, J., "User Datagram Protocol", STD 6, RFC 768, 585 DOI 10.17487/RFC0768, August 1980, 586 . 588 [RFC1112] Deering, S., "Host extensions for IP multicasting", STD 5, 589 RFC 1112, DOI 10.17487/RFC1112, August 1989, 590 . 592 [RFC1122] Braden, R., Ed., "Requirements for Internet Hosts - 593 Communication Layers", STD 3, RFC 1122, 594 DOI 10.17487/RFC1122, October 1989, 595 . 597 [RFC1123] Braden, R., Ed., "Requirements for Internet Hosts - 598 Application and Support", STD 3, RFC 1123, 599 DOI 10.17487/RFC1123, October 1989, 600 . 602 [RFC1191] Mogul, J. and S. Deering, "Path MTU discovery", RFC 1191, 603 DOI 10.17487/RFC1191, November 1990, 604 . 606 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 607 Requirement Levels", BCP 14, RFC 2119, 608 DOI 10.17487/RFC2119, March 1997, 609 . 611 [RFC3168] Ramakrishnan, K., Floyd, S., and D. Black, "The Addition 612 of Explicit Congestion Notification (ECN) to IP", 613 RFC 3168, DOI 10.17487/RFC3168, September 2001, 614 . 616 [RFC3493] Gilligan, R., Thomson, S., Bound, J., McCann, J., and W. 617 Stevens, "Basic Socket Interface Extensions for IPv6", 618 RFC 3493, DOI 10.17487/RFC3493, February 2003, 619 . 621 [RFC3828] Larzon, L-A., Degermark, M., Pink, S., Jonsson, L-E., Ed., 622 and G. Fairhurst, Ed., "The Lightweight User Datagram 623 Protocol (UDP-Lite)", RFC 3828, DOI 10.17487/RFC3828, July 624 2004, . 626 [RFC6864] Touch, J., "Updated Specification of the IPv4 ID Field", 627 RFC 6864, DOI 10.17487/RFC6864, February 2013, 628 . 630 [RFC6935] Eubanks, M., Chimento, P., and M. Westerlund, "IPv6 and 631 UDP Checksums for Tunneled Packets", RFC 6935, 632 DOI 10.17487/RFC6935, April 2013, 633 . 635 [RFC6936] Fairhurst, G. and M. Westerlund, "Applicability Statement 636 for the Use of IPv6 UDP Datagrams with Zero Checksums", 637 RFC 6936, DOI 10.17487/RFC6936, April 2013, 638 . 640 [RFC8085] Eggert, L., Fairhurst, G., and G. Shepherd, "UDP Usage 641 Guidelines", BCP 145, RFC 8085, DOI 10.17487/RFC8085, 642 March 2017, . 644 [RFC8200] Deering, S. and R. Hinden, "Internet Protocol, Version 6 645 (IPv6) Specification", STD 86, RFC 8200, 646 DOI 10.17487/RFC8200, July 2017, 647 . 649 [RFC8201] McCann, J., Deering, S., Mogul, J., and R. Hinden, Ed., 650 "Path MTU Discovery for IP version 6", STD 87, RFC 8201, 651 DOI 10.17487/RFC8201, July 2017, 652 . 654 7.2. Informative References 656 [POSIX] "IEEE Std. 1003.1-2001, , "Standard for Information 657 Technology - Portable Operating System Interface (POSIX)", 658 Open Group Technical Standard: Base Specifications Issue 659 6, ISO/IEC 9945:2002", December 2001. 661 [RFC2474] Nichols, K., Blake, S., Baker, F., and D. Black, 662 "Definition of the Differentiated Services Field (DS 663 Field) in the IPv4 and IPv6 Headers", RFC 2474, 664 DOI 10.17487/RFC2474, December 1998, 665 . 667 [RFC2475] Blake, S., Black, D., Carlson, M., Davies, E., Wang, Z., 668 and W. Weiss, "An Architecture for Differentiated 669 Services", RFC 2475, DOI 10.17487/RFC2475, December 1998, 670 . 672 [RFC3260] Grossman, D., "New Terminology and Clarifications for 673 Diffserv", RFC 3260, DOI 10.17487/RFC3260, April 2002, 674 . 676 [RFC3376] Cain, B., Deering, S., Kouvelas, I., Fenner, B., and A. 677 Thyagarajan, "Internet Group Management Protocol, Version 678 3", RFC 3376, DOI 10.17487/RFC3376, October 2002, 679 . 681 [RFC3678] Thaler, D., Fenner, B., and B. Quinn, "Socket Interface 682 Extensions for Multicast Source Filters", RFC 3678, 683 DOI 10.17487/RFC3678, January 2004, 684 . 686 [RFC3810] Vida, R., Ed. and L. Costa, Ed., "Multicast Listener 687 Discovery Version 2 (MLDv2) for IPv6", RFC 3810, 688 DOI 10.17487/RFC3810, June 2004, 689 . 691 [RFC4566] Handley, M., Jacobson, V., and C. Perkins, "SDP: Session 692 Description Protocol", RFC 4566, DOI 10.17487/RFC4566, 693 July 2006, . 695 [RFC4604] Holbrook, H., Cain, B., and B. Haberman, "Using Internet 696 Group Management Protocol Version 3 (IGMPv3) and Multicast 697 Listener Discovery Protocol Version 2 (MLDv2) for Source- 698 Specific Multicast", RFC 4604, DOI 10.17487/RFC4604, 699 August 2006, . 701 [RFC4821] Mathis, M. and J. Heffner, "Packetization Layer Path MTU 702 Discovery", RFC 4821, DOI 10.17487/RFC4821, March 2007, 703 . 705 [RFC5082] Gill, V., Heasley, J., Meyer, D., Savola, P., Ed., and C. 706 Pignataro, "The Generalized TTL Security Mechanism 707 (GTSM)", RFC 5082, DOI 10.17487/RFC5082, October 2007, 708 . 710 [RFC5097] Renker, G. and G. Fairhurst, "MIB for the UDP-Lite 711 protocol", RFC 5097, DOI 10.17487/RFC5097, January 2008, 712 . 714 [RFC5790] Liu, H., Cao, W., and H. Asaeda, "Lightweight Internet 715 Group Management Protocol Version 3 (IGMPv3) and Multicast 716 Listener Discovery Version 2 (MLDv2) Protocols", RFC 5790, 717 DOI 10.17487/RFC5790, February 2010, 718 . 720 [RFC6633] Gont, F., "Deprecation of ICMP Source Quench Messages", 721 RFC 6633, DOI 10.17487/RFC6633, May 2012, 722 . 724 [RFC7657] Black, D., Ed. and P. Jones, "Differentiated Services 725 (Diffserv) and Real-Time Communication", RFC 7657, 726 DOI 10.17487/RFC7657, November 2015, 727 . 729 [STEVENS] "Stevens, W., Fenner, B., and A. Rudoff, "UNIX Network 730 Programming, The sockets Networking API", Addison- 731 Wesley.", 2004. 733 Appendix A. Multicast Primitives 735 This appendix describes primitives that are used when UDP and UDP- 736 Lite support IPv4/IPv6 Multicast. Multicast services are not 737 considered by the IETF TAPS WG, but the currently specified 738 primitives are included for completeness in this appendix. Guidance 739 on the use of UDP and UDP-Lite for multicast services is provided in 740 the UDP Guidelines[RFC8085]. 742 IP multicast may be supported using the Any Source Multicast (ASM) 743 model or by the Source-Specific Multicast (SSM) model. The latter 744 requires use of a Multicast Source Filter (MSF) when specifying an IP 745 multicast group destination address. 747 Use of multicast requires additional primitives at the transport API 748 that need to be called to coordinate operation of the IPv4 and IPv6 749 network layer protocols. For example, to receive datagrams sent to a 750 group, an endpoint must first become a member of a multicast group at 751 the network layer. Local multicast reception is signalled for IPv4 752 by the Internet Group Management Protocol (IGMP) [RFC3376] [RFC4604]. 753 IPv6 uses the equivalent Multicast Listener Discovery (MLD) protocol 754 [RFC3810] [RFC5790], carried over ICMPv6. A lightweight version of 755 these protocols has also been specified [RFC5790]. 757 The following are defined: 759 JoinGroup: Section 7.1 of the Host Extensions for IP Multicasting 760 [RFC1112] provides a function that allows receiving traffic from 761 an IP multicast group. 763 JoinLocalGroup: Section 7.2 of the Host Extensions for IP 764 Multicasting [RFC1112] provides a function that allows receiving 765 traffic from a local IP multicast group. 767 LeaveHostGroup: Section 7.1 of the Host Extensions for IP 768 Multicasting [RFC1112] provides a function that allows leaving an 769 IP multicast group. 771 LeaveLocalGroup: Section 7.2 of the Host Extensions for IP 772 Multicasting [RFC1112] provides a function that allows leaving a 773 local IP multicast group. 775 IPV6_MULTICAST_IF: Section 5.2 of the basic socket extensions for 776 IPv6 [RFC3493] states that this sets the interface that will be 777 used for outgoing multicast packets. 779 IP_MULTICAST_TTL: This sets the time to live field t to use for 780 outgoing IPv4 multicast packets. This is used to limit scope of 781 multicast datagrams. Methods such as The Generalized TTL Security 782 Mechanism (GTSM) [RFC5082], set this value to ensure link-local 783 transmission. GTSM also requires the UDP receiver API to pass the 784 received value of this field to the application. 786 IPV6_MULTICAST_HOPS: Section 5.2 of the basic socket extensions for 787 IPv6 [RFC3493] states that sets the hop count to use for outgoing 788 multicast IPv6 packets. (This is equivalent to IP_MULTICAST_TTL 789 used for IPv4 multicast). 791 IPV6_MULTICAST_LOOP: Section 5.2 of the basic socket extensions for 792 IPv6 [RFC3493] states that this sets whether a copy of a datagram 793 is looped back by the IP layer for local delivery when the 794 datagram is sent to a group to which the sending host itself 795 belongs). 797 IPV6_JOIN_GROUP: Section 5.2 of the basic socket extensions for IPv6 798 [RFC3493] provides a function that allows an endpoint to join an 799 IPv6 multicast group. 801 SIOCGIPMSFILTER: Section 8.1 of the socket interface for MSF 802 [RFC3678] provides a function that allows reading the multicast 803 source filters. 805 SIOCSIPMSFILTER: Section 8.1 of the socket interface for MSF 806 [RFC3678] provides a function that allows setting/modifying the 807 multicast source filters. 809 IPV6_LEAVE_GROUP: Section 5.2 of the basic socket extensions for 810 IPv6 [RFC3493] provides a function that allows leaving an IPv6 811 multicast group. 813 Section 4.1.1 of the Socket Interface Extensions for MSF [RFC3678] 814 updates the multicast interface to add support for MSF for IPv4 and 815 IPv6 required by IGMPv3. Three sets of API functionality are 816 defined: 818 1. IPv4 Basic (Delta-based) API. "Each function call specifies a 819 single source address which should be added to or removed from 820 the existing filter for a given multicast group address on which 821 to listen." 823 2. IPv4 Advanced (Full-state) API. "This API allows an application 824 to define a complete source-filter comprised of zero or more 825 source addresses, and replace the previous filter with a new 826 one." 828 3. Protocol-Independent Basic MSF (Delta-based) API. 830 4. Protocol-Independent Advanced MSF (Full-state) API. 832 It specifies the following primitives: 834 IP_ADD_MEMBERSHIP: This is used to join an ASM group. 836 IP_BLOCK_SOURCE: This MSF can block data from a given multicast 837 source to a given ASM or SSM group. 839 IP_UNBLOCK_SOURCE: This updates an MSF to undo a previous call to 840 IP_UNBLOCK_SOURCE for an ASM or SSM group. 842 IP_DROP_MEMBERSHIP: This is used to leave an ASM or SSM group. (In 843 SSM, this drops all sources that have been joined for a particular 844 group and interface. The operations are the same as if the socket 845 had been closed.) 847 Section 4.1.2 of the socket interface for MSF [RFC3678] updates the 848 interface to add IPv4 MSF support to IGMPv3 using ASM: 850 IP_ADD_SOURCE_MEMBERSHIP: This is used to join an SSM group. 852 IP_DROP_SOURCE_MEMBERSHIP: This is used to leave an SSM group. 854 Section 4.1.2 of the socket interface for MSF [RFC3678] defines the 855 Advanced (Full-state) API: 857 setipv4sourcefilter This is used to join an IPv4 multicast group, or 858 to enable multicast from a specified source. 860 getipv4sourcefilter: This is used to leave an IPv4 multicast group, 861 or to filter multicast from a specified source. 863 Section 5.1 of the socket interface for MSF [RFC3678] specifies 864 Protocol-Independent Multicast API functions: 866 MCAST_JOIN_GROUP This is used to join an ASM group. 868 MCAST_JOIN_SOURCE_GROUP This is used to join an SSM group. 870 MCAST_BLOCK_SOURCE: This is used to block a source in an ASM group. 872 MCAST_UNBLOCK_SOURCE: This removes a previous MSF set by 873 MCAST_BLOCK_SOURCE. 875 MCAST_LEAVE_GROUP: This leaves an ASM or SSM group. 877 MCAST_LEAVE_SOURCE_GROUP: This leaves a SSM group. 879 Section 5.2 of the socket interface for MSF [RFC3678] specifies the 880 Protocol-Independent Advanced MSF (Full-state) API applicable for 881 both IPv4 and IPv6: 883 setsourcefilter This is used to join an IPv4 or IPv6 multicast 884 group, or to enable multicast from a specified source. 886 getsourcefilter: This is used to leave an IPv4 or IPv6 multicast 887 group, or to filter multicast from a specified source. 889 The Lightweight IGMPv3 (LW_IGMPv3) and MLDv2 protocol [RFC5790] 890 updates this interface (in Section 7.2 of RFC5790). 892 Appendix B. Revision Notes 894 Note to RFC-Editor: please remove this entire section prior to 895 publication. 897 Individual draft -00: 899 o This is the first version. Comments and corrections are welcome 900 directly to the authors or via the IETF TAPS working group mailing 901 list. 903 Individual draft -01: 905 o Includes ability of a UDP receiver to disallow zero checksum 906 datagrams. 908 o Fixes to references and some connect on UDP usage. 910 Individual draft -02: 912 o Fixes to address issues noted by WG. 914 o Completed Multicast section to specify modern APIs. 916 o Noted comments on API usage for UDP. 918 o Feedback from various reviewers. 920 Individual draft -03: 922 o Removes pass 2 and 3 of the TAPS analysis from this revision. 923 These are expected to be incorporated into a combined draft of the 924 TAPS WG. 926 o Fixed Typos. 928 TAPS WG draft -00: 930 o Expected to progress with draft-ietf-taps-transports-usage of the 931 TAPS WG. 933 TAPS WG draft -01: 935 o No intentional changes were made to the specification of 936 primitives, this update is editorial 938 o Reorganised text to eliminate the appendices. 940 o Editorial changes were make to complete the document for a WGLSeC. 942 o Rephrasing to eliminate using references as nouns, and to make 943 text more consistent. 945 o One appendix was incorporated. 947 o This appendix was moved to the end (for later deletion by the RFC- 948 Ed). 950 TAPS WG draft -02: 952 o Updated to align with latest taps-transport-usage ID. 954 o Revised to clarify MTU usage and track work in IPv6 PMTU 956 o Usage of DF clarified. 958 o 960 TAPS WG draft -03 962 o edit to MMS entries. 964 TAPS WG draft -04 966 o Typos noted by Tommy Pauly 4/6/2017 and corrected here. 968 o Checked and corrected parenthesis and use of period. 970 o Document Shepherd review 7/2017. 972 o Fixed citations and abbreviations. 974 TAPS WG draft -05 976 o AD review 8/2017. 978 o Updates to reflect published RFCs and refer to PMTUD for IPv6. 980 o Aligned to latest TAPS transport usage ID. 982 TAPS WG draft -06 984 o Fix to text for get TTL and IPv6 Hop Count 986 TAPS WG draft -07 988 o Edit after secdir review - text on how a sender knows how to 989 request UDP-Lite - added a para; 991 o Abstract query about citing TAPS-transports; 993 o Secdir editorial/format fixes have been applied. 995 o Moved the note about "LISTEN:" to the text on "CONNECT:", Mirja 996 suggested clarity that there is no LISTEN primitive for UDP. 998 o Ben Campbell: Clarified the socket options were common examples 999 used by multicast sockets. 1001 o Ben Campbell: Clarified that RFC 2119 is being cited, and not used 1002 to create new terms. 1004 o Ben Campbell: Added a direct copy of the text in RFC 768 1005 describing the User Interface. 1007 o Francis Dupont: Many technical corrections. 1009 Authors' Addresses 1011 Godred Fairhurst 1012 University of Aberdeen 1013 School of Engineering 1014 Fraser Noble Building 1015 Fraser Noble Building Aberdeen AB24 3UE 1016 UK 1018 Email: gorry@erg.abdn.ac.uk 1020 Tom Jones 1021 University of Aberdeen 1022 School of Engineering 1023 Fraser Noble Building 1024 Aberdeen AB24 3UE 1025 UK 1027 Email: tom@erg.abdn.ac.uk