idnits 2.17.1 draft-ietf-idmr-msf-api-03.txt: ** The Abstract section seems to be numbered 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 'Intended status' indicated for this document; assuming Proposed Standard 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 4 instances of too long lines in the document, the longest one being 3 characters in excess of 72. == 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 == Line 275 has weird spacing: '... struct in_ad...' == Line 276 has weird spacing: '... struct in_ad...' == Line 280 has weird spacing: '... struct in_ad...' == Line 281 has weird spacing: '... struct in_ad...' == Line 282 has weird spacing: '... struct in_ad...' -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (29 June 2002) is 7965 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: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 2553 (ref. '1') (Obsoleted by RFC 3493) -- Unexpected draft version: The latest known version of draft-ietf-idmr-igmp-v3 is -10, but you're referring to -11. Summary: 5 errors (**), 0 flaws (~~), 8 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 IDMR Working Group Dave Thaler 3 INTERNET-DRAFT Microsoft 4 Expires December 2002 Bill Fenner 5 Type: Informational AT&T Research 6 Bob Quinn 7 Stardust.com 8 29 June 2002 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 2002 38 Copyright (C) The Internet Society (2002). All Rights Reserved. 40 1. Abstract 42 IGMPv3 for IPv4 adds the capability for applications to express 43 source filters on multicast group memberships, which allows 44 receiver applications to determine the set of senders (sources) 45 from which to accept multicast traffic. This capability also 46 simplifies support of one-to-many type multicast applications. It 47 is expected that in the future, the same capability will be 48 available in IPv6 as well. 50 This document specifies new socket options and ioctl commands to 51 manage 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 2. 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 ioctl commands to 71 manage 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 2553 [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 2002 84 for IPv6, it does not provide protocol-independent versions of 85 these operations. Such functions will be described in this 86 document. 88 3. Design Considerations 90 There are a number of important considerations in designing 91 changes to this well-worn API: 93 o The API changes should provide both source and binary 94 compatibility for programs written to the original API. That 95 is, existing program binaries should continue to operate when 96 run on a system supporting the new API. In addition, existing 97 applications that are re-compiled and run on a system 98 supporting the new API should continue to operate. Simply 99 put, the API changes for multicast receivers that specify 100 source filters should not break existing programs. 102 o The changes to the API should be as small as possible in 103 order to simplify the task of converting existing multicast 104 receiver applications to use source filters. 106 o Applications should be able to detect when the new source 107 filter APIs are unavailable (e.g., calls fail with the 108 ENOTSUPP error) and react gracefully (e.g., revert to old 109 non-source-filter API or display a meaningful error message 110 to the user). 112 3.1. What Needs to be Added 114 The current IP Multicast APIs allow a receiver application to 115 specify the group address (destination) and (optionally) the local 116 interface. These existing APIs need not change (and cannot, to 117 retain binary compatibility). Hence, what is needed are new 118 source filter APIs that provide the same functionality and also 119 allow receiver multicast applications to: 121 o Specify zero or more unicast (source) address(es) in a source 122 filter. 124 o Determine whether the source filter describes an inclusive or 125 exclusive list of sources. 127 Draft Multicast Source Filter API June 2002 129 The new API design must enable this functionality for both IPv4 130 and IPv6. 132 3.2. Data Types 134 The data types of the structure elements given in this memo are 135 intended to be examples, not absolute requirements. Whenever 136 possible, data types from Draft 6.6 (March 1997) of POSIX 1003.1g 137 are used: uintN_t means an unsigned integer of exactly N bits 138 (e.g., uint32_t). We also assume the argument data types from 139 1003.1g when possible (e.g., the final argument to setsockopt() is 140 a size_t value). 142 3.3. Headers 144 When function prototypes and structures are shown, we show the 145 headers that must be #included to cause that item to be defined. 147 3.4. Structures 149 When structures are described, the members shown are the ones that 150 must appear in an implementation. Additional, nonstandard members 151 may also be defined by an implementation. As an additional 152 precaution, nonstandard members could be verified by Feature Test 153 Macros as described in IEEE Std 1003.1. (Such Feature Test Macros 154 are not defined by this RFC.) The ordering shown for the members 155 of a structure is the recommended ordering, given alignment 156 considerations of multibyte members, but an implementation may 157 order the members differently. 159 4. Overview of APIs 161 There are a number of different APIs described in this document, 162 that are appropriate for a number of different application types 163 and IP versions. Before providing detailed descriptions, this 164 section provides a "taxonomy" with a brief description of each. 166 IPv4 Multicast Source Filter APIs: 168 o Basic (Delta-based): Use setsockopt() and reference a single 169 source and group address pair to make incremental changes 171 Draft Multicast Source Filter API June 2002 173 + Any-Source: Data accepted from any source by default, but 174 source filter control is available 176 + Controlled-Source: A source filter is required 178 o Advanced (Full-state): Use ioctl() and reference the entire set 179 of sources with the group address to affect membership changes 181 Protocol-Independent Multicast Source Filter APIs: 183 o Basic (Delta-based): Use setsockopt() and reference a single 184 source and group address pair to make incremental changes 186 + Any-Source: Data accepted from any source by default, but 187 source filter control is available 189 + Controlled-Source: A source filter is required 191 o Advanced (Full-state): Use ioctl() and reference the entire set 192 of sources 194 One might ask why the protocol-independent APIs cannot accomodate 195 IPv4 applications as well as IPv6. Since any IPv4 application 196 requires modification to use multicast source filters anyway, it 197 might seem like a good opportunity to create IPv6-compatible 198 source code. 200 The primary reasons for extending an IPv4-specific API are: 202 o To minimize changes needed in existing IPv4 multicast 203 application source code to add source filter support 205 o To avoid overloading APIs to accomodate the differences 206 between IPv4 interface addresses (e.g., in the ip_mreq 207 structure), and interface indices. 209 5. IPv4 Multicast Source Filter APIs 211 Version 3 of the Internet Group Management Protocol (IGMPv3) [2] 212 provides the ability to communicate source filter information to 213 the router and hence avoid pulling down data from unwanted sources 214 onto the local link. However, source filters may be implemented 215 by the operating system regardless of whether the routers support 216 IGMPv3, so when the source-filter API is available, applications 217 Draft Multicast Source Filter API June 2002 219 can always benefit from using it. 221 There are two categories of the IPv4 source-filter APIs, both of 222 which are designed to allow multicast receiver applications to 223 designate the unicast address(es) of sender(s) along with the 224 multicast group (destination address) to receive. 226 o The "Basic" (Delta-based) API is the simpler of the two and 227 allows an application to reference a single source address in 228 each operation. 230 o The "Advanced" (Full-state) API allows an application to 231 define a source-filter comprised of zero or more source 232 addresses. 234 5.1. Basic (Delta-based) API for IPv4 236 Some applications desire the simplicity of a delta-based API in 237 which each function call references a single source address along 238 with the multicast group address on which to listen. Such 239 applications typically fall into either of two categories: 241 Any-source: 242 By default, all sources are accepted. Individual sources may 243 be turned off and back on as needed over time. 245 Controlled-source: 246 Only sources in a given list are allowed. The list may 247 change over time. 249 5.1.1. Any-Source IPv4 Applications 251 The following socket options are defined in for 252 applications in the any-source category: 254 Socket option Argument type 255 IP_ADD_MEMBERSHIP struct ip_mreq 256 IP_BLOCK_SOURCE struct ip_mreq_source 257 IP_UNBLOCK_SOURCE struct ip_mreq_source 258 IP_DROP_MEMBERSHIP struct ip_mreq 260 IP_ADD_MEMBERSHIP and IP_DROP_MEMBERSHIP are already implemented 261 Draft Multicast Source Filter API June 2002 263 on most operating systems, and are used to join and leave an any- 264 source group. 266 IP_BLOCK_SOURCE can be used to block data from a given source to a 267 given group (e.g., if the user "mutes" that source), and 268 IP_UNBLOCK_SOURCE can be used to undo this (e.g., if the user then 269 "unmutes" the source). 271 The argument types of these options are defined as a result of 272 including the header. 274 struct ip_mreq { 275 struct in_addr imr_multiaddr; /* IP multicast address of group */ 276 struct in_addr imr_interface; /* local IP address of interface */ 277 }; 279 struct ip_mreq_source { 280 struct in_addr imr_multiaddr; /* IP multicast address of group */ 281 struct in_addr imr_sourceaddr; /* IP address of source */ 282 struct in_addr imr_interface; /* local IP address of interface */ 283 }; 285 5.1.2. Controlled-Source IPv4 Applications 287 The following socket options are available for applications in the 288 Controlled-source category: 290 Socket option Argument type 291 IP_ADD_SOURCE_MEMBERSHIP struct ip_mreq_source 292 IP_DROP_SOURCE_MEMBERSHIP struct ip_mreq_source 293 IP_DROP_MEMBERSHIP struct ip_mreq 295 These options would be used, for example, by "single-source" style 296 applications such as audio/video broadcasting. They can also be 297 used for logical multi-source sessions where each source 298 independently allocates its own source-specific group address. 300 IP_DROP_MEMBERSHIP can be supported, as a convenience, to drop all 301 sources which have been joined. The operations are the same as if 302 the socket had been closed. 304 Draft Multicast Source Filter API June 2002 306 5.1.3. Error Codes 308 When the option would be legal on the group, but an address is 309 invalid (e.g., when trying to block a source that is already 310 blocked by the socket, or when trying to drop an unjoined group) 311 the error generated is EADDRNOTAVAIL. 313 When the option itself is not legal on the group (i.e., when 314 trying a Controlled-Source option on a group after doing 315 IP_ADD_MEMBERSHIP, or when trying an Any-Source option without 316 doing IP_ADD_MEMBERSHIP) the error generated is EINVAL. 318 When any of these options are used with getsockopt(), the error 319 generated is EOPNOTSUPP. 321 Finally, if the implementation imposes a limit on the maximum 322 number of sources in a source filter, ENOBUFS is generated when an 323 operation would exceed the maximum. 325 5.2. Advanced (Full-state) API for IPv4 327 Applications which require the ability to switch between filter 328 modes without leaving a group must use a full-state API (i.e., to 329 change the semantics of the source filter from inclusive to 330 exclusive, or vice versa). Applications which use a large source 331 list for a given group address should also use the full-state API, 332 since filter changes can be done atomically in a single operation. 334 For this purpose the following are defined in : 336 o ioctl() SIOCGIPMSFILTER: to retrieve the list of source 337 addresses that comprise the source filter along with the 338 current filter mode. 340 o ioctl() SIOCSIPMSFILTER: to set or modify the source filter 341 content (e.g. unicast source address list) or mode (exclude 342 or include). 344 SIOCGIPMSFILTER could not be done with getsockopt(), since 345 the group and interface must be passed down in order to 346 retrieve the correct filter. This can, however, be done with 347 an ioctl(), and hence for symmetry, both gets and sets are 348 done with an ioctl. 350 Draft Multicast Source Filter API June 2002 352 5.2.1. Set Source Filter 354 Ioctl option Argument type 355 SIOCSIPMSFILTER struct ip_msfilter 357 The argument type of this option is defined as a result of 358 including the header. 360 struct ip_msfilter { 361 struct in_addr imsf_multiaddr; /* IP multicast address of group */ 362 struct in_addr imsf_interface; /* local IP address of interface */ 363 uint32_t imsf_fmode; /* filter mode */ 364 uint32_t imsf_numsrc; /* number of sources in src_list */ 365 struct in_addr imsf_slist[1]; /* start of source list */ 366 }; 368 #define IP_MSFILTER_SIZE(numsrc) \ 369 (sizeof(struct ip_msfilter) - sizeof(struct in_addr) \ 370 + (numsrc) * sizeof(struct in_addr)) 372 The imsf_fmode mode is a 32-bit integer that identifies the filter 373 mode. The value of this field must be either MCAST_INCLUDE or 374 MCAST_EXCLUDE, which are likewise defined in . 376 If the implementation imposes a limit on the maximum number of 377 sources in a source filter, ENOBUFS is generated when the 378 operation would exceed the maximum. 380 5.2.2. Get Source Filter 382 SIOCGIPMSFILTER cannot be done with getsockopt(), since the group 383 and interface must be passed down in order to retrieve the correct 384 filter. This can, however, be done with an ioctl(): 386 Ioctl option Argument type 387 SIOCGIPMSFILTER struct ip_msfilter 389 The structure length pointed to must be at least 390 IP_MSFILTER_SIZE(0) bytes long, and the imsf_numsrc parameter 391 should be set so that IP_MSFILTER_SIZE(imsf_numsrc) indicates the 392 buffer length. The result of this call will be that the 393 imsf_multiaddr and imsf_interface fields will be unchanged, while 394 imsf_fmode, imsf_numsrc, and as many source addresses as fit will 395 be filled into the application's buffer. 397 Draft Multicast Source Filter API June 2002 399 If the application does not know the size of the source list 400 beforehand, it can make a reasonable guess (e.g., 0), and if upon 401 completion, the imsf_numsrc field holds a larger value, the 402 operation can be repeated with a large enough buffer. 404 6. Protocol-Independent Multicast Source Filter APIs 406 Protocol-independent functions are provided for join and leave 407 operations so that an application may pass a sockaddr_storage 408 structure obtained from calls such as getaddrinfo() [1] as the 409 group to join. For example, an application can resolve a DNS name 410 (e.g., NTP.MCAST.NET) to a multicast address which may be either 411 IPv4 or IPv6, and may easily join and leave the group. 413 While the Multicast Listener Discovery (MLD) protocol [3] for IPv6 414 does not currently support source-filters, the operating system 415 may provide filtering services with this API. A future version of 416 MLD will support source-filters on routers, providing 417 functionality equivalent to IGMPv3 for IPv4. 419 6.1. Basic (Delta-based) API 421 The reception of multicast packets is controlled by the 422 setsockopt() options summarized below. An error of EOPNOTSUPP is 423 returned if these options are used with getsockopt(). 425 Socket option Argument type 426 MCAST_JOIN_GROUP struct group_req 427 MCAST_BLOCK_SOURCE struct group_source_req 428 MCAST_UNBLOCK_SOURCE struct group_source_req 429 MCAST_LEAVE_GROUP struct group_req 430 MCAST_JOIN_SOURCE_GROUP struct group_source_req 431 MCAST_LEAVE_SOURCE_GROUP struct group_source_req 433 The argument types of these options are defined as a result of 434 including the header. 436 struct group_req { 437 uint32_t gr_interface; /* interface index */ 438 struct sockaddr_storage gr_group; /* group address */ 439 }; 441 struct group_source_req { 442 Draft Multicast Source Filter API June 2002 444 uint32_t gsr_interface; /* interface index */ 445 struct sockaddr_storage gsr_group; /* group address */ 446 struct sockaddr_storage gsr_source; /* source address */ 447 }; 449 The sockaddr_storage structure is defined in RFC 2553 [1] to be 450 large enough to hold either IPv4 or IPv6 address information. 452 The rules for generating errors are the same as those given in 453 Section 5.1.3. 455 6.2. Advanced (Full-state) API 457 For the full-state API, the following ioctl() options are defined 458 in . An ioctl() is required for obtaining the 459 filter on a group, since it requires both in and out parameter 460 fields, which cannot be done with getsockopt. For symmetry, we 461 use ioctl() for both get and set operations. 463 Ioctl option Argument type 464 SIOCGMSFILTER struct group_filter 465 SIOCSMSFILTER struct group_filter 467 The argument types of these options are defined as a result of 468 including the header. 470 struct group_filter { 471 uint32_t gf_interface; /* interface index */ 472 struct sockaddr_storage gf_group; /* multicast address */ 473 uint32_t gf_fmode; /* filter mode */ 474 uint32_t gf_numsrc; /* number of sources */ 475 struct sockaddr_storage gf_slist[1]; /* source address */ 476 }; 478 #define GROUP_FILTER_SIZE(numsrc) \ 479 (sizeof(struct group_filter) - sizeof(struct sockaddr_storage) \ 480 + (numsrc) * sizeof(struct sockaddr_storage)) 482 The imf_numsrc field is used in the same way as described for 483 imsf_numsrc in section 5.2.2. 485 Draft Multicast Source Filter API June 2002 487 7. Security Considerations 489 Although source filtering can help to combat denial-of-service 490 attacks, source filtering alone is not a complete solution, since 491 it does not provide protection against spoofing the source address 492 to be an allowed source. Multicast routing protocols which use 493 reverse-path forwarding based on the source address, however, do 494 provide some natural protection against spoofing the source 495 address, since if a router receives a packet on an interface other 496 than the one towards the "real" source, it will drop the packet. 497 However, this still does not provide any guarantee of protection. 499 8. Acknowledgements 501 This draft was updated based on feedback from the IETF's Internet- 502 Draft Multicast Remnants (IDMR) Working Group. Wilbert de Graaf 503 also provided many helpful comments. 505 9. Authors' Addresses 507 Dave Thaler 508 Microsoft Corporation 509 One Microsoft Way 510 Redmond, WA 98052-6399 511 Phone: +1 425 703 8835 512 EMail: dthaler@microsoft.com 514 Bill Fenner 515 75 Willow Road 516 Menlo Park, CA 94025 517 Phone: +1 650 867 6073 518 EMail: fenner@research.att.com 520 Bob Quinn 521 IP Multicast Initiative (IPMI) 522 Stardust.com 523 1901 S. Bascom Ave. #333 524 Campbell, CA 95008 525 Phone: +1 408 879 8080 526 EMail: rcq@ipmulticast.com 528 Draft Multicast Source Filter API June 2002 530 10. Normative References 532 [1] Gilligan, R., Thomson, S., Bound, J., and W. Stevens, "Basic 533 Socket Interface Extensions for IPv6", RFC 2553, March 1999. 535 11. Non-normative References 537 [2] Cain, B., Deering, S., Fenner, B., Kouvelas, I., and A. 538 Thyagarajan, "Internet Group Management Protocol, Version 3", 539 draft-ietf-idmr-igmp-v3-11.txt, Work in progress, May 2002. 541 [3] Deering, S., Fenner, W., and B. Haberman, "Multicast Listener 542 Discovery (MLD) for IPv6", RFC 2710, October 1999. 544 12. Full Copyright Statement 546 Copyright (C) The Internet Society (2002). All Rights Reserved. 548 This document and translations of it may be copied and furnished 549 to others, and derivative works that comment on or otherwise 550 explain it or assist in its implmentation may be prepared, copied, 551 published and distributed, in whole or in part, without 552 restriction of any kind, provided that the above copyright notice 553 and this paragraph are included on all such copies and derivative 554 works. However, this document itself may not be modified in any 555 way, such as by removing the copyright notice or references to the 556 Internet Society or other Internet organizations, except as needed 557 for the purpose of developing Internet standards in which case the 558 procedures for copyrights defined in the Internet Standards 559 process must be followed, or as required to translate it into 560 languages other than English. 562 The limited permissions granted above are perpetual and will not 563 be revoked by the Internet Society or its successors or assigns. 565 This document and the information contained herein is provided on 566 an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET 567 ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR 568 IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 569 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 570 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 572 Draft Multicast Source Filter API June 2002 574 Table of Contents 576 1: Abstract ................................................. 2 577 2: Introduction ............................................. 2 578 3: Design Considerations .................................... 3 579 3.1: What Needs to be Added ................................. 3 580 3.2: Data Types ............................................. 4 581 3.3: Headers ................................................ 4 582 3.4: Structures ............................................. 4 583 4: Overview of APIs ......................................... 4 584 5: IPv4 Multicast Source Filter APIs ........................ 5 585 5.1: Basic (Delta-based) API for IPv4 ....................... 6 586 5.1.1: Any-Source IPv4 Applications ......................... 6 587 5.1.2: Controlled-Source IPv4 Applications .................. 7 588 5.1.3: Error Codes .......................................... 8 589 5.2: Advanced (Full-state) API for IPv4 ..................... 8 590 5.2.1: Set Source Filter .................................... 9 591 5.2.2: Get Source Filter .................................... 9 592 6: Protocol-Independent Multicast Source Filter APIs ........ 10 593 6.1: Basic (Delta-based) API ................................ 10 594 6.2: Advanced (Full-state) API .............................. 11 595 7: Security Considerations .................................. 12 596 8: Acknowledgements ......................................... 12 597 9: Authors' Addresses ....................................... 12 598 10: Normative References .................................... 13 599 11: Non-normative References ................................ 13 600 12: Full Copyright Statement ................................ 13