draft-ietf-ipngwg-rfc2292bis-05.txt   draft-ietf-ipngwg-rfc2292bis-06.txt 
INTERNET-DRAFT W. Richard Stevens INTERNET-DRAFT W. Richard Stevens
Expires: August 12, 2002 Matt Thomas (Consultant) Expires: August 25, 2002 Matt Thomas (Consultant)
Obsoletes RFC 2292 Erik Nordmark (Sun) Obsoletes RFC 2292 Erik Nordmark (Sun)
Tatuya Jinmei (Toshiba) Tatuya Jinmei (Toshiba)
February 12, 2002 February 25, 2002
Advanced Sockets API for IPv6 Advanced Sockets API for IPv6
<draft-ietf-ipngwg-rfc2292bis-05.txt> <draft-ietf-ipngwg-rfc2292bis-06.txt>
Abstract Abstract
A separate specification [RFC-2553] contain changes to the sockets A separate specification [RFC-2553] contain changes to the sockets
API to support IP version 6. Those changes are for TCP and UDP-based API to support IP version 6. Those changes are for TCP and UDP-based
applications and will support most end-user applications in use applications and will support most end-user applications in use
today: Telnet and FTP clients and servers, HTTP clients and servers, today: Telnet and FTP clients and servers, HTTP clients and servers,
and the like. and the like.
But another class of applications exists that will also be run under But another class of applications exists that will also be run under
skipping to change at page 2, line 14 skipping to change at page 2, line 14
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt http://www.ietf.org/ietf/1id-abstracts.txt
The list of Internet-Draft Shadow Directories can be accessed at The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html. http://www.ietf.org/shadow.html.
This Internet Draft expires August 12, 2002. This Internet Draft expires August 25, 2002.
Table of Contents Table of Contents
1. Introduction .................................................... 6 1. Introduction .................................................... 6
2. Common Structures and Definitions ............................... 7 2. Common Structures and Definitions ............................... 7
2.1. The ip6_hdr Structure ...................................... 8 2.1. The ip6_hdr Structure ...................................... 8
2.1.1. IPv6 Next Header Values ............................. 8 2.1.1. IPv6 Next Header Values ............................. 8
2.1.2. IPv6 Extension Headers .............................. 9 2.1.2. IPv6 Extension Headers .............................. 9
2.1.3. IPv6 Options ........................................ 10 2.1.3. IPv6 Options ........................................ 10
skipping to change at page 3, line 43 skipping to change at page 3, line 43
6. Packet Information .............................................. 28 6. Packet Information .............................................. 28
6.1. Specifying/Receiving the Interface ......................... 29 6.1. Specifying/Receiving the Interface ......................... 29
6.2. Specifying/Receiving Source/Destination Address ............ 29 6.2. Specifying/Receiving Source/Destination Address ............ 29
6.3. Specifying/Receiving the Hop Limit ......................... 30 6.3. Specifying/Receiving the Hop Limit ......................... 30
6.4. Specifying the Next Hop Address ............................ 31 6.4. Specifying the Next Hop Address ............................ 31
6.5. Specifying/Receiving the Traffic Class value ............... 32 6.5. Specifying/Receiving the Traffic Class value ............... 32
6.6. Additional Errors with sendmsg() and setsockopt() .......... 33 6.6. Additional Errors with sendmsg() and setsockopt() .......... 33
6.7. Summary of outgoing interface selection .................... 33 6.7. Summary of outgoing interface selection .................... 33
7. Routing Header Option ........................................... 34 7. Routing Header Option ........................................... 34
7.1. inet6_rth_space ............................................ 35 7.1. inet6_rth_space ............................................ 36
7.2. inet6_rth_init ............................................. 36 7.2. inet6_rth_init ............................................. 36
7.3. inet6_rth_add .............................................. 36 7.3. inet6_rth_add .............................................. 37
7.4. inet6_rth_reverse .......................................... 37 7.4. inet6_rth_reverse .......................................... 37
7.5. inet6_rth_segments ......................................... 37 7.5. inet6_rth_segments ......................................... 37
7.6. inet6_rth_getaddr .......................................... 37 7.6. inet6_rth_getaddr .......................................... 37
8. Hop-By-Hop Options .............................................. 38 8. Hop-By-Hop Options .............................................. 38
8.1. Receiving Hop-by-Hop Options ............................... 39 8.1. Receiving Hop-by-Hop Options ............................... 39
8.2. Sending Hop-by-Hop Options ................................. 39 8.2. Sending Hop-by-Hop Options ................................. 39
9. Destination Options ............................................. 40 9. Destination Options ............................................. 40
9.1. Receiving Destination Options .............................. 40 9.1. Receiving Destination Options .............................. 40
9.2. Sending Destination Options ................................ 40 9.2. Sending Destination Options ................................ 40
10. Hop-by-Hop and Destination Options Processing ................... 41 10. Hop-by-Hop and Destination Options Processing ................... 41
10.1. inet6_opt_init ............................................ 41 10.1. inet6_opt_init ............................................ 42
10.2. inet6_opt_append .......................................... 42 10.2. inet6_opt_append .......................................... 42
10.3. inet6_opt_finish .......................................... 42 10.3. inet6_opt_finish .......................................... 43
10.4. inet6_opt_set_val ......................................... 43 10.4. inet6_opt_set_val ......................................... 43
10.5. inet6_opt_next ............................................ 43 10.5. inet6_opt_next ............................................ 43
10.6. inet6_opt_find ............................................ 44 10.6. inet6_opt_find ............................................ 44
10.7. inet6_opt_get_val ......................................... 44 10.7. inet6_opt_get_val ......................................... 44
11. Additional Advanced API Functions ............................... 45 11. Additional Advanced API Functions ............................... 45
11.1. Sending with the Minimum MTU .............................. 45 11.1. Sending with the Minimum MTU .............................. 45
11.2. Sending without fragmentation ............................. 45 11.2. Sending without fragmentation ............................. 45
11.3. Path MTU Discovery and UDP ................................ 46 11.3. Path MTU Discovery and UDP ................................ 46
11.4. Determining the current path MTU .......................... 47 11.4. Determining the current path MTU .......................... 48
11.5. Neighbor Reachability and UDP ............................. 48
12. Ordering of Ancillary Data and IPv6 Extension Headers ........... 49 12. Ordering of Ancillary Data and IPv6 Extension Headers ........... 48
13. IPv6-Specific Options with IPv4-Mapped IPv6 Addresses ........... 51 13. IPv6-Specific Options with IPv4-Mapped IPv6 Addresses ........... 50
14. Extended interfaces for rresvport, rcmd and rexec ............... 51 14. Extended interfaces for rresvport, rcmd and rexec ............... 51
14.1. rresvport_af .............................................. 51 14.1. rresvport_af .............................................. 51
14.2. rcmd_af ................................................... 52 14.2. rcmd_af ................................................... 52
14.3. rexec_af .................................................. 52 14.3. rexec_af .................................................. 52
15. Summary of New Definitions ...................................... 53 15. Summary of New Definitions ...................................... 53
16. Security Considerations ......................................... 57 16. Security Considerations ......................................... 56
17. Change History .................................................. 57 17. Change History .................................................. 57
18. References ...................................................... 62 18. References ...................................................... 62
19. Acknowledgments ................................................. 62 19. Acknowledgments ................................................. 62
20. Authors' Addresses .............................................. 63 20. Authors' Addresses .............................................. 63
21. Appendix A: Ancillary Data Overview ............................. 63 21. Appendix A: Ancillary Data Overview ............................. 63
skipping to change at page 24, line 29 skipping to change at page 24, line 29
1. The send/receive interface and source/destination address, 1. The send/receive interface and source/destination address,
2. The hop limit, 2. The hop limit,
3. Next hop address, 3. Next hop address,
4. The traffic class, 4. The traffic class,
5. Routing header, 5. Routing header,
6. Hop-by-Hop options header, and 6. Hop-by-Hop options header, and
7. Destination options header. 7. Destination options header.
First, to receive any of this optional information (other than the First, to receive any of this optional information (other than the
next hop address, which can only be set), the application must call next hop address, which can only be set) on a UDP or raw socket, the
setsockopt() to turn on the corresponding flag: application must call setsockopt() to turn on the corresponding flag:
int on = 1; int on = 1;
setsockopt(fd, IPPROTO_IPV6, IPV6_RECVPKTINFO, &on, sizeof(on)); setsockopt(fd, IPPROTO_IPV6, IPV6_RECVPKTINFO, &on, sizeof(on));
setsockopt(fd, IPPROTO_IPV6, IPV6_RECVHOPLIMIT, &on, sizeof(on)); setsockopt(fd, IPPROTO_IPV6, IPV6_RECVHOPLIMIT, &on, sizeof(on));
setsockopt(fd, IPPROTO_IPV6, IPV6_RECVRTHDR, &on, sizeof(on)); setsockopt(fd, IPPROTO_IPV6, IPV6_RECVRTHDR, &on, sizeof(on));
setsockopt(fd, IPPROTO_IPV6, IPV6_RECVHOPOPTS, &on, sizeof(on)); setsockopt(fd, IPPROTO_IPV6, IPV6_RECVHOPOPTS, &on, sizeof(on));
setsockopt(fd, IPPROTO_IPV6, IPV6_RECVDSTOPTS, &on, sizeof(on)); setsockopt(fd, IPPROTO_IPV6, IPV6_RECVDSTOPTS, &on, sizeof(on));
setsockopt(fd, IPPROTO_IPV6, IPV6_RECVTCLASS, &on, sizeof(on)); setsockopt(fd, IPPROTO_IPV6, IPV6_RECVTCLASS, &on, sizeof(on));
When any of these options are enabled, the corresponding data is When any of these options are enabled, the corresponding data is
returned as control information by recvmsg(), as one or more returned as control information by recvmsg(), as one or more
ancillary data objects. ancillary data objects.
This document does not define how to receive the optional information
on a TCP socket. See Section 4.1 for more details.
Two different mechanisms exist for sending this optional information: Two different mechanisms exist for sending this optional information:
1. Using setsockopt to specify the option content for a socket. These 1. Using setsockopt to specify the option content for a socket. These
are known "sticky" options since they affect all transmitted are known "sticky" options since they affect all transmitted
packets on the socket until either a new setsockopt is done or the packets on the socket until either a new setsockopt is done or the
options are overridden using ancillary data. options are overridden using ancillary data.
2. Using ancillary data to specify the option content for a single 2. Using ancillary data to specify the option content for a single
datagram. This only applies to datagram and raw sockets; not to datagram. This only applies to datagram and raw sockets; not to
TCP sockets. TCP sockets.
skipping to change at page 26, line 10 skipping to change at page 26, line 13
with optlen being zero. with optlen being zero.
The application does not explicitly need to access the data The application does not explicitly need to access the data
structures for the Routing header, Hop-by-Hop options header, and structures for the Routing header, Hop-by-Hop options header, and
Destination options header, since the API to these features is Destination options header, since the API to these features is
through a set of inet6_rth_XXX() and inet6_opt_XXX() functions that through a set of inet6_rth_XXX() and inet6_opt_XXX() functions that
we define in Section 7 and Section 10. Those functions simplify the we define in Section 7 and Section 10. Those functions simplify the
interface to these features instead of requiring the application to interface to these features instead of requiring the application to
know the intimate details of the extension header formats. know the intimate details of the extension header formats.
When specifying extension headers, this API assumes the header
ordering and the number of occurrences of each header as described in
[RFC-2460]. More details about the ordering issue will be discussed
in Section 12.
4.1. TCP Implications 4.1. TCP Implications
It is not possible to use ancillary data to transmit the above It is not possible to use ancillary data to transmit the above
options for TCP since there is not a one-to-one mapping between send options for TCP since there is not a one-to-one mapping between send
operations and the TCP segments being transmitted. Instead an operations and the TCP segments being transmitted. Instead an
application can use setsockopt to specify them as sticky options. application can use setsockopt to specify them as sticky options.
When the application uses setsockopt to specify the above options it When the application uses setsockopt to specify the above options it
is expected that TCP will start using the new information when is expected that TCP will start using the new information when
sending segments. However, TCP may or may not use the new sending segments. However, TCP may or may not use the new
information when retransmitting segments that were originally sent information when retransmitting segments that were originally sent
skipping to change at page 27, line 40 skipping to change at page 27, line 47
sticky option and later passes IPV6_HOPOPTS with a zero length as an sticky option and later passes IPV6_HOPOPTS with a zero length as an
ancillary data item, the packet will not have a Hop-by-Hop options ancillary data item, the packet will not have a Hop-by-Hop options
header. header.
5. Extensions to Socket Ancillary Data 5. Extensions to Socket Ancillary Data
This specification uses ancillary data as defined in Posix.1g with This specification uses ancillary data as defined in Posix.1g with
the following compatible extensions: the following compatible extensions:
- CMSG_NXTHDR has been extended to handle a NULL 2nd argument to mean - CMSG_NXTHDR has been extended to handle a NULL 2nd argument to mean
"get the first header". See Section 22.3.2. "get the first header". See Section 21.3.2.
- A new CMSG_SPACE macro is defined. It is used to determine how much - A new CMSG_SPACE macro is defined. It is used to determine how much
space need to be allocated for an ancillary data item. See Section space need to be allocated for an ancillary data item. See Section
22.3.4. 21.3.4.
- A new CMSG_LEN macro is defined. It returns the value to store in - A new CMSG_LEN macro is defined. It returns the value to store in
the cmsg_len member of the cmsghdr structure, taking into account the cmsg_len member of the cmsghdr structure, taking into account
any padding needed to satisfy alignment requirements. See Section any padding needed to satisfy alignment requirements. See Section
22.3.5. 21.3.5.
6. Packet Information 6. Packet Information
There are five pieces of information that an application can specify There are five pieces of information that an application can specify
for an outgoing packet using ancillary data: for an outgoing packet using ancillary data:
1. the source IPv6 address, 1. the source IPv6 address,
2. the outgoing interface index, 2. the outgoing interface index,
3. the outgoing hop limit, 3. the outgoing hop limit,
4. the next hop address, and 4. the next hop address, and
skipping to change at page 29, line 27 skipping to change at page 29, line 32
6.1. Specifying/Receiving the Interface 6.1. Specifying/Receiving the Interface
Interfaces on an IPv6 node are identified by a small positive Interfaces on an IPv6 node are identified by a small positive
integer, as described in Section 4 of [RFC-2553]. That document also integer, as described in Section 4 of [RFC-2553]. That document also
describes a function to map an interface name to its interface index, describes a function to map an interface name to its interface index,
a function to map an interface index to its interface name, and a a function to map an interface index to its interface name, and a
function to return all the interface names and indexes. Notice from function to return all the interface names and indexes. Notice from
this document that no interface is ever assigned an index of 0. this document that no interface is ever assigned an index of 0.
When specifying the outgoing interface, if the ipi6_ifindex value is When specifying the outgoing interface, if the ipi6_ifindex value is
0, the kernel will choose the outgoing interface. If the application 0, the kernel will choose the outgoing interface.
specifies an outgoing interface for a multicast packet, the interface
specified by the ancillary data overrides any interface specified by The ordering among various options that can specify the outgoing
the IPV6_MULTICAST_IF socket option (described in [RFC-2553]), for interface, including IPV6_PKTINFO, is defined in Section 6.7.
that call to sendmsg() only. Also, if the application specifies an
outgoing interface for a multicast packet as well as specifying a
generic outgoing interface by the IPV6_PKTINFO sticky option, the
latter will override the former for every multicast packet on the
corresponding socket. The reason for the ordering comes from
expectation that the source address is specified as well and that the
pair of the address and the outgoing interface should be desired.
When the IPV6_RECVPKTINFO socket option is enabled, the received When the IPV6_RECVPKTINFO socket option is enabled, the received
interface index is always returned as the ipi6_ifindex member of the interface index is always returned as the ipi6_ifindex member of the
in6_pktinfo structure. in6_pktinfo structure.
6.2. Specifying/Receiving Source/Destination Address 6.2. Specifying/Receiving Source/Destination Address
The source IPv6 address can be specified by calling bind() before The source IPv6 address can be specified by calling bind() before
each output operation, but supplying the source address together with each output operation, but supplying the source address together with
the data requires less overhead (i.e., fewer system calls) and the data requires less overhead (i.e., fewer system calls) and
skipping to change at page 30, line 28 skipping to change at page 30, line 26
particularly the case for link-local addresses. In such a case, the particularly the case for link-local addresses. In such a case, the
kernel must first determine the appropriate scope zone based on the kernel must first determine the appropriate scope zone based on the
zone of the destination address or the outgoing interface (if known), zone of the destination address or the outgoing interface (if known),
then qualify the address. This also means that it is not feasible to then qualify the address. This also means that it is not feasible to
specify the source address for a non-binding socket by the specify the source address for a non-binding socket by the
IPV6_PKTINFO sticky option, unless the outgoing interface is also IPV6_PKTINFO sticky option, unless the outgoing interface is also
specified. The application should simply use bind() for such specified. The application should simply use bind() for such
purposes. purposes.
IPV6_PKTINFO can also be used as a sticky option for specifying the IPV6_PKTINFO can also be used as a sticky option for specifying the
socket's default source address. However, the ipi6_addr member socket's default source address. However, the ipi6_addr member must
should be ignored when the option is specified for a TCP socket, be the unspecified address for TCP sockets, because it is not
because it is not possible to dynamically change the source address possible to dynamically change the source address of a TCP
of a TCP connection. This restriction should be applied even before connection. When the IPV6_PKTINFO option is specified for a TCP
the socket binds a specific address. socket with a non-unspecified address, the call will fail. This
restriction should be applied even before the socket binds a specific
address.
When the in6_pktinfo structure is returned as ancillary data by When the in6_pktinfo structure is returned as ancillary data by
recvmsg(), the ipi6_addr member contains the destination IPv6 address recvmsg(), the ipi6_addr member contains the destination IPv6 address
from the received packet. from the received packet.
6.3. Specifying/Receiving the Hop Limit 6.3. Specifying/Receiving the Hop Limit
The outgoing hop limit is normally specified with either the The outgoing hop limit is normally specified with either the
IPV6_UNICAST_HOPS socket option or the IPV6_MULTICAST_HOPS socket IPV6_UNICAST_HOPS socket option or the IPV6_MULTICAST_HOPS socket
option, both of which are described in [RFC-2553]. Specifying the option, both of which are described in [RFC-2553]. Specifying the
skipping to change at page 34, line 19 skipping to change at page 34, line 19
3. otherwise, if the destination address is a multicast address and 3. otherwise, if the destination address is a multicast address and
the IPV6_MULTICAST_IF socket option is specified for the socket, the IPV6_MULTICAST_IF socket option is specified for the socket,
the interface is used. the interface is used.
4. otherwise, if an IPV6_NEXTHOP ancillary data item is specified, 4. otherwise, if an IPV6_NEXTHOP ancillary data item is specified,
the interface to the next hop is used. the interface to the next hop is used.
5. otherwise, if an IPV6_NEXTHOP sticky option is specified, 5. otherwise, if an IPV6_NEXTHOP sticky option is specified,
the interface to the next hop is used. the interface to the next hop is used.
6. otherwise, the outgoing interface should be determined in an 6. otherwise, the outgoing interface should be determined in an
implementation dependent manner. implementation dependent manner.
The ordering above particularly means if the application specifies an
interface by the IPV6_MULTICAST_IF socket option (described in
[RFC-2553]) as well as specifying a different interface by the
IPV6_PKTINFO sticky option, the latter will override the former for
every multicast packet on the corresponding socket. The reason for
the ordering comes from expectation that the source address is
specified as well and that the pair of the address and the outgoing
interface should be desired.
In any case, the kernel must also verify that the source and In any case, the kernel must also verify that the source and
destination addresses do not break their scope zones with regard to destination addresses do not break their scope zones with regard to
the outgoing interface. the outgoing interface.
7. Routing Header Option 7. Routing Header Option
Source routing in IPv6 is accomplished by specifying a Routing header Source routing in IPv6 is accomplished by specifying a Routing header
as an extension header. There can be different types of Routing as an extension header. There can be different types of Routing
headers, but IPv6 currently defines only the Type 0 Routing header headers, but IPv6 currently defines only the Type 0 Routing header
[RFC-2460]. This type supports up to 127 intermediate nodes (limited [RFC-2460]. This type supports up to 127 intermediate nodes (limited
skipping to change at page 35, line 26 skipping to change at page 35, line 32
setsockopt(fd, IPPROTO_IPV6, IPV6_RECVRTHDR, &on, sizeof(on)); setsockopt(fd, IPPROTO_IPV6, IPV6_RECVRTHDR, &on, sizeof(on));
Each received Routing header is returned as one ancillary data object Each received Routing header is returned as one ancillary data object
described by a cmsghdr structure with cmsg_type set to IPV6_RTHDR. described by a cmsghdr structure with cmsg_type set to IPV6_RTHDR.
When multiple Routing headers are received, multiple ancillary data When multiple Routing headers are received, multiple ancillary data
objects (with cmsg_type set to IPV6_RTHDR) will be returned to the objects (with cmsg_type set to IPV6_RTHDR) will be returned to the
application. application.
To send a Routing header the application specifies it either as To send a Routing header the application specifies it either as
ancillary data in a call to sendmsg() or using setsockopt(). For the ancillary data in a call to sendmsg() or using setsockopt(). For the
sending side, this API assumes the recommended order about extension sending side, this API assumes the number of occurrences of the
headers described in [RFC-2460]. Thus, applications can only specify Routing header as described in [RFC-2460]. That is, applications can
at most one outgoing Routing header. only specify at most one outgoing Routing header.
The application can remove any sticky Routing header by calling The application can remove any sticky Routing header by calling
setsockopt() for IPV6_RTHDR with a zero option length. setsockopt() for IPV6_RTHDR with a zero option length.
When using ancillary data a Routing header is passed between the When using ancillary data a Routing header is passed between the
application and the kernel as follows: The cmsg_level member has a application and the kernel as follows: The cmsg_level member has a
value of IPPROTO_IPV6 and the cmsg_type member has a value of value of IPPROTO_IPV6 and the cmsg_type member has a value of
IPV6_RTHDR. The contents of the cmsg_data[] member is implementation IPV6_RTHDR. The contents of the cmsg_data[] member is implementation
dependent and should not be accessed directly by the application, but dependent and should not be accessed directly by the application, but
should be accessed using the six functions that we are about to should be accessed using the six functions that we are about to
skipping to change at page 40, line 43 skipping to change at page 41, line 5
9.2. Sending Destination Options 9.2. Sending Destination Options
To send a Destination options header, the application specifies it To send a Destination options header, the application specifies it
either as ancillary data in a call to sendmsg() or using either as ancillary data in a call to sendmsg() or using
setsockopt(). setsockopt().
The application can remove any sticky Destination options header by The application can remove any sticky Destination options header by
calling setsockopt() for IPV6_RTHDRDSTOPTS/IPV6_DSTOPTS with a zero calling setsockopt() for IPV6_RTHDRDSTOPTS/IPV6_DSTOPTS with a zero
option length. option length.
This API assumes the recommended ordering about extension headers This API assumes the ordering about extension headers as described in
described in [RFC-2460]. Thus, one set of Destination options can [RFC-2460]. Thus, one set of Destination options can only appear
only appear before a Routing header, and one set can only appear before a Routing header, and one set can only appear after a Routing
after a Routing header (or in a packet with no Routing header). Each header (or in a packet with no Routing header). Each set can consist
set can consist of one or more options but each set is a single of one or more options but each set is a single extension header.
extension header.
Today all destination options that an application may want to specify
can be put after (or without) a Routing header. Thus, applications
should usually need IPV6_DSTOPTS only and should avoid using
IPV6_RTHDRDSTOPTS whenever possible.
When using ancillary data a Destination options header is passed When using ancillary data a Destination options header is passed
between the application and the kernel as follows: The set preceding between the application and the kernel as follows: The set preceding
a Routing header are specified with the cmsg_level member set to a Routing header are specified with the cmsg_level member set to
IPPROTO_IPV6 and the cmsg_type member set to IPV6_RTHDRDSTOPTS. Any IPPROTO_IPV6 and the cmsg_type member set to IPV6_RTHDRDSTOPTS. Any
setsockopt or ancillary data for IPV6_RTHDRDSTOPTS is silently setsockopt or ancillary data for IPV6_RTHDRDSTOPTS is silently
ignored when sending packets unless a Routing header is also ignored when sending packets unless a Routing header is also
specified. Note that the "Routing header" here means the one specified. Note that the "Routing header" here means the one
specified by this API. Even when the kernel inserts a routing header specified by this API. Even when the kernel inserts a routing header
in its internal routine (e.g. in a mobile IPv6 stack), the in its internal routine (e.g. in a mobile IPv6 stack), the
skipping to change at page 46, line 22 skipping to change at page 46, line 32
In the cmsghdr structure containing this ancillary data, the In the cmsghdr structure containing this ancillary data, the
cmsg_level member will be IPPROTO_IPV6, the cmsg_type member will be cmsg_level member will be IPPROTO_IPV6, the cmsg_type member will be
IPV6_DONTFRAG, and the first byte of cmsg_data[] will be the first IPV6_DONTFRAG, and the first byte of cmsg_data[] will be the first
byte of the integer. This API only specifies the use of this option byte of the integer. This API only specifies the use of this option
for UDP and raw sockets, and does not define the usage for TCP for UDP and raw sockets, and does not define the usage for TCP
sockets. sockets.
When the data size is larger than the MTU of the outgoing interface, When the data size is larger than the MTU of the outgoing interface,
the packet will be discarded. Applications can know the result by the packet will be discarded. Applications can know the result by
enabling the IPV6_RECVPATHMTU option described below and receiving enabling the IPV6_RECVPATHMTU option described below and receiving
the corresponding ancillary data items. (Note: since the socket API the corresponding ancillary data items. An additional error EMSGSIZE
allows an implementation to not return a certain error, such as may also be returned in some implementations. Note, however, that
EHOSTUNREACH, for the send variant system calls, this API some other implementations might not be able to return this
specification does not define an error code in this case.) additional error when sending a message.
11.3. Path MTU Discovery and UDP 11.3. Path MTU Discovery and UDP
UDP and raw socket applications need to be able to determine the UDP and raw socket applications need to be able to determine the
"maximum send transport-message size" (Section 5.1 of [RFC-1981]) to "maximum send transport-message size" (Section 5.1 of [RFC-1981]) to
a given destination so that those applications can participate in a given destination so that those applications can participate in
path MTU discovery. This lets those applications send smaller path MTU discovery. This lets those applications send smaller
datagrams to the destination, avoiding fragmentation. datagrams to the destination, avoiding fragmentation.
This is accomplished using a new ancillary data item (IPV6_PATHMTU) This is accomplished using a new ancillary data item (IPV6_PATHMTU)
skipping to change at page 48, line 32 skipping to change at page 48, line 45
there is no way to pass the destination via getsockopt(). When there is no way to pass the destination via getsockopt(). When
getsockopt() for this option is issued on a non-connected socket, the getsockopt() for this option is issued on a non-connected socket, the
call will fail. Despite this limitation, this option is still useful call will fail. Despite this limitation, this option is still useful
from a practical point of view, because applications that care about from a practical point of view, because applications that care about
the path MTU tend to send a lot of packets to a single destination the path MTU tend to send a lot of packets to a single destination
and to connect the socket to the destination for performance reasons. and to connect the socket to the destination for performance reasons.
If the application needs to get the MTU value in a more generic way, If the application needs to get the MTU value in a more generic way,
it should use a more generic interface, such as routing sockets it should use a more generic interface, such as routing sockets
[TCPIPILLUST]. [TCPIPILLUST].
11.5. Neighbor Reachability and UDP
UDP and raw socket applications might know that communication is
making forward progress i.e. that the path from the node to the next
hop is working. In such a case the applications, similarly to TCP as
specified in [RFC-2461], has the option indicate to the internet
layer that the neighbor is reachable. See section 7.3.1 of
[RFC-2461]. This could save unneeded neighbor solicitation and
neighbor advertisement messages.
This is done by including an ancillary data item with cmsg_type being
IPV6_REACHCONF and with no attached CMSG_DATA. IPV6_REACHCONF can
only be used as an ancillary data item. This also means that this
cannot be used for TCP sockets.
If implementations honor the IPV6_REACHCONF from any application
there is a possibility that, when there is an unreachability
situation, one application can cause a denial of service attack on
another application running on the same node by periodically issuing
sendmsg() with an IPV6_REACHCONF ancillary data item to prevent the
Neighbor Unreachability Detection algorithm to send probe messages
and declare the neighbor unreachable. It is unclear whether
implementations need to mitigate this very minor threat by e.g.
restricting IPV6_REACHCONF to privileged applications.
12. Ordering of Ancillary Data and IPv6 Extension Headers 12. Ordering of Ancillary Data and IPv6 Extension Headers
Three IPv6 extension headers can be specified by the application and Three IPv6 extension headers can be specified by the application and
returned to the application using ancillary data with sendmsg() and returned to the application using ancillary data with sendmsg() and
recvmsg(): the Routing header, Hop-by-Hop options header, and recvmsg(): the Routing header, Hop-by-Hop options header, and
Destination options header. When multiple ancillary data objects are Destination options header. When multiple ancillary data objects are
transferred via recvmsg() and these objects represent any of these transferred via recvmsg() and these objects represent any of these
three extension headers, their placement in the control buffer is three extension headers, their placement in the control buffer is
directly tied to their location in the corresponding IPv6 datagram. directly tied to their location in the corresponding IPv6 datagram.
For example, when the application has enabled the IPV6_RECVRTHDR and For example, when the application has enabled the IPV6_RECVRTHDR and
skipping to change at page 49, line 40 skipping to change at page 49, line 30
then the application will receive three ancillary data objects in the then the application will receive three ancillary data objects in the
following order: following order:
an object with cmsg_type set to IPV6_DSTOPTS, which represents an object with cmsg_type set to IPV6_DSTOPTS, which represents
the destination options header (1) the destination options header (1)
an object with cmsg_type set to IPV6_RTHDR, which represents the an object with cmsg_type set to IPV6_RTHDR, which represents the
Routing header Routing header
an object with cmsg_type set to IPV6_DSTOPTS, which represents the an object with cmsg_type set to IPV6_DSTOPTS, which represents the
destination options header (2) destination options header (2)
This example follows the recommended order described in [RFC-2460], This example follows the header ordering described in [RFC-2460], but
but the receiving side of this specification does not assume the the receiving side of this specification does not assume the
recommended order. Applications may receive any numbers of objects ordering. Applications may receive any numbers of objects in any
in any order according to the ordering of the received IPv6 datagram. order according to the ordering of the received IPv6 datagram.
For the sending side, however, this API imposes some ordering For the sending side, however, this API imposes some ordering
constraints according to the recommendation. Applications using this constraints according to [RFC-2460]. Applications using this API
API cannot make a packet with extension headers that do not follow cannot make a packet with extension headers that do not follow the
the recommended ordering. Should an application need to make an ordering. Note, however, that this does not mean applications must
always follow the restriction. This is just a limitation in this API
in order to give application programmers a guideline to construct
headers in a practical manner. Should an application need to make an
outgoing packet in an arbitrary order about the extension headers, outgoing packet in an arbitrary order about the extension headers,
some other technique, such as the datalink interfaces BPF or DLPI, some other technique, such as the datalink interfaces BPF or DLPI,
must be used. must be used.
The followings are more details about the constraints: The followings are more details about the constraints:
- Each IPV6_xxx ancillary data object for a particular type of - Each IPV6_xxx ancillary data object for a particular type of
extension header can be specified at most once in a single control extension header can be specified at most once in a single control
buffer. buffer.
- IPV6_xxx ancillary data objects can appear in any order in a control - IPV6_xxx ancillary data objects can appear in any order in a control
buffer, because there is no ambiguity of the ordering. buffer, because there is no ambiguity of the ordering.
- Each set of IPV6_xxx ancillary data objects and sticky options will - Each set of IPV6_xxx ancillary data objects and sticky options will
be put in the outgoing packet along with the recommended header be put in the outgoing packet along with the header ordering
ordering described in [RFC-2460]. described in [RFC-2460].
- An ancillary data object or a sticky option of IPV6_RTHDRDSTOPTS - An ancillary data object or a sticky option of IPV6_RTHDRDSTOPTS
will affect the outgoing packet only when a Routing header is will affect the outgoing packet only when a Routing header is
specified as an ancillary data object or a sticky option. specified as an ancillary data object or a sticky option.
Otherwise, the specified value for IPV6_RTHDRDSTOPTS will be Otherwise, the specified value for IPV6_RTHDRDSTOPTS will be
ignored. ignored.
For example, when an application sends a UDP datagram with a control For example, when an application sends a UDP datagram with a control
data buffer containing ancillary data objects in the following order: data buffer containing ancillary data objects in the following order:
skipping to change at page 50, line 44 skipping to change at page 50, line 37
The IPv6 header The IPv6 header
A Hop-by-Hop options header A Hop-by-Hop options header
A Destination options header A Destination options header
A UDP header and UDP data A UDP header and UDP data
where the destination options header corresponds to the ancillary where the destination options header corresponds to the ancillary
data object with the type IPV6_DSTOPTS. data object with the type IPV6_DSTOPTS.
Note that the constraints above do not necessarily mean that the Note that the constraints above do not necessarily mean that the
outgoing packet sent on the wire always follows the recommended outgoing packet sent on the wire always follows the header ordering
header ordering. The kernel may insert additional headers that break specified in this API document. The kernel may insert additional
the recommended order as a result. For example, if the kernel headers that break the ordering as a result. For example, if the
supports Mobile IPv6, an additional destination options header may be kernel supports Mobile IPv6, an additional destination options header
inserted before an authentication header, even without a routing may be inserted before an authentication header, even without a
header. routing header.
This API does not provide access to any other extension headers than This API does not provide access to any other extension headers than
the supported three types of headers. In particular, no information the supported three types of headers. In particular, no information
is provided about the IP security headers on an incoming packet, nor is provided about the IP security headers on an incoming packet, nor
can be specified for an outgoing packet. This API is for can be specified for an outgoing packet. This API is for
applications that do not care about the existence of IP security applications that do not care about the existence of IP security
headers. headers.
13. IPv6-Specific Options with IPv4-Mapped IPv6 Addresses 13. IPv6-Specific Options with IPv4-Mapped IPv6 Addresses
The various socket options and ancillary data specifications defined The various socket options and ancillary data specifications defined
in this document apply only to true IPv6 sockets. It is possible to in this document apply only to true IPv6 sockets. It is possible to
create an IPv6 socket that actually sends and receives IPv4 packets, create an IPv6 socket that actually sends and receives IPv4 packets,
using IPv4-mapped IPv6 addresses, but the mapping of the options using IPv4-mapped IPv6 addresses, but the mapping of the options
defined in this document to an IPv4 datagram is beyond the scope of defined in this document to an IPv4 datagram is beyond the scope of
this document. this document.
In general, attempting to specify an IPv6-only option, such as the In general, attempting to specify an IPv6-only option, such as the
Hop-by-Hop options, Destination options, or Routing header on an IPv6 Hop-by-Hop options, Destination options, or Routing header on an IPv6
socket that is using IPv4-mapped IPv6 addresses, will probably result socket that is using IPv4-mapped IPv6 addresses, will probably result
skipping to change at page 55, line 18 skipping to change at page 55, line 11
<netinet/in.h> IPV6_RECVDSTOPTS <netinet/in.h> IPV6_RECVDSTOPTS
<netinet/in.h> IPV6_RECVHOPLIMIT <netinet/in.h> IPV6_RECVHOPLIMIT
<netinet/in.h> IPV6_RECVHOPOPTS <netinet/in.h> IPV6_RECVHOPOPTS
<netinet/in.h> IPV6_RECVPKTINFO <netinet/in.h> IPV6_RECVPKTINFO
<netinet/in.h> IPV6_RECVRTHDR <netinet/in.h> IPV6_RECVRTHDR
<netinet/in.h> IPV6_RECVTCLASS <netinet/in.h> IPV6_RECVTCLASS
<netinet/in.h> IPV6_RTHDR <netinet/in.h> IPV6_RTHDR
<netinet/in.h> IPV6_RTHDRDSTOPTS <netinet/in.h> IPV6_RTHDRDSTOPTS
<netinet/in.h> IPV6_RTHDR_TYPE_0 <netinet/in.h> IPV6_RTHDR_TYPE_0
<netinet/in.h> IPV6_RECVPATHMTU <netinet/in.h> IPV6_RECVPATHMTU
<netinet/in.h> IPV6_REACHCONF
<netinet/in.h> IPV6_TCLASS <netinet/in.h> IPV6_TCLASS
<netinet/in.h> IPV6_USE_MIN_MTU <netinet/in.h> IPV6_USE_MIN_MTU
<netinet/in.h> struct in6_pktinfo{}; <netinet/in.h> struct in6_pktinfo{};
<netinet/in.h> struct ip6_mtuinfo{}; <netinet/in.h> struct ip6_mtuinfo{};
<netinet/ip6.h> IP6F_MORE_FRAG <netinet/ip6.h> IP6F_MORE_FRAG
<netinet/ip6.h> IP6F_OFF_MASK <netinet/ip6.h> IP6F_OFF_MASK
<netinet/ip6.h> IP6F_RESERVED_MASK <netinet/ip6.h> IP6F_RESERVED_MASK
<netinet/ip6.h> IP6OPT_JUMBO <netinet/ip6.h> IP6OPT_JUMBO
<netinet/ip6.h> IP6OPT_JUMBO_LEN <netinet/ip6.h> IP6OPT_JUMBO_LEN
skipping to change at page 57, line 16 skipping to change at page 57, line 10
16. Security Considerations 16. Security Considerations
The setting of certain Hop-by-Hop options and Destination options may The setting of certain Hop-by-Hop options and Destination options may
be restricted to privileged processes. Similarly some Hop-by-Hop be restricted to privileged processes. Similarly some Hop-by-Hop
options and Destination options may not be returned to non-privileged options and Destination options may not be returned to non-privileged
applications. applications.
The ability to specify an arbitrary source address using IPV6_PKTINFO The ability to specify an arbitrary source address using IPV6_PKTINFO
must be prevented; at least for non-privileged processes. must be prevented; at least for non-privileged processes.
The use of IPV6_REACHCONF ancillary data item may cause a denial of
service attack from a local application.
17. Change History 17. Change History
Changes from RFC 2292: Changes from RFC 2292:
- Removed the IPV6_PKTOPTIONS socket option by allowing sticky options - Removed the IPV6_PKTOPTIONS socket option by allowing sticky options
to be set with individual setsockopt calls. This simplifies the to be set with individual setsockopt calls. This simplifies the
protocol stack implementation by not having to handle options within protocol stack implementation by not having to handle options within
options and also clarifies the failure semantics when some option is options and also clarifies the failure semantics when some option is
incorrectly formatted. incorrectly formatted.
skipping to change at page 62, line 12 skipping to change at page 61, line 50
- Described why an error code was not defined when the application - Described why an error code was not defined when the application
sets IPV6_DONTFRAG and data size is larger than the MTU of the sets IPV6_DONTFRAG and data size is larger than the MTU of the
outgoing interface. outgoing interface.
- Added a note that an application that wants to perform the path MTU - Added a note that an application that wants to perform the path MTU
discovery by itself needs to keep history of destinations. discovery by itself needs to keep history of destinations.
- Mentioned the routing socket, with a reference, as a generic - Mentioned the routing socket, with a reference, as a generic
interface to get the path MTU for arbitrary destinations. interface to get the path MTU for arbitrary destinations.
Changes since -05:
- Disallowed to specify a non-unspecified address by the IPV6_PKTINFO
option for a TCP socket.
- Added EMSGSIZE as an additional error when the outgoing packet is
larger than the MTU of the outgoing interface with IPV6_DONTFRAG
being enabled.
- Moved description about the ordering between IPV6_PKTINFO and
IPV6_MULTICAST_IF to Section 6.7, which summarized the ordering
among various options.
- Removed the section for IPV6_REACHCONF and all references to this
option, based on a discussion after 04.
- Clarified the header ordering issue much more, to make it clear that
the ordering is just for this particular API.
18. References 18. References
[RFC-2460] Deering, S., Hinden, R., "Internet Protocol, Version 6 [RFC-2460] Deering, S., Hinden, R., "Internet Protocol, Version 6
(IPv6), Specification", RFC 2460, Dec. 1998. (IPv6), Specification", RFC 2460, Dec. 1998.
[RFC-2553] Gilligan, R. E., Thomson, S., Bound, J., Stevens, W., [RFC-2553] Gilligan, R. E., Thomson, S., Bound, J., Stevens, W.,
"Basic Socket Interface Extensions for IPv6", RFC 2553, "Basic Socket Interface Extensions for IPv6", RFC 2553,
March 1999. March 1999.
[RFC-1981] McCann, J., Deering, S., Mogul, J, "Path MTU Discovery for [RFC-1981] McCann, J., Deering, S., Mogul, J, "Path MTU Discovery for
skipping to change at page 65, line 26 skipping to change at page 65, line 32
}; };
This structure is declared as a result of including <sys/socket.h>. This structure is declared as a result of including <sys/socket.h>.
(Note: Before Posix.1g the cmsg_len member was an integer, and not a (Note: Before Posix.1g the cmsg_len member was an integer, and not a
socklen_t. See the Note in the previous section for why socklen_t is socklen_t. See the Note in the previous section for why socklen_t is
used here.) used here.)
As shown in this definition, normally there is no member with the As shown in this definition, normally there is no member with the
name cmsg_data[]. Instead, the data portion is accessed using the name cmsg_data[]. Instead, the data portion is accessed using the
CMSG_xxx() macros, as described in Section 22.3. Nevertheless, it is CMSG_xxx() macros, as described in Section 21.3. Nevertheless, it is
common to refer to the cmsg_data[] member. common to refer to the cmsg_data[] member.
When ancillary data is sent or received, any number of ancillary data When ancillary data is sent or received, any number of ancillary data
objects can be specified by the msg_control and msg_controllen objects can be specified by the msg_control and msg_controllen
members of the msghdr structure, because each object is preceded by a members of the msghdr structure, because each object is preceded by a
cmsghdr structure defining the object's length (the cmsg_len member). cmsghdr structure defining the object's length (the cmsg_len member).
Historically Berkeley-derived implementations have passed only one Historically Berkeley-derived implementations have passed only one
object at a time, but this API allows multiple objects to be passed object at a time, but this API allows multiple objects to be passed
in a single call to sendmsg() or recvmsg(). The following example in a single call to sendmsg() or recvmsg(). The following example
shows two ancillary data objects in a control buffer. shows two ancillary data objects in a control buffer.
 End of changes. 34 change blocks. 
93 lines changed or deleted 100 lines changed or added

This html diff was produced by rfcdiff 1.33. The latest version is available from http://tools.ietf.org/tools/rfcdiff/