draft-ietf-ipngwg-rfc2292bis-02.txt

bind-3.2.

INTERNET-DRAFT                           W. Richard Stevens (Consultant)
Expires: May 7, 2001                            Matt Thomas (Consultant)
Obsoletes RFC 2292                                   Erik Nordmark (Sun)
                                                        November 7, 2000


                     Advanced Sockets API for IPv6
                   <draft-ietf-ipngwg-rfc2292bis-02.txt>



Abstract

   A separate specification [RFC-2553] contain changes to the sockets
   API to support IP version 6.  Those 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-2553]:  The Routing header (source
   routing), Hop-by-Hop options, and Destination options.  This document
   provides API access to these features too.

Status of this Memo

   This document is an Internet-Draft and is in full conformance with
   all provisions of Section 10 of RFC2026.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF), its areas, and its working groups.  Note that
   other groups may also distribute working documents as Internet-
   Drafts.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any



draft-ietf-ipngwg-2292bis-02.txt                                [Page 1]

INTERNET-DRAFT       Advanced Sockets API for IPv6          Nov. 7, 2000


   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   The list of current Internet-Drafts can be accessed at
   http://www.ietf.org/ietf/1id-abstracts.txt

   The list of Internet-Draft Shadow Directories can be accessed at
   http://www.ietf.org/shadow.html.

   This Internet Draft expires May 7, 2001.









































draft-ietf-ipngwg-2292bis-02.txt                                [Page 2]

INTERNET-DRAFT       Advanced Sockets API for IPv6          Nov. 7, 2000


Table of Contents

   1.  Introduction .....................................................  6

   2.  Common Structures and Definitions ................................  7
   2.1.  The ip6_hdr Structure ..........................................  8
   2.1.1.  IPv6 Next Header Values ......................................  8
   2.1.2.  IPv6 Extension Headers .......................................  9
   2.1.3.  IPv6 Options ................................................. 10
   2.2.  The icmp6_hdr Structure ........................................ 13
   2.2.1.  ICMPv6 Type and Code Values .................................. 13
   2.2.2.  ICMPv6 Neighbor Discovery Definitions ........................ 14
   2.2.3.  Multicast Listener Discovery Definitions ..................... 17
   2.2.4.  ICMPv6 Router Renumbering Definitions ........................ 18
   2.3.  Address Testing Macros ......................................... 19
   2.4.  Protocols File ................................................. 20

   3.  IPv6 Raw Sockets ................................................. 20
   3.1.  Checksums ...................................................... 22
   3.2.  ICMPv6 Type Filtering .......................................... 22
   3.3.  ICMPv6 Verification of Received Packets ........................ 25

   4.  Access to IPv6 and Extension Headers ............................. 25
   4.1.  TCP Implications ............................................... 27
   4.2.  UDP and Raw Socket Implications ................................ 28

   5.  Extensions to Socket Ancillary Data .............................. 28

   6.  Packet Information ............................................... 29
   6.1.  Specifying/Receiving the Interface ............................. 30
   6.2.  Specifying/Receiving Source/Destination Address ................ 30
   6.3.  Specifying/Receiving the Hop Limit ............................. 31
   6.4.  Specifying the Next Hop Address ................................ 32
   6.5.  Additional Errors with sendmsg() and setsockopt() .............. 32

   7.  Routing Header Option ............................................ 33
   7.1.  inet6_rth_space ................................................ 34
   7.2.  inet6_rth_init ................................................. 35
   7.3.  inet6_rth_add .................................................. 35
   7.4.  inet6_rth_reverse .............................................. 35
   7.5.  inet6_rth_segments ............................................. 36
   7.6.  inet6_rth_getaddr .............................................. 36

   8.  Hop-By-Hop Options ............................................... 36
   8.1.  Receiving Hop-by-Hop Options ................................... 38
   8.2.  Sending Hop-by-Hop Options ..................................... 38

   9.  Destination Options .............................................. 38



draft-ietf-ipngwg-2292bis-02.txt                                [Page 3]

