INTERNET-DRAFT                                    Samita Chakrabarti
Expires: Novemebr, 2005                           Erik Nordmark
                                                  Sun Microsystems, Inc.
                                                  May, 2005

                 Extension to Sockets API for Mobile IPv6
                 <draft-ietf-mip6-mipext-advapi-04.txt>



Status of this Memo

   This document is an Internet-Draft and is subject to all provisions
   of Section 3 of RFC 3667.  By submitting this Internet-Draft, each
   author represents that any applicable patent or other IPR claims of
   which he or she is aware have been or will be disclosed, and any of
   which he or she becomes aware will be disclosed, in accordance with
   Section 6 of BCP 79.

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

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

   This Internet Draft expires November, 2005.

Copyright Notice

   Copyright (C) The Internet Society (2005).  All Rights Reserved.

Abstract

   This document describes data structures and API support for Mobile
   IPv6 as an extension to Advanced Socket API for IPv6.

   Mobility Support in IPv6 introduces mobility protocol header
   for IPv6. It is expected that future Mobile IPv6 applications
   and implementations may need to access Mobility binding messages
   and Return Routability messages for diagnostic, packet accounting




Chakrabarti, Nordmark       Expires Novemebr, 2005              [Page 1]


INTERNET-DRAFT   Extension to Sockets API for MIPv6      May, 2005


   and local policy setting purposes. In order to provide portability
   for Mobile IP applications that use sockets under IPv6,
   standardization is needed for the Mobile IPv6 specific APIs.
   This document provides mechanism for API access to retrieve and set
   information for Mobility Header messages, Home Address destination
   options and type 2 Routing header extension headers. It discusses
   the common data structures and definitions that might be used by
   advanced Mobile IPv6 socket applications.


Table of Contents

    1. Introduction .............................................  3

    2. Common Structures and Definitions ........................  4

       2.1  The Mobility Header Data Structures .................  5
       2.2  Mobility Header Constants ...........................  8
       2.3  IPv6 Home Address Destination Option ................ 10
       2.4  Type 2 Routing Header ............................... 10
       2.5  ICMP Mobile IPv6 Messages ........................... 11
       2.6  IPv6 Neighbor Discovery Changes ..................... 12

    3. Access to Home Address Destination Option and Routing Headers
                                 ................................ 13
       3.1  Routing Header Access Functions ..................... 15
       3.2  Home Address Destination Option Access Functions .... 16

    4. Mobility Protocol Headers  ............................... 17

       4.1 Receiving and Sending Mobility Header Messages ....... 18

    5. Protocols File ........................................... 19

    6. IPv4-Mapped IPv6 Addresses ............................... 19

    7. Security Considerations .................................. 19

    8. IANA Considerations ...................................... 20

    9. References ............................................... 20

    10. Acknowledgement ......................................... 20

    11. Changes from last revisions ............................. 20

    12. Authors' Addresses ...................................... 21

    13. Full Copyright Statement ................................ 22





Chakrabarti, Nordmark       Expires November, 2005              [Page 2]


INTERNET-DRAFT   Extension to Sockets API for MIPv6      May, 2005


1.  Introduction

   Mobility Support in IPv6 [2] defines a new Mobility Protocol header,
   Home Address destination option and a new Routing Header type.
   It is expected that Mobile IPv6 user-level implementations and some
   applications will need to access and process these IPv6 extension
   headers. This document is an extension to existing Advanced Sockets
   API document [1]; it addresses the IPv6 Sockets API for Mobile IPv6
   protocol support.
   The applicability of this API mainly target user-level applications.
   However, some Mobile IPv6 implementations may take advantage of this
   API and implement part of the Mobile IPv6 protocol at the user-level.
   It is up to the implementors to architect which part of the Mobile
   IPv6 packet processing should be done at the user-level in order to
   meet the design needs of the particular platform and operating system.
   The target applications for this socket API is believed to be the
   debugging and diagnostic applications as well as some policy
   applications which would like to receive a copy of protocol
   information at the application layer.

   Note that user applications for transferring data between two
   systems may not need to be mobility aware. Future IPv6 mobility
   aware applications may use this socket API for per-packet
   information for further processing at the application layer
   program interface.


   This document can be divided into the following parts.

   1. Definitions of constants and structures for C programs that
      capture the Mobile IPv6 packet formats on the wire. A common
      definition of these is useful at least for packet snooping
      appplications. This is captured in section 2.

   2. Notes on how to use the IPv6 Advanced API to access Home Address
      options and type 2 Routing Headers. This is captured in
      section 3.

   3. Notes on how user-level applications can observe MH (Mobility
      Header) packets using raw sockets (in section 4). The IPv6 RAW
      socket interface described in this document, allows applications
      to receive  MH packets whether or not the systems MH processing
      takes place in the "kernel" or at the "user space".

   4. Suggested  name for /etc/protocols (in section 5).







Chakrabarti, Nordmark       Expires Novemebr, 2005              [Page 3]


