doc: Add RFC documents

1 files changed, 1011 insertions, 0 deletions

diff --git a/doc/rfc/rfc3678.txt b/doc/rfc/rfc3678.txt
new file mode 100644
index 0000000..bc6fdf0
--- /dev/null
+++ b/doc/rfc/rfc3678.txt
@@ -0,0 +1,1011 @@
+
+
+
+
+
+
+Network Working Group                                          D. Thaler
+Request for Comments: 3678                                     Microsoft
+Category: Informational                                        B. Fenner
+                                                           AT&T Research
+                                                                B. Quinn
+                                                            Stardust.com
+                                                            January 2004
+
+
+        Socket Interface Extensions for Multicast Source Filters
+
+Status of this Memo
+
+   This memo provides information for the Internet community.  It does
+   not specify an Internet standard of any kind.  Distribution of this
+   memo is unlimited.
+
+Copyright Notice
+
+   Copyright (C) The Internet Society (2004).  All Rights Reserved.
+
+Abstract
+
+   The Internet Group Management Protocol (IGMPv3) for IPv4 and the
+   Multicast Listener Discovery (MLDv2) for IPv6 add the capability for
+   applications to express source filters on multicast group
+   memberships, which allows receiver applications to determine the set
+   of senders (sources) from which to accept multicast traffic.  This
+   capability also simplifies support of one-to-many type multicast
+   applications.
+
+   This document specifies new socket options and functions to manage
+   source filters for IP Multicast group memberships.  It also defines
+   the socket structures to provide input and output arguments to these
+   new application program interfaces (APIs).  These extensions are
+   designed to provide access to the source filtering features, while
+   introducing a minimum of change into the system and providing
+   complete compatibility for existing multicast applications.
+
+Table of Contents
+
+   1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  2
+   2.  Design Considerations. . . . . . . . . . . . . . . . . . . . .  3
+       2.1 What Needs to be Added . . . . . . . . . . . . . . . . . .  4
+       2.2 Data Types . . . . . . . . . . . . . . . . . . . . . . . .  4
+       2.3 Headers. . . . . . . . . . . . . . . . . . . . . . . . . .  4
+       2.4 Structures . . . . . . . . . . . . . . . . . . . . . . . .  4
+   3. Overview of APIs. . . . . . . . . . . . . . . . . . . . . . . .  5
+
+
+
+Thaler, et al.               Informational                      [Page 1]
+
+RFC 3678              Multicast Source Filter API           January 2004
+
+
+   4. IPv4 Multicast Source Filter APIs . . . . . . . . . . . . . . .  6
+      4.1 Basic (Delta-based) API for IPv4. . . . . . . . . . . . . .  6
+           4.1.1 IPv4 Any-Source Multicast API. . . . . . . . . . . .  7
+           4.1.2 IPv4 Source-Specific Multicast API . . . . . . . . .  7
+           4.1.3 Error Codes. . . . . . . . . . . . . . . . . . . . .  8
+      4.2 Advanced (Full-state) API for IPv4. . . . . . . . . . . . .  8
+           4.2.1 Set Source Filter. . . . . . . . . . . . . . . . . .  8
+           4.2.2 Get Source Filter. . . . . . . . . . . . . . . . . .  9
+   5: Protocol-Independent Multicast Source Filter APIs . . . . . . . 10
+      5.1 Basic (Delta-based) API . . . . . . . . . . . . . . . . . . 10
+           5.1.1 Any-Source Multicast API . . . . . . . . . . . . . . 11
+           5.1.2 Source-Specific Multicast API. . . . . . . . . . . . 11
+      5.2 Advanced (Full-state) API . . . . . . . . . . . . . . . . . 11
+           5.2.1 Set Source Filter. . . . . . . . . . . . . . . . . . 11
+           5.2.2 Get Source Filter. . . . . . . . . . . . . . . . . . 12
+   6.  Security Considerations. . . . . . . . . . . . . . . . . . . . 13
+   7.  Acknowledgments. . . . . . . . . . . . . . . . . . . . . . . . 13
+   8.  Appendix A: Use of ioctl() for full-state operations . . . . . 14
+       8.1. IPv4 Options. . . . . . . . . . . . . . . . . . . . . . . 14
+       8.2. Protocol-Independent Options. . . . . . . . . . . . . . . 15
+   9.  Normative References . . . . . . . . . . . . . . . . . . . . . 16
+   10. Informative References . . . . . . . . . . . . . . . . . . . . 16
+   11. Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 17
+   12. Full Copyright Statement . . . . . . . . . . . . . . . . . . . 18
+
+1.  Introduction
+
+   The de facto standard application program interface (API) for TCP/IP
+   applications is the "sockets" interface.  Although this API was
+   developed for Unix in the early 1980s it has also been implemented on
+   a wide variety of non-Unix systems.  TCP/IP applications written
+   using the sockets API have in the past enjoyed a high degree of
+   portability and we would like the same portability with applications
+   that employ multicast source filters.  Changes are required to the
+   sockets API to support such filtering and this memo describes these
+   changes.
+
+   This document specifies new socket options and functions to manage
+   source filters for IP Multicast group memberships.  It also defines
+   the socket structures to provide input and output arguments to these
+   new APIs.  These extensions are designed to provide access to the
+   source filtering features required by applications, while introducing
+   a minimum of change into the system and providing complete
+   compatibility for existing multicast applications.
+
+   Furthermore, RFC 3493 [1] defines socket interface extensions for
+   IPv6, including protocol-independent functions for most operations.
+
+
+
+
+Thaler, et al.               Informational                      [Page 2]
+
+RFC 3678              Multicast Source Filter API           January 2004
+
+
+   However, while it defines join and leave functions for IPv6, it does
+   not provide protocol-independent versions of these operations.  Such
+   functions will be described in this document.
+
+   The reader should note that this document is for informational
+   purposes only, and that the official standard specification of the
+   sockets API is [2].
+
+2.  Design Considerations
+
+   There are a number of important considerations in designing changes
+   to this well-worn API:
+
+      o  The API changes should provide both source and binary
+         compatibility for programs written to the original API.  That
+         is, existing program binaries should continue to operate when
+         run on a system supporting the new API.  In addition, existing
+         applications that are re-compiled and run on a system
+         supporting the new API should continue to operate.  Simply put,
+         the API changes for multicast receivers that specify source
+         filters should not break existing programs.
+
+      o  The changes to the API should be as small as possible in order
+         to simplify the task of converting existing multicast receiver
+         applications to use source filters.
+
+      o  Applications should be able to detect when the new source
+         filter APIs are unavailable (e.g., calls fail with the ENOTSUPP
+         error) and react gracefully (e.g., revert to old non-source-
+         filter API or display a meaningful error message to the user).
+
+      o  Lack of type-safety in an API is a bad thing which should be
+         avoided when possible.
+
+   Several implementations exist that use ioctl() for a portion of the
+   functionality described herein, and for historical purposes, the
+   ioctl API is documented in Appendix A.  The preferred API, however,
+   includes new functions.  The reasons for adding new functions are:
+
+      o  New functions provide type-safety, unlike ioctl, getsockopt,
+         and setsockopt.
+
+      o  A new function can be written as a wrapper over an ioctl,
+         getsockopt, or setsockopt call, if necessary.  Hence, it
+         provides more freedom as to how the functionality is
+         implemented in an operating system.  For example, a new
+         function might be implemented as an inline function in an
+
+
+
+
+Thaler, et al.               Informational                      [Page 3]
+
+RFC 3678              Multicast Source Filter API           January 2004
+
+
+         include file, or a function exported from a user-mode library
+         which internally uses some mechanism to exchange information
+         with the kernel, or be implemented directly in the kernel.
+
+      o  At least one operation defined herein needs to be able to both
+         pass information to the TCP/IP stack, as well as retrieve
+         information from it.  In some implementations this is
+         problematic without either changing getsockopt or using ioctl.
+         Using new functions avoids the need to change such
+         implementations.
+
+2.1.  What Needs to be Added
+
+   The current IP Multicast APIs allow a receiver application to specify
+   the group address (destination) and (optionally) the local interface.
+   These existing APIs need not change (and cannot, to retain binary
+   compatibility).  Hence, what is needed are new source filter APIs
+   that provide the same functionality and also allow receiver multicast
+   applications to:
+
+      o  Specify zero or more unicast (source) address(es) in a source
+         filter.
+
+      o  Determine whether the source filter describes an inclusive or
+         exclusive list of sources.
+
+   The new API design must enable this functionality for both IPv4 and
+   IPv6.
+
+2.2.  Data Types
+
+   The data types of the structure elements given in this memo are
+   intended to be examples, not absolute requirements.  Whenever
+   possible, data types from POSIX 1003.1g [2] are used: uintN_t means
+   an unsigned integer of exactly N bits (e.g., uint32_t).
+
+2.3.  Headers
+
+   When function prototypes and structures are shown, we show the
+   headers that must be #included to cause that item to be defined.
+
+2.4.  Structures
+
+   When structures are described, the members shown are the ones that
+   must appear in an implementation.  Additional, nonstandard members
+   may also be defined by an implementation.  As an additional
+
+
+
+
+
+Thaler, et al.               Informational                      [Page 4]
+
+RFC 3678              Multicast Source Filter API           January 2004
+
+
+   precaution, nonstandard members could be verified by Feature Test
+   Macros as described in [2].  (Such Feature Test Macros are not
+   defined by this RFC.)
+
+   The ordering shown for the members of a structure is the recommended
+   ordering, given alignment considerations of multibyte members, but an
+   implementation may order the members differently.
+
+3.  Overview of APIs
+
+   There are a number of different APIs described in this document that
+   are appropriate for a number of different application types and IP
+   versions.  Before providing detailed descriptions, this section
+   provides a "taxonomy" with a brief description of each.
+
+   There are two categories of source-filter APIs, both of which are
+   designed to allow multicast receiver applications to designate the
+   unicast address(es) of sender(s) along with the multicast group
+   (destination address) to receive.
+
+      o  Basic (Delta-based): Some applications desire the simplicity of
+         a delta-based API in which 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.  Such applications typically fall into either
+         of two categories:
+
+         +  Any-Source Multicast: By default, all sources are accepted.
+            Individual sources may be turned off and back on as needed
+            over time.  This is also known as "exclude" mode, since the
+            source filter contains a list of excluded sources.
+
+         +  Source-Specific Multicast: Only sources in a given list are
+            allowed.  The list may change over time.  This is also known
+            as "include" mode, since the source filter contains a list
+            of included sources.
+
+            This API would be used, for example, by "single-source"
+            applications such as audio/video broadcasting.  It would
+            also be used for logical multi-source sessions where each
+            source independently allocates its own Source-Specific
+            Multicast group address.
+
+      o  Advanced (Full-state): 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.
+
+
+
+
+
+Thaler, et al.               Informational                      [Page 5]
+
+RFC 3678              Multicast Source Filter API           January 2004
+
+
+         Applications which require the ability to switch between filter
+         modes without leaving a group must use a full-state API (i.e.,
+         to change the semantics of the source filter from inclusive to
+         exclusive, or vice versa).
+
+         Applications which use a large source list for a given group
+         address should also use the full-state API, since filter
+         changes can be done atomically in a single operation.
+
+   The above types of APIs exist in IPv4-specific variants as well as
+   with protocol-independent variants.  One might ask why the protocol-
+   independent APIs cannot accommodate IPv4 applications as well as
+   IPv6.  Since any IPv4 application requires modification to use
+   multicast source filters anyway, it might seem like a good
+   opportunity to create IPv6-compatible source code.
+
+   The primary reasons for extending an IPv4-specific API are:
+
+      o  To minimize changes needed in existing IPv4 multicast
+         application source code to add source filter support.
+
+      o  To avoid overloading APIs to accommodate the differences
+         between IPv4 interface addresses (e.g., in the ip_mreq
+         structure) and interface indices.
+
+4.  IPv4 Multicast Source Filter APIs
+
+   Version 3 of the Internet Group Management Protocol (IGMPv3) [3] and
+   version 2 of the Multicast Listener Discovery (MLDv2) protocol [4]
+   provide the ability to communicate source filter information to the
+   router and hence avoid pulling down data from unwanted sources onto
+   the local link.  However, source filters may be implemented by the
+   operating system regardless of whether the routers support IGMPv3 or
+   MLDv2, so when the source-filter API is available, applications can
+   always benefit from using it.
+
+4.1.  Basic (Delta-based) API for IPv4
+
+   The reception of multicast packets is controlled by the setsockopt()
+   options summarized below.  An error of EOPNOTSUPP is returned if
+   these options are used with getsockopt().
+
+
+
+
+
+
+
+
+
+
+Thaler, et al.               Informational                      [Page 6]
+
+RFC 3678              Multicast Source Filter API           January 2004
+
+
+   The following structures are used by both the Any-Source Multicast
+   and the Source-Specific Multicast API:
+
+   #include <netinet/in.h>
+
+   struct ip_mreq {
+      struct in_addr imr_multiaddr;  /* IP address of group */
+      struct in_addr imr_interface;  /* IP address of interface */
+   };
+
+   struct ip_mreq_source {
+      struct in_addr imr_multiaddr;  /* IP address of group */
+      struct in_addr imr_sourceaddr; /* IP address of source */
+      struct in_addr imr_interface;  /* IP address of interface */
+   };
+
+4.1.1.  IPv4 Any-Source Multicast API
+
+   The following socket options are defined in <netinet/in.h> for
+   applications in the Any-Source Multicast category:
+
+   Socket option             Argument type
+   IP_ADD_MEMBERSHIP         struct ip_mreq
+   IP_BLOCK_SOURCE           struct ip_mreq_source
+   IP_UNBLOCK_SOURCE         struct ip_mreq_source
+   IP_DROP_MEMBERSHIP        struct ip_mreq
+
+   IP_ADD_MEMBERSHIP and IP_DROP_MEMBERSHIP are already implemented on
+   most operating systems, and are used to join and leave an any-source
+   group.
+
+   IP_BLOCK_SOURCE can be used to block data from a given source to a
+   given group (e.g., if the user "mutes" that source), and
+   IP_UNBLOCK_SOURCE can be used to undo this (e.g., if the user then
+   "unmutes" the source).
+
+4.1.2.  IPv4 Source-Specific Multicast API
+
+   The following socket options are available for applications in the
+   Source-Specific category:
+
+   Socket option             Argument type
+   IP_ADD_SOURCE_MEMBERSHIP  struct ip_mreq_source
+   IP_DROP_SOURCE_MEMBERSHIP struct ip_mreq_source
+   IP_DROP_MEMBERSHIP        struct ip_mreq
+
+   IP_ADD_SOURCE_MEMBERSHIP and IP_DROP_SOURCE_MEMBERSHIP are used to
+   join and leave a source-specific group.
+
+
+
+Thaler, et al.               Informational                      [Page 7]
+
+RFC 3678              Multicast Source Filter API           January 2004
+
+
+   IP_DROP_MEMBERSHIP is supported, as a convenience, to drop all
+   sources which have been joined for a particular group and interface.
+   The operations are the same as if the socket had been closed.
+
+4.1.3.  Error Codes
+
+   When the option would be legal on the group, but an address is
+   invalid (e.g., when trying to block a source that is already blocked
+   by the socket, or when trying to drop an unjoined group) the error
+   generated is EADDRNOTAVAIL.
+
+   When the option itself is not legal on the group (i.e., when trying a
+   Source-Specific option on a group after doing IP_ADD_MEMBERSHIP, or
+   when trying an Any-Source option without doing IP_ADD_MEMBERSHIP) the
+   error generated is EINVAL.
+
+   When any of these options are used with getsockopt(), the error
+   generated is EOPNOTSUPP.
+
+   Finally, if the implementation imposes a limit on the maximum number
+   of sources in a source filter, ENOBUFS is generated when an operation
+   would exceed the maximum.
+
+4.2.  Advanced (Full-state) API for IPv4
+
+   Several implementations exist that use ioctl() for this API, and for
+   historical purposes, the ioctl() API is documented in Appendix A.
+   The preferred API uses the new functions described below.
+
+4.2.1.  Set Source Filter
+
+     #include <netinet/in.h>
+
+     int setipv4sourcefilter(int s, struct in_addr interface,
+                             struct in_addr group, uint32_t fmode,
+                             uint32_t numsrc, struct in_addr *slist);
+
+   On success the value 0 is returned, and on failure, the value -1 is
+   returned and errno is set accordingly.
+
+   The s argument identifies the socket.
+
+   The interface argument holds the local IP address of the interface.
+
+   The group argument holds the IP multicast address of the group.
+
+
+
+
+
+
+Thaler, et al.               Informational                      [Page 8]
+
+RFC 3678              Multicast Source Filter API           January 2004
+
+
+   The fmode argument identifies the filter mode.  The value of this
+   field must be either MCAST_INCLUDE or MCAST_EXCLUDE, which are
+   likewise defined in <netinet/in.h>.
+
+   The numsrc argument holds the number of source addresses in the slist
+   array.
+
+   The slist argument points to an array of IP addresses of sources to
+   include or exclude depending on the filter mode.
+
+   If the implementation imposes a limit on the maximum number of
+   sources in a source filter, ENOBUFS is generated when the operation
+   would exceed the maximum.
+
+4.2.2.  Get Source Filter
+
+     #include <netinet/in.h>
+
+     int getipv4sourcefilter(int s, struct in_addr interface,
+                             struct in_addr group, uint32_t *fmode,
+                             uint32_t *numsrc, struct in_addr *slist);
+
+   On success the value 0 is returned, and on failure, the value -1 is
+   returned and errno is set accordingly.
+
+   The s argument identifies the socket.
+
+   The interface argument holds the local IP address of the interface.
+
+   The group argument holds the IP multicast address of the group.
+
+   The fmode argument points to an integer that will contain the filter
+   mode on a successful return.  The value of this field will be either
+   MCAST_INCLUDE or MCAST_EXCLUDE, which are likewise defined in
+   <netinet/in.h>.
+
+   On input, the numsrc argument holds the number of source addresses
+   that will fit in the slist array.  On output, the numsrc argument
+   will hold the total number of sources in the filter.
+
+   The slist argument points to buffer into which an array of IP
+   addresses of included or excluded (depending on the filter mode)
+   sources will be written.  If numsrc was 0 on input, a NULL pointer
+   may be supplied.
+
+
+
+
+
+
+
+Thaler, et al.               Informational                      [Page 9]
+
+RFC 3678              Multicast Source Filter API           January 2004
+
+
+   If the application does not know the size of the source list
+   beforehand, it can make a reasonable guess (e.g., 0), and if upon
+   completion, numsrc holds a larger value, the operation can be
+   repeated with a large enough buffer.
+
+   That is, on return, numsrc is always updated to be the total number
+   of sources in the filter, while slist will hold as many source
+   addresses as fit, up to the minimum of the array size passed in as
+   the original numsrc value and the total number of sources in the
+   filter.
+
+5.  Protocol-Independent Multicast Source Filter APIs
+
+   Protocol-independent functions are provided for join and leave
+   operations so that an application may pass a sockaddr_storage
+   structure obtained from calls such as getaddrinfo() [1] as the group
+   to join.  For example, an application can resolve a DNS name (e.g.,
+   NTP.MCAST.NET) to a multicast address which may be either IPv4 or
+   IPv6, and may easily join and leave the group.
+
+5.1.  Basic (Delta-based) API
+
+   The reception of multicast packets is controlled by the setsockopt()
+   options summarized below.  An error of EOPNOTSUPP is returned if
+   these options are used with getsockopt().
+
+   The following structures are used by both the Any-Source Multicast
+   and the Source-Specific Multicast API:  #include <netinet/in.h>
+
+   struct group_req {
+      uint32_t                gr_interface; /* interface index */
+      struct sockaddr_storage gr_group;     /* group address */
+   };
+
+   struct group_source_req {
+      uint32_t                gsr_interface; /* interface index */
+      struct sockaddr_storage gsr_group;     /* group address */
+      struct sockaddr_storage gsr_source;    /* source address */
+   };
+
+   The sockaddr_storage structure is defined in RFC 3493 [1] to be large
+   enough to hold either IPv4 or IPv6 address information.
+
+   The rules for generating errors are the same as those given in
+   Section 5.1.3.
+
+
+
+
+
+
+Thaler, et al.               Informational                     [Page 10]
+
+RFC 3678              Multicast Source Filter API           January 2004
+
+
+5.1.1.  Any-Source Multicast API
+
+   Socket option               Argument type
+   MCAST_JOIN_GROUP            struct group_req
+   MCAST_BLOCK_SOURCE          struct group_source_req
+   MCAST_UNBLOCK_SOURCE        struct group_source_req
+   MCAST_LEAVE_GROUP           struct group_req
+
+   MCAST_JOIN_GROUP and MCAST_LEAVE_GROUP are used to join and leave an
+   any-source group.
+
+   MCAST_BLOCK_SOURCE can be used to block data from a given source to a
+   given group (e.g., if the user "mutes" that source), and
+   MCAST_UNBLOCK_SOURCE can be used to undo this (e.g., if the user then
+   "unmutes" the source).
+
+5.1.2.  Source-Specific Multicast API
+
+   Socket option               Argument type
+   MCAST_JOIN_SOURCE_GROUP     struct group_source_req
+   MCAST_LEAVE_SOURCE_GROUP    struct group_source_req
+   MCAST_LEAVE_GROUP           struct group_req
+
+   MCAST_JOIN_SOURCE_GROUP and MCAST_LEAVE_SOURCE_GROUP are used to join
+   and leave a source-specific group.
+
+   MCAST_LEAVE_GROUP is supported, as a convenience, to drop all sources
+   which have been joined for a particular group and interface.  The
+   operations are the same as if the socket had been closed.
+
+5.2.  Advanced (Full-state) API
+
+   Implementations may exist that use ioctl() for this API, and for
+   historical purposes, the ioctl() API is documented in Appendix A.
+   The preferred API uses the new functions described below.
+
+5.2.1.  Set Source Filter
+
+     #include <netinet/in.h>
+
+     int setsourcefilter(int s, uint32_t interface,
+                         struct sockaddr *group, socklen_t grouplen,
+                         uint32_t fmode, uint_t numsrc,
+                         struct sockaddr_storage *slist);
+
+   On success the value 0 is returned, and on failure, the value -1 is
+   returned and errno is set accordingly.
+
+
+
+
+Thaler, et al.               Informational                     [Page 11]
+
+RFC 3678              Multicast Source Filter API           January 2004
+
+
+   The s argument identifies the socket.
+
+   The interface argument holds the interface index of the interface.
+
+   The group argument points to either a sockaddr_in structure (for
+   IPv4) or a sockaddr_in6 structure (for IPv6) that holds the IP
+   multicast address of the group.
+
+   The grouplen argument gives the length of the sockaddr_in or
+   sockaddr_in6 structure.
+
+   The fmode argument identifies the filter mode.  The value of this
+   field must be either MCAST_INCLUDE or MCAST_EXCLUDE, which are
+   likewise defined in <netinet/in.h>.
+
+   The numsrc argument holds the number of source addresses in the slist
+   array.
+
+   The slist argument points to an array of IP addresses of sources to
+   include or exclude depending on the filter mode.
+
+   If the implementation imposes a limit on the maximum number of
+   sources in a source filter, ENOBUFS is generated when the operation
+   would exceed the maximum.
+
+5.2.2.  Get Source Filter
+
+     #include <netinet/in.h>
+
+     int getsourcefilter(int s, uint32_t interface,
+                         struct sockaddr *group, socklen_t grouplen,
+                         uint32_t fmode, uint_t *numsrc,
+                         struct sockaddr_storage *slist);
+
+   On success the value 0 is returned, and on failure, the value -1 is
+   returned and errno is set accordingly.
+
+   The s argument identifies the socket.
+
+   The interface argument holds the local IP address of the interface.
+
+   The group argument points to either a sockaddr_in structure (for
+   IPv4) or a sockaddr_in6 structure (for IPv6) that holds the IP
+   multicast address of the group.
+
+
+
+
+
+
+
+Thaler, et al.               Informational                     [Page 12]
+
+RFC 3678              Multicast Source Filter API           January 2004
+
+
+   The fmode argument points to an integer that will contain the filter
+   mode on a successful return.  The value of this field will be either
+   MCAST_INCLUDE or MCAST_EXCLUDE, which are likewise defined in
+   <netinet/in.h>.
+
+   On input, the numsrc argument holds the number of source addresses
+   that will fit in the slist array.  On output, the numsrc argument
+   will hold the total number of sources in the filter.
+
+   The slist argument points to buffer into which an array of IP
+   addresses of included or excluded (depending on the filter mode)
+   sources will be written.  If numsrc was 0 on input, a NULL pointer
+   may be supplied.
+
+   If the application does not know the size of the source list
+   beforehand, it can make a reasonable guess (e.g., 0), and if upon
+   completion, numsrc holds a larger value, the operation can be
+   repeated with a large enough buffer.
+
+   That is, on return, numsrc is always updated to be the total number
+   of sources in the filter, while slist will hold as many source
+   addresses as fit, up to the minimum of the array size passed in as
+   the original numsrc value and the total number of sources in the
+   filter.
+
+6.  Security Considerations
+
+   Although source filtering can help to combat denial-of-service
+   attacks, source filtering alone is not a complete solution, since it
+   does not provide protection against spoofing the source address to be
+   an allowed source.  Multicast routing protocols which use reverse-
+   path forwarding based on the source address, however, do provide some
+   natural protection against spoofing the source address, since if a
+   router receives a packet on an interface other than the one toward
+   the "real" source, it will drop the packet.  However, this still does
+   not provide any guarantee of protection.
+
+7.  Acknowledgments
+
+   This document was updated based on feedback from the IETF's IDMR and
+   MAGMA Working Groups, and the Austin Group.  Wilbert de Graaf also
+   provided many helpful comments.
+
+
+
+
+
+
+
+
+
+Thaler, et al.               Informational                     [Page 13]
+
+RFC 3678              Multicast Source Filter API           January 2004
+
+
+8.  Appendix A: Use of ioctl() for full-state operations
+
+   The API defined here is historic, but is documented here for
+   informational purposes since it is implemented by multiple platforms.
+   The new functions defined earlier in this document should now be used
+   instead.
+
+   Retrieving the source filter for a given group cannot be done with
+   getsockopt() on some existing platforms, since the group and
+   interface must be passed down in order to retrieve the correct
+   filter, and getsockopt only supports an output buffer.  This can,
+   however, be done with an ioctl(), and hence for symmetry, both gets
+   and sets are done with an ioctl.
+
+8.1.  IPv4 Options
+
+   The following are defined in <sys/sockio.h>:
+
+      o  ioctl() SIOCGIPMSFILTER: to retrieve the list of source
+         addresses that comprise the source filter along with the
+         current filter mode.
+
+      o  ioctl() SIOCSIPMSFILTER: to set or modify the source filter
+         content (e.g., unicast source address list) or mode (exclude or
+         include).
+
+Ioctl option                  Argument type
+SIOCGIPMSFILTER               struct ip_msfilter
+SIOCSIPMSFILTER               struct ip_msfilter
+
+struct ip_msfilter {
+   struct in_addr imsf_multiaddr;  /* IP multicast address of group */
+   struct in_addr imsf_interface;  /* local IP address of interface */
+   uint32_t       imsf_fmode;      /* filter mode */
+   uint32_t       imsf_numsrc;     /* number of sources in src_list */
+   struct in_addr imsf_slist[1];   /* start of source list */
+};
+
+#define IP_MSFILTER_SIZE(numsrc) \
+   (sizeof(struct ip_msfilter) - sizeof(struct in_addr) \
+   + (numsrc) * sizeof(struct in_addr))
+
+   The imsf_fmode mode is a 32-bit integer that identifies the filter
+   mode.  The value of this field must be either MCAST_INCLUDE or
+   MCAST_EXCLUDE, which are likewise defined in <netinet/in.h>.
+
+
+
+
+
+
+Thaler, et al.               Informational                     [Page 14]
+
+RFC 3678              Multicast Source Filter API           January 2004
+
+
+   The structure length pointed to must be at least IP_MSFILTER_SIZE(0)
+   bytes long, and the imsf_numsrc parameter should be set so that
+   IP_MSFILTER_SIZE(imsf_numsrc) indicates the buffer length.
+
+   If the implementation imposes a limit on the maximum number of
+   sources in a source filter, ENOBUFS is generated when a set operation
+   would exceed the maximum.
+
+   The result of a get operation (SIOCGIPMSFILTER) will be that the
+   imsf_multiaddr and imsf_interface fields will be unchanged, while
+   imsf_fmode, imsf_numsrc, and as many source addresses as fit will be
+   filled into the application's buffer.
+
+   If the application does not know the size of the source list
+   beforehand, it can make a reasonable guess (e.g., 0), and if upon
+   completion, the imsf_numsrc field holds a larger value, the operation
+   can be repeated with a large enough buffer.
+
+   That is, on return from SIOCGIPMSFILTER, imsf_numsrc is always
+   updated to be the total number of sources in the filter, while
+   imsf_slist will hold as many source addresses as fit, up to the
+   minimum of the array size passed in as the original imsf_numsrc value
+   and the total number of sources in the filter.
+
+8.2.  Protocol-Independent Options
+
+   The following are defined in <sys/sockio.h>:
+
+      o  ioctl() SIOCGMSFILTER: to retrieve the list of source addresses
+         that comprise the source filter along with the current filter
+         mode.
+
+      o  ioctl() SIOCSMSFILTER: to set or modify the source filter
+         content (e.g., unicast source address list) or mode (exclude or
+         include).
+
+   Ioctl option                 Argument type
+   SIOCGMSFILTER                struct group_filter
+   SIOCSMSFILTER                struct group_filter
+
+   struct group_filter {
+      uint32_t                gf_interface; /* interface index */
+      struct sockaddr_storage gf_group;     /* multicast address */
+      uint32_t                gf_fmode;     /* filter mode */
+      uint32_t                gf_numsrc;    /* number of sources */
+      struct sockaddr_storage gf_slist[1];  /* source address */
+   };
+
+
+
+
+Thaler, et al.               Informational                     [Page 15]
+
+RFC 3678              Multicast Source Filter API           January 2004
+
+
+   #define GROUP_FILTER_SIZE(numsrc) \
+      (sizeof(struct group_filter) - sizeof(struct sockaddr_storage) \
+      + (numsrc) * sizeof(struct sockaddr_storage))
+
+   The imf_numsrc field is used in the same way as described for
+   imsf_numsrc above.
+
+9.  Normative References
+
+   [1]  Gilligan, R., Thomson, S., Bound, J., McCann, J. and W.
+        Stevens, "Basic Socket Interface Extensions for IPv6", RFC 3493,
+        February 2003.
+
+   [2]  IEEE Std. 1003.1-2001 Standard for Information Technology --
+        Portable Operating System Interface (POSIX).  Open Group
+        Technical Standard: Base Specifications, Issue 6, December 2001.
+        ISO/IEC 9945:2002.  http://www.opengroup.org/austin
+
+10.  Informative References
+
+   [3]  Cain, B., Deering, S., Kouvelas, I., Fenner, B. and A.
+        Thyagarajan, "Internet Group Management Protocol, Version 3",
+        RFC 3376, October 2002.
+
+   [4]  Vida, R. and L. Costa, "Multicast Listener Discovery Version 2
+        (MLDv2) for IPv6", Work in Progress, December 2003.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Thaler, et al.               Informational                     [Page 16]
+
+RFC 3678              Multicast Source Filter API           January 2004
+
+
+11.  Authors' Addresses
+
+   Dave Thaler
+   Microsoft Corporation
+   One Microsoft Way
+   Redmond, WA  98052-6399
+
+   Phone: +1 425 703 8835
+   EMail: dthaler@microsoft.com
+
+
+   Bill Fenner
+   75 Willow Road
+   Menlo Park, CA  94025
+
+   Phone: +1 650 867 6073
+   EMail: fenner@research.att.com
+
+
+   Bob Quinn
+   IP Multicast Initiative (IPMI)
+   Stardust.com
+   1901 S. Bascom Ave. #333
+   Campbell, CA 95008
+
+   Phone: +1 408 879 8080
+   EMail: rcq@ipmulticast.com
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Thaler, et al.               Informational                     [Page 17]
+
+RFC 3678              Multicast Source Filter API           January 2004
+
+
+12.  Full Copyright Statement
+
+   Copyright (C) The Internet Society (2004).  All Rights Reserved.
+
+   This document and translations of it may be copied and furnished to
+   others, and derivative works that comment on or otherwise explain it
+   or assist in its implementation may be prepared, copied, published
+   and distributed, in whole or in part, without restriction of any
+   kind, provided that the above copyright notice and this paragraph are
+   included on all such copies and derivative works.  However, this
+   document itself may not be modified in any way, such as by removing
+   the copyright notice or references to the Internet Society or other
+   Internet organizations, except as needed for the purpose of
+   developing Internet standards in which case the procedures for
+   copyrights defined in the Internet Standards process must be
+   followed, or as required to translate it into languages other than
+   English.
+
+   The limited permissions granted above are perpetual and will not be
+   revoked by the Internet Society or its successors or assignees.
+
+   This document and the information contained herein is provided on an
+   "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
+   TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
+   BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
+   HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
+   MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+
+Acknowledgement
+
+   Funding for the RFC Editor function is currently provided by the
+   Internet Society.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Thaler, et al.               Informational                     [Page 18]
+