Tech-invite3GPPspaceIETFspace
959493929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 2292

Advanced Sockets API for IPv6

Pages: 67
Obsoleted by:  3542
Part 1 of 3 – Pages 1 to 17
None   None   Next

ToP   noToC   RFC2292 - Page 1
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.
ToP   noToC   RFC2292 - Page 2
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
ToP   noToC   RFC2292 - Page 3
    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.
ToP   noToC   RFC2292 - Page 4
   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.
ToP   noToC   RFC2292 - Page 5
   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
ToP   noToC   RFC2292 - Page 6
    #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>.

   /* Hop-by-Hop options header */
   /* XXX should we pad it to force alignment on an 8-byte boundary? */
   struct ip6_hbh {
     uint8_t  ip6h_nxt;        /* next header */
     uint8_t  ip6h_len;        /* length in units of 8 octets */
       /* followed by options */
   };

   /* Destination options header */
   /* XXX should we pad it to force alignment on an 8-byte boundary? */
   struct ip6_dest {
     uint8_t  ip6d_nxt;        /* next header */
     uint8_t  ip6d_len;        /* length in units of 8 octets */
       /* followed by options */
   };

   /* Routing header */
   struct ip6_rthdr {
ToP   noToC   RFC2292 - Page 7
     uint8_t  ip6r_nxt;        /* next header */
     uint8_t  ip6r_len;        /* length in units of 8 octets */
     uint8_t  ip6r_type;       /* routing type */
     uint8_t  ip6r_segleft;    /* segments left */
       /* followed by routing type specific data */
   };

   /* Type 0 Routing header */
   struct ip6_rthdr0 {
     uint8_t  ip6r0_nxt;       /* next header */
     uint8_t  ip6r0_len;       /* length in units of 8 octets */
     uint8_t  ip6r0_type;      /* always zero */
     uint8_t  ip6r0_segleft;   /* segments left */
     uint8_t  ip6r0_reserved;  /* reserved field */
     uint8_t  ip6r0_slmap[3];  /* strict/loose bit map */
     struct in6_addr  ip6r0_addr[1];  /* up to 23 addresses */
   };

   /* Fragment header */
   struct ip6_frag {
     uint8_t   ip6f_nxt;       /* next header */
     uint8_t   ip6f_reserved;  /* reserved field */
     uint16_t  ip6f_offlg;     /* offset, reserved, and flag */
     uint32_t  ip6f_ident;     /* identification */
   };

   #if     BYTE_ORDER == BIG_ENDIAN
   #define IP6F_OFF_MASK       0xfff8  /* mask out offset from _offlg */
   #define IP6F_RESERVED_MASK  0x0006  /* reserved bits in ip6f_offlg */
   #define IP6F_MORE_FRAG      0x0001  /* more-fragments flag */
   #else   /* BYTE_ORDER == LITTLE_ENDIAN */
   #define IP6F_OFF_MASK       0xf8ff  /* mask out offset from _offlg */
   #define IP6F_RESERVED_MASK  0x0600  /* reserved bits in ip6f_offlg */
   #define IP6F_MORE_FRAG      0x0100  /* more-fragments flag */
   #endif

   Defined constants for fields larger than 1 byte depend on the byte
   ordering that is used.  This API assumes that the fields in the
   protocol headers are left in the network byte order, which is big-
   endian for the Internet protocols.  If not, then either these
   constants or the fields being tested must be converted at run-time,
   using something like htons() or htonl().

   (Note: We show an implementation that supports both big-endian and
   little-endian byte ordering, assuming a hypothetical compile-time #if
   test to determine the byte ordering.  The constant that we show,
ToP   noToC   RFC2292 - Page 8
   BYTE_ORDER, with values of BIG_ENDIAN and LITTLE_ENDIAN, are for
   example purposes only.  If an implementation runs on only one type of
   hardware it need only define the set of constants for that hardware's
   byte ordering.)