INTERNET-DRAFT    Extensions to Sockets API for MIPv6    May, 2005


   The packet information along with access to the extension headers
   (Routing header 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 is in conformance with Advanced Sockets API for
   IPv6 [1].

   This document does not address application access to either the
   authentication header or the encapsulating security payload header.
   This document also does not address any API that might be necessary
   for Mobile Network [4] specific needs. Futhermore, it should be noted
   that this API document excludes discussion on application level API.
   It assumes that address selection socket API [5] takes care of
   selection of Care-of-address or home-address as the source address
   by the application, when source address selection is required due to
   the nature of the application.

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

   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.

   Data types 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).

   Once the API specification becomes mature and is deployed among
   implementations, it may be formally standardized by a more appropriate
   body, such as has been done with the Basic API [RFC-3493]. However,
   since this specification largely builds upon the advanced API
   [RFC3245], such standardization would make sense only if the advanced
   API was also standardized.


2.  Common Structures and Definitions


   This document assumes that it is the responsibility of system
   networking implementation or the user application to ensure that the
   fields in the protocol headers are in network byte order across API
   invocations.

   A new header file : <netinet/ip6mh.h>








Chakrabarti, Nordmark       Expires November, 2005              [Page 4]


INTERNET-DRAFT    Extension to Sockets API for MIPv6    May, 2005


2.1.  The Mobility Header Data Structures

2.1.1 The ip6_mh Structure

    The following structure is defined as a result of including
    <netinet/ip6mh.h>. This is fixed part of the Mobility Header.

    struct  ip6_mh {
        uint8_t    ip6mh_proto;   /* NO_NXTHDR by default */
        uint8_t    ip6mh_hdrlen;  /* Header Len in unit of 8 Octets
                                     excluding the first 8 Octets */
        uint8_t    ip6mh_type;    /* Type of Mobility Header */
        uint8_t    ip6mh_reserved;   /* Reserved */
        uint16_t   ip6mh_cksum;   /* Mobility Header Checksum */
        /* Followed by type specific messages */
    };



2.1.2  Binding Refresh Request Mobility Message

    struct  ip6_mh_binding_request {
        struct ip6_mh  ip6mhbr_hdr;
        uint16_t   ip6mhbr_reserved;
        /* Followed by optional Mobility Options */
    };




2.1.3  Home Address Test Init (HoTI) Message

     struct   ip6_mh_home_test_init {
        struct  ip6_mh  ip6mhhti_hdr;
        uint16_t        ip6mhhti_reserved;
        uint32_t        ip6mhhti_cookie[2]; /* 64 bit Cookie by MN */
        /* Followed by optional Mobility Options */
     };












Chakrabarti, Nordmark       Expires November, 2005              [Page 5]


INTERNET-DRAFT    Extension to Sockets API for MIPv6     May, 2005


2.1.4  Care-of Address Test Init (CoTI) Message

     struct   ip6_mh_careof_test_init {
        struct  ip6_mh  ip6mhcti_hdr;
        uint16_t        ip6mhcti_reserved;
        uint32_t        ip6mhcti_cookie[2]; /* 64 bit Cookie by MN */
        /* Followed by optional Mobility Options */
     };


2.1.5  Home Address Test (HOT) Message

     struct  ip6_mh_home_test {
        struct  ip6_mh  ip6mhht_hdr;
        uint16_t    ip6mhht_nonce_index;
        uint32_t    ip6mhht_cookie[2];    /* Cookie from HOTI msg */
        uint32_t    ip6mhht_keygen[2];  /* 64 Bit Key by CN */
        /* Followed by optional Mobility Options */
    };


2.1.6  Care Of Address Test (COT) Message

     struct  ip6_mh_careof_test {
        struct  ip6_mh  ip6mhct_hdr;
        uint16_t   ip6mhct_nonce_index;
        uint32_t   ip6mhct_cookie[2]; /* Cookie from COTI message */
        uint32_t   ip6mhct_keygen[2];  /* 64bit key by CN */
        /* Followed by optional Mobility Options */
     };


2.1.7  Binding Update Mobility Message

    struct ip6_mh_binding_update {
       struct ip6_mh ip6mhbu_hdr;
       uint16_t    ip6mhbu_seqno;      /* Sequence Number */
       uint16_t    ip6mhbu_flags;
       uint16_t    ip6mhbu_lifetime; /* Time in unit of 4 sec */
        /* Followed by optional Mobility Options */
    };

    /* Binding Update Flags, in network byte-order */
    #define IP6_MH_BU_ACK    0x8000  /* Request a binding ack */
    #define IP6_MH_BU_HOME   0x4000  /* Home Registration */
    #define IP6_MH_BU_LLOCAL 0x2000  /* Link-local compatibility */
    #define IP6_MH_BU_KEYM   0x1000  /* Key management mobility  */






Chakrabarti, Nordmark       Expires November, 2005              [Page 6]


INTERNET-DRAFT    Extension to Sockets API for MIPv6    May, 2005


