Internet DRAFT - draft-borst-mip6api
draft-borst-mip6api
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
