Internet Draft Aki Yokote Document: draft-yokote-mobileip-api-01.txt Alper E. Yegin Expires: December 2002 Muhammad M. Tariq Guangrui Fu Carl Williams Atsushi Takeshita June 2002 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 is 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. API provides awareness of mobility 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 August 2002 [Page 1] Internet Draft Mobile IP API June 2002 Table of Contents Status of this Memo...............................................1 Abstract..........................................................1 1. Introduction..............................................3 2. Key Words.................................................4 3. Usage Scenarios...........................................4 3.1 Selective Request Based on Location.......................4 3.2 Service Re-Discovery upon Movement........................5 3.3 Location Based Content Delivery...........................6 4. Requirements..............................................7 4.1 Location awareness........................................7 4.2 Movement awareness........................................7 4.3 Use of API................................................7 4.4 Scope of Mobile IP API....................................8 5. Security Considerations...................................8 6. Data Structures and Constants.............................8 7. Functions.................................................9 7.1 Retrieving all mobile nodes...............................9 7.2 Retrieving one mobile node...............................10 7.3 Freeing allocated memory.................................10 7.4 Movement Notification....................................10 7.4.1 Blocking mode movement notification......................11 7.4.2 Non-blocking mode movement notification..................11 7.4.3 Registering callback function............................12 7.4.4 Deregistering Callback...................................12 7.5 Verifying location.......................................13 8. IPR Statement............................................13 9. References...............................................13 10. Author's Addresses.......................................13 11. Full Copyright Statement.................................14 Expires August 2002 [Page 2] Internet Draft Mobile IP API June 2002 1. Introduction The Mobile IP API is an interface between mobility management and application layer. See Figure-1.0. +-------------------------------+ Application | Application | 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. 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. Using Mobile IP, mobility management (module) already has the mobility information. 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. API at this stage can be called Basic Mobile IP API. Basic API deals with "reading mobility information". In addition, advanced Mobile IP API would be considered at a later stage. In order to meet the demands of sophisticated applications, advanced Mobile IP API would enable applications to "control mobility". The advanced API would be discussed in a future revision of this document. Mobile IP has been designed to provide network layer mobility in a transparent manner and with use of Mobile IP it is understood that 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 advantageous to pass mobility information from IP layer to applications. A mobility aware application can exploit such information in many different ways. Some of these are discussed in usage scenarios. Mobility information can be rephrased as awareness of MNÆs location and movement. Location awareness allows the applications on the MN Expires August 2002 [Page 3] Internet Draft Mobile IP API June 2002 and the CN to query the current location of a MN, either home or away from home. Movement awareness allows the applications on the MN or CN to get notification of a MNÆs movement. Location of MN refers to location in IP topology, not a geographic location. Mapping IP topological location to geographical location is outside the scope of this API. 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 basic Mobile IP API. The following scenarios apply to one of four classes of usage. (a) MN queries its own location i.e. whether it is at æhomeÆ or in a visiting network. (b) MN gets notification of its own movement, and new location; (c) CN queries the MNÆs location; and (d) CN gets notification of MNÆs movement, and new location Section 3.1 explains email access service scenario which can apply to usage (a). Section 3.2 explains local service discovery scenario which can apply to usage (b). And section 3.3 explains location based content delivery scenario which can apply to usage (d). 3.1 Selective Request Based on Location This section describes the scenario wherein an e-mail clientÆs decision to download attachments depends on the whether the MN that this application is running on is at home or in a visited network. When a user is roaming in a visited network, it may need to pay a fee with higher rate than rate in home network for network access. This may make the user avoid downloading large size of e-mail attachment files at visited network if those files are not needed right away. The user can get all files when it gets back home. The e-mail client application on MN gets mobility information (MNÆs location) from mobility management, and then application initiates request which includes choice of download according to the current location. The messages will be downloaded with or without attachments from the server depending on the request. For example, in the figure-3.1 Expires August 2002 [Page 4] Internet Draft Mobile IP API June 2002 below, e-mail client application on MN queries MNÆs location from MM- layer (1). The application initiates downloading e-mail messages without attached files (3) when it realizes the MN is away from home. E-mail server responds and messages are downloaded without attachments (4). +--------------+ +--------------+ | POP server | | MN | +--------------+ +--------------+ | MM-module Application | | | | |Queries | | |location(1)| | |<----------| | | | | | MN away | | | from home | | |---------->| | Request choice of download option (3) | |<-------------------------------------------| | | | Message download without attachments (4) | |------------------------------------------->| | | Figure-3.1: Selective Request Based on Location 3.2 Service Re-Discovery upon Movement This section describes the scenario where a MN can trigger its service discovery process upon detecting network-layer movement. This is the case that the MN gets notification of its own movement, and new location. SLP [2] can be used for discovering local services and servers. An application using SLP for service discovery needs to initiate the discovery process before it can use a particular service. When a mobile node moves to a new IP subnet, it may need to discover local services again. It can either wait until the next request for initiating the discovery, or perform discovery as soon as it detects the movement. Latter provides better performance as the serverÆs identity is already discovered before the first service request is issued by the client. In this usage scenario (shown in Figure 3.2 below), an application running on the MN is using SLP for discovering local printers. As MN performs a network-layer handover, it gets a new CoA (1). Application gets notified of this movement (2) and initiates local printer Expires August 2002 [Page 5] Internet Draft Mobile IP API June 2002 discovery (3). Local printers are discovered using SLP and their information is cached (4). Later on, when the application has to send a request to a local printer (5) it does not need to start a discovery process and it can use one of the cached printer servers. +-------+ +-----+ +--------------+ |Printer| | SLP | | MN | +-------+ +-----+ +--------------+ | | MM-Module Application | | New CoA(1) | | | | --------->| (2) | | | |-------->| | | SLP lookup (3)| | | |<-------------------------------| | |Location of nearest printer (4) | | |------------------------------->| | | +--------+ | | |Refresh | | | |Cache of| | | |local | | | |printer | | | +--------+ | Printing job request (5) | |<------------------------------------------| | | Figure 3.2: Service Re-discovery on Movement 3.3 Location Based Content Delivery This section describes the scenario where content delivered to a MN can be customized based on its location. This is the case where a CN gets notification of MNÆs movement, and new location. In this scenario, the CN is a content server capable of serving location based content. The CN keeps track of MNÆs movement by receiving a binding update from MN. In the Figure-3.3 below, every time CN gets a binding update form MN (1), content server application gets mobility information from mobility management module on CN (2). The application can map the MNÆs IP address to its geographic location (3), and then it can dispatch location based content to MN. Expires August 2002 [Page 6] Internet Draft Mobile IP API June 2002 CONTENT SERVER +--------------+ +--------------+ | CN | | MN | +--------------+ +--------------+ Application MM-Module MM-Module Application | | New CoA | | | | --------->| | | | | | | | Binding Update(1) | | | (2) |<-----------------------| | |<--------| | | +--------------+ | | | |Map new addr | | | | |to geographic | | | | |location (3) | | | | +--------------+ | | | | | | Send location based content (4) | |------------------------------------------>| | | Figure 3.3: Location Based Content Provisioning 4. Requirements This section describes the requirements of Mobile IP API. Identifying following requirements that will render to the API becomes essential in designing a widely accepted solution. 4.1 Location awareness Mobile IP API must enable applications to learn MN's location (i.e., whether the MN is at home, or it is away from home and has a CoA). These applications might be running on the MN itself, or 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 a CN that this MN is corresponding with. 4.3 Use of API Basic Mobile IP API should have read-only functions and must not effect the operation of any other application on the same host. Expires August 2002 [Page 7] Internet Draft Mobile IP API June 2002 4.4 Scope of Mobile IP API Basic Mobile IP API must be designed specific to Mobile IP, and should not generate new signaling or change functions of Mobile IP protocols [3][5]. It should work with both Mobile IPv4 and Mobile IPv6. 5. 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. 6. Data Structures and Constants The union ip_addr holds IPv6 address and IPv4 address and is usually defined in the header file. union ip_addr { struct in6_addr ipv6_addr; struct in_addr ipv4_addr; }; The mobile_node_t can hold home address and care-of address(es) of a MN. struct mobile_node_t { unsigned int addr_family; /* AF_INET (for ipv4) and AF_INET6 */ /* (for ipv6), AF_UNSPEC is */ /* acceptable in certain cases*/ union ip_addr home_addr; /* the home address*/ unsigned int num_coa; /* number of care of addresses*/ union ip_addr *coa; /* pointer to first address in*/ /* care of address array */ }; The addr_family field specifies whether the MN is using IPv4 or IPv6. Both home address and the care-of address(es) must belong to same family. The value of this field should be AF_INET for IPv4 and AF_INET6 for IPv6. AF_UNSPEC is acceptable in certain cases. Expires August 2002 [Page 8] Internet Draft Mobile IP API June 2002 The home_addr field holds MNÆs home address. The num_coa field holds number of care-of addresses that are maintained at the MN. The coa is the pointer to first address in care-of_address array. Since Mobile IPv4 supports simultaneous bindings, a Mobile IPv4 MN may have more than one care-of address simultaneously. num_coa should be assigned to 0 (zero) when coa does not point to a valid address, such as upon instantiation. Apart from above mentioned data structures, following are also defined. #define MIP_MN_MOVED 1 #define MIP_BCE_DELETE 2 #define MIP_CB_DEREGISTER 4 These definitions are used by movement notification API (see section 7.4) 7. Functions 7.1 Retrieving 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, unsigned int addr_family); Since the number of mobile nodes may not be known in advance, so the function itself allocates appropriate memory to hold all the mobile nodes and assigns that to *mn_list. The function also allocates the memory for individual care-of address arrays for each mobile node. It is, however, the responsibility of the application to free the memory at an appropriate time using the mip_free_memory function (see 8.3) or some other means. 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 not local. Expires August 2002 [Page 9] Internet Draft Mobile IP API June 2002 The addr_family argument specifies what kind of mobile nodes the application is interested in. If AF_INET is specified then only IPv4 mobile nodes are returned, if AF_INET6 is specified then only IPv6 mobile nodes are returned, and if AF_UNSPEC is specified then all mobile nodes are returned regardless of address family. If there was no mobile node existed in memory, the function shall return zero. If there was an error, the function shall return -1. 7.2 Retrieving one mobile node Applications can call the mip_get_one_mobile_nodes() function to get information about a specific mobile node. int mip_get_one_mobile_node(mobile_node_t *mobile_node); The home_addr and the addr_family field should be initialized with looked up address and address family respectively. AF_UNSPEC is not acceptable as value for the addr_family field of mobile_node. The function allocates sufficient memory for the array to hold all the care-of addresses that are associated with the home address specified in the mobile_node. The function then initializes the num_coa_care_of_addr and fills in all the care-of addresses. However it is responsibility of the application to later free the memory using the mip_free_memory() function or some other means. This function shall return positive value for success, return zero if there are no mobile nodes known, and return -1 if there is any error. 7.3 Freeing allocated memory Applications can call mip_free_memory() function to free the allocated memory for the mobile_node_t on the heap. int mip_free_memory(mobile_node_t *) This function shall return zero if it was succeed and -1 if there was an error. 7.4 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 wherein a callback function is not used rather the mip_notify_movement() function itself blocks until the event of interest is detected. Expires August 2002 [Page 10] Internet Draft Mobile IP API June 2002 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 addr_family field of the mobile_node is set to AF_UNSPEC, or if the addr_family field of the mobile_node is set to any particular address family but home address is left unspecified (i.e. :: or 0.0.0.0) then it is treated as a wildcard and application will get notification for all mobile nodes. 7.4.1 Blocking mode movement notification If the value of non_blocking (flag) argument 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 (or for wildcard address) is received or timeout_ms milliseconds are passed (whichever comes first). Upon return, the addr_family field of the mobile_node contains a valid address family, the home_addr field of the mobile_node contains the home address of the mobile node that has moved. The coa field of the mobile_node points to the first element of the array of the care- of addresses known for the mobile node whose home address is specified in the home_addr field of the mobile_node. The num_coa field of the mobile_node is initialized to number of addresses in the coa array. In certain events such as for when event is triggered due to timeout or deletion of home address from the binding cache while function is still blocked and waiting for event, the num_coa may be set to zero and coa set to NULL when the function returns. The function shall return zero, if timeout occurred; otherwise a return positive value. The possible error is Unknown Home Address, and others may be defined later. Specifications for how applications can learn about these errors will follow in a later revision of this document. 7.4.2 Non-blocking mode movement notification If the value of non_blocking argument is set to non-zero, then this function call will register the callback function (see 7.4.3) or deregister callback function (see 7.4.4). Expires August 2002 [Page 11] Internet Draft Mobile IP API June 2002 7.4.3 Registering callback function When the non_blocking (flag) argument is set to non-zero, 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 mobile_node (containing the home address, address family and latest address bindings) of the mobile node on which the event has occurred (kernel may also pass a wild card address in certain cases, so application should be on the lookout). 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(es) 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 zero. 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 life time. More events may be defined later. The value of timeout_ms will be ignored when callback registration occurred. The possible error is Unknown Home Address, and others may be defined later. Specifications for how applications can learn about these errors will follow in a later revision of this document. 7.4.4 Deregistering Callback If the value of callback argument is set to zero, 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. Expires August 2002 [Page 12] Internet Draft Mobile IP API June 2002 The possible errors are no callback registered by calling process for that home address, Unknown Home Address, and others may be defined later. 7.5 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. at least one of the care of addresses is same as the home address of the mobile node); otherwise it returns zero. 8. IPR Statement The IETF has been notified of intellectual property rights claimed in regard to some or all of the specification contained in this document. For more information consult the online list of claimed rights. 9. 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 and C. Perkins. Mobility Support in IPv6. draft- ietf-mobileip-ipv6-17.txt, May 2002. [4] J. Myers, M. Rose. "Post Office Protocol - Version 3". RFC 1939, May 1996. [5] C. Perkins, editor. IP Mobility Support. RFC 2002, October 1996. 10. Author's Addresses Aki Yokote 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: yokote@docomolabs-usa.com Expires August 2002 [Page 13] Internet Draft Mobile IP API June 2002 Alper Yegin DoCoMo Communications Laboratories USA, Inc. E-mail: alper@docomolabs-usa.com Muhammad Mukarram Bin Tariq DoCoMo Communications Laboratories USA, Inc. E-mail: tariq@docomolabs-usa.com Guangrui Fu DoCoMo Communications Laboratories USA, Inc. E-mail: fu@docomolabs-usa.com Carl Williams DoCoMo Communications Laboratories USA, Inc. E-mail: carlw@docomolabs-usa.com Atsushi Takeshita DoCoMo Communications Laboratories USA, Inc. E-mail: takeshita@docomolabs-usa.com 11. 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. 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 August 2002 [Page 14]