2.1.8  Binding Acknowledgment Mobility Message


     struct  ip6_mh_binding_ack {
        struct ip6_mh  ip6mhba_hdr;
        uint8_t   ip6mhba_status;    /* Status code */
        uint8_t   ip6mhba_flags;
        uint16_t  ip6mhba_seqno;
        uint16_t  ip6mhba_lifetime;
        /* Followed by optional Mobility Options */
     };


    /* Binding Acknowledgement Flags */
    #define IP6_MH_BA_KEYM       0x80    /* Key management mobility */





2.1.9  Binding Error Mobility Message

     struct   ip6_mh_binding_error {
        struct ip6_mh   ip6mhbe_hdr;
        uint8_t        ip6mhbe_status;  /* Error Status */
        uint8_t        ip6mhbe_reserved;
        struct in6_addr ip6mhbe_homeaddr;
        /* Followed by optional Mobility Options */
      };




2.1.10  Mobility Option TLV data structure

       struct   ip6_mh_opt {
          uint8_t    ip6mhopt_type;   /* Option Type */
          uint8_t    ip6mhopt_len;    /* Option Length */
          /* Followed by variable length Option Data in bytes */
       };










Chakrabarti, Nordmark       Expires November, 2005              [Page 7]


INTERNET-DRAFT    Extension to Sockets API for MIPv6     May, 2005



2.1.11 Mobility Option Data Structures

2.1.11.1  Binding Refresh Advice

       struct ip6_mh_opt_refresh_advice {
           uint8_t  ip6mora_type;
           uint8_t  ip6mora_len;
           uint16_t ip6mora_interval; /* Refresh interval in 4 sec */
       };


2.1.11.2  Alternate Care-of Address

       struct ip6_mh_opt_altcoa {
           uint8_t ip6moa_type;
           uint8_t ip6moa_len;
           struct in6_addr ip6moa_addr; /* Alternate Care-of Address */
       };


2.1.11.3  Nonce Indices

        struct ip6_mh_opt_nonce_index {
            uint8_t ip6moni_type;
            uint8_t ip6moni_len;
            uint16_t ip6moni_home_nonce;
            uint16_t ip6moni_coa_nonce;
        };


2.1.11.4 Binding Authorization Data

        struct ip6_mh_opt_auth_data {
            uint8_t ip6moad_type;
            uint8_t ip6moad_len;
            uint8_t ip6moad_data[12];
        };



2.2  Mobility Header Constants


     IPv6 Next Header Value for Mobility:
     <netinet/in.h>

     #define IPPROTO_MH       135 /* IPv6 Mobility Header: IANA */





Chakrabarti, Nordmark       Expires November, 2005              [Page 8]


INTERNET-DRAFT    Extension to Sockets API for MIPv6     May, 2005



       Mobility Header Message Types:
       <netinet/ip6mh.h>

       #define IP6_MH_TYPE_BRR       0   /* Binding Refresh Request */
       #define IP6_MH_TYPE_HOTI      1   /* HOTI Message   */
       #define IP6_MH_TYPE_COTI      2   /* COTI Message  */
       #define IP6_MH_TYPE_HOT       3   /* HOT Message   */
       #define IP6_MH_TYPE_COT       4   /* COT Message  */
       #define IP6_MH_TYPE_BU        5   /* Binding Update */
       #define IP6_MH_TYPE_BACK      6   /* Binding ACK */
       #define IP6_MH_TYPE_BERROR    7   /* Binding Error */



       Mobility Header Message Option Types:
       <netinet/ip6mh.h>

       #define  IP6_MHOPT_PAD1       0x00  /* PAD1 */
       #define  IP6_MHOPT_PADN       0x01  /* PADN */
       #define  IP6_MHOPT_BREFRESH   0x02  /* Binding Refresh */
       #define  IP6_MHOPT_ALTCOA     0x03  /* Alternate COA */
       #define  IP6_MHOPT_NONCEID    0x04  /* Nonce Index */
       #define  IP6_MHOPT_BAUTH      0x05  /* Binding Auth Data */




      Status values accompanied with Mobility Binding Acknowledgement:
      <netinet/ip6mh.h>

       #define IP6_MH_BAS_ACCEPTED          0   /* BU accepted */
       #define IP6_MH_BAS_PRFX_DISCOV       1   /* Accepted, but prefix
                                                discovery Required */
       #define IP6_MH_BAS_UNSPECIFIED       128 /* Reason unspecified */
       #define IP6_MH_BAS_PROHIBIT          129 /* Administratively
                                                  prohibited */
       #define IP6_MH_BAS_INSUFFICIENT      130 /* Insufficient
                                                  resources */
       #define IP6_MH_BAS_HA_NOT_SUPPORTED  131 /* HA registration not
                                                  supported */
       #define IP6_MH_BAS_NOT_HOME_SUBNET   132  /* Not Home subnet */
       #define IP6_MH_BAS_NOT_HA            133  /* Not HA for this
                                                   mobile node */
       #define IP6_MH_BAS_DAD_FAILED        134  /* DAD failed */
       #define IP6_MH_BAS_SEQNO_BAD         135  /* Sequence number out
                                                   of range */





