INTERNET-DRAFT Samita Chakrabarti Expires: January, 2005 Erik Nordmark Sun Microsystems, Inc. July, 2004 Extension to Sockets API for Mobile IPv6 Status of this Memo By submitting this Internet-Draft, I certify that any applicable patent or other IPR claims of which I am aware have been disclosed, and any of which I become aware will be disclosed, in accordance with RFC 3668. 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.txt The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. This Internet Draft expires January, 2005. Copyright Notice Copyright (C) The Internet Society (2004). 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 Janyary, 2005 [Page 1] INTERNET-DRAFT Extension to Sockets API for MIPv6 July, 2004 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 January, 2005 [Page 2] INTERNET-DRAFT Extension to Sockets API for MIPv6 July, 2004 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 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). It is anticipated that Mobile IPv6 will be used widely from mobile devices to Server and Routing platforms. Thus it is useful to have a standard API for portability of Mobile IPv6 applications on a wide variety of platforms and operating systems. Chakrabarti, Nordmark Expires January, 2005 [Page 3] INTERNET-DRAFT Extensions to Sockets API for MIPv6 July, 2004 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. 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). This document provides guidelines on Mobile IPv6 socket applications and believes that some other appropriate standardization body will standardize the APIs along with other IPv6 advanced socket APIs. 2. Common Structures and Definitions 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(). A new header file : Chakrabarti, Nordmark Expires January, 2005 [Page 4] INTERNET-DRAFT Extension to Sockets API for MIPv6 July, 2004 2.1. The Mobility Header Data Structures 2.1.1 The ip6_mh Structure The following structure is defined as a result of including . 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 January, 2005 [Page 5] INTERNET-DRAFT Extension to Sockets API for MIPv6 July, 2004 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 ip6mht_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 January, 2005 [Page 6] INTERNET-DRAFT Extension to Sockets API for MIPv6 July, 2004 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 January, 2005 [Page 7] INTERNET-DRAFT Extension to Sockets API for MIPv6 July, 2004 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: #define IPPROTO_MH 135 /* IPv6 Mobility Header: IANA */ Chakrabarti, Nordmark Expires January, 2005 [Page 8] INTERNET-DRAFT Extension to Sockets API for MIPv6 July, 2004 Mobility Header Message Types: #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: #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: #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 January, 2005 [Page 9] INTERNET-DRAFT Extension to Sockets API for MIPv6 July, 2004 #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: #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 /* 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 /* 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 January, 2005 [Page 10] INTERNET-DRAFT Extension to Sockets API for MIPv6 July, 2004 2.5 New ICMP Messages for Mobile IPv6 ICMP message types and definitions for Mobile IPv6 are defined in #define MIP6_HA_DISCOVERY_REQUEST 150 #define MIP6_HA_DISCOVERY_REPLY 151 #define MIP6_PREFIX_SOLICIT 152 #define MIP6_PREFIX_ADVERT 153 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 January, 2005 [Page 11] INTERNET-DRAFT Extension to Sockets API for MIPv6 July, 2004 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 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 Rouer 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 January, 2005 [Page 12] INTERNET-DRAFT Extension to Sockets API for MIPv6 July, 2004 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 January, 2005 [Page 13] INTERNET-DRAFT Extension to Sockets API for MIPv6 July, 2004 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: Mobile IPv6 un-aware applications or existing IPv6 socket applications that do not know about the new routing header type 2 and Home Address destination option, SHOULD ignore these new routing header type and Home Address destination option upon receipt of them. 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 January, 2005 [Page 14] INTERNET-DRAFT Extension to Sockets API for MIPv6 July, 2004 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 Adavanced 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 Routing Header Type 2 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 pakcets 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 January, 2005 [Page 15] INTERNET-DRAFT Extension to Sockets API for MIPv6 July, 2004 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. All portable Mobile IPv6 aware applications MUST receive the home-address as source address of the incoming packet from the socket-level functions like recvfrom(), recvmsg(), accept() and getpeername(). This is necessary for: Chakrabarti, Nordmark Expires January, 2005 [Page 16] INTERNET-DRAFT Extension to Sockets API for MIPv6 July, 2004 - 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 January, 2005 [Page 17] INTERNET-DRAFT Extension to Sockets API for MIPv6 July, 2004 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 January, 2005 [Page 18] INTERNET-DRAFT Extension to Sockets API for MIPv6 July, 2004 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 same rule applies as described in section 13 of Advanced Sockets API for IPv6 [1]. Thus processing of IPv4-mapped IPv6 addresses for the Mobile IPv6 specific socket options are out of 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 January, 2005 [Page 19] INTERNET-DRAFT Extension to Sockets API for MIPv6 July, 2004 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. 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 Brost, 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 02 changes: * Added section 3.1.1 and 3.2.1 to clarify content of routing header type 2 and destination options. Chakrabarti, Nordmark Expires January, 2005 [Page 20] INTERNET-DRAFT Extension to Sockets API for MIPv6 July, 2004 * 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, UMPK17-203 Santa Clara, CA 95054, USA Email: samita.chakrabarti@Sun.com Erik Nordmark Sun Microsystems Laboratories 4150 Network Circle, UMPK17-308 Santa Clara, CA 95054, USA Email: Erik.Nordmark@sun.com Chakrabarti, Nordmark Expires January, 2005 [Page 21] INTERNET-DRAFT Extension to Sockets API for MIPv6 July, 2004 13. Full Copyright Statement Copyright (C) The Internet Society (2004). 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 January, 2005 [Page 22]