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.
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.
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.
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>.
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 */
};
#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.
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
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.