Chakrabarti, Nordmark       Expires Novemebr, 2005              [Page 9]


INTERNET-DRAFT    Extension to Sockets API for MIPv6     May, 2005


       #define IP6_MH_BAS_HOME_NI_EXPIRED   136  /* Expired Home nonce
                                                   index */
       #define IP6_MH_BAS_COA_NI_EXPIRED    137  /* Expired Care-of
                                                   nonce index */
       #define IP6_MH_BAS_NI_EXPIRED        138  /* Expired Nonce
                                                   Indices */
       #define IP6_MH_BAS_REG_NOT_ALLOWED   139  /* Registration type
                                                   change disallowed */


      Status values for the Binding Error mobility messages:
      <netinet/ip6mh.h>


      #define IP6_MH_BES_UNKNOWN_HAO    1 /* Unknown binding for HOA */
      #define IP6_MH_BES_UNKNOWN_MH     2 /* Unknown MH Type */


2.3.  IPv6 Home Address Destination Option

      <netinet/ip6.h>

      /* Home Address Destination Option */
      struct ip6_opt_home_address {
         uint8_t           ip6oha_type;
         uint8_t           ip6oha_len;
         uint8_t           ip6oha_addr[16];   /* Home Address */
      };

      Option Type Definition:

      #define IP6OPT_HOME_ADDRESS             0xc9    /* 11 0 01001 */



2.4  Type 2 Routing Header

     <netinet/ip6.h>

      /* Type 2 Routing header for Mobile IPv6 */
       struct ip6_rthdr2 {
         uint8_t  ip6r2_nxt;       /* next header */
         uint8_t  ip6r2_len;       /* length : always 2 */
         uint8_t  ip6r2_type;      /* always 2 */
         uint8_t  ip6r2_segleft;   /* segments left: always 1 */
         uint32_t ip6r2_reserved;  /* reserved field */
         struct in6_addr ip6r2_homeaddr;  /* Home Address */
       };





Chakrabarti, Nordmark       Expires November, 2005             [Page 10]


INTERNET-DRAFT    Extension to Sockets API for MIPv6     May, 2005


2.5  New ICMP Messages for Mobile IPv6

     ICMP message types and definitions for Mobile IPv6 are defined in
     <netinet/icmp6.h>

     #define MIP6_HA_DISCOVERY_REQUEST    144
     #define MIP6_HA_DISCOVERY_REPLY      145
     #define MIP6_PREFIX_SOLICIT          146
     #define MIP6_PREFIX_ADVERT           147


     The following data structures can be used for the ICMP message
     types discussed in section 6.5 through 6.8 in the base Mobile
     IPv6 [2] specification.

     struct mip6_dhaad_req {          /* Dynamic HA Address Discovery */
            struct  icmp6_hdr   mip6_dhreq_hdr;
     };

     #define  mip6_dhreq_type      mip6_dhreq_hdr.icmp6_type
     #define  mip6_dhreq_code      mip6_dhreq_hdr.icmp6_code
     #define  mip6_dhreq_cksum     mip6_dhreq_hdr.icmp6_cksum
     #define  mip6_dhreq_id        mip6_dhreq_hdr.icmp6_data16[0]
     #define  mip6_dhreq_reserved  mip6_dhreq_hdr.icmp6_data16[1]


     struct mip6_dhaad_rep {         /* HA Address Discovery Reply */
            struct icmp6_hdr   mip6_dhrep_hdr;
            /* Followed by Home Agent IPv6 addresses */
     };

     #define  mip6_dhrep_type      mip6_dhrep_hdr.icmp6_type
     #define  mip6_dhrep_code      mip6_dhrep_hdr.icmp6_code
     #define  mip6_dhrep_cksum     mip6_dhrep_hdr.icmp6_cksum
     #define  mip6_dhrep_id        mip6_dhrep_hdr.icmp6_data16[0]
     #define  mip6_dhrep_reserved  mip6_dhrep_hdr.icmp6_data16[1]


     struct mip6_prefix_solicit {   /* Mobile Prefix Solicitation */
            struct icmp6_hdr     mip6_ps_hdr;
     };

     #define  mip6_ps_type          mip6_ps_hdr.icmp6_type
     #define  mip6_ps_code          mip6_ps_hdr.icmp6_code
     #define  mip6_ps_cksum         mip6_ps_hdr.icmp6_cksum
     #define  mip6_ps_id            mip6_ps_hdr.icmp6_data16[0]
     #define  mip6_ps_reserved      mip6_ps_hdr.icmp6_data16[1]





Chakrabarti, Nordmark       Expires November, 2005             [Page 11]


