draft-ietf-ipngwg-rfc2292bis-02.txt

bind-3.2.

       #define ICMP6_RR_PCOUSE_FLAGS_DECRVLTIME 0x80
       #define ICMP6_RR_PCOUSE_FLAGS_DECRPLTIME 0x40
       #endif

       struct rr_result {    /* router renumbering result message */
         u_int16_t         rrr_flags;
         u_int8_t          rrr_ordinal;
         u_int8_t          rrr_matchedlen;
         u_int32_t         rrr_ifid;
         struct in6_addr   rrr_prefix;
       };

       #if BYTE_ORDER == BIG_ENDIAN
       #define ICMP6_RR_RESULT_FLAGS_OOB        0x0002
       #define ICMP6_RR_RESULT_FLAGS_FORBIDDEN  0x0001
       #elif BYTE_ORDER == LITTLE_ENDIAN
       #define ICMP6_RR_RESULT_FLAGS_OOB        0x0200
       #define ICMP6_RR_RESULT_FLAGS_FORBIDDEN  0x0100
       #endif



2.3.  Address Testing Macros

   The basic API ([RFC-2553]) 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 *);

   This macro returns non-zero if the addresses are equal; otherwise it






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


   returns zero.


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(PF_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



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



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


   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 used the host's byte order for certain IP header fields.

   Another difference from IPv4 raw sockets is that complete packets
   (that is, IPv6 packets with extension headers) cannot be sent or
   received using the IPv6 raw sockets API.  Instead, ancillary data
   objects are used to transfer the extension headers and hoplimit
   information, as described in Section 6.  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 and on receipt the application will
   only receive the payload i.e. the data after the IPv6 header and all
   the extension headers.

   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, to have it mean that the application will send down
   complete packets including the IPv4 header.  (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.)  We note that IPPROTO_RAW has no
   special meaning to an IPv6 raw socket (and the IANA currently






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


   reserves the value of 255 when used as a next-header field).


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

   An attempt to set IPV6_CHECKSUM for an ICMPv6 socket will fail.

   (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 multicast listener discovery messages.




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


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

   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



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


   filter pointed to by the second argument.

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



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


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


3.3.  ICMPv6 Verification of Received Packets

   The protocol stack will verify the ICMPv6 checksum and discard any
   packets with invalid checksums.

   An implementation might perform additional validity checks on the
   ICMP message content and discard malformed packets.  However, a
   portable application must not assume that such validity checks have
   been performed.