2.2.  The icmp6_hdr Structure

   The ICMPv6 header is needed by numerous IPv6 applications including
   Ping, Traceroute, router discovery daemons, and neighbor discovery
   daemons.  The following structure is defined as a result of including
   <netinet/icmp6.h>.  Note that this is a new header.

   struct icmp6_hdr {
     uint8_t     icmp6_type;   /* type field */
     uint8_t     icmp6_code;   /* code field */
     uint16_t    icmp6_cksum;  /* checksum field */
     union {
       uint32_t  icmp6_un_data32[1]; /* type-specific field */
       uint16_t  icmp6_un_data16[2]; /* type-specific field */
       uint8_t   icmp6_un_data8[4];  /* type-specific field */
     } icmp6_dataun;
   };

   #define icmp6_data32    icmp6_dataun.icmp6_un_data32
   #define icmp6_data16    icmp6_dataun.icmp6_un_data16
   #define icmp6_data8     icmp6_dataun.icmp6_un_data8
   #define icmp6_pptr      icmp6_data32[0]  /* parameter prob */
   #define icmp6_mtu       icmp6_data32[0]  /* packet too big */
   #define icmp6_id        icmp6_data16[0]  /* echo request/reply */
   #define icmp6_seq       icmp6_data16[1]  /* echo request/reply */
   #define icmp6_maxdelay  icmp6_data16[0]  /* mcast group membership */

2.2.1.  ICMPv6 Type and Code Values

   In addition to a common structure for the ICMPv6 header, common
   definitions are required for the ICMPv6 type and code fields.  The
   following constants are also defined as a result of including
   <netinet/icmp6.h>.

#define ICMP6_DST_UNREACH             1
#define ICMP6_PACKET_TOO_BIG          2
#define ICMP6_TIME_EXCEEDED           3
#define ICMP6_PARAM_PROB              4

#define ICMP6_INFOMSG_MASK  0x80    /* all informational messages */

#define ICMP6_ECHO_REQUEST          128
#define ICMP6_ECHO_REPLY            129
ToP   noToC   RFC2292 - Page 9
#define ICMP6_MEMBERSHIP_QUERY      130
#define ICMP6_MEMBERSHIP_REPORT     131
#define ICMP6_MEMBERSHIP_REDUCTION  132

#define ICMP6_DST_UNREACH_NOROUTE     0 /* no route to destination */
#define ICMP6_DST_UNREACH_ADMIN       1 /* communication with */
                                        /* destination */
                                        /* administratively */
                                        /* prohibited */
#define ICMP6_DST_UNREACH_NOTNEIGHBOR 2 /* not a neighbor */
#define ICMP6_DST_UNREACH_ADDR        3 /* address unreachable */
#define ICMP6_DST_UNREACH_NOPORT      4 /* bad port */

#define ICMP6_TIME_EXCEED_TRANSIT     0 /* Hop Limit == 0 in transit */
#define ICMP6_TIME_EXCEED_REASSEMBLY  1 /* Reassembly time out */

#define ICMP6_PARAMPROB_HEADER        0 /* erroneous header field */
#define ICMP6_PARAMPROB_NEXTHEADER    1 /* unrecognized Next Header */
#define ICMP6_PARAMPROB_OPTION        2 /* unrecognized IPv6 option */

   The five ICMP message types defined by IPv6 neighbor discovery (133-
   137) are defined in the next section.

