One document matched: draft-fairhurst-taps-transports-usage-udp-02.xml
<?xml version="1.0" encoding="US-ASCII"?>
<!-- This template is for creating an Internet Draft using xml2rfc,
which is available here: http://xml.resource.org. -->
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!-- One method to get references from the online citation libraries.
There has to be one entity for each item to be referenced.
An alternate method (rfc include) is described in the references. -->
<!ENTITY RFC2119 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
<!ENTITY RFC3552 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3552.xml">
<!ENTITY RFC5226 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5226.xml">
<!ENTITY RFC3828 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3828.xml">
<!ENTITY RFC768 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.0768.xml">
<!ENTITY RFC5097 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5097.xml">
<!ENTITY RFC2460 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2460.xml">
<!ENTITY RFC6936 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6936.xml">
<!ENTITY RFC4828 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4828.xml">
<!ENTITY RFC6968 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6968.xml">
<!ENTITY RFC6679 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6679.xml">
<!ENTITY RFC1191 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.1191.xml">
<!ENTITY RFC3168 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3168.xml">
<!ENTITY RFC3395 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3395.xml">
<!ENTITY RFC3396 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3396.xml">
<!ENTITY RFC4566 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4566.xml">
<!ENTITY RFC4821 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4821.xml">
<!ENTITY RFC1981 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.1981.xml">
<!ENTITY RFC6935 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6935.xml">
<!ENTITY RFC3260 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3260.xml">
<!ENTITY RFC2475 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2475.xml">
<!ENTITY RFC1122 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.1122.xml">
<!ENTITY RFC3493 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3493.xml">
<!ENTITY RFC3678 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3678.xml">
<!ENTITY RFC2553 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2553.xml">
<!ENTITY RFC678 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.0678.xml">
<!ENTITY RFC5082 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5082.xml">
<!ENTITY RFC6633 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6633.xml">
<!ENTITY RFC6458 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6458.xml">
<!ENTITY RFC5790 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5790.xml">
<!ENTITY RFC7657 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7657.xml">
<!ENTITY I-D.draft-ietf-tsvwg-rfc5405bis SYSTEM "http://xml2rfc.ietf.org/public/rfc/bibxml3/reference.I-D.draft-ietf-tsvwg-rfc5405bis-07.xml">
<!ENTITY I-D.draft-ietf-aqm-ecn-benefits SYSTEM "http://xml2rfc.ietf.org/public/rfc/bibxml3/reference.I-D.draft-ietf-aqm-ecn-benefits-08.xml">
<!ENTITY I-D.ietf-taps-transports-usage SYSTEM "http://xml2rfc.ietf.org/public/rfc/bibxml3/reference.I-D.ietf-taps-transports-usage.xml">
]>
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
<!-- used by XSLT processors -->
<!-- For a complete list and description of processing instructions (PIs),
please see http://xml.resource.org/authoring/README.html. -->
<!-- Below are generally applicable Processing Instructions (PIs) that most I-Ds might want to use.
(Here they are set differently than their defaults in xml2rfc v1.32) -->
<?rfc strict="yes" ?>
<!-- give errors regarding ID-nits and DTD validation -->
<!-- control the table of contents (ToC) -->
<?rfc toc="yes"?>
<!-- generate a ToC -->
<?rfc tocdepth="4"?>
<!-- the number of levels of subsections in ToC. default: 3 -->
<!-- control references -->
<?rfc symrefs="yes"?>
<!-- use symbolic references tags, i.e, [RFC2119] instead of [1] -->
<?rfc sortrefs="yes" ?>
<!-- sort the reference entries alphabetically -->
<!-- control vertical white space
(using these PIs as follows is recommended by the RFC Editor) -->
<?rfc compact="yes" ?>
<!-- do not start each main section on a new page -->
<?rfc subcompact="no" ?>
<!-- keep one blank line between list items -->
<!-- end of list of popular I-D processing instructions -->
<rfc category="info" docName="draft-fairhurst-taps-transports-usage-udp-02"
ipr="trust200902">
<!-- category values: std, bcp, info, exp, and historic
ipr values: trust200902, noModificationTrust200902, noDerivativesTrust200902,
or pre5378Trust200902
you can add the attributes updates="NNNN" and obsoletes="NNNN"
they will automatically be output with "(if approved)" -->
<!-- ***** FRONT MATTER ***** -->
<front>
<!-- The abbreviated title is used in the page header - it is only necessary if the
full title is longer than 39 characters -->
<title abbrev="UDP Transport Features">Features of the User Datagram
Protocol (UDP) and Lightweight UDP (UDP-Lite) Transport Protocols</title>
<!-- add 'role="editor"' below for the editors if appropriate -->
<!-- Another author who claims to be an editor -->
<author fullname="Godred Fairhurst" initials="G" surname="Fairhurst">
<organization>University of Aberdeen</organization>
<address>
<postal>
<street>School of Engineering</street>
<street>Fraser Noble Building</street>
<!-- Reorder these if your country does things differently -->
<city>Fraser Noble Building Aberdeen</city>
<region></region>
<code>AB24 3UE</code>
<country>UK</country>
</postal>
<email>gorry@erg.abdn.ac.uk</email>
<!-- uri and facsimile elements may also be added -->
</address>
</author>
<author fullname="Tom Jones" initials="T" surname="Jones">
<organization>University of Aberdeen</organization>
<address>
<postal>
<street>School of Engineering</street>
<street>Fraser Noble Building</street>
<!-- Reorder these if your country does things differently -->
<city>Aberdeen</city>
<region></region>
<code>AB24 3UE</code>
<country>UK</country>
</postal>
<email>tom@erg.abdn.ac.uk</email>
<!-- uri and facsimile elements may also be added -->
</address>
</author>
<date day="26" month="May" year="2016" />
<!-- If the month and year are both specified and are the current ones,
xml2rfc will fill in the current day for you. If only the current year
is specified, xml2rfc will fill in the current day and month for you.
If the year is not the current one, it is necessary to specify at
least a month (xml2rfc assumes day="1" if not specified for the
purpose of calculating the expiry date). With drafts it is normally
sufficient to specify just the year. -->
<!-- Meta-data Declarations -->
<area>Transport</area>
<workgroup>Internet Engineering Task Force</workgroup>
<!-- WG name at the upperleft corner of the doc,
IETF is fine for individual submissions. If this element is not
present, the default is "Network Working Group", which is used by the
RFC Editor as a nod to the history of the IETF. -->
<keyword>UDP Transport</keyword>
<!-- Keywords will be incorporated into HTML output
files in a meta tag but they have no effect on text or nroff output. If
you submit your draft to the RFC Editor, the keywords will be used for
the search engine. -->
<abstract>
<t>This document describes how the User Datagram Protocol (UDP) and the
Lightweight User Datagram Protocol (UDP-Lite) transport protocols expose
services to applications and how an application can configure and use
the features offered by the transport service. The document is intended
as a contribution to the Transport Services (TAPS) working group to
assist in analysis of the UDP and UDP-Lite transport interface.</t>
</abstract>
</front>
<middle>
<section title="Terminology">
<t>This document uses common terminology defined in <xref
target="I-D.ietf-taps-transports-usage"></xref>. This document also
refers to the terminology of <xref target="RFC2119"></xref>, but does
not itself define new terms using this terminology.</t>
</section>
<section title="Introduction">
<t>This document presents defined interactions between transport
protocols and applications in the form of 'primitives' (function calls).
Primitives can be invoked by an application or a transport protocol; the
latter type is called an "event". The list of transport service features
and primitives in this document is strictly based on the parts of
protocol specifications that relate to what the protocol provides to an
application using it and how the application interacts with it. It does
not cover parts of a protocol that are explicitly stated as optional to
implement.</t>
<t>This follows the methodology defined in <xref
target="I-D.ietf-taps-transports-usage"></xref>, specifically:</t>
<t><list style="hanging">
<t>"The document presents a three-pass process to arrive at a list
of transport service features.</t>
<t>In the first pass, the relevant RFC text is discussed for each
protocol.</t>
<t>In the second pass, this discussion is used to derive a list of
primitives that are uniformly categorized across protocols. Here, an
attempt is made to present or -- where text describing primitives
does not yet exist -- construct primitives in a slightly generalized
form to highlight similarities. This is, for example, achieved by
renaming primitives of protocols or by avoiding a strict 1:1-mapping
between the primitives in the protocol specification and primitives
in the list.</t>
<t>Finally, the third pass presents transport service features based
on pass 2, identifying which protocols implement them. In the list
resulting from the second pass, some transport service features are
missing because they are implicit in some protocols, and they only
become explicit when we consider the superset of all features
offered by all protocols. For example, TCP's reliability includes
integrity via a checksum, but we have to include a protocol like
UDP-Lite as specified in <xref target="RFC3828"></xref> (which has a
configurable checksum) in the list before we can consider an
always-on checksum as a transport service feature. Similar arguments
apply to other protocol functions (e.g., congestion control).</t>
<t>The complete list of features across all protocols is therefore
only available after pass 3.</t>
</list></t>
</section>
<section title="Pass 1">
<t>This first iteration summarizes the relevant text parts of the RFCs
describing the UDP and UDP-Lite protocols, focusing on what the
transport protocols provide to the application and how the transport is
used (based on abstract API descriptions, where they are available).</t>
<section title="Primitives Provided by UDP">
<t><xref target="RFC0768">The User Datagram Protocol (UDP)</xref>
States: "This User Datagram Protocol (UDP) is defined to make
available a datagram mode of packet-switched computer communication in
the environment of an interconnected set of computer networks." It
“provides a procedure for application programs to send messages
to other programs with a minimum of protocol mechanism
(..)”.</t>
<t>The User Interface section of <xref target="RFC0768"></xref>
specifies that the user interface to an application should be able to
create receive ports, source and destination ports and addresses, and
provide operations to receive data based on ports with an indication
of source port and address. Operations should be provided that allows
datagrams be sent specifying the source and destination ports and
addresses to be sent.</t>
<t>UDP for IPv6 is defined by <xref target="RFC2460"></xref>, and API
extensions to support this in <xref target="RFC3493"></xref>. <xref
target="RFC6935"></xref> and <xref target="RFC6936"></xref> defines an
update to the UDP transport specified in RFC 2460. This enables use of
a zero UDP checksum mode with a tunnel protocol, providing that the
method satisfies the requirements in <xref
target="RFC6936"></xref>.</t>
<t>UDP offers only a basic transport interface. UDP datagrams may be
directly sent and received, without exchanging messages between the
endpoints to setup a connection (i.e., there is no handshake prior to
communication). Using the sockets API, applications can receive
packets from more than one IP source address on a single UDP socket.
Common support allows specification of the local IP address,
destination IP address, local port and destination port values. Any or
all of these can be indicated, with defaults supplied by the local
system when these are not specified. The local endpoint is set using
the BIND call and set on the remote endpoint using the CONNECT call.
The CLOSE function has local significance only. This does not impact
the status of the remote endpoint.</t>
<t>UDP and UDP-Lite do not provide congestion control, retransmission,
nor support to optimise fragmentation etc. This means that
applications using UDP need to provide additional functions on top of
the UDP transport API. This requires parameters to be passed through
the API to control the network layer (IPv4 or IPv6). These additional
primitives could be considered a part of the network layer (e.g.,
control of the setting of the Don't Fragment flag on a transmitted
datagram), but are nonetheless essential to allow a user of the UDP
API to implement functions that are normally associated with the
transport layer (such as probing for Path maximum transmission size).
Although this adds complexity to the analysis of the API, this
document includes such primitives.</t>
<t><xref target="I-D.ietf-tsvwg-rfc5405bis"></xref> also states "many
operating systems also allow a UDP socket to be connected, i.e., to
bind a UDP socket to a specific pair of addresses and ports. This is
similar to the corresponding TCP sockets API functionality. However,
for UDP, this is only a local operation that serves to simplify the
local send/receive functions and to filter the traffic for the
specified addresses and ports. Binding a UDP socket does not establish
a connection - UDP does not notify the remote end when a local UDP
socket is bound. Binding a socket also allows configuring options that
affect the UDP or IP layers, for example, use of the UDP checksum or
the IP Timestamp option. On some stacks, a bound socket also allows an
application to be notified when ICMP error messages are received for
its transmissions <xref target="RFC1122"></xref>."</t>
<t>The <xref target="POSIX"></xref> API offers mechanisms for an
application to receive asynchronous data events at the socket layer.
Calls such as poll, select or queue allow an application to be
notified when data has arrived at a socket or a socket has flushed its
buffers. It is possible to structure a callback-driven API to the
network interface on top of these calls. There are protocols that
allow a macro interface to network primitives, <xref
target="RFC6458"></xref> describes implicit association setup for
sending datagram messages using SCTP. Implicit connection setup allows
an application to delegate connection life management to the transport
API. The transport API uses protocol primitives to offer the automated
service to the application via the socket API. By combining UDP
primitives (CONNECT.UDP, SEND.UDP), a higher level API could offer a
similar service.</t>
<t>Guidance on the use of services provided by UDP is provided in
<xref target="I-D.ietf-tsvwg-rfc5405bis"></xref>.</t>
<t>The following primitives are specified:</t>
<t><list style="hanging">
<t hangText="CONNECT:">The CONNECT primitive allows the
association of source and port sets to a socket to enable creation
of a 'connection' for UDP traffic. This UDP connection allows an
application to be notified of errors received from the network
stack and provides a shorthand access to the send and receive
primitives. Since UDP is itself connectionless, no datagrams are
sent because this primitive is executed. A further connect call
can be used to change the association to a source/port pair.</t>
<t hangText="">Two forms of usage may be identified for the
CONNECT primitive:</t>
<t hangText=""><list style="numbers">
<t>bind(): A bind operation sets the local port, either
implicitly, triggered by a send to operation on an unbound,
unconnected socket using an ephemeral port. Or by an explicit
bind to makes use of a configured or well-known port.</t>
<t>bind(); connect(): A bind operation followed by a CONNECT
primitive. The bind operation establishes the use of a known
local port for datagrams, rather than using an ephemeral port.
The connect operation specifies a known address port
combination to be used by default for future datagrams. This
form is used either after receiving a datagram from an
endpoint causing the creation of a connection or can be
triggered by third party configuration or a protocol trigger
(such as reception of a UDP Service Description Protocol, SDP
<xref target="RFC4566"></xref>, record).</t>
</list></t>
<t hangText="LISTEN:">The roles of a client and a server are often
not appropriate for UDP, where connections can be peer-to-peer.
The listening functions are performed using one of the forms of
CONNECT primitive described above.</t>
<t hangText="SEND:">The SEND primitive hands over a provided
number of bytes that UDP should send to the other side of a UDP
connection in a UDP datagram. The primitive can be used by an
application to directly send datagrams to an endpoint defined by
an address/port pair. If a connection has been created, then the
address/port pair is inferred from the current connection for the
socket. A connection created on the socket will allow network
errors to be returned to the application as a notification on the
send primitive. Messages passed to the send primitive that cannot
be sent atomically in a datagram will not be sent by the network
layer, generating an error.</t>
<t hangText="RECEIVE:">The RECEIVE primitive allocates a receiving
buffer to accommodate a received datagram. The primitive returns
the number of bytes provided from a received UDP datagram. Section
4.1.3.5 of <xref target="RFC1122"></xref> states "When a UDP
datagram is received, its specific-destination address MUST be
passed up to the application layer."</t>
<t hangText="DISABLE_CHECKSUM:">The CHECKSUM function controls
whether a sender disables the UDP checksum when sending datagrams.
<xref target="RFC0768"></xref> and IPv6 <xref
target="RFC6935"></xref> <xref target="RFC6936"></xref> <xref
target="I-D.ietf-tsvwg-rfc5405bis"></xref>. When set it overrides
the default UDP behaviour disabling the checksum on sending.
Section 4.1.3.4 of <xref target="RFC1122"></xref> states "An
application MAY optionally be able to control whether a UDP
checksum will be generated, but it MUST default to checksumming
on."</t>
<t hangText="REQUIRE_CHECKSUM:">The REQUIRE_CHECKSUM function
determines whether UDP datagrams received with a zero checksum are
permitted or discarded. Section 4.1.3.4 of <xref
target="RFC1122"></xref> states "An application MAY optionally be
able to control whether UDP datagrams without checksums should be
discarded or passed to the application." Section 3.1 of <xref
target="RFC3828"></xref> requires that the checksum field is
non-zero, and hence UDP-Lite need to discard all datagrams
received with a zero checksum.</t>
<t hangText="SET_IP_OPTIONS:">The SET_IP_OPTIONS function enables
a datagram to be sent with the specified IP options. Section
4.1.3.2 of<xref target="RFC1122"> </xref> states that an
"application MUST be able to specify IP options to be sent in its
UDP datagrams, and UDP MUST pass these options to the IP
layer."</t>
<t hangText="GET_IP_OPTIONS:">The GET_IP_OPTIONS function is a
network-layer function that enables a receiver to read the IP
options of a received datagram. Section 4.1.3.2 of<xref
target="RFC1122"> </xref> states that a UDP receiver "MUST pass
any IP option that it receives from the IP layer transparently to
the application layer".</t>
<t hangText="SET_DF:">The SET_DF function is a network-layer
function that sets the Don't Fragment (DF) flag to be used in the
field of an IP header of a packet that carries a UDP datagram. A
UDP application should implement a method that avoids IP
fragmentation ( section 4 of <xref
target="I-D.ietf-tsvwg-rfc5405bis"></xref>). It can use
Packetization-Layer-Path MTU Discovery (PLPMTUD) <xref
target="RFC4821"></xref> or Path MTU Discovery <xref
target="RFC1191"></xref>. NOTE: In many other IETF transports
(e.g. TCP) the transport provides the support needed to use DF,
when using UDP, the application is responsible for the techniques
needed to discover the path MTU, coordinating with the network
layer.</t>
<t hangText="GET_INTERFACE_MTU:">The GET_INTERFACE_MTU function a
network-layer function that indicates the largest unfragmented IP
packet that may be sent. A UDP endpoint can subtract the size of
all network and transport headers to determine the maximum size of
unfragmented UDP payload. UDP applications should use this value
as part of a method to avoid sending UDP datagrams that would
result in IP packets that exceed the effective path maximum
transmission unit (PMTU) allowed on the network path. The
effective PMTU specified in Section 1 of <xref
target="RFC1191"></xref> is equivalent to the "effective MTU for
sending" specified in <xref target="RFC1122"></xref>. <xref
target="RFC4821"></xref> states: "If PLPMTUD updates the MTU for a
particular path, all Packetization Layer sessions that share the
path representation (as described in Section 5.2) SHOULD be
notified to make use of the new MTU and make the required
congestion control adjustments."</t>
<t hangText="SET_TTL:">The SET_TTL function a network-layer
function that sets the hop limit (TTL field) to be used in the
field of an IPv4 header of a packet that carries an UDP datagram.
This is used to limit the scope of unicast datagrams. Section
3.2.2.4 of <xref target="RFC1122"></xref> states an "incoming Time
Exceeded message MUST be passed to the transport layer".</t>
<t hangText="GET_TTL:">The GET_TTL function is a network-layer
function that reads the value of the TTL field from the IPv4
header of a received UDP datagram. Section 3.2.2.4 of <xref
target="RFC1122"></xref> states that a UDP receiver "MAY pass the
received TOS up to the application layer" When used for
applications such as the Generalized TTL Security Mechanism (GTSM)
<xref target="RFC5082"></xref>, this needs the UDP receiver API to
pass the received value of this field to the application.</t>
<t hangText="SET_IPV6_UNICAST_HOPS:">The SET_IPV6_UNICAST_HOPS
function is a network-layer function that sets the hop limit field
to be used in the field of an IPv6 header of a packet that carries
a UDP datagram. For IPv6 unicast datagrams, this is functionally
equivalent to the SET_TTL IPv4 function.</t>
<t hangText="GET_IPV6_UNICAST_HOPS:">The GET_IPV6_UNICAST_HOPS
function is a network-layer function that reads the value from the
hop count field in the IPv6 header from the IP header information
of a received UDP datagram. For IPv6 unicast datagrams, this is
functionally equivalent to the GET_TTL IPv4 function.</t>
<t hangText="SET_DSCP:">The SET_DSCP function is a network-layer
function that sets the DSCP (or legacy TOS) value to be used in
the field of an IP header of a packet that carries a UDP Datagram.
Section 2.4 of <xref target="RFC1122"></xref> states that
"Applications MUST select appropriate TOS values when they invoke
transport layer services, and these values MUST be configurable.".
The application should be able to change the TOS during the
connection lifetime, and the TOS value should be passed to the IP
layer unchanged. Section 4.1.4 of <xref target="RFC1122"></xref>
also states that on reception the "UDP MAY pass the received TOS
value up to the application layer". <xref target="RFC2475"></xref>
<xref target="RFC3260"></xref> replaces this field in the IP
Header assigning the six most significant bits to carry the
Differentiated Services Code Point (DSCP) field. Preserving the
intention of <xref target="RFC1122"></xref> to allow the
application to specify the "Type of Service", this should be
interpreted to mean that an API should allow the application to
set the DSCP. Section 3.1.6 of <xref
target="I-D.ietf-tsvwg-rfc5405bis"></xref> describes the way UDP
applications should use this field. Normally a UDP socket will
assign a single DSCP value to all Datagrams in a flow, but it is
allowed to use different DSCP values for datagrams within the same
flow in some cases, as described in <xref
target="I-D.ietf-tsvwg-rfc5405bis"></xref>.</t>
<t hangText="SET_ECN:">The SET_ECN function is a network-layer
function that sets the ECN field in the IP Header of a UDP
Datagram. When use of the TOS field was redefined <xref
target="RFC3260"></xref>, 2 bits of the field were assigned to
support Explicit Congestion Notification (ECN) <xref
target="RFC3168"></xref>. Section 3.1.5 <xref
target="I-D.ietf-tsvwg-rfc5405bis"></xref> describes the way UDP
applications should use this field. NOTE: In many other IETF
transports (e.g. TCP) the transport provides the support needed to
use ECN, when using UDP, the application itself is responsible for
the techniques needed to use ECN.</t>
<t hangText="GET_ECN:">The GET_ECN function is a network-layer
function that returns the value of the ECN field in the IP Header
of a received UDP Datagram. Section 3.1.5 <xref
target="I-D.ietf-tsvwg-rfc5405bis"></xref> states that a UDP
receiver "MUST check the ECN field at the receiver for each UDP
datagram that it receives on this port", requiring the UDP
receiver API to pass to pass the received ECN field up to the
application layer to enable appropriate congestion feedback.</t>
<t hangText="ERROR_REPORT">The ERROR_REPORT event informs an
application of "soft errors", including the arrival of an ICMP or
ICMPv6 error message. Section 4.1.4 of <xref
target="RFC1122"></xref> states "UDP MUST pass to the application
layer all ICMP error messages that it receives from the IP layer."
For example, this event is required to implement ICMP-based Path
MTU Discovery <xref target="RFC1191"></xref> <xref
target="RFC1981"></xref>.</t>
<t hangText="CLOSE:">The close primitive closes a connection. No
further datagrams may be sent/received. Since UDP is itself
connectionless, no datagrams are sent because this command is
executed.</t>
</list></t>
<section title="Excluded Primitives">
<t>Section 3.4 of <xref target="RFC1122"></xref> also describes
"GET_MAXSIZES: - replaced, GET_SRCADDR (Section 3.3.4.3) and
ADVISE_DELIVPROB:". These mechanisms are no longer used. It also
specifies use of the Source Quench ICMP message, which has since
been deprecated <xref target="RFC6633"></xref>. The IPV6_V6ONLY
function defined in Section 5.3 of <xref target="RFC3493"></xref>
restricts the use of information from the name resolver to only
allow communication of AF_INET6 sockets to use IPv6 only. This is
not considered part of the transport service.</t>
</section>
</section>
<section title="Primitives Provided by UDP-Lite">
<t>The Lightweight User Datagram Protocol (UDP-Lite) <xref
target="RFC3828"></xref> provides similar services to UDP. It changed
the semantics of the UDP "payload length" field to that of a "checksum
coverage length" field. UDP-Lite requires the pseudo-header checksum
to be computed at the sender and checked at a receiver. Apart from the
length and coverage changes, UDP-Lite is semantically identical to
UDP.</t>
<t>The sending interface of UDP-Lite differs from that of UDP by the
addition of a single (socket) option that communicates the checksum
coverage length. This specifies the intended checksum coverage, with
the remaining unprotected part of the payload called the
"error-insensitive part".</t>
<t>The receiving interface of UDP-Lite differs from that of UDP by the
addition of a single (socket) option that specifies the minimum
acceptable checksum coverage.</t>
<t>The UDP-Lite Management Information Base (MIB) further defines the
checksum coverage method <xref target="RFC5097"></xref>. Guidance on
the use of services provided by UDP-Lite is provided in <xref
target="I-D.ietf-tsvwg-rfc5405bis"></xref>.</t>
<t>UDP-Lite requires use of the UDP or UDP-Lite checksum, and hence it
is not permitted to use the "DISABLE_CHECKSUM:" function to disable
use of a checksum, nor is it possible to disable receiver checksum
processing using the "REQUIRE_CHECKSUM:" function . All other
primitives and functions for UDP are permitted.</t>
<t>In addition, the following are defined:</t>
<t><list style="hanging">
<t hangText="SET_CHECKSUM_COVERAGE:">The SET_CHECKSUM_COVERAGE
function sets the coverage area for a sent datagram. UDP-Lite
traffic uses this primitive to set the coverage length provided by
the UDP checksum. Section 3.3 of <xref target="RFC5097"></xref>
states that "Applications that wish to define the payload as
partially insensitive to bit errors ... Should do this by an
explicit system call on the sender side." The default is to
provide the same coverage as for UDP.</t>
<t hangText="SET_MIN_COVERAGE">The SET_MIN_COVERAGE function sets
the minimum a acceptable coverage protection for received
datagrams. UDP-Lite traffic uses this primitive to set the
coverage length that is checked on receive (section 1.1 of <xref
target="RFC5097"></xref> describes the corresponding MIB entry as
udpliteEndpointMinCoverage). Section 3.3 of <xref
target="RFC3828"></xref> states that "applications that wish to
receive payloads that were only partially covered by a checksum
should inform the receiving system by an explicit system call".
The default is to require only minimal coverage of the datagram
payload.</t>
</list></t>
</section>
</section>
<section title="Pass 2">
<t>Here we categorize the services from pass 1 based on whether they
relate to a connection or to data transmission. Services are presented
following the nomenclature
"CATEGORY.[SUBCATEGORY].SERVICENAME.PROTOCOL". We present "connection"
as a general protocol-independent concept and use it to refer to UDP and
UDP-Lite connections (identifiable by a unique socket pair, where a
socket is defined as an IP address and port). We define the "transport
address" as "the combination of an IP address, transport protocol and
the port number used by the transport protocol". The "application" is
the user of the protocol <xref
target="I-D.ietf-tsvwg-rfc5405bis"></xref>.</t>
<section title="CONNECTION-Related Primitives">
<t>ESTABLISHMENT: Active creation of a connection from one transport
address to one or more transport addresses. <vspace />Interfaces to
UDP and UDP-Lite allow both connection-oriented and connection-less
usage of the API <xref target="I-D.ietf-tsvwg-rfc5405bis"></xref>.</t>
<t><list style="symbols">
<t>CONNECT.UDP: <vspace /> Pass 1 primitive event: 'connect'
followed by 'send'.<vspace /> Parameters: 1 local IP address
(default (ANY), or specified); 1 destination transport address; 1
local port (default (OS chooses), or specified); 1 destination
port (default (OS chooses), or specified).<vspace />Comments:
Associates a transport address creating a UDP socket connection.
This can be called again with a new transport address to create a
new connection. The CONNECT function allows an application to
receive errors from messages sent to a transport address. <vspace
blankLines="0" /></t>
<t>CONNECT.UDP-Lite: <vspace /> Pass 1 primitive event: 'connect'
followed by 'send'.<vspace />Parameters: 1 local IP address
(default (ANY), or specified); 1 destination transport address; 1
local port (default (OS chooses), or specified); 1 destination
port (default (OS chooses), or specified).<vspace />Comments:
Associates the transport address creating a UDP-Lite socket
connection. This can be called again with a new transport address
to create a new connection. The CONNECT function allows an
application to receive errors from messages sent to a transport
address.</t>
</list></t>
<t>AVAILABILITY<vspace /> <list style="symbols">
<t>LISTEN.UDP: <vspace /> Pass 1 primitive: 'receive'. <vspace />
Parameters: 1 local IP address (default (ANY), or specified); 1
destination transport address; local port (default (OS chooses),
or specified); destination port (default (OS chooses), or
specified).<vspace /> Comments: The receive function registers the
application to listen for in-coming UDP datagrams at an endpoint.
<vspace blankLines="0" /></t>
<t>LISTEN.UDP-Lite: <vspace /> Pass 1 primitive: 'receive'
<vspace /> Parameters: 1 local IP address (default (ANY), or
specified); 1 destination transport address; local port (default
(OS chooses), or specified); destination port (default (OS
chooses), or specified).<vspace /> Comments: The receive function
registers the application to listen for in-coming UDP-Lite
datagrams at an endpoint. <vspace blankLines="0" /></t>
</list></t>
<t>MAINTENANCE</t>
<t><vspace />- For UDP and UDP-LIte, these functions may establish a
setting per connection, but also may be changed per datagram message.
<list style="symbols">
<t>CHECKSUM.UDP: <vspace />pass 1 primitive event: 'send' or
'connect' followed by 'send'.<vspace />Parameter: 0 when no
checksum is used, 1 for checksum (default).<vspace />Comments:
Only possible for UDP.<vspace blankLines="1" /></t>
<t>CHECKSUM_REQUIRED.UDP: <vspace /><vspace />Parameter: 0 when
checksum is required, 1 for allow zero checksum
(default).<vspace />Comments: Only possible for UDP.<vspace
blankLines="1" /></t>
<t>SET_CHECKSUM_COVERAGE.UDP-Lite: <vspace /><vspace />
Parameters: Coverage length at sender (default maximum
coverage)<vspace />Comments: Only possible for UDP-Lite.<vspace
blankLines="0" /></t>
<t>SET_MIN_CHECKSUM_COVERAGE.UDP-Lite:
<vspace /><vspace />Parameter: Coverage length at receiver
(default minimum coverage)<vspace />Comments: Only possible for
UDP-Lite.<vspace blankLines="0" /></t>
<t>SET_DF.UDP: <vspace />Pass 1 primitive event: 'send' or 'open'
followed by 'send'.<vspace /><vspace />Parameter: 0 when DF is not
set (default), 1 when DF is set.<vspace blankLines="0" /></t>
<t>SET_DF.UDP-Lite: <vspace /> Pass 1 primitive event: 'send' or
'open' followed by 'send'.<vspace /><vspace />Parameter: 0 when DF
is not set (default), 1 when DF is set.<vspace
blankLines="0" /></t>
<t>GET_INTERFACE_MTU<vspace /> Pass 1 primitive / event:
GET_INTERFACE_MTU <vspace /> Parameters: MTU value set at sending
interface. <vspace /> Comments: This allows an application to
determine the local MTU for sending. <vspace blankLines="0" /></t>
<t>SET_TTL.UDP (IPV6_UNICAST_HOPS):<vspace /> Pass 1 primitive /
event: SET_TTL/IPV6_UNICAST_HOPS <vspace /> Parameter: IPv4 TTL
value or IPv6 Hop Count value <vspace /> Comments: This allows an
application to change the IPv4 TTL of IPv6 Hop count value for
outgoing UDP datagrams. <vspace blankLines="0" /></t>
<t>SET_TTL.UDP-Lite (IPV6_UNICAST_HOPS):<vspace /> Pass 1
primitive / event: TTL/IPV6_UNICAST_HOPS <vspace /> Parameter:
IPv4 TTL value or IPv6 Hop Count value <vspace /> Comments: This
allows an application to change the IPv4 TTL of IPv6 Hop count
value for outgoing UDP datagrams. <vspace blankLines="0" /></t>
<t>SET_DSCP.UDP:<vspace /><vspace />Parameter: DSCP value
<vspace /> Comments: This allows a UDP application to change the
DSCP value for outgoing UDP datagrams. <xref
target="RFC7657"></xref> and <xref
target="I-D.ietf-tsvwg-rfc5405bis"></xref> provide current
guidance on using this value with UDP.<vspace
blankLines="0" /></t>
<t>SET_DSCP.UDP-Lite:<vspace /><vspace /> Parameter: DSCP value
<vspace /> Comments: This allows a UDP-Lite application to change
the DSCP value. <xref target="RFC7657"></xref> and <xref
target="I-D.ietf-tsvwg-rfc5405bis"></xref> provide current
guidance on using this value with UDP.<vspace
blankLines="0" /></t>
<t>SET_ECN.UDP:<vspace /><vspace /> Parameter: ECN value
<vspace /> Comments: This allows a UDP application to set the ECN
codepoint field for outgoing UDP datagrams.</t>
<t>SET_ECN.UDP-Lite:<vspace /><vspace /> Parameter: ECN value
<vspace /> Comments: This allows a UDP-Lite application to set the
ECN codepoint field for outgoing UDP-Lite datagrams.</t>
<t>GET_ECN.UDP:<vspace /><vspace /> Parameter: ECN value
<vspace /> Comments: This allows a UDP application to read the ECN
codepoint field from a received UDP datagram.</t>
<t>GET_ECN.UDP-Lite:<vspace /><vspace /> Parameter: ECN value
<vspace /> Comments: This allows a UDP-Lite application to read
the ECN codepoint field from a received UDP-Lite datagram.</t>
<t>ERROR.UDP: <vspace /> Pass 1 primitive event:
'ERROR_REPORT'.<vspace /> Parameters: Error report
<vspace />Comments: This returns soft errors that may be ignored
without harm by many applications; An application must connect to
be able receive these notifications. <vspace blankLines="0" /></t>
<t>ERROR.UDP-Lite: <vspace />Pass 1 primitive event:
'ERROR_REPORT'.<vspace /> Parameters: Error report
<vspace />Comments: This returns soft errors that may be ignored
without harm by many applications; An application must connect to
be able receive these notifications. <vspace blankLines="0" /></t>
</list></t>
<t>TERMINATION<vspace /> <list style="symbols">
<t>CLOSE.UDP: <vspace /> Pass 1 primitive event: Close <vspace />
Comments: No further UDP datagrams are sent/received. <vspace
blankLines="0" /></t>
<t>CLOSE.UDP-Lite: <vspace /> Pass 1 primitive event: Close
<vspace /> Comments: No further UDP-Lite datagrams are
sent/received. <vspace blankLines="0" /></t>
</list></t>
</section>
<section title="DATA-Related Primitives">
<t>All functions in this section refer to an existing connection, i.e.
a connection that was either established or made available for
receiving data. In addition to the listed parameters, all sending
commands contain a reference to a data block and all receiving
commands contain a reference to available buffer space for the data.
<list style="symbols">
<t>SEND.UDP: <vspace /> Pass 1 primitive / event: 'send'
<vspace /> Parameters: IP Address and Port Number of the
destination endpoint (optional if connected). <vspace />Comments:
This provides a message for unreliable transmission using UDP to
the specified transport address. IP address and Port may be
omitted for connected UDP sockets. <vspace blankLines="0" /></t>
<t>SEND.UDP-Lite: <vspace /> Pass 1 primitive / event: 'send'
<vspace /> Parameters: IP Address and Port Number of the
destination endpoint (optional if connected). <vspace />Comments:
This provides a message for unreliable transmission using UDP-Lite
to the specified transport address. IP address and Port may be
omitted for connected UDP sockets. <vspace blankLines="0" /></t>
<t>RECEIVE.UDP: <vspace /> Pass 1 primitive / event:
'receive'<vspace blankLines="0" />Parameters: Buffer for received
datagram.<vspace blankLines="0" />Comments: The datagram received
TTL/Hop count field, received ECN field, and IP options can be
read per message on receive. <vspace blankLines="0" /></t>
<t>RECEIVE.UDP-Lite: <vspace /> Pass 1 primitive / event:
'receive' <vspace blankLines="0" />Parameters: Buffer for received
datagram.<vspace blankLines="0" />Comments: The datagram received
TTL/Hop count field, received ECN field, and IP options can be
read per message on receive. <vspace blankLines="0" /></t>
<t>SEND_FAILURE.UDP: <vspace /> Pass 1 primitive / event:
'send'<vspace blankLines="0" />Comment: This may be used to probe
effective PMTU when using in combination with the 'set-DF'
function.<vspace blankLines="0" /></t>
<t>SEND_FAILURE.UDP-Lite: <vspace blankLines="0" /> Pass 1
primitive / event: 'send'<vspace blankLines="0" />Comment: This
may be used to probe effective PMTU when using in combination with
the 'set-DF' function.<vspace blankLines="0" /></t>
</list></t>
</section>
</section>
<section title="Pass 3">
<t>This section presents the superset of all transport service features
in all protocols that were discussed in the preceding sections, based on
the list of primitives in pass 2, but also on text in pass 1 to include
features that can be configured in one protocol and are static
properties in another. Some minor details are omitted for the sake of
generalization.</t>
<t>[AUTHOR'S NOTE: the list here looks pretty similar to the list in
pass 2 for now. This will change as more protocols are integrated. For
example, when we merge with TCP and SCTP. In pass 3, we can derive "no
congestion control" as a transport service feature of UDP; however,
since it would be strange to call the lack of congestion control a
feature, the natural outcome is then to list "congestion control" as a
feature of TCP and SCTP.]</t>
<section anchor="conn-pass3"
title="CONNECTION-Related Transport Service Features">
<t>ESTABLISHMENT:<vspace /> Active creation of a connection from one
transport endpoint to one or more transport endpoints.<vspace
blankLines="0" /></t>
<t>AVAILABILITY:<vspace /> Prepare to receive incoming requests<vspace
blankLines="0" /> <list style="symbols">
<t>Listen, 1 specified interface<vspace /> Protocols: UDP,
UDP-Lite<vspace /> <vspace blankLines="1" /></t>
<t>Listen, N specified interfaces<vspace /> Protocols: UDP,
UDP-Lite<vspace /></t>
<t>Listen, All local interfaces (unspecified)<vspace /> Protocols:
UDP, UDP-Lite<vspace /></t>
</list></t>
<t>MAINTENANCE:<vspace /> Make adjustments to an open connection or
notifications from the connection.<vspace blankLines="0" /> <list
style="symbols">
<t>Specify IP options<vspace /> Protocols: UDP,
UDP-Lite<vspace /></t>
<t>Specify Checksum enabled <vspace /> Protocols:
UDP<vspace /></t>
<t>Specify Checksum_Coverage <vspace /> Protocols:
UDP-Lite<vspace /></t>
<t>Specify Checksum_Coverage <vspace /> Protocols:
UDP-Lite<vspace /></t>
<t>Specify DF field <vspace /> Protocols: UDP,
UDP-Lite<vspace /></t>
<t>Specify TTL/Hop count field<vspace /> Protocols: UDP,
UDP-Lite<vspace /></t>
<t>Specify DSCP Field<vspace /> Protocols: UDP,
UDP-Lite<vspace /></t>
<t>Specify ECN field<vspace /> Protocols: UDP,
UDP-Lite<vspace /></t>
</list></t>
</section>
<section anchor="data-pass3"
title="DATA Transfer Related Transport Service Features">
<t>All features in the this section relate to DATA.SEND and
DATA.RECEIVE in Pass 2.</t>
<section anchor="data-sending-pass3" title="Sending Data">
<t>All features in this section are provided by DATA.SEND from pass
2. DATA.SEND is given a data block from the application, which we
here call a "message".</t>
<t><list style="symbols">
<t>Send data<vspace /> Protocols: UDP, UDP-Lite<vspace /></t>
<t>Send data on a connection<vspace /> Protocols: UDP,
UDP-Lite<vspace /></t>
</list></t>
</section>
<section anchor="data-receiving-pass3" title="Receiving Data">
<t>All features in this section are provided by DATA.RECEIVE from
pass 2. DATA.RECEIVE is given a data block from the application,
which we here call a "message".</t>
<t><list style="symbols">
<t>Receive data<vspace /> Protocols: UDP, UDP-Lite<vspace />
<vspace blankLines="1" /></t>
<t>Receive data on a connection<vspace /> Protocols: UDP,
UDP-Lite<vspace /></t>
</list></t>
</section>
</section>
</section>
<section anchor="Acknowledgements" title="Acknowledgements">
<t>This work was partially funded by the European Union's Horizon 2020
research and innovation programme under grant agreement No. 644334
(NEAT). The views expressed are solely those of the author(s). Thanks to
all who have commented or contributed, including Joe Touch, Ted Hardie,
Aaron Falk.</t>
</section>
<section anchor="IANA" title="IANA Considerations">
<t>This memo includes no request to IANA.</t>
<t>If there are no requirements for IANA, the section will be removed
during conversion into an RFC by the RFC Editor.</t>
</section>
<section anchor="Security" title="Security Considerations">
<t>Security considerations for the use of UDP and UDP-Lire are provided
in the referenced RFCs. Security guidance for application usage is
provide in the UDP-Guidelines <xref
target="I-D.ietf-tsvwg-rfc5405bis"></xref>.</t>
</section>
</middle>
<!-- *****BACK MATTER ***** -->
<back>
<!-- References split into informative and normative -->
<references title="Normative References">
<!--?rfc include="http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml"?-->
&RFC768;
&RFC1122;
&RFC2119;
&RFC2460;
&RFC2553;
&RFC3168;
&RFC3493;
&RFC3828;
&RFC6935;
&I-D.ietf-taps-transports-usage;
&I-D.draft-ietf-tsvwg-rfc5405bis;
</references>
<references title="Informative References">
<!-- Here we use entities that we defined at the beginning. -->
&RFC1191;
&RFC1981;
&RFC2475;
&RFC3260;
&RFC3678;
&RFC4821;
&RFC5082;
&RFC5097;
&RFC6458;
&RFC4566;
&RFC6936;
&RFC6633;
&RFC5790;
&RFC7657;
<reference anchor="POSIX">
<front>
<title>IEEE Std. 1003.1-2001, , "Standard for Information Technology
- Portable Operating System Interface (POSIX)", Open Group Technical
Standard: Base Specifications Issue 6, ISO/IEC 9945:2002</title>
<author>
<organization></organization>
</author>
<date month="December" year="2001" />
</front>
</reference>
<reference anchor="STEVENS">
<front>
<title>Stevens, W., Fenner, B., and A. Rudoff, "UNIX Network
Programming, The sockets Networking API", Addison-Wesley.</title>
<author>
<organization></organization>
</author>
<date year="2004" />
</front>
</reference>
</references>
<section title="Revision Notes">
<t>Note to RFC-Editor: please remove this entire section prior to
publication.</t>
<t>Individual draft -00:</t>
<t><list style="symbols">
<t>This is the first version. Comments and corrections are welcome
directly to the authors or via the IETF TAPS working group mailing
list.</t>
</list></t>
<t>Individual draft -01:<list style="symbols">
<t>Includes ability of a UDP receiver to disallow zero checksum
datagrams.</t>
<t>Fixes to references and some connect on UDP usage.</t>
</list>Individual draft -02:</t>
<t><list style="symbols">
<t>Fixes to address issues noted by WG.</t>
<t>Completed Multicast section to specify modern APIs.</t>
<t>Noted comments on API usage for UDP.</t>
<t>Feedback from various reviewers.</t>
</list></t>
</section>
<section anchor="typical-usage" title="Notes Based on Typical Usage">
<t>This appendix contains notes to assist in a later revision.</t>
<t>The de facto standard application programming interface (API) for
TCP/IP applications is the "sockets" interface<xref
target="POSIX"></xref>. Some platforms also offer applications the
ability to directly assemble and transmit IP packets through "raw
sockets" or similar facilities. This is a second, more cumbersome method
of using UDP. The use of this API is discussed in the RFC series in
<xref target="I-D.ietf-tsvwg-rfc5405bis"></xref>.</t>
<t>The UDP sockets API differs from that for TCP in several key ways.
Because application programmers are typically more familiar with the TCP
sockets API, this section discusses these differences. <xref
target="STEVENS"></xref> provides usage examples of the UDP sockets
API.</t>
<t>This section provides notes on some topics relating to implemented
UDP APIs.</t>
<t>A UDP application can use the recv() and send() POSIX functions as
well as the recvfrom() and sendto() and recvmsg and sendmsg()
functions.</t>
<t>SO_REUSEADDR specifies that the rules used in validating addresses
supplied to bind() should allow reuse of local addresses.</t>
<t>SO_REUSEPORT specifies that the rules used in validating ports
supplied to bind() should allow reuse of a local port</t>
<t>Accessing TTL From applications: If the IP_RECVTTL option is enabled
on a SOCK_DGRAM socket, the recvmsg(2) call will return the IP TTL (time
to live) field for a UDP datagram. The msg_control field in the msghdr
structure points to a buffer that contains a cmsghdr structure followed
by the TTL.</t>
</section>
<section anchor="multicast-note" title="UDP Multicast">
<t>UDP and UDP-Lite Multicast may be considered in later versions of
this document. This appendix contains notes to assist in this later
revision.</t>
<t>A host must request the ability to broadcast before it can
send/receive ipv4 broadcast traffic. A host must become a member of a
multicast group at the network layer before it can receive datagrams
sent to the group.</t>
<section title="Multicast Primitives ">
<t>UDP and UDP-Lite support IPv4 broadcast and IPv4/IPv6 Multicast.
Use of multicast requires additional functions at the transport API
that must be called to coordinate operation of the IPv4 and IPv6
network layer protocols.</t>
<t>Guidance on the use of UDP and UDP-Lite for multicast services is
provided in <xref target="I-D.ietf-tsvwg-rfc5405bis"></xref>.</t>
<t>The following are defined:</t>
<t><list style="hanging">
<t hangText="JoinLocalGroup:">1 of <xref target="RFC3493"></xref>
provides a function that allows joining of a local IPv4 multicast
group.</t>
<t hangText="IPV6_MULTICAST_IF:">Section 5.2 of <xref
target="RFC2553"></xref> states that this sets the interface to
use for outgoing multicast packets.</t>
<t hangText="IP_MULTICAST_TTL:">This sets the hop limit to use for
outgoing multicast packets. This is used to limit scope of
multicast datagrams. When used for applications such as GTSM, this
needs the UDP receiver API to pass the received value of this
field to the application. (This is equivalent to
IPV6_MULTICAST_HOPS for IPv6 multicast and TTL/IPV6_UNICAST_HOPS
for unicast datagrams).</t>
<t hangText="IPV6_MULTICAST_HOPS:">Section 5.2 of <xref
target="RFC2553"></xref> states that this sets the hop limit to
use for outgoing multicast packets. When used for applications
such as GTSM, this needs the UDP receiver API to pass the received
value of this field to the application. (This is equivalent to
IP_MULTICAST_TTL for IPv4 multicast and TTL/IPV6_UNICAST_HOPS for
unicast datagrams).</t>
<t hangText="IPV6_MULTICAST_LOOP:">Section 5.2 of <xref
target="RFC2553"></xref> states that this sets whether a copy of a
datagram is looped back by the IP layer for local delivery when
the datagram is sent to a group to which the sending host itself
belongs).</t>
<t hangText="IPV6_JOIN_GROUP:">Section 5.2 of <xref
target="RFC2553"></xref> provides a function that allows joining
of an IPv6 multicast group.</t>
<t hangText="SIOCGIPMSFILTER:">Section 8.1 of <xref
target="RFC3678"></xref> provides a function that allows reading
the multicast source filters.</t>
<t hangText="SIOCSIPMSFILTER:">Section 8.1 of <xref
target="RFC3678"></xref> provides a function that allows
setting/modifying the multicast source filters.</t>
<t hangText="IPV6_LEAVE_GROUP:">Section 5.2 of <xref
target="RFC2553"></xref> provides a function that allows leaving
of a multicast group.</t>
<t hangText="LeaveHostGroup:">Section 7.1 of <xref
target="RFC3493"></xref> provides a function that allows joining
of an IPv4 multicast group.</t>
<t hangText="LeaveLocalGroup:">Section 7.1 of <xref
target="RFC3493"></xref> provides a function that allows joining
of a local IPv4 multicast group.</t>
</list></t>
<t>Section 4.1.1 of <xref target="RFC3678"></xref> updates the
interface to add support for Multicast Source Filters (MSF) to IGMPv3
for Any Source Multicast (ASM):</t>
<t>This identifies three sets of API functionality:</t>
<t><list style="numbers">
<t>IPv4 Basic (Delta-based) API. "Each function call specifies a
single source address which should be added to or removed from the
existing filter for a given multicast group address on which to
listen."</t>
<t>IPv4 Advanced (Full-state) API. "This API allows an application
to define a complete source-filter comprised of zero or more
source addresses, and replace the previous filter with a new
one."</t>
<t>Protocol-Independent Basic MSF (Delta-based) API</t>
<t>Protocol-Independent Advanced MSF (Full-state) API</t>
</list>It specifies the following primitives:</t>
<t><list style="hanging">
<t hangText="IP_ADD_MEMBERSHIP:">This is used to join an ASM
group.</t>
<t hangText="IP_BLOCK_SOURCE:">This is a MSF that can be used to
block data from a given multicast source to a given group for ASM
or SSM.</t>
<t hangText="IP_UNBLOCK_SOURCE:">This updates an MSF to undo a
previous call to IP_UNBLOCK_SOURCE for ASM or SSM.</t>
<t hangText="IP_DROP_MEMBERSHIP:">This is used to leave an ASM or
SSM group. (In SSM this drops all sources that have been joined
for a particular group and interface. The operations are the same
as if the socket had been closed.)</t>
</list></t>
<t>Section 4.1.2 of <xref target="RFC3678"></xref> updates the
interface to add Multicast Source Filter (MSF) support for IGMPv3 with
Any Source Multicast (ASM) using IPv4:</t>
<t><list style="hanging">
<t hangText="IP_ADD_SOURCE_MEMBERSHIP:">This is used to join an
SSM group.</t>
<t hangText="IP_DROP_SOURCE_MEMBERSHIP:">This is used to leave an
SSM group.</t>
</list></t>
<t>Section 4.1.2 of <xref target="RFC3678"></xref> defines the
Advanced (Full-state) API:</t>
<t><list style="hanging">
<t hangText="setipv4sourcefilter">This is used to join an IPv4
multicast group, or to enable multicast from a specified
source.</t>
<t hangText="getipv4sourcefilter:">This is used to leave an IPv4
multicast group, or to filter multicast from a specified
source.</t>
</list>Section 5.1 of <xref target="RFC3678"></xref> specifies
Protocol-Independent Multicast API functions:</t>
<t><list style="hanging">
<t hangText="MCAST_JOIN_GROUP">This is used to join an ASM
group.</t>
<t hangText="MCAST_JOIN_SOURCE_GROUP">This is used to join an SSM
group.</t>
<t hangText="MCAST_BLOCK_SOURCE:">This is used to block a source
in an ASM group.</t>
<t hangText="MCAST_UNBLOCK_SOURCE:">This removes a previous MSF
set by MCAST_BLOCK_SOURCE:</t>
<t hangText="MCAST_LEAVE_GROUP:">This leaves a SSM group.</t>
<t hangText="MCAST_LEAVE_GROUP:">This leaves a ASM or SSM
group.</t>
</list></t>
<t>Section 5.2 of <xref target="RFC3678"></xref> specifies the
Protocol-Independent Advanced MSF (Full-state) API applicable for both
IPv4 and IPv6 multicast:</t>
<t><list style="hanging">
<t hangText="setsourcefilter">This is used to join an IPv4 or IPv6
multicast group, or to enable multicast from a specified
source.</t>
<t hangText="getsourcefilter:">This is used to leave an IPv4 or
IPv6 multicast group, or to filter multicast from a specified
source.</t>
</list>Section 7.2 of <xref target="RFC5790"></xref> updates the
interface to specify support for Lightweight IGMPv3 (LW_IGMPv3) and
MLDv2.</t>
<t>According to the MSF API definition <xref target="RFC3678"></xref>,
"an LW-IGMPv3 host should implement either the IPv4 Basic MSF API or
the Protocol-Independent Basic MSF API, and an LW-MLDv2 host should
implement the Protocol- Independent Basic MSF API. Other APIs, IPv4
Advanced MSF API and Protocol-Independent Advanced MSF API, are
optional to implement in an LW-IGMPv3/LW-MLDv2 host."</t>
</section>
</section>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-23 16:33:26 |