Network Working Group W. Stevens
Request for Comments: 2292 Consultant
Category: Informational M. Thomas
AltaVista
February 1998
Advanced Sockets API for IPv6
Status of this Memo
This memo provides information for the Internet community. It does
not specify an Internet standard of any kind. Distribution of this
memo is unlimited.
Copyright Notice
Copyright (C) The Internet Society (1998). All Rights Reserved.
Abstract
Specifications are in progress for changes to the sockets API to
support IP version 6 [RFC-2133]. These changes are for TCP and UDP-
based applications and will support most end-user applications in use
today: Telnet and FTP clients and servers, HTTP clients and servers,
and the like.
But another class of applications exists that will also be run under
IPv6. We call these "advanced" applications and today this includes
programs such as Ping, Traceroute, routing daemons, multicast routing
daemons, router discovery daemons, and the like. The API feature
typically used by these programs that make them "advanced" is a raw
socket to access ICMPv4, IGMPv4, or IPv4, along with some knowledge
of the packet header formats used by these protocols. To provide
portability for applications that use raw sockets under IPv6, some
standardization is needed for the advanced API features.
There are other features of IPv6 that some applications will need to
access: interface identification (specifying the outgoing interface
and determining the incoming interface) and IPv6 extension headers
that are not addressed in [RFC-2133]: Hop-by-Hop options, Destination
options, and the Routing header (source routing). This document
provides API access to these features too.
Stevens & Thomas Informational [Page 1]
RFC 2292 Advanced Sockets API for IPv6 February 1998
Table of Contents
1. Introduction ................................................3
2. Common Structures and Definitions ...........................5
2.1. The ip6_hdr Structure ..................................5
2.1.1. IPv6 Next Header Values .........................6
2.1.2. IPv6 Extension Headers ..........................6
2.2. The icmp6_hdr Structure ................................8
2.2.1. ICMPv6 Type and Code Values .....................8
2.2.2. ICMPv6 Neighbor Discovery Type and Code Values ..9
2.3. Address Testing Macros .................................12
2.4. Protocols File .........................................12
3. IPv6 Raw Sockets ............................................13
3.1. Checksums ..............................................14
3.2. ICMPv6 Type Filtering ..................................14
4. Ancillary Data ..............................................17
4.1. The msghdr Structure ...................................18
4.2. The cmsghdr Structure ..................................18
4.3. Ancillary Data Object Macros ...........................19
4.3.1. CMSG_FIRSTHDR ...................................20
4.3.2. CMSG_NXTHDR .....................................22
4.3.3. CMSG_DATA .......................................22
4.3.4. CMSG_SPACE ......................................22
4.3.5. CMSG_LEN ........................................22
4.4. Summary of Options Described Using Ancillary Data ......23
4.5. IPV6_PKTOPTIONS Socket Option ..........................24
4.5.1. TCP Sticky Options ..............................25
4.5.2. UDP and Raw Socket Sticky Options ...............26
5. Packet Information ..........................................26
5.1. Specifying/Receiving the Interface .....................27
5.2. Specifying/Receiving Source/Destination Address ........27
5.3. Specifying/Receiving the Hop Limit .....................28
5.4. Specifying the Next Hop Address ........................29
5.5. Additional Errors with sendmsg() .......................29
6. Hop-By-Hop Options ..........................................30
6.1. Receiving Hop-by-Hop Options ...........................31
6.2. Sending Hop-by-Hop Options .............................31
6.3. Hop-by-Hop and Destination Options Processing ..........32
6.3.1. inet6_option_space ..............................32
6.3.2. inet6_option_init ...............................32
6.3.3. inet6_option_append .............................33
6.3.4. inet6_option_alloc ..............................33
6.3.5. inet6_option_next ...............................34
6.3.6. inet6_option_find ...............................35
6.3.7. Options Examples ................................35
7. Destination Options .........................................42
7.1. Receiving Destination Options ..........................42
7.2. Sending Destination Options ............................43
Stevens & Thomas Informational [Page 2]
RFC 2292 Advanced Sockets API for IPv6 February 1998
8. Routing Header Option .......................................43
8.1. inet6_rthdr_space ......................................44
8.2. inet6_rthdr_init .......................................45
8.3. inet6_rthdr_add ........................................45
8.4. inet6_rthdr_lasthop ....................................46
8.5. inet6_rthdr_reverse ....................................46
8.6. inet6_rthdr_segments ...................................46
8.7. inet6_rthdr_getaddr ....................................46
8.8. inet6_rthdr_getflags ...................................47
8.9. Routing Header Example .................................47
9. Ordering of Ancillary Data and IPv6 Extension Headers .......53
10. IPv6-Specific Options with IPv4-Mapped IPv6 Addresses .......54
11. rresvport_af ................................................55
12. Future Items ................................................55
12.1. Flow Labels ...........................................55
12.2. Path MTU Discovery and UDP ............................56
12.3. Neighbor Reachability and UDP .........................56
13. Summary of New Definitions ..................................56
14. Security Considerations .....................................59
15. Change History ..............................................59
16. References ..................................................65
17. Acknowledgments .............................................65
18. Authors' Addresses ..........................................66
19. Full Copyright Statement ....................................67
1. Introduction
Specifications are in progress for changes to the sockets API to
support IP version 6 [RFC-2133]. These changes are for TCP and UDP-
based applications. The current document defines some the "advanced"
features of the sockets API that are required for applications to
take advantage of additional features of IPv6.
Today, the portability of applications using IPv4 raw sockets is
quite high, but this is mainly because most IPv4 implementations
started from a common base (the Berkeley source code) or at least
started with the Berkeley headers. This allo