2.2.2.  ICMPv6 Neighbor Discovery Type and Code Values

   The following structures and definitions are defined as a result of
   including <netinet/icmp6.h>.

   #define ND_ROUTER_SOLICIT           133
   #define ND_ROUTER_ADVERT            134
   #define ND_NEIGHBOR_SOLICIT         135
   #define ND_NEIGHBOR_ADVERT          136
   #define ND_REDIRECT                 137

   struct nd_router_solicit {     /* router solicitation */
     struct icmp6_hdr  nd_rs_hdr;
       /* could be followed by options */
   };

   #define nd_rs_type               nd_rs_hdr.icmp6_type
   #define nd_rs_code               nd_rs_hdr.icmp6_code
   #define nd_rs_cksum              nd_rs_hdr.icmp6_cksum
   #define nd_rs_reserved           nd_rs_hdr.icmp6_data32[0]

   struct nd_router_advert {      /* router advertisement */
     struct icmp6_hdr  nd_ra_hdr;
     uint32_t   nd_ra_reachable;   /* reachable time */
     uint32_t   nd_ra_retransmit;  /* retransmit timer */
ToP   noToC   RFC2292 - Page 10
       /* could be followed by options */
   };

   #define nd_ra_type               nd_ra_hdr.icmp6_type
   #define nd_ra_code               nd_ra_hdr.icmp6_code
   #define nd_ra_cksum              nd_ra_hdr.icmp6_cksum
   #define nd_ra_curhoplimit        nd_ra_hdr.icmp6_data8[0]
   #define nd_ra_flags_reserved     nd_ra_hdr.icmp6_data8[1]
   #define ND_RA_FLAG_MANAGED       0x80
   #define ND_RA_FLAG_OTHER         0x40
   #define nd_ra_router_lifetime    nd_ra_hdr.icmp6_data16[1]

   struct nd_neighbor_solicit {   /* neighbor solicitation */
     struct icmp6_hdr  nd_ns_hdr;
     struct in6_addr   nd_ns_target; /* target address */
       /* could be followed by options */
   };

   #define nd_ns_type               nd_ns_hdr.icmp6_type
   #define nd_ns_code               nd_ns_hdr.icmp6_code
   #define nd_ns_cksum              nd_ns_hdr.icmp6_cksum
   #define nd_ns_reserved           nd_ns_hdr.icmp6_data32[0]

   struct nd_neighbor_advert {    /* neighbor advertisement */
     struct icmp6_hdr  nd_na_hdr;
     struct in6_addr   nd_na_target; /* target address */
       /* could be followed by options */
   };

   #define nd_na_type               nd_na_hdr.icmp6_type
   #define nd_na_code               nd_na_hdr.icmp6_code
   #define nd_na_cksum              nd_na_hdr.icmp6_cksum
   #define nd_na_flags_reserved     nd_na_hdr.icmp6_data32[0]
   #if     BYTE_ORDER == BIG_ENDIAN
   #define ND_NA_FLAG_ROUTER        0x80000000
   #define ND_NA_FLAG_SOLICITED     0x40000000
   #define ND_NA_FLAG_OVERRIDE      0x20000000
   #else   /* BYTE_ORDER == LITTLE_ENDIAN */
   #define ND_NA_FLAG_ROUTER        0x00000080
   #define ND_NA_FLAG_SOLICITED     0x00000040
   #define ND_NA_FLAG_OVERRIDE      0x00000020
   #endif

   struct nd_redirect {           /* redirect */
     struct icmp6_hdr  nd_rd_hdr;
     struct in6_addr   nd_rd_target; /* target address */
     struct in6_addr   nd_rd_dst;    /* destination address */
       /* could be followed by options */
ToP   noToC   RFC2292 - Page 11
   };

   #define nd_rd_type               nd_rd_hdr.icmp6_type
   #define nd_rd_code               nd_rd_hdr.icmp6_code
   #define nd_rd_cksum              nd_rd_hdr.icmp6_cksum
   #define nd_rd_reserved           nd_rd_hdr.icmp6_data32[0]

   struct nd_opt_hdr {           /* Neighbor discovery option header */
     uint8_t  nd_opt_type;
     uint8_t  nd_opt_len;        /* in units of 8 octets */
       /* followed by option specific data */
   };

   #define  ND_OPT_SOURCE_LINKADDR       1
   #define  ND_OPT_TARGET_LINKADDR       2
   #define  ND_OPT_PREFIX_INFORMATION    3
   #define  ND_OPT_REDIRECTED_HEADER     4
   #define  ND_OPT_MTU                   5

   struct nd_opt_prefix_info {    /* prefix information */
     uint8_t   nd_opt_pi_type;
     uint8_t   nd_opt_pi_len;
     uint8_t   nd_opt_pi_prefix_len;
     uint8_t   nd_opt_pi_flags_reserved;
     uint32_t  nd_opt_pi_valid_time;
     uint32_t  nd_opt_pi_preferred_time;
     uint32_t  nd_opt_pi_reserved2;
     struct in6_addr  nd_opt_pi_prefix;
   };

   #define ND_OPT_PI_FLAG_ONLINK        0x80
   #define ND_OPT_PI_FLAG_AUTO          0x40

   struct nd_opt_rd_hdr {         /* redirected header */
     uint8_t   nd_opt_rh_type;
     uint8_t   nd_opt_rh_len;
     uint16_t  nd_opt_rh_reserved1;
     uint32_t  nd_opt_rh_reserved2;
       /* followed by IP header and data */
   };

   struct nd_opt_mtu {            /* MTU option */
     uint8_t   nd_opt_mtu_type;
     uint8_t   nd_opt_mtu_len;
     uint16_t  nd_opt_mtu_reserved;
     uint32_t  nd_opt_mtu_mtu;
   };