INTERNET-DRAFT       Advanced Sockets API for IPv6          Nov. 7, 2000


   9.1.  Receiving Destination Options .................................. 39
   9.2.  Sending Destination Options .................................... 39

   10.  Hop-by-Hop and Destination Options Processing ................... 40
   10.1.  inet6_opt_init ................................................ 40
   10.2.  inet6_opt_append .............................................. 41
   10.3.  inet6_opt_finish .............................................. 41
   10.4.  inet6_opt_set_val ............................................. 42
   10.5.  inet6_opt_next ................................................ 42
   10.6.  inet6_opt_find ................................................ 42
   10.7.  inet6_opt_get_val ............................................. 43

   11.  Additional Advanced API Functions ............................... 43
   11.1.  Sending with the Minimum MTU .................................. 43
   11.2.  Path MTU Discovery and UDP .................................... 44
   11.3.  Neighbor Reachability and UDP ................................. 44

   12.  Ordering of Ancillary Data and IPv6 Extension Headers ........... 45

   13.  IPv6-Specific Options with IPv4-Mapped IPv6 Addresses ........... 46

   14.  Extended interfaces for rresvport, rcmd and rexec ............... 46
   14.1.  rresvport_af .................................................. 46
   14.2.  rcmd_af ....................................................... 47
   14.3.  rexec_af ...................................................... 47

   15.  Summary of New Definitions ...................................... 47

   16.  Security Considerations ......................................... 52

   17.  Change History .................................................. 52

   18.  TODO and Open Issues ............................................ 54

   19.  References ...................................................... 56

   20.  Acknowledgments ................................................. 56

   21.  Authors' Addresses .............................................. 57

   22.  Appendix A: Ancillary Data Overview ............................. 57
   22.1.  The msghdr Structure .......................................... 58
   22.2.  The cmsghdr Structure ......................................... 59
   22.3.  Ancillary Data Object Macros .................................. 60
   22.3.1.  CMSG_FIRSTHDR ............................................... 61
   22.3.2.  CMSG_NXTHDR ................................................. 62
   22.3.3.  CMSG_DATA ................................................... 63
   22.3.4.  CMSG_SPACE .................................................. 63



draft-ietf-ipngwg-2292bis-02.txt                                [Page 4]

INTERNET-DRAFT       Advanced Sockets API for IPv6          Nov. 7, 2000


   22.3.5.  CMSG_LEN .................................................... 64

   23.  Appendix B: Examples using the inet6_rth_XXX() functions ........ 64
   23.1.  Sending a Routing Header ...................................... 64
   23.2.  Receiving Routing Headers ..................................... 69

   24.  Appendix C: Examples using the inet6_opt_XXX() functions ........ 71
   24.1.  Building options .............................................. 71
   24.2.  Parsing received options ...................................... 73










































draft-ietf-ipngwg-2292bis-02.txt                                [Page 5]

INTERNET-DRAFT       Advanced Sockets API for IPv6          Nov. 7, 2000


1.  Introduction

   A separate specification [RFC-2553] contain changes to the sockets
   API to support IP version 6.  Those changes are for TCP and UDP-based
   applications.  This 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 header files.  This allows programs such as
   Ping and Traceroute, for example, to compile with minimal effort on
   many hosts that support the sockets API.  With IPv6, however, there
   is no common source code base that implementors are starting from,
   and the possibility for divergence at this level between different
   implementations is high.  To avoid a complete lack of portability
   amongst applications that use raw IPv6 sockets, some standardization
   is necessary.

   There are also features from the basic IPv6 specification that are
   not addressed in [RFC-2553]:  sending and receiving Routing headers,
   Hop-by-Hop options, and Destination options, specifying the outgoing
   interface, and being told of the receiving interface.

   This document can be divided into the following main sections.

   1.  Definitions of the basic constants and structures required for
       applications to use raw IPv6 sockets.  This includes structure
       definitions for the IPv6 and ICMPv6 headers and all associated
       constants (e.g., values for the Next Header field).

   2.  Some basic semantic definitions for IPv6 raw sockets.  For
       example, a raw ICMPv4 socket requires the application to
       calculate and store the ICMPv4 header checksum.  But with IPv6
       this would require the application to choose the source IPv6
       address because the source address is part of the pseudo header
       that ICMPv6 now uses for its checksum computation.  It should be
       defined that with a raw ICMPv6 socket the kernel always
       calculates and stores the ICMPv6 header checksum.

   3.  Packet information:  how applications can obtain the received
       interface, destination address, and received hop limit, along
       with specifying these values on a per-packet basis.  There are a
       class of applications that need this capability and the technique
       should be portable.

   4.  Access to the optional Routing header, Hop-by-Hop, and



draft-ietf-ipngwg-2292bis-02.txt                                [Page 6]

INTERNET-DRAFT       Advanced Sockets API for IPv6          Nov. 7, 2000


       Destination extension headers.

   5.  Additional features required for improved IPv6 application
       portability.