INTERNET-DRAFT    Extension to Sockets API for MIPv6    May, 2005



     struct mip6_prefix_advert {    /* Mobile Prefix Adverisements */
            struct  icmp6_hdr   mip6_pa_hdr;
             /* Followed by one or more PI options */
     };

     #define  mip6_pa_type            mip6_pa_hdr.icmp6_type
     #define  mip6_pa_code            mip6_pa_hdr.icmp6_code
     #define  mip6_pa_cksum           mip6_pa_hdr.icmp6_cksum
     #define  mip6_pa_id              mip6_pa_hdr.icmp6_data16[0]
     #define  mip6_pa_flags_reserved  mip6_pa_hdr.icmp6_data16[1]

     #define  MIP6_PA_FLAG_MANAGED    0x8000
     #define  MIP6_PA_FLAG_OTHER      0x4000

     Prefix options are defined in IPv6 Advanced Socket API [1].
     Mobile IPv6 Base specification [2] describes the modified
     behavior in 'Modifications to IPv6 Neighbor Discovery' section.
     Prefix Options for Mobile IP are defined in the following section.


2.6  IPv6 Neighbor Discovery Changes

     IPv6 Neighbor Discovery changes are also defined in
     <netinet/icmp6.h>

     New 'Home Agent' flag in router advertisement:
     #define  ND_RA_FLAG_HOMEAGENT   0x20  /* Home Agent flag in RA */

     New Router flag with prefix information of the home agent:
     #define  ND_OPT_PI_FLAG_ROUTER  0x20  /* Router flag in PI */

     As per Mobile IPv6 specification [2] a Home Agent MUST include
     at least one prefix option with the Router Address (R) bit set.
     Advanced Socket API [1] defines data structure for prefix option
     as follows:

     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;
      };





Chakrabarti, Nordmark       Expires November, 2005             [Page 12]


INTERNET-DRAFT    Extension to Sockets API for MIPv6     May, 2005



     New advertisement interval option and home agent information
     options are defined in Mobile IPv6 [2] base specification.

     struct nd_opt_adv_interval {   /* Advertisement interval option */
        uint8_t        nd_opt_ai_type;
        uint8_t        nd_opt_ai_len;
        uint16_t       nd_opt_ai_reserved;
        uint32_t       nd_opt_ai_interval;
     };


     The option types  for the new Mobile IPv6 specific options:

     #define  ND_OPT_ADV_INTERVAL    7     /* Adv Interval Option  */
     #define  ND_OPT_HA_INFORMATION  8     /* HA Information option */

     struct nd_opt_homeagent_info {  /* Home Agent information */
        uint8_t        nd_opt_hai_type;
        uint8_t        nd_opt_hai_len;
        uint16_t       nd_opt_hai_reserved;
        uint16_t       nd_opt_hai_preference;
        uint16_t       nd_opt_hai_lifetime;
     };




3.  Access to Home Address Destination Option and Routing Headers

    Applications that need to be able to access home address destination
    option and routing header type 2 information should use the same
    mechanism defined in Advanced Sockets API for IPv6 in section 4.

    In order to receive Home Address destination option or Route Header
    Type 2 extension header, application must call setsockopt() to turn
    on the corresponding flag:

       int  on = 1;

       setsockopt(fd, IPPROTO_IPV6, IPV6_RECVRTHDR,    &on, sizeof(on));
       setsockopt(fd, IPPROTO_IPV6, IPV6_RECVDSTOPTS,  &on, sizeof(on));

    When any of these options are enabled, the corresponding data is
    returned as control information by recvmsg(), as one or more
    ancillary data objects. Receiving the above information for TCP
    applications is not defined in this document (see section 4.1 of
    Advanced Sockets API for IPv6 [1]).





Chakrabarti, Nordmark       Expires November, 2005             [Page 13]


INTERNET-DRAFT    Extension to Sockets API for MIPv6     May, 2005


    For sending Home Address destination option, ancillary data can be
    used to specify the option content for a single datagram. This
    only applies to datagram and raw sockets; not to TCP sockets.
    Advanced API [1] document restricts one IPV6_xxx ancillary data
    object for a particular extension header in the control buffer.
    Thus there would be a single ancillary data object for Home address
    destination option in a ancillary data buffer. If the kernel
    implementation supports this API, it is responsible for extracting
    the Home address destination option data object and placing it as
    destination option extension header in compliance with section
    6.3 of Mobile IPv6 [2] base specification.

    For TCP data packets with Home Address destination option may be
    used with "sticky" option for all transmitted packets. However,
    at this point, it is unknown why an application  would want to
    set Home Address option or Route Header Type 2 extension header
    along with its data packets as Mobile IPv6 protocol takes care of
    them transparently at the protocol stack.

    However, the following socket option parameters and cmsghdr fields
    may be used for sending.

       opt level/    optname/          optval/
       cmsg_level    cmsg_type         cmsg_data[]
       ------------  ------------      ------------------------
       IPPROTO_IPV6  IPV6_DSTOPTS      ip6_dest structure
       IPPROTO_IPV6  IPV6_RTHDR        ip6_rthdr structure


   Some IPv6 implementations may support "sticky" options [1] for IPv6
   destination option for datagram sockets.

   Behavior of legacy IPv6 socket applications:

   Applications, whether or not they implement this specification, that
   use the Advanced API mechanisms to receive Destination options or
   Routing headers, need to ignore or otherwise properly handle the Home
   Address destination option and the type 2 routing headers according
   to this API specifications.