ToP   noToC   RFC2292 - Page 12
   We note that the nd_na_flags_reserved flags have the same byte
   ordering problems as we discussed with ip6f_offlg.

2.3.  Address Testing Macros

   The basic API ([RFC-2133]) defines some macros for testing an IPv6
   address for certain properties.  This API extends those definitions
   with additional address testing macros, defined as a result of
   including <netinet/in.h>.

    int  IN6_ARE_ADDR_EQUAL(const struct in6_addr *,
                            const struct in6_addr *);

2.4.  Protocols File

   Many hosts provide the file /etc/protocols that contains the names of
   the various IP protocols and their protocol number (e.g., the value
   of the protocol field in the IPv4 header for that protocol, such as 1
   for ICMP).  Some programs then call the function getprotobyname() to
   obtain the protocol value that is then specified as the third
   argument to the socket() function.  For example, the Ping program
   contains code of the form

       struct protoent  *proto;

       proto = getprotobyname("icmp");

       s = socket(AF_INET, SOCK_RAW, proto->p_proto);

   Common names are required for the new IPv6 protocols in this file, to
   provide portability of applications that call the getprotoXXX()
   functions.

   We define the following protocol names with the values shown.  These
   are taken from ftp://ftp.isi.edu/in-notes/iana/assignments/protocol-
   numbers.

       hopopt           0    # hop-by-hop options for ipv6
       ipv6            41    # ipv6
       ipv6-route      43    # routing header for ipv6
       ipv6-frag       44    # fragment header for ipv6
       esp             50    # encapsulating security payload for ipv6
       ah              51    # authentication header for ipv6
       ipv6-icmp       58    # icmp for ipv6
       ipv6-nonxt      59    # no next header for ipv6
       ipv6-opts       60    # destination options for ipv6
