rfc2292.txt

netcat

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 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.







Stevens & Thomas             Informational                      [Page 3]

RFC 2292             Advanced Sockets API for IPv6         February 1998


   There are also features from the basic IPv6 specification that are
   not addressed in [RFC-2133]: sending and receiving Hop-by-Hop
   options, Destination options, and Routing headers, 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 Hop-by-Hop, Destination, and Routing
       headers.

   5.  Additional features required for IPv6 application portability.

   The packet information along with access to the extension headers
   (Hop-by-Hop options, Destination options, and Routing header) are
   specified using the "ancillary data" fields that were added to the
   4.3BSD Reno sockets API in 1990.  The reason is that these ancillary
   data fields are part of the Posix.1g standard (which should be
   approved in 1997) and should therefore be adopted by most vendors.

   This document does not address application access to either the
   authentication header or the encapsulating security payload header.

   All examples in this document omit error checking in favor of brevity
   and clarity.







Stevens & Thomas             Informational                      [Page 4]

RFC 2292             Advanced Sockets API for IPv6         February 1998


   We note that many of the functions and socket options defined in this
   document may have error returns that are not defined in this
   document.  Many of these possible error returns will be recognized
   only as implementations proceed.

   Datatypes in this document follow the Posix.1g format: intN_t means a
   signed integer of exactly N bits (e.g., int16_t) and uintN_t means an
   unsigned integer of exactly N bits (e.g., uint32_t).

   Note that we use the (unofficial) terminology ICMPv4, IGMPv4, and
   ARPv4 to avoid any confusion with the newer ICMPv6 protocol.

2.  Common Structures and Definitions

   Many advanced applications examine fields in the IPv6 header and set
   and examine fields in the various ICMPv6 headers.  Common structure
   definitions for these headers are required, along with common
   constant definitions for the structure members.

   Two new headers are defined: <netinet/ip6.h> and <netinet/icmp6.h>.

   When an include file is specified, that include file is allowed to
   include other files that do the actual declaration or definition.

2.1.  The ip6_hdr Structure

   The following structure is defined as a result of including
   <netinet/ip6.h>.  Note that this is a new header.

    struct ip6_hdr {
      union {
        struct ip6_hdrctl {
          uint32_t ip6_un1_flow;   /* 24 bits of flow-ID */
          uint16_t ip6_un1_plen;   /* payload length */
          uint8_t  ip6_un1_nxt;    /* next header */
          uint8_t  ip6_un1_hlim;   /* hop limit */
        } ip6_un1;
        uint8_t ip6_un2_vfc;       /* 4 bits version, 4 bits priority */
      } ip6_ctlun;
      struct in6_addr ip6_src;      /* source address */
      struct in6_addr ip6_dst;      /* destination address */
    };

    #define ip6_vfc   ip6_ctlun.ip6_un2_vfc
    #define ip6_flow  ip6_ctlun.ip6_un1.ip6_un1_flow
    #define ip6_plen  ip6_ctlun.ip6_un1.ip6_un1_plen
    #define ip6_nxt   ip6_ctlun.ip6_un1.ip6_un1_nxt
    #define ip6_hlim  ip6_ctlun.ip6_un1.ip6_un1_hlim



Stevens & Thomas             Informational                      [Page 5]

RFC 2292             Advanced Sockets API for IPv6         February 1998


    #define ip6_hops  ip6_ctlun.ip6_un1.ip6_un1_hlim

2.1.1.  IPv6 Next Header Values

   IPv6 defines many new values for the Next Header field.  The
   following constants are defined as a result of including
   <netinet/in.h>.

   #define IPPROTO_HOPOPTS        0 /* IPv6 Hop-by-Hop options */
   #define IPPROTO_IPV6          41 /* IPv6 header */
   #define IPPROTO_ROUTING       43 /* IPv6 Routing header */
   #define IPPROTO_FRAGMENT      44 /* IPv6 fragmentation header */
   #define IPPROTO_ESP           50 /* encapsulating security payload */
   #define IPPROTO_AH            51 /* authentication header */
   #define IPPROTO_ICMPV6        58 /* ICMPv6 */
   #define IPPROTO_NONE          59 /* IPv6 no next header */
   #define IPPROTO_DSTOPTS       60 /* IPv6 Destination options */

   Berkeley-derived IPv4 implementations also define IPPROTO_IP to be 0.
   This should not be a problem since IPPROTO_IP is used only with IPv4
   sockets and IPPROTO_HOPOPTS only with IPv6 sockets.

2.1.2.  IPv6 Extension Headers

   Six extension headers are defined for IPv6.  We define structures for
   all except the Authentication header and Encapsulating Security
   Payload header, both of which are beyond the scope of this document.
   The following structures are defined as a result of including
   <netinet/ip6.h>.