3.1 Routing Header access functions

    While accessing Routing header Type 2 extension header, one MUST
    use type = 2 and segment = 1. The following existing functions
    defined in Advanced API for IPv6 Sockets [1] are supported
    for Mobile IPv6 applications for sending and receiving Routing
    Header Type 2 headers:






Chakrabarti, Nordmark       Expires November, 2005             [Page 14]


INTERNET-DRAFT    Extension to Sockets API for MIPv6    May, 2005


    For sending:

    size_t inet6_rth_space(int type, int segments);
    void *inet6_rth_init(void *bp, int bp_len, int type, int segments);
    int inet6_rth_add(void *bp, const struct in6_addr *addr);

    For receiving:

    int inet6_rth_segments(const void *bp);
    struct in6_addr *inet6_rth_getaddr(const void *bp, int index);

    NOTE: Reversing operation is not possible using Route Header Type 2
          extension header.

    Detail description and examples of accessing a IPv6 Routing Header
    are discussed in Advanced Sockets API for IPv6 [1].
    However, section 7 of Advanced API for IPv6 Sockets [1] indicates
    that multiple types of routing headers can be received as multiple
    ancillary data objects to the application (with cmsg_type set to
    IPV6_RTHDR). Currently there is no API functions defined to return
    the routing header type, hence this document defines a function
    for getting the type of the received routing header.

    int inet6_rth_gettype(const void *bp);

3.1.1 Content of Type 2 Routing Header

    It is assumed that no portable applications will send routing hader
    Type 2 ancillary data from application layer, since many
    implementations take care of that at the kernel layer and may not
    support API for sending routing header type 2. However, if any
    Mobile IPv6 implementation requires to send/process packets at the
    user level, it can use the API mentioned in section 3.1 and set
    value of routing header as the home-address as specified in [2].

    For user level applications that receive routing header type 2,
    inet6_rth_getaddr() returns the Care-Of-Address or the original
    destination address of the received packet. This is in compliance
    with the existing Routing header Type=0 processing for IPv6 [1].

    Thus on the receive side, the  socket application will always
    receive data packets at its original home-address.
    The implementations are responsible for processing the routing
    header type 2 packet as per Mobile IPv6 RFC [2], before passing
    the routing header type 2 information to the Socket API.








Chakrabarti, Nordmark       Expires November, 2005             [Page 15]


INTERNET-DRAFT    Extension to Sockets API for MIPv6    May, 2005


3.2  Home Address Destination Option access functions

   The application must enable the IPV6_RECVDSTOPTS socket option in
   order to receive the Home Address destination option:

       int  on = 1;
       setsockopt(fd, IPPROTO_IPV6, IPV6_RECVDSTOPTS, &on, sizeof(on));

   Each Destination option header is returned as one ancillary data
   object described by a cmsghdr structure with cmsg_level set to
   IPPROTO_IPV6 and cmsg_type set to IPV6_DSTOPTS.

   The receive side Home Address destination option is further
   processed by calling the inet6_opt_next(), inet6_opt_find(),
   and inet6_opt_get_value() functions as defined in Advanced API
   for IPv6 sockets [1].

   This document assumes that portable Mobile IPv6 applications will
   not send Home Address Destination Option from the application level,
   as many Mobile IPv6 implementations take care of sending Home Address
   option and routing header type 2 at the kernel. However, some
   embedded software implementations may require to implement the IPv6
   packet processing/sending at the user level; those implementations
   may choose to provide API spport for sending home-address option
   at the application layer. For API which support sending Home Address
   destination options, they  are normally constructed by using the
   inet6_opt_init(), inet6_opt_append(), inet6_opt_finish(), and
   inet6_opt_set_val() functions, described in Section 10 of Advanced
   sockets API for IPv6 [1].


3.2.1 Content of Home Address Destination option

   The received ancillary data object for Home Address destination
   option SHOULD contain the Care-Of-Address of the mobile node. It
   is assumed that the initial processing of the Home Address
   destination option will verify the validity of home-address as
   described in 6.3 and 9.5 of Mobile IPv6 Specification [2] and
   swap the source address of the packet (COA) with the content of
   Home Address destination option.

   Note that whether or not these new APIs are used, the senders home
   address is contained in the source address (which is passed to the
   application using the socket-level functions recvfrom(), recvmsg(),
   accept() and getpeername()).  This is  necessary for:








Chakrabarti, Nordmark       Expires November, 2005             [Page 16]