ToP   noToC   RFC2292 - Page 13
3.  IPv6 Raw Sockets

   Raw sockets bypass the transport layer (TCP or UDP).  With IPv4, raw
   sockets are used to access ICMPv4, IGMPv4, and to read and write IPv4
   datagrams containing a protocol field that the kernel does not
   process.  An example of the latter is a routing daemon for OSPF,
   since it uses IPv4 protocol field 89.  With IPv6 raw sockets will be
   used for ICMPv6 and to read and write IPv6 datagrams containing a
   Next Header field that the kernel does not process.  Examples of the
   latter are a routing daemon for OSPF for IPv6 and RSVP (protocol
   field 46).

   All data sent via raw sockets MUST be in network byte order and all
   data received via raw sockets will be in network byte order.  This
   differs from the IPv4 raw sockets, which did not specify a byte
   ordering and typically used the host's byte order.

   Another difference from IPv4 raw sockets is that complete packets
   (that is, IPv6 packets with extension headers) cannot be read or
   written using the IPv6 raw sockets API.  Instead, ancillary data
   objects are used to transfer the extension headers, as described
   later in this document.  Should an application need access to the
   complete IPv6 packet, some other technique, such as the datalink
   interfaces BPF or DLPI, must be used.

   All fields in the IPv6 header that an application might want to
   change (i.e., everything other than the version number) can be
   modified using ancillary data and/or socket options by the
   application for output.  All fields in a received IPv6 header (other
   than the version number and Next Header fields) and all extension
   headers are also made available to the application as ancillary data
   on input.  Hence there is no need for a socket option similar to the
   IPv4 IP_HDRINCL socket option.

   When writing to a raw socket the kernel will automatically fragment
   the packet if its size exceeds the path MTU, inserting the required
   fragmentation headers.  On input the kernel reassembles received
   fragments, so the reader of a raw socket never sees any fragment
   headers.

   When we say "an ICMPv6 raw socket" we mean a socket created by
   calling the socket function with the three arguments PF_INET6,
   SOCK_RAW, and IPPROTO_ICMPV6.

   Most IPv4 implementations give special treatment to a raw socket
   created with a third argument to socket() of IPPROTO_RAW, whose value
   is normally 255.  We note that this value has no special meaning to
   an IPv6 raw socket (and the IANA currently reserves the value of 255
ToP   noToC   RFC2292 - Page 14
   when used as a next-header field).  (Note: This feature was added to
   IPv4 in 1988 by Van Jacobson to support traceroute, allowing a
   complete IP header to be passed by the application, before the
   IP_HDRINCL socket option was added.)

3.1.  Checksums

   The kernel will calculate and insert the ICMPv6 checksum for ICMPv6
   raw sockets, since this checksum is mandatory.

   For other raw IPv6 sockets (that is, for raw IPv6 sockets created
   with a third argument other than IPPROTO_ICMPV6), the application
   must set the new IPV6_CHECKSUM socket option to have the kernel (1)
   compute and store a checksum for output, and (2) verify the received
   checksum on input, discarding the packet if the checksum is in error.
   This option prevents applications from having to perform source
   address selection on the packets they send.  The checksum will
   incorporate the IPv6 pseudo-header, defined in Section 8.1 of [RFC-
   1883].  This new socket option also specifies an integer offset into
   the user data of where the checksum is located.

    int  offset = 2;
    setsockopt(fd, IPPROTO_IPV6, IPV6_CHECKSUM, &offset, sizeof(offset));

   By default, this socket option is disabled.  Setting the offset to -1
   also disables the option.  By disabled we mean (1) the kernel will
   not calculate and store a checksum for outgoing packets, and (2) the
   kernel will not verify a checksum for received packets.

   (Note: Since the checksum is always calculated by the kernel for an
   ICMPv6 socket, applications are not able to generate ICMPv6 packets
   with incorrect checksums (presumably for testing purposes) using this
   API.)

3.2.  ICMPv6 Type Filtering

   ICMPv4 raw sockets receive most ICMPv4 messages received by the
   kernel.  (We say "most" and not "all" because Berkeley-derived
   kernels never pass echo requests, timestamp requests, or address mask
   requests to a raw socket.  Instead these three messages are processed
   entirely by the kernel.)  But ICMPv6 is a superset of ICMPv4, also
   including the functionality of IGMPv4 and ARPv4.  This means that an
   ICMPv6 raw socket can potentially receive many more messages than
   would be received with an ICMPv4 raw socket: ICMP messages similar to
   ICMPv4, along with neighbor solicitations, neighbor advertisements,
   and the three group membership messages.
