draft-ietf-ipngwg-rfc2292bis-04.txt   draft-ietf-ipngwg-rfc2292bis-05.txt 
INTERNET-DRAFT W. Richard Stevens INTERNET-DRAFT W. Richard Stevens
Expires: July 14, 2002 Matt Thomas (Consultant) Expires: August 12, 2002 Matt Thomas (Consultant)
Obsoletes RFC 2292 Erik Nordmark (Sun) Obsoletes RFC 2292 Erik Nordmark (Sun)
Tatuya Jinmei (Toshiba) Tatuya Jinmei (Toshiba)
January 14, 2002 February 12, 2002
Advanced Sockets API for IPv6 Advanced Sockets API for IPv6
<draft-ietf-ipngwg-rfc2292bis-04.txt> <draft-ietf-ipngwg-rfc2292bis-05.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 July 14, 2002. This Internet Draft expires August 12, 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 4, line 24 skipping to change at page 4, line 24
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 .......................... 47
11.5. Neighbor Reachability and UDP ............................. 48 11.5. Neighbor Reachability and UDP ............................. 48
12. Ordering of Ancillary Data and IPv6 Extension Headers ........... 48 12. Ordering of Ancillary Data and IPv6 Extension Headers ........... 49
13. IPv6-Specific Options with IPv4-Mapped IPv6 Addresses ........... 50 13. IPv6-Specific Options with IPv4-Mapped IPv6 Addresses ........... 51
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 ................................................... 51 14.2. rcmd_af ................................................... 52
14.3. rexec_af .................................................. 52 14.3. rexec_af .................................................. 52
15. Summary of New Definitions ...................................... 52 15. Summary of New Definitions ...................................... 53
16. Security Considerations ......................................... 56 16. Security Considerations ......................................... 57
17. Change History .................................................. 56 17. Change History .................................................. 57
18. References ...................................................... 61 18. References ...................................................... 62
19. Acknowledgments ................................................. 61 19. Acknowledgments ................................................. 62
20. Authors' Addresses .............................................. 62 20. Authors' Addresses .............................................. 63
21. Appendix A: Ancillary Data Overview ............................. 62 21. Appendix A: Ancillary Data Overview ............................. 63
21.1. The msghdr Structure ...................................... 63 21.1. The msghdr Structure ...................................... 64
21.2. The cmsghdr Structure ..................................... 63 21.2. The cmsghdr Structure ..................................... 65
21.3. Ancillary Data Object Macros .............................. 65 21.3. Ancillary Data Object Macros .............................. 66
21.3.1. CMSG_FIRSTHDR ...................................... 65 21.3.1. CMSG_FIRSTHDR ...................................... 67
21.3.2. CMSG_NXTHDR ........................................ 66 21.3.2. CMSG_NXTHDR ........................................ 68
21.3.3. CMSG_DATA .......................................... 67 21.3.3. CMSG_DATA .......................................... 69
21.3.4. CMSG_SPACE ......................................... 68 21.3.4. CMSG_SPACE ......................................... 69
21.3.5. CMSG_LEN ........................................... 68 21.3.5. CMSG_LEN ........................................... 70
22. Appendix B: Examples using the inet6_rth_XXX() functions ........ 69 22. Appendix B: Examples using the inet6_rth_XXX() functions ........ 70
22.1. Sending a Routing Header .................................. 69 22.1. Sending a Routing Header .................................. 70
22.2. Receiving Routing Headers ................................. 74 22.2. Receiving Routing Headers ................................. 75
23. Appendix C: Examples using the inet6_opt_XXX() functions ........ 76 23. Appendix C: Examples using the inet6_opt_XXX() functions ........ 77
23.1. Building options .......................................... 76 23.1. Building options .......................................... 77
23.2. Parsing received options .................................. 78 23.2. Parsing received options .................................. 79
1. Introduction 1. Introduction
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. This document defines some of the "advanced" features applications. This document defines some of the "advanced" features
of the sockets API that are required for applications to take of the sockets API that are required for applications to take
advantage of additional features of IPv6. advantage of additional features of IPv6.
Today, the portability of applications using IPv4 raw sockets is Today, the portability of applications using IPv4 raw sockets is
skipping to change at page 46, line 22 skipping to change at page 46, line 22
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. the corresponding ancillary data items. (Note: since the socket API
allows an implementation to not return a certain error, such as
EHOSTUNREACH, for the send variant system calls, this API
specification does not define an error code in this case.)
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 47, line 5 skipping to change at page 47, line 8
option for UDP and raw sockets, and does not define the usage for TCP option for UDP and raw sockets, and does not define the usage for TCP
sockets. sockets.
When the application is sending packets too big for the path MTU When the application is sending packets too big for the path MTU
recvmsg() will return zero (indicating no data) but there will be a recvmsg() will return zero (indicating no data) but there will be a
cmsghdr with cmsg_type set to IPV6_PATHMTU, and cmsg_len will cmsghdr with cmsg_type set to IPV6_PATHMTU, and cmsg_len will
indicate that cmsg_data is sizeof(struct ip6_mtuinfo) bytes long. indicate that cmsg_data is sizeof(struct ip6_mtuinfo) bytes long.
This can happen when the sending node receives a corresponding ICMPv6 This can happen when the sending node receives a corresponding ICMPv6
packet too big error, or when the packet is sent from a socket with packet too big error, or when the packet is sent from a socket with
the IPV6_DONTFRAG option being on and the packet size is larger than the IPV6_DONTFRAG option being on and the packet size is larger than
the MTU of the outgoing interface. The first byte of cmsg_data[] the MTU of the outgoing interface. This indication is considered as
will point to a struct ip6_mtuinfo carrying the path MTU to use an ancillary data item for a separate (empty) message. Thus, when
together with the IPv6 destination address. there are buffered messages (i.e., messages that the application has
not received yet) on the socket the application will first receive
the buffered messages and then receive the indication.
The first byte of cmsg_data[] will point to a struct ip6_mtuinfo
carrying the path MTU to use together with the IPv6 destination
address.
struct ip6_mtuinfo { struct ip6_mtuinfo {
struct sockaddr_in6 ip6m_addr; /* dst address including zone ID */ struct sockaddr_in6 ip6m_addr; /* dst address including zone ID */
uint32_t ip6m_mtu; /* path MTU in host byte order */ uint32_t ip6m_mtu; /* path MTU in host byte order */
}; };
This cmsghdr will be passed to every socket that sets the This cmsghdr will be passed to every socket that sets the
IPV6_RECVPATHMTU socket option, even if the socket is non-connected. IPV6_RECVPATHMTU socket option, even if the socket is non-connected.
Note that this also means an application that sets the option may get Note that this also means an application that sets the option may
the ancillary data upon a too big message sent from other receive an IPv6_MTU ancillary data item for each ICMP too big error
applications to the same destination. An implementation may choose the node receives, including such ICMP errors caused by other
not to delivery data to a connected socket that has a foreign address applications on the node. Thus, an application that wants to perform
that is different than the address specified in the ip6m_addr the path MTU discovery by itself needs to keep history of
structure. destinations that it has actually sent to and to compare the address
returned in the ip6_mtuinfo structure to the history. An
implementation may choose not to delivery data to a connected socket
that has a foreign address that is different than the address
specified in the ip6m_addr structure.
When an application sends a packet with a routing header, the final When an application sends a packet with a routing header, the final
destination stored in the ip6m_addr member does not necessarily destination stored in the ip6m_addr member does not necessarily
contain complete information of the entire path. contain complete information of the entire path.
11.4. Determining the current path MTU 11.4. Determining the current path MTU
Some applications might need to determine the current path MTU e.g. Some applications might need to determine the current path MTU e.g.
applications using IPV6_RECVPATHMTU might want to pick a good applications using IPV6_RECVPATHMTU might want to pick a good
starting value. starting value.
skipping to change at page 48, line 11 skipping to change at page 48, line 24
When the call succeeds, the path MTU value is stored in the ip6m_mtu When the call succeeds, the path MTU value is stored in the ip6m_mtu
member of the ip6_mtuinfo structure. Since the socket is connected, member of the ip6_mtuinfo structure. Since the socket is connected,
the ip6m_addr member is meaningless and should not be referred to by the ip6m_addr member is meaningless and should not be referred to by
the application. the application.
This option can only be used for a connected socket, because a non- This option can only be used for a connected socket, because a non-
connected socket does not have the information of the destination and connected socket does not have the information of the destination and
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. call will fail. Despite this limitation, this option is still useful
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
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,
it should use a more generic interface, such as routing sockets
[TCPIPILLUST].
11.5. Neighbor Reachability and UDP 11.5. Neighbor Reachability and UDP
UDP and raw socket applications might know that communication is UDP and raw socket applications might know that communication is
making forward progress i.e. that the path from the node to the next 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 hop is working. In such a case the applications, similarly to TCP as
specified in [RFC-2461], has the option indicate to the internet specified in [RFC-2461], has the option indicate to the internet
layer that the neighbor is reachable. See section 7.3.1 of layer that the neighbor is reachable. See section 7.3.1 of
[RFC-2461]. This could save unneeded neighbor solicitation and [RFC-2461]. This could save unneeded neighbor solicitation and
neighbor advertisement messages. neighbor advertisement messages.
skipping to change at page 52, line 14 skipping to change at page 52, line 32
The existing rcmd() function can not transparently use AF_INET6 The existing rcmd() function can not transparently use AF_INET6
sockets since an application would not be prepared to handle AF_INET6 sockets since an application would not be prepared to handle AF_INET6
addresses returned by e.g. getpeername() on the file descriptor addresses returned by e.g. getpeername() on the file descriptor
created by rcmd(). Thus a new function is needed. created by rcmd(). Thus a new function is needed.
int rcmd_af(char **ahost, unsigned short rport, const char *locuser, int rcmd_af(char **ahost, unsigned short rport, const char *locuser,
const char *remuser, const char *cmd, int *fd2p, int af) const char *remuser, const char *cmd, int *fd2p, int af)
This function behaves the same as the existing rcmd() function, but This function behaves the same as the existing rcmd() function, but
instead of creating an AF_INET TCP socket, it can also create an instead of creating an AF_INET TCP socket, it can also create an
AF_INET6 TCP socket. The family argument is either AF_INET or AF_INET6 TCP socket. The family argument is AF_INET, AF_INET6, or
AF_INET6, and a new error return is EAFNOSUPPORT if the address AF_UNSPEC. When either AF_INET or AF_INET6 is specified, this
family is not supported. function will create a socket of the specified address family. When
AF_UNSPEC is specified, it will try all possible address families
until a connection can be established, and will return the associated
socket of the connection. A new error EAFNOSUPPORT will be returned
if the address family is not supported.
14.3. rexec_af 14.3. rexec_af
The existing rexec() function can not transparently use AF_INET6 The existing rexec() function can not transparently use AF_INET6
sockets since an application would not be prepared to handle AF_INET6 sockets since an application would not be prepared to handle AF_INET6
addresses returned by e.g. getpeername() on the file descriptor addresses returned by e.g. getpeername() on the file descriptor
created by rexec(). Thus a new function is needed. created by rexec(). Thus a new function is needed.
int rexec_af(char **ahost, unsigned short rport, const char *name, int rexec_af(char **ahost, unsigned short rport, const char *name,
const char *pass, const char *cmd, int *fd2p, int af) const char *pass, const char *cmd, int *fd2p, int af)
This function behaves the same as the existing rexec() function, but This function behaves the same as the existing rexec() function, but
instead of creating an AF_INET TCP socket, it can also create an instead of creating an AF_INET TCP socket, it can also create an
AF_INET6 TCP socket. The family argument is either AF_INET or AF_INET6 TCP socket. The family argument is AF_INET, AF_INET6, or
AF_INET6, and a new error return is EAFNOSUPPORT if the address AF_UNSPEC. When either AF_INET or AF_INET6 is specified, this
family is not supported. function will create a socket of the specified address family. When
AF_UNSPEC is specified, it will try all possible address families
until a connection can be established, and will return the associated
socket of the connection. A new error EAFNOSUPPORT will be returned
if the address family is not supported.
15. Summary of New Definitions 15. Summary of New Definitions
The following list summarizes the constants and structure, The following list summarizes the constants and structure,
definitions discussed in this memo, sorted by header. definitions discussed in this memo, sorted by header.
<netinet/icmp6.h> ICMP6_DST_UNREACH <netinet/icmp6.h> ICMP6_DST_UNREACH
<netinet/icmp6.h> ICMP6_DST_UNREACH_ADDR <netinet/icmp6.h> ICMP6_DST_UNREACH_ADDR
<netinet/icmp6.h> ICMP6_DST_UNREACH_ADMIN <netinet/icmp6.h> ICMP6_DST_UNREACH_ADMIN
<netinet/icmp6.h> ICMP6_DST_UNREACH_BEYONDSCOPE <netinet/icmp6.h> ICMP6_DST_UNREACH_BEYONDSCOPE
skipping to change at page 61, line 16 skipping to change at page 61, line 43
non-raw sockets. non-raw sockets.
- Added more precise description about some arguments to - Added more precise description about some arguments to
inet6_opt_next() to make the semantics clear. inet6_opt_next() to make the semantics clear.
- Made the way to get received information on TCP sockets unspecified, - Made the way to get received information on TCP sockets unspecified,
based on a discussion in the working group mailing list. Removed based on a discussion in the working group mailing list. Removed
references to IPV6_PKTOPTIONS, which was revived in the previous references to IPV6_PKTOPTIONS, which was revived in the previous
revision, accordingly. revision, accordingly.
Changes since -04:
- Allowed AF_UNSPEC for rcmd_af() and rexec_af().
- Clarified that buffered messages would be received before a path MTU
indication as an IPV6_PATHMTU ancillary data.
- Described why an error code was not defined when the application
sets IPV6_DONTFRAG and data size is larger than the MTU of the
outgoing interface.
- Added a note that an application that wants to perform the path MTU
discovery by itself needs to keep history of destinations.
- Mentioned the routing socket, with a reference, as a generic
interface to get the path MTU for arbitrary destinations.
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., "Basic [RFC-2553] Gilligan, R. E., Thomson, S., Bound, J., Stevens, W.,
Socket Interface Extensions for IPv6", RFC 2553, March 1999. "Basic Socket Interface Extensions for IPv6", RFC 2553,
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
IP version 6", RFC 1981, Aug. 1996. IP version 6", RFC 1981, Aug. 1996.
[TCPIPILLUST] Wright, G., Stevens, W., "TCP/IP Illustrated, Volume 2:
The Implementation", Addison Wesley, 1994.
[RFC-2461] Narten, T., Nordmark, E., Simpson, W., "Neighbor Discovery [RFC-2461] Narten, T., Nordmark, E., Simpson, W., "Neighbor Discovery
for IP Version 6 (IPv6)", RFC 2461, Dec. 1998. for IP Version 6 (IPv6)", RFC 2461, Dec. 1998.
19. Acknowledgments 19. Acknowledgments
Matt Thomas and Jim Bound have been working on the technical details Matt Thomas and Jim Bound have been working on the technical details
in this draft for over a year. Keith Sklower is the original in this draft for over a year. Keith Sklower is the original
implementor of ancillary data in the BSD networking code. Craig Metz implementor of ancillary data in the BSD networking code. Craig Metz
provided lots of feedback, suggestions, and comments based on his provided lots of feedback, suggestions, and comments based on his
implementing many of these features as the document was being implementing many of these features as the document was being
skipping to change at page 62, line 5 skipping to change at page 63, line 6
The following provided comments on earlier drafts: Pascal Anelli, The following provided comments on earlier drafts: Pascal Anelli,
Hamid Asayesh, Ran Atkinson, Karl Auerbach, Hamid Asayesh, Don Hamid Asayesh, Ran Atkinson, Karl Auerbach, Hamid Asayesh, Don
Coolidge, Matt Crawford, Sam T. Denton, Richard Draves, Francis Coolidge, Matt Crawford, Sam T. Denton, Richard Draves, Francis
Dupont, Lilian Fernandes, Bob Gilligan, Gerri Harter, Tim Hartrick, Dupont, Lilian Fernandes, Bob Gilligan, Gerri Harter, Tim Hartrick,
Bob Halley, Masaki Hirabaru, Yoshinobu Inoue, Mukesh Kacker, A. N. Bob Halley, Masaki Hirabaru, Yoshinobu Inoue, Mukesh Kacker, A. N.
Kuznetsov, Sam Manthorpe, Pedro Marques, Jack McCann, der Mouse, John Kuznetsov, Sam Manthorpe, Pedro Marques, Jack McCann, der Mouse, John
Moy, Lori Napoli, Thomas Narten, Atsushi Onoe, Steve Parker, Charles Moy, Lori Napoli, Thomas Narten, Atsushi Onoe, Steve Parker, Charles
Perkins, Ken Powell, Tom Pusateri, Pedro Roque, Sameer Shah, Peter Perkins, Ken Powell, Tom Pusateri, Pedro Roque, Sameer Shah, Peter
Sjodin, Stephen P. Spackman, Jinmei Tatuya, Karen Tracey, Sowmini Sjodin, Stephen P. Spackman, Jinmei Tatuya, Karen Tracey, Sowmini
Varadhan, Quaizar Vohra, Carl Williams, Steve Wise, Eric Wong, Varadhan, Quaizar Vohra, Carl Williams, Steve Wise, Eric Wong,
Farrell Woods, Kazu Yamamoto, Vlad Yasevich, and YOSHIFUJI Hideaki. Farrell Woods, Kazu Yamamoto, Vladislav Yasevich, and YOSHIFUJI
Hideaki.
20. Authors' Addresses 20. Authors' Addresses
W. Richard Stevens (deceased) W. Richard Stevens (deceased)
Matt Thomas Matt Thomas
3am Software Foundry 3am Software Foundry
8053 Park Villa Circle 8053 Park Villa Circle
Cupertino, CA 95014 Cupertino, CA 95014
Email: matt@3am-software.com Email: matt@3am-software.com
 End of changes. 26 change blocks. 
48 lines changed or deleted 97 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/