Internet Draft Alper E. Yegin Document: draft-yokote-mobileip-api-02.txt Muhammad M. Tariq Expires: December 2003 Aki Yokote Guangrui Fu Carl Williams Atsushi Takeshita June 2003 Mobile IP API Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. 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. Abstract The Mobile IP API provides an interface between the mobility management module and the application layer. Using Mobile IP API, applications can extract the mobility information that is already maintained by the mobility management module. This API provides mobility awareness for applications. This document describes application scenarios followed by requirements and definition of Mobile IP API. Application scenarios are example applications that can take advantage of awareness of the mobility information. Expires December 2003 [Page 1] Internet Draft Mobile IP API June 2003 Table of Contents 1. Introduction...................................................3 2. Key Words......................................................4 3. Usage Scenarios................................................4 4. Requirements...................................................5 4.1 Location awareness...........................................5 4.2 Movement awareness...........................................5 4.3 Use of API...................................................5 4.4 Scope of Mobile IP API.......................................5 5. Data Structures and Constants..................................5 6. Functions......................................................6 6.1 Retrieving Information on All Mobile Nodes...................6 6.2 Retrieving Information on a Given Mobile Node................6 6.3 Movement Notification........................................7 6.3.1 Blocking Mode...............................................7 6.3.2 Non-blocking Mode...........................................7 6.3.3 Registering Callback Function...............................7 6.3.4 Deregistering Callback......................................8 6.4 Verifying location...........................................9 7. Security Considerations........................................9 8. References.....................................................9 9. Author's Addresses.............................................9 10. Full Copyright Statement....................................10 Expires December 2003 [Page 2] Internet Draft Mobile IP API June 2003 1. Introduction The Mobile IP API is an interface between mobility management and application layer. The basic functionality of the Mobile IP API is to enable applications to get mobility information about the host they are running on or other hosts they are communicating with. It is assumed that the mobility management (module) already has the mobility information (via Mobile IP signaling). There is no need to generate any extra signaling between the Mobile Node (MN) and the Correspondent Node (CN), or change the functionality of current Mobile IP [3][5] functions for the host to obtain mobility information. +-------------------------------+ Application | Applications | Layer | | +-----------/ \-----------------+ | |A| | Transport | |P| TCP/UDP | Layer | |I| | +-----------\ /-------+---------+ Network | Mobility Management | IP | Layer | Module (Mobile IP) | | +---------------------+---------+ Link | | Layer | | +-------------------------------+ Physical | | Layer | | +-------------------------------+ Figure-1.0 Network stack and Mobile IP API Mobile IP has been designed to provide network layer mobility in a transparent manner. Host mobility can be managed without having to involve applications in any way. There is no need to let the application layer know about underlying mobility of mobile terminals. However, it does not mean that the applications should not know about mobility of mobile terminal. It can be useful to pass mobility information from network layer to the applications. A mobility aware application can exploit such information in many different ways. Some of these are discussed in usage scenarios section. Depending on the access technology and network architecture (including access points deployment plan), learning an IP address within a topology can also imply learning geographical location with some level of accuracy. While this API provides location information in terms of topologically correct IP addresses (let’s call this Expires December 2003 [Page 3] Internet Draft Mobile IP API June 2003 routing-based location), mapping that to geographic location is outside the scope of this API. External mechanisms, such as subnet- location database lookups, can be used for this purpose. An application running on the MN can learn the location of the host within IP topology by using this API. Similarly, an application running on the CN can learn the routing-based location of MNs it’s communicating with. Applications can also detect movement by observing change in IP addresses. Mobile IP API does not generate any extra signaling between the MN and CN. The API only relies on receipt of Binding Update (BU) on the CN to provide information to the applications running on the CN. 2. Key Words The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC-2119 [1]. 3. Usage Scenarios This section describes the example application scenarios for the Mobile IP API. The following scenarios apply to one of four classes of usage. (a) MN queries its own routing-based location and verifies whether it is home or in a visiting network. Applications that take different actions based on the location of the local host can use this functionality. For example, in case network access fees are higher in visited networks, an e-mail client might choose not to download attachments when it detects the local host is away from home network. (b) MN gets notification of its own movement, and learns the new routing-based location. Applications that take actions upon any movement can use this functionality. For example, SLP [2] discovery can be kick started as soon as movement is detected. This would increase the performance of the service by proactively discovering servers upon movement. (c) CN queries the MN’s location. Location-based service providers can utilize this functionality. For example, a web server can deliver location-based content by determining the location of the clients (MNs). (d) CN gets notification of MN’s movement, and learns the new routing-based location. Expires December 2003 [Page 4] Internet Draft Mobile IP API June 2003 4. Requirements This section describes the requirements for the Mobile IP API design. Current version of the Mobile IP API is designed for Mobile IPv6 [3]. It can easily be extended to support Mobile IPv4 [5]. 4.1 Location awareness Mobile IP API must enable applications to learn MN's routing-based location (i.e., MN’s care-of address). These applications might be running on the MN itself, or on a CN that this MN is corresponding with. 4.2 Movement awareness Mobile IP API must enable applications to get notified when MN changes location. These applications might be running on the MN itself, or on a CN that this MN is corresponding with. 4.3 Use of API Mobile IP API should have read-only functions and must not effect the operation of any other application or the mobility module on the host. 4.4 Scope of Mobile IP API Mobile IP API must be designed specific to Mobile IP, and should not generate new signaling or change functionality of the Mobile IP protocols [3]. 5. Data Structures and Constants The mobile_node_t can hold home address and care-of address of a MN. struct mobile_node_t { struct in6_addr home_addr; /* home address of MN */ struct in6_addr co_addr; /* care-of address of MN */ struct in6_addr ha_addr; /* MN’s home agent */ } Expires December 2003 [Page 5] Internet Draft Mobile IP API June 2003 Apart from above mentioned data structures, following are also defined. #define MIP_MN_MOVED 1 #define MIP_BCE_DELETE 2 #define MIP_CB_DEREGISTER 3 These definitions are used by movement notification API (see section 6.3) 6. Functions 6.1 Retrieving Information on All Mobile Nodes Applications can call the mip_get_all_mobile_nodes() function to get information about all mobile nodes maintained by the mobility management module. int mip_get_all_mobile_nodes(mobile_node_t **mn_list, int local) Since the number of mobile nodes may not be known in advance, the function itself allocates appropriate amount of memory to hold all the mobile nodes and assigns that to *mn_list. The local argument determines whether this function should list all the mobile nodes running on the same host as the caller, or all the mobile nodes this host is communicating with. Latter simply dumps the content of the binding cache of a correspondent node. The value of this field should be one for local, and zero for non-local. If there was no mobile node existed in memory, the function shall return zero. If there was an error, the function shall return -1. 6.2 Retrieving Information on a Given Mobile Node Applications can call the mip_get_one_mobile_node() function to get information about a specific mobile node. int mip_get_one_mobile_node(mobile_node_t *mobile_node) Desired mobile node’s home address should be stored in the home_addr field of the structure. This function shall return positive value for success, return zero if the mobile node is unknown, and return -1 if there is any error. Expires December 2003 [Page 6] Internet Draft Mobile IP API June 2003 6.3 Movement Notification Applications can call mip_notify_movement() function to get a notification upon movement of mobile nodes. Applications can do so either in non-blocking mode by registering a callback function for notification, or in blocking mode function call blocks until the event of interest is detected. int mip_notify_movement(mobile_node_t *mobile_node, int non_blocking, unsigned int timeout_ms, long int cb_parameter, int (*callback) (mobile_node_t mobile_node, int event, long int_cb_parameter)) If the home address is set to unspecified IPv6 address (i.e. 0::0) then it is treated as a wildcard and the application will get notification for all mobile nodes. 6.3.1 Blocking Mode If the value of non_blocking (flag) argument is set to zero, then the function will not return until a new binding update for mobile node whose home address is specified in mobile__node is received or timeout_ms milliseconds are passed (whichever comes first). Upon return, the co_addr field of the mobile_node is initialized to the latest care-of address of the mobile node. The function shall return zero, if timeout occurred; otherwise a return positive value. A possible error is Unknown Home Address, and others may be defined later. 6.3.2 Non-blocking Mode If the value of non_blocking argument is set to non-zero, then this function call will register or deregister a callback function. 6.3.3 Registering Callback Function Expires December 2003 [Page 7] Internet Draft Mobile IP API June 2003 When the non_blocking (flag) argument is set to a non-zero value, a (pointer to) callback function must be provided as well. This callback function is called when specified mobile node(s)moves. During callback, the callback function is passed with an initialized mobile_node structure. The cb_parameter is passed to the callback function as is, and the event is set to an appropriate value such as MIP_MN_MOVED. Other events include MIP_CB_DEREGISTER, MIP_BCE_DELETE (binding cache entry deleted). The description of these events is as follows: (a) MIP_MN_MOVED The mobility management module has received a binding update indicating that the mobile node has acquired a new care-of-address. (b) MIP_CB_DEREGISTER The call back function for the specified address has been deregistered. This may occur due to application calling mip_notify_movement() function with non_blocking flag set to non-zero and callback set to NULL. This may also occur due to deletion of (all of) home-address(es) that the callback was registered for. (c) MIP_BCE_DELETE The binding cache entry has been deleted for a reason such as expiration of lifetime. The value of timeout_ms will be ignored when callback registration occurred. A possible error is Unknown Home Address, and others may be defined later. 6.3.4 Deregistering Callback If the value of callback argument is set to NULL, then this call will de-register any callbacks registered for the specific mobile_node(s) (wildcard address is allowed here as well). The callback function is called one final time with mobile_node (containing latest binding), cb_parameter, and MIP_CB_DEREGISTER as the event. The possible errors are due to no callback registered by the calling process for that home address, and unknown home address. Expires December 2003 [Page 8] Internet Draft Mobile IP API June 2003 6.4 Verifying location This macro can be used for determining whether a given mobile node is at home or away from home. int IS_AT_HOME(struct mobile_node_t *) This macro returns non-zero if the mobile node is at home (i.e. the care of addresses is same as the home address of the mobile node); otherwise it returns zero. 7. Security Considerations As previously stated, Mobile IP API does not generate extra signaling between the MN and the CN. For providing information to the applications running on the CN, the API only relies on receipt of Binding Updates on the CN. If the MN does not send a Binding Update for any reason including location privacy, this API will not provide any information to the applications running on the CN. As such, this API does not reveal any information other than what MN is willing to provide. 8. References [1] S. Bradner, "Key words for use in RFCs to Indicate Requirement Levels", RFC 2119, March 1997. [2] E. Guttman, C. Perkins, J. Veizades, M. Day. "Service Location Protocol, Version 2". RFC 2608, June 1999. [3] D. Johnson, C. Perkins, J. Arkko. Mobility Support in IPv6. draft-ietf-mobileip-ipv6-22.txt, May 2003. [4] J. Myers, M. Rose. "Post Office Protocol - Version 3". RFC 1939, May 1996. [5] C. Perkins, editor. IP Mobility Support. RFC 3344, August 2002. 9. Author's Addresses Alper Yegin DoCoMo Communications Laboratories USA, Inc. 181 Metro Drive, Suite 300 San Jose, CA 95110 Phone: +1-408-573-1050 (main) Fax: +1-408-573-1090 E-mail: alper@docomolabs-usa.com Expires December 2003 [Page 9] Internet Draft Mobile IP API June 2003 Muhammad Mukarram Bin Tariq DoCoMo Communications Laboratories USA, Inc. 181 Metro Drive, Suite 300 San Jose, CA 95110 Phone: +1-408-573-1050 (main) Fax: +1-408-573-1090 E-mail: tariq@docomolabs-usa.com Guangrui Fu DoCoMo Communications Laboratories USA, Inc. 181 Metro Drive, Suite 300 San Jose, CA 95110 Phone: +1-408-573-1050 (main) Fax: +1-408-573-1090 E-mail: fu@docomolabs-usa.com Carl Williams MCSR Labs 3790 El Camino Real, #154 Palo Alto, CA 94306 Phone: +1-650-279-5903 E-mail: carlw@mcsr-labs.org Atsushi Takeshita NTT DoCoMo, Inc. 3-5m Hikarinooka, Yokosuka, Kanagawa, 239-8536 Japan E-mail: takeshita@mml.yrp.nttdocomo.co.jp 10. Full Copyright Statement Copyright (C) The Internet Society (2001). All Rights Reserved. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English. Expires December 2003 [Page 10] Internet Draft Mobile IP API June 2003 The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns. This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS 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. Expires December 2003 [Page 11]