ToP   noToC   RFC2292 - Page 15
   Most applications using an ICMPv6 raw socket care about only a small
   subset of the ICMPv6 message types.  To transfer extraneous ICMPv6
   messages from the kernel to user can incur a significant overhead.
   Therefore this API includes a method of filtering ICMPv6 messages by
   the ICMPv6 type field.

   Each ICMPv6 raw socket has an associated filter whose datatype is
   defined as

       struct icmp6_filter;

   This structure, along with the macros and constants defined later in
   this section, are defined as a result of including the
   <netinet/icmp6.h> header.

   The current filter is fetched and stored using getsockopt() and
   setsockopt() with a level of IPPROTO_ICMPV6 and an option name of
   ICMP6_FILTER.

   Six macros operate on an icmp6_filter structure:

       void ICMP6_FILTER_SETPASSALL (struct icmp6_filter *);
       void ICMP6_FILTER_SETBLOCKALL(struct icmp6_filter *);

       void ICMP6_FILTER_SETPASS ( int, struct icmp6_filter *);
       void ICMP6_FILTER_SETBLOCK( int, struct icmp6_filter *);

       int  ICMP6_FILTER_WILLPASS (int, const struct icmp6_filter *);
       int  ICMP6_FILTER_WILLBLOCK(int, const struct icmp6_filter *);

   The first argument to the last four macros (an integer) is an ICMPv6
   message type, between 0 and 255.  The pointer argument to all six
   macros is a pointer to a filter that is modified by the first four
   macros examined by the last two macros.

   The first two macros, SETPASSALL and SETBLOCKALL, let us specify that
   all ICMPv6 messages are passed to the application or that all ICMPv6
   messages are blocked from being passed to the application.

   The next two macros, SETPASS and SETBLOCK, let us specify that
   messages of a given ICMPv6 type should be passed to the application
   or not passed to the application (blocked).

   The final two macros, WILLPASS and WILLBLOCK, return true or false
   depending whether the specified message type is passed to the
   application or blocked from being passed to the application by the
   filter pointed to by the second argument.
ToP   noToC   RFC2292 - Page 16
   When an ICMPv6 raw socket is created, it will by default pass all
   ICMPv6 message types to the application.

   As an example, a program that wants to receive only router
   advertisements could execute the following:

struct icmp6_filter  myfilt;

fd = socket(PF_INET6, SOCK_RAW, IPPROTO_ICMPV6);

ICMP6_FILTER_SETBLOCKALL(&myfilt);
ICMP6_FILTER_SETPASS(ND_ROUTER_ADVERT, &myfilt);
setsockopt(fd, IPPROTO_ICMPV6, ICMP6_FILTER, &myfilt, sizeof(myfilt));

   The filter structure is declared and then initialized to block all
   messages types.  The filter structure is then changed to allow router
   advertisement messages to be passed to the application and the filter
   is installed using setsockopt().

   The icmp6_filter structure is similar to the fd_set datatype used
   with the select() function in the sockets API.  The icmp6_filter
   structure is an opaque datatype and the application should not care
   how it is implemented.  All the application does with this datatype
   is allocate a variable of this type, pass a pointer to a variable of
   this type to getsockopt() and setsockopt(), and operate on a variable
   of this type using the six macros that we just defined.

   Nevertheless, it is worth showing a simple implementation of this
   datatype and the six macros.

struct icmp6_filter {
  uint32_t  icmp6_filt[8];  /* 8*32 = 256 bits */
};

#define ICMP6_FILTER_WILLPASS(type, filterp) \
    ((((filterp)->icmp6_filt[(type) >> 5]) & (1 << ((type) & 31))) != 0)
#define ICMP6_FILTER_WILLBLOCK(type, filterp) \
    ((((filterp)->icmp6_filt[(type) >> 5]) & (1 << ((type) & 31))) == 0)
#define ICMP6_FILTER_SETPASS(type, filterp) \
    ((((filterp)->icmp6_filt[(type) >> 5]) |=  (1 << ((type) & 31))))
#define ICMP6_FILTER_SETBLOCK(type, filterp) \
    ((((filterp)->icmp6_filt[(type) >> 5]) &= ~(1 << ((type) & 31))))
#define ICMP6_FILTER_SETPASSALL(filterp) \
    memset((filterp), 0xFF, sizeof(struct icmp6_filter))
#define ICMP6_FILTER_SETBLOCKALL(filterp) \
    memset((filterp), 0, sizeof(struct icmp6_filter))
ToP   noToC   RFC2292 - Page 17
   (Note: These sample definitions have two limitations that an
   implementation may want to change.  The first four macros evaluate
   their first argument two times.  The second two macros require the
   inclusion of the <string.h> header for the memset() function.)



(page 17 continued on part 2)

Next Section