diff options
Diffstat (limited to 'doc/rfc/rfc3678.txt')
| -rw-r--r-- | doc/rfc/rfc3678.txt | 1011 |
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] + |