idnits 2.17.00 (12 Aug 2021) /tmp/idnits38653/draft-ietf-magma-msf-api-05.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) == There are 1 instance of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year -- The document date (June 27, 2003) is 6896 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Informational ---------------------------------------------------------------------------- == Outdated reference: draft-vida-mld-v2 has been published as RFC 3810 Summary: 2 errors (**), 0 flaws (~~), 3 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 MAGMA Working Group D. Thaler 3 INTERNET-DRAFT Microsoft 4 Expires December 2003 B. Fenner 5 Category: Informational AT&T Research 6 B. Quinn 7 Stardust.com 8 June 27, 2003 10 Socket Interface Extensions for Multicast Source Filters 11 13 Status of this Memo 15 This document is an Internet-Draft and is in full conformance with 16 all provisions of Section 10 of RFC2026. 18 Internet-Drafts are working documents of the Internet Engineering 19 Task Force (IETF), its areas, and its working groups. Note that 20 other groups may also distribute working documents as Internet- 21 Drafts. 23 Internet-Drafts are draft documents valid for a maximum of six 24 months and may be updated, replaced, or obsoleted by other 25 documents at any time. It is inappropriate to use Internet- 26 Drafts as reference material or to cite them other than as "work 27 in progress." 29 The list of current Internet-Drafts can be accessed at 30 http://www.ietf.org/ietf/1id-abstracts.txt 32 The list of Internet-Draft Shadow Directories can be accessed at 33 http://www.ietf.org/shadow.html. 35 Copyright Notice 36 Draft Multicast Source Filter API June 2003 38 Copyright (C) The Internet Society (2003). All Rights Reserved. 40 Abstract 42 IGMPv3 for IPv4 and MLDv2 for IPv6 add the capability for 43 applications to express source filters on multicast group 44 memberships, which allows receiver applications to determine the 45 set of senders (sources) from which to accept multicast traffic. 46 This capability also simplifies support of one-to-many type 47 multicast applications. It is expected that in the near future, 48 the same capability will be available in IPv6 as well. 50 This document specifies new socket options and functions to manage 51 source filters for IP Multicast group memberships. It also 52 defines the socket structures to provide input and output 53 arguments to these new APIs. These extensions are designed to 54 provide access to the source filtering features, while introducing 55 a minimum of change into the system and providing complete 56 compatibility for existing multicast applications. 58 1. Introduction 60 The de facto standard application program interface (API) for 61 TCP/IP applications is the "sockets" interface. Although this API 62 was developed for Unix in the early 1980s it has also been 63 implemented on a wide variety of non-Unix systems. TCP/IP 64 applications written using the sockets API have in the past 65 enjoyed a high degree of portability and we would like the same 66 portability with applications that employ multicast source 67 filters. Changes are required to the sockets API to support such 68 filtering and this memo describes these changes. 70 This document specifies new socket options and functions to manage 71 source filters for IP Multicast group memberships. It also 72 defines the socket structures to provide input and output 73 arguments to these new APIs. These extensions are designed to 74 provide access to the source filtering features required by 75 applications, while introducing a minimum of change into the 76 system and providing complete compatibility for existing multicast 77 applications. 79 Furthermore, RFC 3493 [1] defines socket interface extensions for 80 IPv6, including protocol-independent functions for most 81 operations. However, while it defines join and leave functions 82 Draft Multicast Source Filter API June 2003 84 for IPv6, it does not provide protocol-independent versions of 85 these operations. Such functions will be described in this 86 document. 88 The reader should note that this document is for informational 89 purposes only, and that the official standard specification of the 90 sockets API is [2]. 92 2. Design Considerations 94 There are a number of important considerations in designing 95 changes to this well-worn API: 97 o The API changes should provide both source and binary 98 compatibility for programs written to the original API. That 99 is, existing program binaries should continue to operate when 100 run on a system supporting the new API. In addition, existing 101 applications that are re-compiled and run on a system 102 supporting the new API should continue to operate. Simply 103 put, the API changes for multicast receivers that specify 104 source filters should not break existing programs. 106 o The changes to the API should be as small as possible in 107 order to simplify the task of converting existing multicast 108 receiver applications to use source filters. 110 o Applications should be able to detect when the new source 111 filter APIs are unavailable (e.g., calls fail with the 112 ENOTSUPP error) and react gracefully (e.g., revert to old 113 non-source-filter API or display a meaningful error message 114 to the user). 116 o Lack of type-safety in an API is a bad thing which should be 117 avoided when possible. 119 Several implementations exist that use ioctl() for a portion of 120 the functionality described herein, and for historical purposes, 121 the ioctl API is documented in Appendix A. The preferred API, 122 however, includes new functions. The reasons for adding new 123 functions are: 125 o New functions provide type-safety, unlike ioctl, getsockopt, 126 and setsockopt. 128 Draft Multicast Source Filter API June 2003 130 o A new function can be written as a wrapper over an ioctl, 131 getsockopt, or setsockopt call, if necessary. Hence, it 132 provides more freedom as to how the functionality is 133 implemented in an operating system. For example, a new 134 function might be implemented as an inline function in an 135 include file, or a function exported from a user-mode library 136 which internally uses some mechanism to exchange information 137 with the kernel, or be implemented directly in the kernel. 139 o At least one operation defined herein needs to be able to 140 both pass information to the TCP/IP stack, as well as 141 retrieve information from it. In some implementations this 142 is problematic without either changing getsockopt or using 143 ioctl. Using new functions avoids the need to change such 144 implementations. 146 2.1. What Needs to be Added 148 The current IP Multicast APIs allow a receiver application to 149 specify the group address (destination) and (optionally) the local 150 interface. These existing APIs need not change (and cannot, to 151 retain binary compatibility). Hence, what is needed are new 152 source filter APIs that provide the same functionality and also 153 allow receiver multicast applications to: 155 o Specify zero or more unicast (source) address(es) in a source 156 filter. 158 o Determine whether the source filter describes an inclusive or 159 exclusive list of sources. 161 The new API design must enable this functionality for both IPv4 162 and IPv6. 164 2.2. Data Types 166 The data types of the structure elements given in this memo are 167 intended to be examples, not absolute requirements. Whenever 168 possible, data types from POSIX 1003.1g [2] are used: uintN_t 169 means an unsigned integer of exactly N bits (e.g., uint32_t). 171 Draft Multicast Source Filter API June 2003 173 2.3. Headers 175 When function prototypes and structures are shown, we show the 176 headers that must be #included to cause that item to be defined. 178 2.4. Structures 180 When structures are described, the members shown are the ones that 181 must appear in an implementation. Additional, nonstandard members 182 may also be defined by an implementation. As an additional 183 precaution, nonstandard members could be verified by Feature Test 184 Macros as described in [2]. (Such Feature Test Macros are not 185 defined by this RFC.) 187 The ordering shown for the members of a structure is the 188 recommended ordering, given alignment considerations of multibyte 189 members, but an implementation may order the members differently. 191 3. Overview of APIs 193 There are a number of different APIs described in this document, 194 that are appropriate for a number of different application types 195 and IP versions. Before providing detailed descriptions, this 196 section provides a "taxonomy" with a brief description of each. 198 There are two categories of source-filter APIs, both of which are 199 designed to allow multicast receiver applications to designate the 200 unicast address(es) of sender(s) along with the multicast group 201 (destination address) to receive. 203 o Basic (Delta-based): Some applications desire the simplicity of 204 a delta-based API in which each function call specifies a 205 single source address which should be added to or removed from 206 the existing filter for a given multicast group address on 207 which to listen. Such applications typically fall into either 208 of two categories: 210 + Any-Source Multicast: By default, all sources are accepted. 211 Individual sources may be turned off and back on as needed 212 over time. This is also known as "exclude" mode, since the 213 source filter contains a list of excluded sources. 215 Draft Multicast Source Filter API June 2003 217 + Source-Specific Multicast: Only sources in a given list are 218 allowed. The list may change over time. This is also known 219 as "include" mode, since the source filter contains a list of 220 included sources. 222 This API would be used, for example, by "single-source" 223 applications such as audio/video broadcasting. It would also 224 be used for logical multi-source sessions where each source 225 independently allocates its own Source-Specific Multicast 226 group address. 228 o Advanced (Full-state): This API allows an application to define 229 a complete source-filter comprised of zero or more source 230 addresses, and replace the previous filter with a new one. 232 Applications which require the ability to switch between filter 233 modes without leaving a group must use a full-state API (i.e., 234 to change the semantics of the source filter from inclusive to 235 exclusive, or vice versa). 237 Applications which use a large source list for a given group 238 address should also use the full-state API, since filter 239 changes can be done atomically in a single operation. 241 The above types of APIs exist in IPv4-specific variants as well as 242 with protocol-independent variants. One might ask why the 243 protocol-independent APIs cannot accommodate IPv4 applications as 244 well as IPv6. Since any IPv4 application requires modification to 245 use multicast source filters anyway, it might seem like a good 246 opportunity to create IPv6-compatible source code. 248 The primary reasons for extending an IPv4-specific API are: 250 o To minimize changes needed in existing IPv4 multicast 251 application source code to add source filter support. 253 o To avoid overloading APIs to accommodate the differences 254 between IPv4 interface addresses (e.g., in the ip_mreq 255 structure) and interface indices. 257 Draft Multicast Source Filter API June 2003 259 4. IPv4 Multicast Source Filter APIs 261 Version 3 of the Internet Group Management Protocol (IGMPv3) [3] 262 and version 2 of the Multicast Listener Discovery (MLDv2) protocol 263 [4] provide the ability to communicate source filter information 264 to the router and hence avoid pulling down data from unwanted 265 sources onto the local link. However, source filters may be 266 implemented by the operating system regardless of whether the 267 routers support IGMPv3 or MLDv2, so when the source-filter API is 268 available, applications can always benefit from using it. 270 4.1. Basic (Delta-based) API for IPv4 272 The reception of multicast packets is controlled by the 273 setsockopt() options summarized below. An error of EOPNOTSUPP is 274 returned if these options are used with getsockopt(). 276 The following structures are used by both the Any-Source Multicast 277 and the Source-Specific Multicast API: 279 #include 281 struct ip_mreq { 282 struct in_addr imr_multiaddr; /* IP address of group */ 283 struct in_addr imr_interface; /* IP address of interface */ 284 }; 286 struct ip_mreq_source { 287 struct in_addr imr_multiaddr; /* IP address of group */ 288 struct in_addr imr_sourceaddr; /* IP address of source */ 289 struct in_addr imr_interface; /* IP address of interface */ 290 }; 292 4.1.1. IPv4 Any-Source Multicast API 294 The following socket options are defined in for 295 applications in the Any-Source Multicast category: 297 Socket option Argument type 298 IP_ADD_MEMBERSHIP struct ip_mreq 299 IP_BLOCK_SOURCE struct ip_mreq_source 300 IP_UNBLOCK_SOURCE struct ip_mreq_source 301 IP_DROP_MEMBERSHIP struct ip_mreq 302 Draft Multicast Source Filter API June 2003 304 IP_ADD_MEMBERSHIP and IP_DROP_MEMBERSHIP are already implemented 305 on most operating systems, and are used to join and leave an any- 306 source group. 308 IP_BLOCK_SOURCE can be used to block data from a given source to a 309 given group (e.g., if the user "mutes" that source), and 310 IP_UNBLOCK_SOURCE can be used to undo this (e.g., if the user then 311 "unmutes" the source). 313 4.1.2. IPv4 Source-Specific Multicast API 315 The following socket options are available for applications in the 316 Source-Specific category: 318 Socket option Argument type 319 IP_ADD_SOURCE_MEMBERSHIP struct ip_mreq_source 320 IP_DROP_SOURCE_MEMBERSHIP struct ip_mreq_source 321 IP_DROP_MEMBERSHIP struct ip_mreq 323 IP_ADD_SOURCE_MEMBERSHIP and IP_DROP_SOURCE_MEMBERSHIP are used to 324 join and leave a source-specific group. 326 IP_DROP_MEMBERSHIP is supported, as a convenience, to drop all 327 sources which have been joined for a particular group and 328 interface. The operations are the same as if the socket had been 329 closed. 331 4.1.3. Error Codes 333 When the option would be legal on the group, but an address is 334 invalid (e.g., when trying to block a source that is already 335 blocked by the socket, or when trying to drop an unjoined group) 336 the error generated is EADDRNOTAVAIL. 338 When the option itself is not legal on the group (i.e., when 339 trying a Source-Specific option on a group after doing 340 IP_ADD_MEMBERSHIP, or when trying an Any-Source option without 341 doing IP_ADD_MEMBERSHIP) the error generated is EINVAL. 343 When any of these options are used with getsockopt(), the error 344 generated is EOPNOTSUPP. 346 Finally, if the implementation imposes a limit on the maximum 347 Draft Multicast Source Filter API June 2003 349 number of sources in a source filter, ENOBUFS is generated when an 350 operation would exceed the maximum. 352 4.2. Advanced (Full-state) API for IPv4 354 Several implementations exist that use ioctl() for this API, and 355 for historical purposes, the ioctl() API is documented in Appendix 356 A. The preferred API uses the new functions described below. 358 4.2.1. Set Source Filter 360 #include 362 int setipv4sourcefilter(int s, struct in_addr interface, 363 struct in_addr group, uint32_t fmode, 364 uint32_t numsrc, struct in_addr *slist); 366 On success the value 0 is returned, and on failure, the value -1 367 is returned and errno is set accordingly. 369 The s argument identifies the socket. 371 The interface argument holds the local IP address of the 372 interface. 374 The group argument holds the IP multicast address of the group. 376 The fmode argument identifies the filter mode. The value of this 377 field must be either MCAST_INCLUDE or MCAST_EXCLUDE, which are 378 likewise defined in . 380 The numsrc argument holds the number of source addresses in the 381 slist array. 383 The slist argument points to an array of IP addresses of sources 384 to include or exclude depending on the filter mode. 386 If the implementation imposes a limit on the maximum number of 387 sources in a source filter, ENOBUFS is generated when the 388 operation would exceed the maximum. 390 Draft Multicast Source Filter API June 2003 392 4.2.2. Get Source Filter 394 #include 396 int getipv4sourcefilter(int s, struct in_addr interface, 397 struct in_addr group, uint32_t *fmode, 398 uint32_t *numsrc, struct in_addr *slist); 400 On success the value 0 is returned, and on failure, the value -1 401 is returned and errno is set accordingly. 403 The s argument identifies the socket. 405 The interface argument holds the local IP address of the 406 interface. 408 The group argument holds the IP multicast address of the group. 410 The fmode argument points to an integer that will contain the 411 filter mode on a successful return. The value of this field will 412 be either MCAST_INCLUDE or MCAST_EXCLUDE, which are likewise 413 defined in . 415 On input, the numsrc argument holds the number of source addresses 416 that will fit in the slist array. On output, the numsrc argument 417 will hold the total number of sources in the filter. 419 The slist argument points to buffer into which an array of IP 420 addresses of included or excluded (depending on the filter mode) 421 sources will be written. If numsrc was 0 on input, a NULL pointer 422 may be supplied. 424 If the application does not know the size of the source list 425 beforehand, it can make a reasonable guess (e.g., 0), and if upon 426 completion, numsrc holds a larger value, the operation can be 427 repeated with a large enough buffer. 429 That is, on return, numsrc is always updated to be the total 430 number of sources in the filter, while slist will hold as many 431 source addresses as fit, up to the minimum of the array size 432 passed in as the original numsrc value and the total number of 433 sources in the filter. 435 Draft Multicast Source Filter API June 2003 437 5. Protocol-Independent Multicast Source Filter APIs 439 Protocol-independent functions are provided for join and leave 440 operations so that an application may pass a sockaddr_storage 441 structure obtained from calls such as getaddrinfo() [1] as the 442 group to join. For example, an application can resolve a DNS name 443 (e.g., NTP.MCAST.NET) to a multicast address which may be either 444 IPv4 or IPv6, and may easily join and leave the group. 446 5.1. Basic (Delta-based) API 448 The reception of multicast packets is controlled by the 449 setsockopt() options summarized below. An error of EOPNOTSUPP is 450 returned if these options are used with getsockopt(). 452 The following structures are used by both the Any-Source Multicast 453 and the Source-Specific Multicast API: 454 #include 456 struct group_req { 457 uint32_t gr_interface; /* interface index */ 458 struct sockaddr_storage gr_group; /* group address */ 459 }; 461 struct group_source_req { 462 uint32_t gsr_interface; /* interface index */ 463 struct sockaddr_storage gsr_group; /* group address */ 464 struct sockaddr_storage gsr_source; /* source address */ 465 }; 467 The sockaddr_storage structure is defined in RFC 3493 [1] to be 468 large enough to hold either IPv4 or IPv6 address information. 470 The rules for generating errors are the same as those given in 471 Section 5.1.3. 473 5.1.1. Any-Source Multicast API 475 Socket option Argument type 476 MCAST_JOIN_GROUP struct group_req 477 MCAST_BLOCK_SOURCE struct group_source_req 478 MCAST_UNBLOCK_SOURCE struct group_source_req 479 MCAST_LEAVE_GROUP struct group_req 480 Draft Multicast Source Filter API June 2003 482 MCAST_JOIN_GROUP and MCAST_LEAVE_GROUP are used to join and leave 483 an any-source group. 485 MCAST_BLOCK_SOURCE can be used to block data from a given source 486 to a given group (e.g., if the user "mutes" that source), and 487 MCAST_UNBLOCK_SOURCE can be used to undo this (e.g., if the user 488 then "unmutes" the source). 490 5.1.2. Source-Specific Multicast API 492 Socket option Argument type 493 MCAST_JOIN_SOURCE_GROUP struct group_source_req 494 MCAST_LEAVE_SOURCE_GROUP struct group_source_req 495 MCAST_LEAVE_GROUP struct group_req 497 MCAST_JOIN_SOURCE_GROUP and MCAST_LEAVE_SOURCE_GROUP are used to 498 join and leave a source-specific group. 500 MCAST_LEAVE_GROUP is supported, as a convenience, to drop all 501 sources which have been joined for a particular group and 502 interface. The operations are the same as if the socket had been 503 closed. 505 5.2. Advanced (Full-state) API 507 Implementations may exist that use ioctl() for this API, and for 508 historical purposes, the ioctl() API is documented in Appendix A. 509 The preferred API uses the new functions described below. 511 5.2.1. Set Source Filter 513 #include 515 int setsourcefilter(int s, uint32_t interface, 516 struct sockaddr *group, socklen_t grouplen, 517 uint32_t fmode, uint_t numsrc, 518 struct sockaddr_storage *slist); 520 On success the value 0 is returned, and on failure, the value -1 521 is returned and errno is set accordingly. 523 The s argument identifies the socket. 525 Draft Multicast Source Filter API June 2003 527 The interface argument holds the interface index of the interface. 529 The group argument points to either a sockaddr_in structure (for 530 IPv4) or a sockaddr_in6 structure (for IPv6) that holds the IP 531 multicast address of the group. 533 The grouplen argument gives the length of the sockaddr_in or 534 sockaddr_in6 structure. 536 The fmode argument identifies the filter mode. The value of this 537 field must be either MCAST_INCLUDE or MCAST_EXCLUDE, which are 538 likewise defined in . 540 The numsrc argument holds the number of source addresses in the 541 slist array. 543 The slist argument points to an array of IP addresses of sources 544 to include or exclude depending on the filter mode. 546 If the implementation imposes a limit on the maximum number of 547 sources in a source filter, ENOBUFS is generated when the 548 operation would exceed the maximum. 550 5.2.2. Get Source Filter 552 #include 554 int getsourcefilter(int s, uint32_t interface, 555 struct sockaddr *group, socklen_t grouplen, 556 uint32_t fmode, uint_t *numsrc, 557 struct sockaddr_storage *slist); 559 On success the value 0 is returned, and on failure, the value -1 560 is returned and errno is set accordingly. 562 The s argument identifies the socket. 564 The interface argument holds the local IP address of the 565 interface. 567 The group argument points to either a sockaddr_in structure (for 568 IPv4) or a sockaddr_in6 structure (for IPv6) that holds the IP 569 multicast address of the group. 571 Draft Multicast Source Filter API June 2003 573 The fmode argument points to an integer that will contain the 574 filter mode on a successful return. The value of this field will 575 be either MCAST_INCLUDE or MCAST_EXCLUDE, which are likewise 576 defined in . 578 On input, the numsrc argument holds the number of source addresses 579 that will fit in the slist array. On output, the numsrc argument 580 will hold the total number of sources in the filter. 582 The slist argument points to buffer into which an array of IP 583 addresses of included or excluded (depending on the filter mode) 584 sources will be written. If numsrc was 0 on input, a NULL pointer 585 may be supplied. 587 If the application does not know the size of the source list 588 beforehand, it can make a reasonable guess (e.g., 0), and if upon 589 completion, numsrc holds a larger value, the operation can be 590 repeated with a large enough buffer. 592 That is, on return, numsrc is always updated to be the total 593 number of sources in the filter, while slist will hold as many 594 source addresses as fit, up to the minimum of the array size 595 passed in as the original numsrc value and the total number of 596 sources in the filter. 598 6. Security Considerations 600 Although source filtering can help to combat denial-of-service 601 attacks, source filtering alone is not a complete solution, since 602 it does not provide protection against spoofing the source address 603 to be an allowed source. Multicast routing protocols which use 604 reverse-path forwarding based on the source address, however, do 605 provide some natural protection against spoofing the source 606 address, since if a router receives a packet on an interface other 607 than the one toward the "real" source, it will drop the packet. 608 However, this still does not provide any guarantee of protection. 610 7. Acknowledgments 612 This draft was updated based on feedback from the IETF's IDMR and 613 MAGMA Working Groups, and the Austin Group. Wilbert de Graaf also 614 provided many helpful comments. 616 Draft Multicast Source Filter API June 2003 618 8. Appendix A: Use of ioctl() for full-state operations 620 The API defined here is historic, but is documented here for 621 informational purposes since it is implemented by multiple 622 platforms. The new functions defined earlier in this document 623 should now be used instead. 625 Retrieving the source filter for a given group cannot be done with 626 getsockopt() on some existing platforms, since the group and 627 interface must be passed down in order to retrieve the correct 628 filter, and getsockopt only supports an output buffer. This can, 629 however, be done with an ioctl(), and hence for symmetry, both 630 gets and sets are done with an ioctl. 632 8.1. IPv4 Options 634 The following are defined in : 636 o ioctl() SIOCGIPMSFILTER: to retrieve the list of source 637 addresses that comprise the source filter along with the 638 current filter mode. 640 o ioctl() SIOCSIPMSFILTER: to set or modify the source filter 641 content (e.g. unicast source address list) or mode (exclude 642 or include). 644 Ioctl option Argument type 645 SIOCGIPMSFILTER struct ip_msfilter 646 SIOCSIPMSFILTER struct ip_msfilter 648 struct ip_msfilter { 649 struct in_addr imsf_multiaddr; /* IP multicast address of group */ 650 struct in_addr imsf_interface; /* local IP address of interface */ 651 uint32_t imsf_fmode; /* filter mode */ 652 uint32_t imsf_numsrc; /* number of sources in src_list */ 653 struct in_addr imsf_slist[1]; /* start of source list */ 654 }; 656 #define IP_MSFILTER_SIZE(numsrc) \ 657 (sizeof(struct ip_msfilter) - sizeof(struct in_addr) \ 658 + (numsrc) * sizeof(struct in_addr)) 660 Draft Multicast Source Filter API June 2003 662 The imsf_fmode mode is a 32-bit integer that identifies the filter 663 mode. The value of this field must be either MCAST_INCLUDE or 664 MCAST_EXCLUDE, which are likewise defined in . 666 The structure length pointed to must be at least 667 IP_MSFILTER_SIZE(0) bytes long, and the imsf_numsrc parameter 668 should be set so that IP_MSFILTER_SIZE(imsf_numsrc) indicates the 669 buffer length. 671 If the implementation imposes a limit on the maximum number of 672 sources in a source filter, ENOBUFS is generated when a set 673 operation would exceed the maximum. 675 The result of a get operation (SIOCGIPMSFILTER) will be that the 676 imsf_multiaddr and imsf_interface fields will be unchanged, while 677 imsf_fmode, imsf_numsrc, and as many source addresses as fit will 678 be filled into the application's buffer. 680 If the application does not know the size of the source list 681 beforehand, it can make a reasonable guess (e.g., 0), and if upon 682 completion, the imsf_numsrc field holds a larger value, the 683 operation can be repeated with a large enough buffer. 685 That is, on return from SIOCGIPMSFILTER, imsf_numsrc is always 686 updated to be the total number of sources in the filter, while 687 imsf_slist will hold as many source addresses as fit, up to the 688 minimum of the array size passed in as the original imsf_numsrc 689 value and the total number of sources in the filter. 691 8.2. Protocol-Independent Options 693 The following are defined in : 695 o ioctl() SIOCGMSFILTER: to retrieve the list of source 696 addresses that comprise the source filter along with the 697 current filter mode. 699 o ioctl() SIOCSMSFILTER: to set or modify the source filter 700 content (e.g. unicast source address list) or mode (exclude 701 or include). 702 Ioctl option Argument type 703 SIOCGMSFILTER struct group_filter 704 SIOCSMSFILTER struct group_filter 705 Draft Multicast Source Filter API June 2003 707 struct group_filter { 708 uint32_t gf_interface; /* interface index */ 709 struct sockaddr_storage gf_group; /* multicast address */ 710 uint32_t gf_fmode; /* filter mode */ 711 uint32_t gf_numsrc; /* number of sources */ 712 struct sockaddr_storage gf_slist[1]; /* source address */ 713 }; 715 #define GROUP_FILTER_SIZE(numsrc) \ 716 (sizeof(struct group_filter) - sizeof(struct sockaddr_storage) \ 717 + (numsrc) * sizeof(struct sockaddr_storage)) 719 The imf_numsrc field is used in the same way as described for 720 imsf_numsrc above. 722 9. Authors' Addresses 724 Dave Thaler 725 Microsoft Corporation 726 One Microsoft Way 727 Redmond, WA 98052-6399 728 Phone: +1 425 703 8835 729 EMail: dthaler@microsoft.com 731 Bill Fenner 732 75 Willow Road 733 Menlo Park, CA 94025 734 Phone: +1 650 867 6073 735 EMail: fenner@research.att.com 737 Bob Quinn 738 IP Multicast Initiative (IPMI) 739 Stardust.com 740 1901 S. Bascom Ave. #333 741 Campbell, CA 95008 742 Phone: +1 408 879 8080 743 EMail: rcq@ipmulticast.com 745 10. Normative References 747 [1] Gilligan, R., Thomson, S., Bound, J., McCann, J., and W. 748 Stevens, "Basic Socket Interface Extensions for IPv6", RFC 749 3493, February 2003. 751 Draft Multicast Source Filter API June 2003 753 [2] IEEE Std. 1003.1-2001 Standard for Information Technology -- 754 Portable Operating System Interface (POSIX). Open Group 755 Technical Standard: Base Specifications, Issue 6, December 756 2001. ISO/IEC 9945:2002. http://www.opengroup.org/austin 758 11. Informative References 760 [3] Cain, B., Deering, S., Kouvelas, I., Fenner, B., and A. 761 Thyagarajan, "Internet Group Management Protocol, Version 3", 762 RFC 3376, October 2002. 764 [4] Vida, R. and L. Costa, "Multicast Listener Discovery Version 765 2 (MLDv2) for IPv6", Work in progress, draft-vida-mld- 766 v2-07.txt, June 2003. 768 12. Full Copyright Statement 770 Copyright (C) The Internet Society (2003). All Rights Reserved. 772 This document and translations of it may be copied and furnished 773 to others, and derivative works that comment on or otherwise 774 explain it or assist in its implementation may be prepared, 775 copied, published and distributed, in whole or in part, without 776 restriction of any kind, provided that the above copyright notice 777 and this paragraph are included on all such copies and derivative 778 works. However, this document itself may not be modified in any 779 way, such as by removing the copyright notice or references to the 780 Internet Society or other Internet organizations, except as needed 781 for the purpose of developing Internet standards in which case the 782 procedures for copyrights defined in the Internet Standards 783 process must be followed, or as required to translate it into 784 languages other than English. 786 The limited permissions granted above are perpetual and will not 787 be revoked by the Internet Society or its successors or assigns. 789 This document and the information contained herein is provided on 790 an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET 791 ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR 792 IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 793 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 794 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 796 Draft Multicast Source Filter API June 2003 798 Table of Contents 800 1: Introduction ............................................. 2 801 2: Design Considerations .................................... 3 802 2.1: What Needs to be Added ................................. 4 803 2.2: Data Types ............................................. 4 804 2.3: Headers ................................................ 5 805 2.4: Structures ............................................. 5 806 3: Overview of APIs ......................................... 5 807 4: IPv4 Multicast Source Filter APIs ........................ 7 808 4.1: Basic (Delta-based) API for IPv4 ....................... 7 809 4.1.1: IPv4 Any-Source Multicast API ........................ 7 810 4.1.2: IPv4 Source-Specific Multicast API ................... 8 811 4.1.3: Error Codes .......................................... 8 812 4.2: Advanced (Full-state) API for IPv4 ..................... 9 813 4.2.1: Set Source Filter .................................... 9 814 4.2.2: Get Source Filter .................................... 10 815 5: Protocol-Independent Multicast Source Filter APIs ........ 11 816 5.1: Basic (Delta-based) API ................................ 11 817 5.1.1: Any-Source Multicast API ............................. 11 818 5.1.2: Source-Specific Multicast API ........................ 12 819 5.2: Advanced (Full-state) API .............................. 12 820 5.2.1: Set Source Filter .................................... 12 821 5.2.2: Get Source Filter .................................... 13 822 6: Security Considerations .................................. 14 823 7: Acknowledgments .......................................... 14 824 8: Appendix A: Use of ioctl() for full-state operations ..... 15 825 8.1: IPv4 Options ........................................... 15 826 8.2: Protocol-Independent Options ........................... 16 827 9: Authors' Addresses ....................................... 17 828 10: Normative References .................................... 17 829 11: Informative References .................................. 18 830 12: Full Copyright Statement ................................ 18