Network Working Group M. Borst Internet-Draft B. Silverajan Expires: March 2, 2005 Tampere University of Technology September 2004 Mobile IPv6 Application API draft-borst-mip6api-00.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 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 will expire on March 2, 2005. Copyright Notice Copyright (C) The Internet Society (2004). Abstract By design, Mobile IPv6 does not provide movement information to higher layers or applications. However, new breeds of location-sensitive applications and technologies would benefit from having access to such information. This document outlines how the knowledge of mobility can be usefully harnessed by applications which reside in a mobile node as well as a correspondent node. It then defines an application-level API to fulfill those needs. Borst & Silverajan Expires March 2, 2005 [Page 1] Internet-Draft Mobile IPv6 Application API September 2004 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Use cases . . . . . . . . . . . . . . . . . . . . . . . . . . 3 2.1 Localised Service Discovery . . . . . . . . . . . . . . . 3 2.2 Multicast Group Rejoin . . . . . . . . . . . . . . . . . . 3 2.3 Adaptive TCP Congestion Control . . . . . . . . . . . . . 4 2.4 Policy Applications . . . . . . . . . . . . . . . . . . . 4 2.5 Location Tracking . . . . . . . . . . . . . . . . . . . . 4 2.6 Location-based services . . . . . . . . . . . . . . . . . 5 2.7 Overlay, P2P and Self-Organising Networks . . . . . . . . 5 3. Goals and Requirements . . . . . . . . . . . . . . . . . . . . 5 4. API definition . . . . . . . . . . . . . . . . . . . . . . . . 5 4.1 Data structures . . . . . . . . . . . . . . . . . . . . . 6 4.2 mip6_node_moved_bl() . . . . . . . . . . . . . . . . . . . 7 4.3 mip6_node_moved_nonbl() . . . . . . . . . . . . . . . . . 7 4.3.1 Registering callback instances . . . . . . . . . . . . 8 4.3.2 Unregistering callback instances . . . . . . . . . . . 9 4.4 mip6_am_i_mobile_node() . . . . . . . . . . . . . . . . . 9 4.5 mip6_get_network_context() . . . . . . . . . . . . . . . . 9 4.6 mip6_get_known_mobile_nodes() . . . . . . . . . . . . . . 10 4.7 IS_AT_HOME() . . . . . . . . . . . . . . . . . . . . . . . 10 4.8 mip6_get_binding() . . . . . . . . . . . . . . . . . . . . 10 4.9 mip6_binding_changed() . . . . . . . . . . . . . . . . . . 11 5. Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 6. Security Considerations . . . . . . . . . . . . . . . . . . . 12 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 13 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 14 Intellectual Property and Copyright Statements . . . . . . . . 15 Borst & Silverajan Expires March 2, 2005 [Page 2] Internet-Draft Mobile IPv6 Application API September 2004 1. Introduction Mobility Support for IPv6 [1] describes the adaptations to IPv6, needed for mobility. Its intent is to preserve existing transport connections during movement, and allow mobile nodes to be reachable using only their home IPv6 address, independent of their current points of attachment. Consequently, network layer mobility remains transparent to conventional applications at higher layers, thus eliminating the need to adapt them to mobile situations. On the other hand, several types of applications as described in section 2, would derive great benefit from obtaining local movement information of the mobile node they reside in, or remote movement information of other nodes they are communicating with. The Mobile IPv6 Application API defines a set of basic functions, that can be implemented as a library and effectively used by applications to obtain information about the network-layer mobility of nodes. The intent is to provide a consistent, simple and portable interface for applications without tying them to low-level socket details and header processing. 2. Use cases This section describes cases that show in what way applications can benefit from knowledge of mobility aspects, provided by the Mobile IPv6 Application API. 2.1 Localised Service Discovery When a mobile node moves to another network, it might want to rediscover essential services in its new environment. With movement notification, the mobile node could adjust its network profile settings for proper operation, such as finding and using the local DNS server or web proxy. This would involve triggering rediscovery for discovery mechanisms such as DHCPv6 [2] or mDNS [3]. The mobile node might also be interested in more advanced services, such as locating the printing services in the new network using SLP [4] or UPnP [5], or instant messaging applications such as iChat that use Rendezvous [6] for locating other local users. These services can also be dynamically discovered upon receiving movement notification information from the IP layer. 2.2 Multicast Group Rejoin When a multicast listener in a mobile node moves to another network, multicast group membership (especially global multicast) does not automatically follow. In order to continue receiving the multicast Borst & Silverajan Expires March 2, 2005 [Page 3] Internet-Draft Mobile IPv6 Application API September 2004 traffic, the mobile node has to issue an MLD Report packet. The listener would benefit from receiving movement notification to reduce the delay in joining the desired multicast groups on the new link to receive multicast traffic again and shorten the service disruption. 2.3 Adaptive TCP Congestion Control TCP congestion control is based on the assumption that the end-to-end path of a connection changes only insignificantly after connection establishment. Network layer mobility protocols that change a connection's point of attachment transparently to the transport layer may violate this assumption and cause TCP to make congestion control decisions based on invalid information. The LMDR [7] algorithm proposes a solution for congestion control behaviour in such situations. Although TCP does not normally use lower-layer information, it could use movement information to quickly adapt to congestion (or a lack of congestion) in the new path. 2.4 Policy Applications Low-level or user-defined policy applications may need to know whether nodes have moved, or need to know the current address configuration of a node. As low-level policy application, one can consider for instance the IPsec Internet Key Exchange [8] daemon that can run in userspace. It needs to know when a certain binding has changed, because security associations might have to change then. This requires the possibility to be notified when bindings change. An example of user-defined policy could be when a mobile node runs a local security policy application, such as a packet filtering firewall that uses IP address information. The rules of this firewall might have to be changed whenever a mobile node moves between trusted and untrusted networks, or between its home network and foreign networks, to match the new address configuration of the node. Other types of applications may also defer to user-defined policies for behaviour. An example would be adapting to a minimum of bandwidth usage in networks using a packet-based tariff model such as GPRS, and switching to maximum bandwidth usage in networks with a flat-fee structure such as home ADSL or cable networks. 2.5 Location Tracking An accounting application residing in a correspondent node might want to keep track of the movement of mobile nodes it is communicating Borst & Silverajan Expires March 2, 2005 [Page 4] Internet-Draft Mobile IPv6 Application API September 2004 with, for location management. Thus it needs a notification whenever a mobile node moves. 2.6 Location-based services Service providers might be interested in retrieving the current location of the mobile node they are communicating with, to be able to offer location-based services and content. The current care-of address can be used to determine the location of a mobile node. 2.7 Overlay, P2P and Self-Organising Networks Overlay networks such as application-level P2P networks, build a routing topology, the performance of which is dependent on efficient connectivity paths among nodes in the underlying network layer. Some overlay networks are also self-organising, taking into account changes by nodes entering or leaving the network. Optimal routing decisions in these networks can be achieved if movement information is received from the IP layer to reflect the changing network paths between nodes. 3. Goals and Requirements The following requirements can be specified for this API. o Does not require any special privileges, to be used by any application in user-space. o Does not disrupt or modify Mobile IPv6 signaling. o Be portable, platform independent and use POSIX-compliant sources to obtain its information as far as possible. o Abstracts from the Mobile IPv6 low-level details. Shields applications from Mobile IPv6 signaling and other details, and exports an easy-to-use API for information retrieval. 4. API definition As some functions discuss movement, the concept of movement has to be defined. For the purpose of this document, movement is defined as the moment that a binding is acknowledged. In case of a mobile node, this is the moment that the BACK from the home agent is received. In case of a home agent and correspondent node, it is the moment that the BACK is sent to the mobile node. First the data structures will be presented, then the functions. Borst & Silverajan Expires March 2, 2005 [Page 5] Internet-Draft Mobile IPv6 Application API September 2004 4.1 Data structures A mobile node can be identified by the following parameters: o home address o home address interface index o care-of address o care-of address interface index Therefore, the following structure is defined: struct mobile_node { struct in6_addr ho_addr; int ho_if; struct in6_addr co_addr; int co_if; } A binding is used for both Binding Updates and Binding Cache entries, and is defined by the following parameters: o home address o care-of address o correspondent node address o virtual interface identifier o physical interface identifier o type of binding: * Binding Update List Entry (BULE) (MN) * Binding Cache Entry (BCE) (MN, CN, HA) o type of event: * no event * binding added * binding changed * binding deleted The virtual interface identifier refers to the tunnel between mobile node and home agent. On a mobile node it is associated with the home address. On a home agent it is associated with the home address of the mobile node. On a correspondent node it is not used. The physical interface identifier refers to the 'real' interface used ('real' referring to the fact that it doesn't actually have to be a physical interface; a virtual interface such as a VPN interface is also valid here). On a mobile node it is the interface associated with the care-of address. On a correspondent node and home agent it is the interface used to communicate with the mobile node. Borst & Silverajan Expires March 2, 2005 [Page 6] Internet-Draft Mobile IPv6 Application API September 2004 The structure used to implement a binding is: struct mip6_binding { struct in6_addr ho_addr; struct in6_addr co_addr; struct in6_addr cn_addr; int virt_if; int phys_if; enum binding_type {BULE, BCE} type; enum binding_event {NONE, ADD, CHANGE, DELETE} event; } 4.2 mip6_node_moved_bl() This is a blocking mode function that provides a notification when a mobile node has moved. When the function mip6_node_moved_bl() is called, it will block and only return when either the specified mobile node has moved, or the specified time-out period expires. int mip6_node_moved_bl( bool local_node, unsigned int timeout_ms, struct mobile_node *mn ) The parameter local_node indicates whether notifications are requested only for the movement of the local node, or for any other mobile node that is known to have moved. The parameter timeout_ms indicates a timeout, specified in milliseconds. The parameter mn is a pointer to a structure provided by the calling application, containing information about the mobile node that has moved. On return from the function, the field mn->home_address will be set to the home address of the mobile node that moved and the field mn->co_addr will be filled with the current care-of address. The return value of the function is zero if a timeout has occurred, a positive value on movement, or a negative value on error. 4.3 mip6_node_moved_nonbl() This is a non-blocking mode function which also provides a notification when a mobile node has moved. Borst & Silverajan Expires March 2, 2005 [Page 7] Internet-Draft Mobile IPv6 Application API September 2004 When the function mip6_node_moved_nonbl() is called, it accepts a callback function, and returns immediately. Upon movement of the mobile node, it invokes the callback function. int mip6_node_moved_nonbl( bool local_node, bool registration, void *cb_parameter, int (*callback)( struct mobile_node mn, void *cb_parameter) ) The parameter local_node indicates whether notifications are requested only for the movement of the local node, or notifications for any other node that is known to have moved. The parameter registration indicates whether the provided callback instance is to be registered or unregistered. A value of true means registration, false means unregistration. The parameter cb_parameter is a void pointer that can be used to store context information from the calling application in case of a non-blocking call. This parameter will be passed back unchanged to the callback function. The final parameter is the callback function which the application has to provide. The callback will be invoked upon movement of the specified mobile node. The callback function has to accept two arguments: the mobile_node structure that contains the movement information, and the cb_parameter that was given during registration. The callback function is called each time upon movement, until it is unregistered. (Please note: For brevity, we subsequently refer to callback instances, which simply refers to callback functions and their associated cb_parameters.) The function returns zero on success, a negative value on error. Possible errors are: callback function not registered (during unregistration). 4.3.1 Registering callback instances Registration is performed by calling mip6_notify_movement_nonbl(), setting the parameter registration to true, and providing a callback instance. Multiple callback instances can be registered at the same time. For example, separate callbacks can be specified for movement Borst & Silverajan Expires March 2, 2005 [Page 8] Internet-Draft Mobile IPv6 Application API September 2004 of the local node and for movement of any other node. Several callback functions with different cb_parameter values can also be specified for the same mobile node. 4.3.2 Unregistering callback instances A callback instance is unregistered using mip6_notify_movement_nonbl(), setting the parameter registration to false and providing exactly the same callback instance as was given during registration. When the callback instance is set to NULL and NULL, all registered callback instances are unregistered. 4.4 mip6_am_i_mobile_node() Applications can use this function to query whether the local node is configured to be a mobile node or not. Currently, an application has no way to determine this information, although Mobile IPv6 stack implementations possess this information in their configurations. bool mip6_am_i_mobile_node( void ) The function returns true when the node is mobile, and false otherwise. 4.5 mip6_get_network_context() This function provides the current network context of a specified mobile node's home address. int mip6_get_network_context( struct in6_addr *ho_addr, struct mobile_node **mn) The mobile node's home address is specified by the caller in ho_addr, and its current care-of address will be returned, indicating also to which interface these addresses are coupled. In this case the array **mn contains only one struct. If the value of ho_addr is 0::0, then the local node's home addresses and care-of addresses will be returned. One home address can have multiple care-of addresses associated with it. This will result in multiple entries with the same home address and different care-of addresses. They will be stored in the array **mn. In this case the first entry in the array will contain the primary care-of address. The result will be stored in an array of mobile_node structures Borst & Silverajan Expires March 2, 2005 [Page 9] Internet-Draft Mobile IPv6 Application API September 2004 allocated by the API. The application is responsible for freeing the used memory. The return value indicates the amount of structs in the array. 4.6 mip6_get_known_mobile_nodes() This function provides a list of other known mobile nodes by the local node. This list reflects the contents of the local node's Binding Cache, containing the entries of all mobile nodes that have sent a Binding Update to this node. int mip6_get_known_mobile_nodes( struct mobile_node **mn_list) The function allocates the necessary memory itself, but the caller is responsible for freeing it. The list of returned mobile nodes contains both their home and care-of addresses. The return value is the amount of structs in the array. 4.7 IS_AT_HOME() This is a macro that can be used to verify if a mobile node is in its home network. bool IS_AT_HOME(struct mobile_node *mn) The mobile node to be queried has to be passed in the mn parameter. It probably has to be filled first with mip6_get_network_context(). This macro returns true when the mobile node is at home, and false when it is not. It will not change the contents of mn. 4.8 mip6_get_binding() To retrieve bindings from either the Binding Update List (MN) or the Binding Cache (all), the function get_binding() can be used. It is defined as follows: int mip6_get_binding( struct mip6_binding *binding ) The fields binding->ho_addr and binding->cn_addr specify which binding is requested. In mobile node operations, there are two cases: retrieving either a BULE or a BCE. To retrieve a BULE, the field ho_addr has to be set to an own home address. The field cn_addr has to be set to the address of the cn of which the binding is requested. To retrieve a BCE, the field cn_addr has to be set to an own address (care-of or home). The field ho_addr has to be set to Borst & Silverajan Expires March 2, 2005 [Page 10] Internet-Draft Mobile IPv6 Application API September 2004 the address of the MN of which the binding is needed. This gives the following matrix when two MNs are involved, assuming the call happens on MN-1: +------+--------------+-------------------+ | | ho_addr | cn_addr | +------+--------------+-------------------+ | BULE | MN-1 ho_addr | MN-2 ho_addr | | BCE | MN-2 ho_addr | MN-1 [ho/co]_addr | +------+--------------+-------------------+ For CN and HA operations, there is only one case: retrieving a BCE. To retrieve a BCE, the field cn_addr has to be set to an own address. The field ha_addr has to be set to the home address of the MN of which the binding is requested. The field virt_if is not used on CN operations, so will be set to 0. On MN and HA operations, it will be set to the ifindex of the tunnel. The field phys_if will be set to the real interface used to communicate with the requested node. The field type will be set according to the type of the entry (BULE or BCE). The field event will be set to NONE. A return value of 0 indicates success. Possible error values: binding not found. 4.9 mip6_binding_changed() Analogous to the way movement notifications can be received, also binding changes can be received. A change of binding can be either addition, change or deletion of a binding. The notifications can be filtered based on home address and correspondent node address. It might seem that the functions for node movement are redundant when this function is available. The difference is that the node movement functions provide a higher-level interface, which doesn't deal with bindings. Therefore also these movement functions are provided. For now, only a non-blocking functionality is defined. Basically the way it works is the same as mip6_node_moved_nonbl(). The function is defined as follows: Borst & Silverajan Expires March 2, 2005 [Page 11] Internet-Draft Mobile IPv6 Application API September 2004 int mip6_binding_changed( bool registration, struct in6_addr *ho_addr, struct in6_addr *cn_addr, void *cb_parameter, int (*callback) ( struct mip6_binding b, void *cb_parameter) ) The callback system works the same as for mip6_node_moved_nonbl(), except that it uses a struct binding instead of a struct mobile_node as parameter for the callback function. Two parameters are added: ho_addr and cn_addr. This allows filtering on home address and correspondent node address. A value of 0::0 for any of them means a wildcard, which disables filtering on that field. The filtering enables applications to only receive notifications for the change of bindings of nodes that they are actually communicating with. The filtering only applies to changes and deletions of bindings. Binding additions are not filtered, so an application has to register for unfiltered notifications to know of new bindings. Possible errors include: home address not known, correspondent node address not known. 5. Notes Some anticipated Frequently Asked Questions: o How to get a list of all home agents that are in use by the mobile node (MN) (TBD) o How to get a list of all own home addresses. (MN) (use mip6_get_network_context() with ho_addr = 0::0) o How to get a list of all own care-of addresses. (MN) (use mip6_get_network_context() with ho_addr = 0::0) o How to get a list of all own addresses on a given link. (MN) (use mip6_get_network_context() with ho_addr = 0::0, sort on ho_if or co_if) 6. Security Considerations The API defined in this draft does not provide any way to control or modify the operation of Mobile IPv6. It is meant for information retrieval only. Thus it does not need any special privileges to run. Borst & Silverajan Expires March 2, 2005 [Page 12] Internet-Draft Mobile IPv6 Application API September 2004 7. Acknowledgements We gratefully acknowledge the work of Aki Yokote, Alper Yegin, Muhammad Mukarram Bin Tariq, Guangrui Fu, Carl Williams and Atsushi Takeshita, who wrote the now expired Internet Draft Mobile IP API [9] (draft-yokote-mobileip-api-02.txt). Their document proved invaluable in beginning and developing the main ideas in our work. We would like to thank the people from MIPL, Henrik Petander and Ville Nuorvala, who have provided extensive feedback and lots of clarification, resulting in inclusion of the binding-related functionality and multi-homing issues. We also thank Jarmo Harju for his review of the draft. 8 References [1] Johnson, D., Perkins, C. and J. Arkko, "Mobility Support in IPv6", RFC 3775, June 2004. [2] Droms, R., Bound, J., Volz, B., Lemon, T., Perkins, C. and M. Carney, "Dynamic Host Configuration Protocol for IPv6 (DHCPv6)", RFC 3315, July 2003. [3] Cheshire, S. and M. Krochmal, "Multicast DNS. draft-cheshire-dnsext-multicastdns-04", February 2004. [4] Guttman, E., Perkins, C., Veizades, J. and M. Day, "Service Location Protocol, Version 2", RFC 2608, June 1999. [5] UPnP Forum, "UPnP DeviceType: Printer Device Template Version 1.01", August 2002. [6] Apple Computer, Inc., "Rendezvous, http://developer.apple.com/macosx/rendezvous/index.htm". [7] Swami, Y., Le, K. and W. Eddy, "Lightweight Mobility Detection and Response (LMDR) Algorithm for TCP, draft-swami-tcp-lmdr-04", August 2004. [8] Harkins, D. and D. Carrel, "The Internet Key Exchange (IKE)", RFC 2409, November 1998. [9] Yegin, A., Tariq, M., Yokote, A., Fu, G., Williams, C. and A. Takeshita, "Mobile IP API. draft-yokote-mobileip-api-02", June 2003. Borst & Silverajan Expires March 2, 2005 [Page 13] Internet-Draft Mobile IPv6 Application API September 2004 Authors' Addresses Mark W. Borst Tampere University of Technology Korkeakoulunkatu 1 33720 Tampere Finland EMail: mark@borst.org Bilhanan Silverajan Tampere University of Technology Korkeakoulunkatu 1 33720 Tampere Finland EMail: Bilhanan.Silverajan@tut.fi Borst & Silverajan Expires March 2, 2005 [Page 14] Internet-Draft Mobile IPv6 Application API September 2004 Intellectual Property Statement 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. Disclaimer of Validity 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. 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. Acknowledgment Funding for the RFC Editor function is currently provided by the Internet Society. Borst & Silverajan Expires March 2, 2005 [Page 15] 05