draft-ietf-ipngwg-rfc2292bis-02.txt

bind-3.2.

   The packet information along with access to the extension headers
   (Routing header, Hop-by-Hop options, and Destination options) 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 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.

   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 protocol headers are required, along with
   common constant definitions for the structure members.

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

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

   When an include file is specified, that include file is allowed to



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


   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; /* 4 bits version, 8 bits TC, 20 bits 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, top 4 bits tclass */
         } 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
       #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.



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


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

       /*
        * Generic extension header structure used by many extension headers.
        * Note that not all headers have this format. E.g. the fragmentation
        * header is different.
        */
       struct ip6_ext {
         uint8_t  ip6e_nxt;        /* next header */
         uint8_t  ip6e_len;        /* length in units of 8 octets */
       };

       /* Hop-by-Hop options header */
       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 */
       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 {
         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 */



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


         uint8_t  ip6r0_len;       /* length in units of 8 octets */
         uint8_t  ip6r0_type;      /* always zero */
         uint8_t  ip6r0_segleft;   /* segments left */
         uint32_t ip6r0_reserved;  /* reserved field */
           /* followed by up to 127 struct in6_addr */
       };

       /* 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



2.1.3.  IPv6 Options

   Eleven options are defined for IPv6 at the time of writing this
   document.  We define structures for all except the unspecified EID
   option.  The following structures are defined as a result of
   including <netinet/ip6.h>.

       /* IPv6 options */
       struct ip6_opt {
         uint8_t  ip6o_type;
         uint8_t  ip6o_len;
       };

       /*
        * The high-order 3 bits of the option type define the behavior
        * when processing an unknown option and whether or not the option
        * content changes in flight.
        */
       #define IP6OPT_TYPE(o)        ((o) & 0xc0)
       #define IP6OPT_TYPE_SKIP      0x00
       #define IP6OPT_TYPE_DISCARD   0x40



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


       #define IP6OPT_TYPE_FORCEICMP 0x80
       #define IP6OPT_TYPE_ICMP      0xc0
       #define IP6OPT_MUTABLE        0x20

       #define IP6OPT_PAD1           0x00  /* 00 0 00000 */
       #define IP6OPT_PADN           0x01  /* 00 0 00001 */
       #define IP6OPT_JUMBO          0xc2  /* 11 0 00010 = 194 */
       #define IP6OPT_NSAP_ADDR      0xc3  /* 11 0 00011 */
       #define IP6OPT_TUNNEL_LIMIT   0x04  /* 00 0 00100 */
       #define IP6OPT_ROUTER_ALERT   0x05  /* 00 0 00101 */
       #define IP6OPT_BINDING_UPDATE 0xc6  /* 11 0 00110 */
       #define IP6OPT_BINDING_ACK    0x07  /* 00 0 00111 */
       #define IP6OPT_BINDING_REQ    0x08  /* 00 0 01000 */
       #define IP6OPT_HOME_ADDRESS   0xc9  /* 11 0 01001 */
       #define IP6OPT_EID            0x8a  /* 10 0 01010 */

       /* Jumbo Payload Option */
       struct ip6_opt_jumbo {
         uint8_t  ip6oj_type;
         uint8_t  ip6oj_len;
         uint8_t  ip6oj_jumbo_len[4];
       };
       #define IP6OPT_JUMBO_LEN   6

       /* NSAP Address Option */
       struct ip6_opt_nsap {
         uint8_t  ip6on_type;
         uint8_t  ip6on_len;
         uint8_t  ip6on_src_nsap_len;
         uint8_t  ip6on_dst_nsap_len;
           /* followed by source NSAP */
           /* followed by destination NSAP */
       };

       /* Tunnel Limit Option */
       struct ip6_opt_tunnel {
         uint8_t  ip6ot_type;
         uint8_t  ip6ot_len;
         uint8_t  ip6ot_encap_limit;
       };

       /* Router Alert Option */
       struct ip6_opt_router {
         uint8_t  ip6or_type;
         uint8_t  ip6or_len;
         uint8_t  ip6or_value[2];
       };




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


       /* Router alert values (in network byte order) */
       #ifdef _BIG_ENDIAN
       #define IP6_ALERT_MLD      0x0000
       #define IP6_ALERT_RSVP     0x0001
       #define  IP6_ALERT_AN      0x0002
       #else
       #define IP6_ALERT_MLD      0x0000
       #define IP6_ALERT_RSVP     0x0100
       #define IP6_ALERT_AN       0x0200
       #endif

       /* Binding Update Option */
       struct ip6_opt_binding_update {
         uint8_t  ip6ou_type;
         uint8_t  ip6ou_len;
         uint8_t  ip6ou_flags;
         uint8_t  ip6ou_prefixlen;
         uint8_t  ip6ou_seqno[2];
         uint8_t  ip6ou_lifetime[4];
         uint8_t  ip6ou_coa[16];        /* Optional based on flags */
           /* followed by sub-options */
       };

       /* Binding Update Flags */
       #define IP6_BUF_ACK        0x80  /* Request a binding ack */
       #define IP6_BUF_HOME       0x40  /* Home Registration */
       #define IP6_BUF_COA        0x20  /* Care-of-address present in option */
       #define IP6_BUF_ROUTER     0x10  /* Sending mobile node is a router */

       /* Binding Ack Option */
       struct ip6_opt_binding_ack {
         uint8_t  ip6oa_type;
         uint8_t  ip6oa_len;
         uint8_t  ip6oa_status;
         uint8_t  ip6oa_seqno[2];
         uint8_t  ip6oa_lifetime[4];
         uint8_t  ip6oa_refresh[4];
           /* followed by sub-options */
       };

       /* Binding Request Option */
       struct ip6_opt_binding_request {
         uint8_t  ip6or_type;
         uint8_t  ip6or_len;
           /* followed by sub-options */
       };

       /* Home Address Option */



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


       struct ip6_opt_home_address {
         uint8_t  ip6oh_type;
         uint8_t  ip6oh_len;
         uint8_t  ip6oh_addr[16];    /* Home Address */
           /* followed by sub-options */
       };