INTERNET-DRAFT    Extension to Sockets API for MIPv6    May, 2005


           - maintaining consistency between simple user-level
             applications running between mobile nodes and the
             diagnostic applications on home-agent or on
             correspondent node, which use this API.

           - obtaining the COA address of the mobile node when
             Home Address destination option is used.

           - maintaining consistency of existing IPv6 Socket APIs
             and processing of Home Address destination option.

   If an implementation supports send-side Home Address destination
   API, then it must follow the same rule for data content as
   specified in Mobile IPv6 RFC [2] for sending home-address option.
   Thus the home-address option will contain the home-address and
   the implementation will use the care-of-address as the source
   address of the outgoing packet.



4.  Mobility Protocol Headers

   Mobile IPv6 [2] defines a new IPv6 protocol header to carry mobility
   messages between  Mobile Nodes, Home Agents and Correspondent Nodes.
   These protocol headers carry Mobile IPv6 Binding messages as well as
   Return Routability [2] messages. Currently the specification [2]
   does not allow transport packets (piggybacking) along with the
   mobility messages. Thus the mobility protocol header can be
   accessed through a IPv6 RAW socket. A IPv6 RAW socket that is opened
   for protocol IPPROTO_MH should always be able to see all the MH
   (Mobility Header) packets. It is possible that future applications
   may implement part of Mobile IPv6 signal processing at the
   application level. Having a RAW socket interface may also enable
   an application to execute the Return Routability protocol or other
   future authentication protocol involving mobility header at the user
   level.
















Chakrabarti, Nordmark       Expires November, 2005             [Page 17]


INTERNET-DRAFT    Extension to Sockets API for MIPv6    May, 2005


4.1 Receiving and Sending Mobility Header Messages

   This specification recommends IPv6 RAW sockets mechanism to send
   and receive Mobility Header (MH) packets. The behavior is similar to
   ICMPV6 processing, where kernel passes a copy of the mobility header
   packet to the receiving socket. Depending on the implementation
   kernel may process the mobility header as well in addition to passing
   the mobility header to the application.
   In order to comply with the restriction in Advanced Sockets API for
   IPv6 [1], applications should set IPV6_CHECKSUM socket option with
   IPPROTO_MH protocol RAW Sockets. A Mobile IPv6 implementation
   that supports Mobile IPv6 API, must implement Mobility Header
   API checksum calculation by default at the kernel for both incoming
   and outbound path. A Mobile IPv6 implementation must not return error
   on IPV6_CHECKSUM socket option setting, even if the socket option is
   a NO-OP function for that implementation because it verifies the
   checksum at the kernel level.  Mobility Header checksum procedure
   is described in Mobile IPv6 Protocol [2] specification.
   Again, it is recommended that the applications set the IPV6_CHECKSUM
   socket option along with the RAW sockets for IPPROTO_MH protocol,
   for application portability.


   As an example, a program that wants to send or receive mobility
   header protocol(MH), could open a socket as following:

     fd = socket(AF_INET6, SOCK_RAW, IPPROTO_MH);

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



  For example, if an implementation likes to handle HOTI/HOT and
  COTI/COT message processing, it can do so by using IPv6 RAW Sockets
  for IPPROTO_MH at the application layer.
  The same application may also set IPV6_RECVDSTOPTS socket option for
  receiving home-address option in a binding update [2] from the mobile
  node.












Chakrabarti, Nordmark       Expires November, 2005             [Page 18]


INTERNET-DRAFT    Extension to Sockets API for MIPv6     May, 2005


5.  Protocols File

   Many hosts provide the file /etc/protocols that contains the names
   of the various IP protocols and their protocol numbers. The protocol
   numbers are obtained through function getprotoXXX() functions.

   The following addition should be made to the /etc/protocols file,
   in addition to what is defined in section 2.4 of Advanced Sockets
   API for IPv6 [1].

   The protocol number for Mobility Header:
   (http://www.iana.org/assignments/protocol-numbers)

   ipv6-mh           135      # Mobility Protocol Header




6.  IPv4-Mapped IPv6 Addresses

    The various socket options and ancillary data specifications defined
    in this document apply only to true IPv6 sockets.  It is possible to
    create an IPv6 socket that actually sends and receives IPv4 packets,
    using IPv4-mapped IPv6 addresses, but the mapping of the options
    defined in this document to an IPv4 datagram is beyond the scope of
    this document.


7.  Security Considerations

   The setting of Home Address Destination option and Route Header
   Type 2 IPV6_RTHDR socket option may not be allowed at the
   application level in order to prevent denial-of-service attacks
   or man in the middle attacks by hackers.
   Sending and receiving of mobility header messages are possible by
   IPv6 RAW sockets. Thus it is assumed that this operation is only
   possible by priviledged users. However, this API does not prevent
   the existing security threat from a hacker by sending bogus mobility
   header or other IPv6 packets using Home Address option and Type 2
   Routing Header extension.













Chakrabarti, Nordmark       Expires November, 2005             [Page 19]


INTERNET-DRAFT    Extension to Sockets API for MIPv6     May, 2005



8. IANA Considerations

   This document does not define a new protocol. However, it uses
   Mobility Header Protocol for IPv6 to define an API for
   /etc/protocols file.
   (ref: http://www.iana.org/assignments/protocol-numbers)


9. References

Normative References:

[1]    Stevens, W. R, Thomas, M., Nordmark, E., Jinmei, T., "Advanced
           Sockets API for IPv6", RFC 3542, May 2003
           April 19, 2002.

[2]    Johnson, D., Perkins, C., Arkko, J., "Mobility Support in IPv6",
           RFC3775, June, 2004.

Informative References:

[3]    Deering, S., Hinden, R., "Internet Protocol, Version 6
           (IPv6), Specification", RFC 2460, Dec. 1998.

[4]    V. Devarapalli, R. Wakikawa, A. Petrescu, P. Thubert, "Network
       Mobility (NEMO) Basic Support Protocol", RFC3963, January, 2005

[5]    E. Nordmark, S. Chakrabarti, J. Laganier, "IPv6 Socket API for
       source address selection",
       draft-chakrabarti-ipv6-addrselect-api-01.txt, June, 2003 (work
       in progress)

10.  Acknowledgement

   Thanks to Brian Haley for the thorough review of this draft and many
   helpful comments. Keiichi Shima, Alexandru Petrescu, Ryuji Wakikawa,
   Vijay Devarapalli, Jim Bound, Suvidh Mathur, Karen Nielsen, Mark
   Borst, Vladislav Yasevich and other mobile-ip working group members
   provided valuable input. Antti Tuominen suggested the routing header
   type function for this API document.



11. Changes from last revisions


  Version 04 changes:
  * Addressed Last call comment remaining issues and Area Director
    review comments

  Version 03 changes:
  * Modified new ICMPv6 type definition values to match RFC3775.







Chakrabarti, Nordmark       Expires November, 2005             [Page 20]


INTERNET-DRAFT    Extension to Sockets API for MIPv6     May, 2005


  Version 02 changes:
  * Added section 3.1.1 and 3.2.1 to clarify content of routing header
    type 2 and destination options.

  * Clarified existing socket application behavior in section 3.

  * Updated introduction to clarify scope of the applications wrt
    this API

  * Added IANA section and Full Copyright statement and internet
    draft boiler plate

  * Updated acknowledgement section and fixed typo etc.

  The following changes were made in 01 version per feedback from the
  implementors at Connectathon 2004.

  * Section 2.1.11.2 now  defines alternate COA address data structure
    as struct in6_addr for consistency. It was defined as 16 unit
    of bytes.

  * Added Binding Update Authdata of 12 bytes in the
    struct ip6_mh_opt_auth_data

  * Added a new function inet6_rth_gettype() in section 3.1 in order
    to distinguish routing header type 2 ancillary data items from
    type 0 routing header ancillary data items on the receive side.

  * Updated the Acknowledgement and Authors' address section




12.  Authors' Addresses


    Samita Chakrabarti
    Sun Microsystems, Inc.
    4150 Network Circle, UMPK16-157
    Santa Clara, CA 95054, USA
    Email: samita.chakrabarti@Sun.com


    Erik Nordmark
    Sun Microsystems, Inc.
    4150 Network Circle, UMPK17-308
    Santa Clara, CA 95054, USA
    Email: Erik.Nordmark@sun.com







Chakrabarti, Nordmark       Expires November, 2005             [Page 21]


INTERNET-DRAFT    Extension to Sockets API for MIPv6     May, 2005



13. Full Copyright Statement

   Copyright (C) The Internet Society (2005).  This document is subject
   to the rights, licenses and restrictions contained in BCP 78, and
   except as set forth therein, the authors retain all their rights.

   This document and the information contained herein are provided on an
   "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
   OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
   ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
   INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
   INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
   WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Intellectual Property

   The IETF takes no position regarding the validity or scope of any
   Intellectual Property Rights or other rights that might be claimed to
   pertain to the implementation or use of the technology described in
   this document or the extent to which any license under such rights
   might or might not be available; nor does it represent that it has
   made any independent effort to identify any such rights.  Information
   on the procedures with respect to rights in RFC documents can be
   found in BCP 78 and BCP 79.

   Copies of IPR disclosures made to the IETF Secretariat and any
   assurances of licenses to be made available, or the result of an
   attempt made to obtain a general license or permission for the use of
   such proprietary rights by implementers or users of this
   specification can be obtained from the IETF on-line IPR repository at
   http://www.ietf.org/ipr.

   The IETF invites any interested party to bring to its attention any
   copyrights, patents or patent applications, or other proprietary
   rights that may cover technology that may be required to implement
   this standard.  Please address the information to the IETF at ietf-
   ipr@ietf.org.

Acknowledgement

   Funding for the RFC Editor function is currently provided by the
   Internet Society.










Chakrabarti, Nordmark       Expires November, 2005             [Page 22]