$Id: tech_def.html,v 1.29 1998/12/10 09:29:10 jkmaline Exp $

Table of contents

Summary

1. Introduction

2. General description of the system

3. System architecture description

3.1. Design Principles

3.2. Architecture

4. Module and process descriptions

4.1. Mobile Node

4.2. Foreign Agent

4.3. Home Agent

4.4. Cryptographic algorithm interface and session key generation

4.5. Mobility Bindings

4.6. Tunneling interface

4.7. Routing interface

4.8. ARP interface

4.9. Logging (syslog)

4.10. Configuration files

4.11. Application Programming Interface

4.12. Support tools

5. Module implementation description

5.1. Mobile Node

5.2. Foreign Agent

5.3. Home Agent

Appendix

Summary

The main motive of the Dynamics project is to make mobile IP more flexible by implementing a prototype version of a hierarchical IP tunnel for a IPv4 network.

The Dynamics group will write the implementation from scratch. The implementation relies on the tunneling and advanced routing features of development version (v2.1) of the Linux-kernel and the upcoming stable version (v2.2).

Three main modules, the mobile home, foreign agent and home agent, will be developed. These modules depend on modules that provide an interface to the kernel functionality. An API module that provides functionality for making programs that control and monitor the main modules will also be developed.

Communication between the main modules is done by using Berkeley IP sockets. The message formats used are as defined in mobile IP related Internet standards and drafts.

The mobile nodes are authenticated with message authentication code from the payload of registration requests based on the MD5 hash algorithm. A publicly available implementation of the algorithm will be used. The foreign agents use public key cryptosystem to get the session keys generated by the home agents. A publicly available RSA implementation will be selected for this purpose.

The Linux system logger is used for all log messages generated by the modules.

All main modules will use a general configuration file format and API for accessing the data.

1. Introduction

The main motive of the Dynamics project is to make a prototype version of a hierarchical IP tunnel for IPv4 network. The project deliverables are made for the MART-project. The main goal is to accomplish a system that can be further used and developed in research of the mobile IP field. More thorough description of the project and its goals is available in the beginning of the project plan.

1.1. Terms

1.2. Framework

This project will use existing solutions and solution proposals as far as possible. This will prevent extra work of "reinventing the wheel", and should lead to a more stable implementation. The main task for this project is to select the suitable solutions and to implement a working prototype of the hierarchical IP tunnel.

Chapter 1.2 (Framework) of the functional definition gives the Internet standards and drafts that our implementation depend on. The most import are: IP Mobility Support" [RFC2002], "IP Keys for Route Optimization" [REGKEY] (work in progress) and ICMP Router Discovery Messages [RFC1256]. These documents describe the message formats that we have chosen to use.

1.3. Document structure

A compact summary of the document is given above before the rest of the document. Chapter 1 (Introduction) explains briefly the project and the contents of this document. Chapter 2 (General description of the system) gives a brief summary of the general description of the system in various documents. Chapter 3 (System architecture description) describes the main design decisions and gives an overview of the system architecture. Chapter 4 (Module and process descriptions) gives an overview of each module, defines their interfaces, attributes and intercommunication mechanisms. In chapter 5 (Module implementation description) state machines and pseudocode describes the functionality of the mobile node, foreign agent and home agent.

2. General description of the system

Chapter 2 of the functional definition (Overview) gives a closer consideration of the system and especially of its functionality. It also describes the security design of the system.

Section 4.1 of the project plan (Software tools and hardware resources) defines the implementation environment and the tools to be used.

3. System architecture description

3.1. Design Principles

One of our main design principles was not to put in any functionality beyond the requirements, but still provide the possibility to add further extensions and modifications later on. Keeping the solution as simple as possible was also requested by the customer.

We tried to find a solution where we would need to modify kernel code as little as possible and ultimately not at all, as coding and modifying kernel space code is normally more time consuming and complex than writing user space code. It was found out that by using the current development version of the Linux-kernel (v2.1), and the upcoming stable version (v2.2), we could exploit the new tunneling and advanced routing features to avoid kernel modification.

We also tried to find mobile IP implementations for Linux that we could extend or get ideas from. See appendix for list of implementations that we examined. However, none of the implementations satisfied our requirements, so we decided to write our implementation from scratch.

3.2. Architecture

The modules we will implement can be divided into four categories: the main modules (mobile node, foreign agent and home agent), modules that provide an interface to the kernel (ARP, tunneling and routing), generic support modules (mobility bindings, cryptography and configuration) and an API module.

The following diagram shows the dependencies between the different modules.

The main modules provide the core functionality of the system. Communication between the modules is done through Berkeley sockets using the IP protocol. The exact structure and contents of the messages sent between the mobile node and the mobility agents is described in the Message Formats and Contents document.

The API module functions as an interface between support tools (such as control and monitoring) and the main modules. This module communicates with the main modules through Berkeley sockets using the Unix domain protocol.

The kernel interface provides functions that are easier to use than direct ioctl calls (man 2 ioctl).

The general support modules provide functions that are common to two or more modules.

4. Module and process descriptions

4.1. Mobile Node

4.1.1. General design

Support part and signaling part will be integrated into one module, which runs on a single process. This process waits for signaling messages, library calls (through special socket interface) and timers. When library socket is activated, it is served immediately. Results are sent back and if the library call results in state transition, the transition is processed. In case of a signaling message or timer, the current signaling state is used.

For now only bi-directional (full) tunneling mode is supported. However, the other tunneling modes are easy to implement based on the code for bi-directional tunneling. In triangle tunneling, sent packets will not be wrapped and in no-tunneling mode we just do not make the tunnel and use the computer directly with local network.

4.1.2. Preconfigured data

The Mobile Node will be preconfigured with following data. This data will be read via the configuration file interface on startup and on explicit request.
 

4.1.3. Dynamic state data

4.1.4. Timers

4.1.5. Communications with other elements

Communication with the API module is done over two Unix domain sockets as described in the API section.

The agent reacts to SIGHUP, SIGTERM and SIGINT signals. SIGHUP cauces the configuration file to be reread. The other two signals will make the process exit in a clean way.

4.1.6. Dependency on other modules

4.1.7. Operations

4.1.8. Exceptional situations and error situations

There are several possible error situation mainly caused by the network environment. General exceptional situations are:

1. Received message is erroneous. If the message structure is erroneous or data is corrupted, the message will be silently discarded.
2. The messages are lost. This is an expected situation and the timers in state machine will resend the message.
3. The configuration file has an error. The program exits and informs about the error.

4.1.9. Testability

The module is tested according to the test plan.

4.2. Foreign Agent

4.2.1. Foreign Agent in brief

• One daemon process
• Signaling and API interface communications through sockets
• Routes encapsuled data in IP layer
• Is part of a hierarchical Foreign Agent structure

4.2.2. Preconfigured data

The Foreign Agent will be preconfigured with the following data. This data will be read via the configuration file interface on startup and on explicit request.

Please refer to the configuration file specification document for a concrete view of configurable parameters. The concrete use of these variables may be seen from the Foreign Agent pseudocode presentation.

4.2.3. Dynamic data

4.2.4. Signaling timers

4.2.5. Communication with other elements

The Foreign Agent needs to communicate with:

• Other Foreign Agents
• Mobile Nodes (only the lowest Foreign Agents)
• The Home Agent (only the highest Foreign Agent)
• The Foreign Agent administration program

4.2.6. Operations and interfaces

The Foreign Agent operations are defined in detail in the Foreign Agent state machine document. The Foreign Agent state machine picture illustrates the entire Foreign Agent daemon operation. The Foreign Agent single binding state machine picture illustrates the states of a single binding from the signaling point of view.

The Foreign Agent has the following external interfaces:

• Signaling interface: UDP socket, port 434
• API information request interface: unix socket
• API modification interface: unix socket

Communication with the API module is done over two Unix domain sockets as described in the API section.

The foreign agent reacts to SIGHUP, SIGTERM and SIGINT signals. SIGHUP signal causes the configuration file to be reread. The other two signals will make the process exit in a clean way.

4.2.7. Dependency on other modules

The Foreign Agent is dependent on the routing, cryptographic, bindings, and tunnel modules. Configuration data is read by using the configuration module interface.

4.2.8. Exceptional situations and error situations

There are several possible error situations, caused mainly by the network environment. General exceptional situations are:

1. Received message is erroneous.

   The message structure may be erroneous
   The message data may be corrupted

   The message will be silently discarded. This may result in unnecessary binding timeouts.

2. The authorization of a message fails

   The message is sent upwards to Home Agent

3. A message is lost

   A Registration Reply message is lost (on its way up or down)
   

   Unnecessary binding timeout.
   A Registration Request message is lost
   This may cause more messages to be sent or may result in unnecessary binding timeouts.
   A Mobility Agent Solicitation message is lost
   This may cause more messages to be sent or may result in unnecessary binding timeouts.

4. The messages are received in undesired order

   A Registration Request is received just before the (de)Registration Reply (with expiration time left set to 0) arrives to the Foreign Agent.

   When the Foreign Agent receives a Registration Request it creates a unconfirmed binding for the request. When the Registration Reply comes back from Home Agent the binding is confirmed. In this situation the confirmed binding (old) is removed and the unconfirmed binding is confirmed after the reply from Home Agent.

5. The configuration file has an error

   The program exits and informs about the error.

The error situations are covered by the Foreign Agent state machine document.

4.2.9. Testability

The module is tested according to the test plan.

4.2.10. Data structures

Specific data structures in the Foreign Agent:

4.3. Home Agent

The Home Agent is responsible for encapsulating and forwarding packets to its Mobile Nodes when they are away from their Home Network. It also decapsulates and forwards tunneled packets originating from its Mobile Nodes.

4.3.1. Communication with other elements

The Home Agent needs to communicate with:

• Foreign Agents
• Mobile Nodes
• Home Agent administration program

Communication with the Foreign Agents and Mobile Nodes is done with Berkeley IP sockets. The Home Agent listens to ICMP agent solicitation messages from mobile nodes on a "packet" socket. ICMP agent advertisement messages are sent in reply to these messages on the same socket. The home agent also listens to Registration Requests on a UDP socket, port 434, originating from foreign agents or mobile nodes. If the request is authorized then a mobility binding for the requested mobile node will be established or, if one already exists, updated. The request is then answered with an appropriate Registration Reply.

Communication with the API module is done over two Unix domain sockets as described in the API section.

The home agent reacts to SIGHUP, SIGTERM and SIGINT signals. SIGHUP cauces the configuration file to be reread. The other two signals will make the process exit in a clean way.

4.3.2. Dependency on other modules

The home agent depends on the ARP, routing, cryptographic, bindings and tunnel modules. Configuration data is read by using the configuration module interface.

4.3.3. Preconfigured data

The Home Agent will be preconfigured with the following data. This data will be read via the configuration file interface on startup and on explicit request.

int max_reg_time defines the maximum time a mobility binding will be valid before a re-registration is required.

int max_bindings defines maximum number of mobiles that are allowed to be registered at the same time. When the number of mobility bindings reach this limit, further registrations will be rejected.

char arp_if[8] is the network interface where the Mobile Node will listen to packets destined for registered mobile nodes.

char localtunnel_if[8] is the network interface to where the local tunnel interface will be attached.

HASH auth_mns_hash is a hash table of IP addresses of the Mobile Nodes that are allowed to register.

HASH sec_assocs_hash is a hash table of security associations that are used to authenticate Mobile Nodes as they want to register.

4.3.4. Dynamic data

The following describes the data that will be dynamically maintained while the Home Agent is running:

HASH bindings_hash is a hash table of valid Mobility Bindings. See the section on Mobility Bindings.

HASH tunnels_hash is a hash table of active tunnels. See the section on tunnels.

4.3.5. Exceptional situations and error situations

4.4. Cryptographic algorithm interface and session key generation

4.4.1 Secure hash authentication using MD5

MD5 was selected as the hash algorithm to be used. The design of the software allows an easy addition of optional algorithms, but MD5 is the only one taken into use in this project.

There are many publicly available implementations of MD5 algorithm and one will be chosen by the programmer responsible for implementation of the cryptographic part. The interface to the hash algorithm is simply a function that returns the hash value (128 bits of data).

void MD5_MAC(unsigned char const *key, unsigned int key_len,
             unsigned char const *data, unsigned int data_len,
             unsigned char *MAC);

The operation of the MD5_MAC() function is defined as MAC := MD5(key | data | key).

key and data are pointers to memory containing key_len and data_len bytes of data. The contents of the data is not modified by the function. MAC is a pointer to 128 bits (16 bytes) of memory to be used for the result of the calculation.

The normal operation of MD5_MAC() function is to calculate the MAC for the registration reply message sent by a mobile node and authentication of the message by foreign agents or a home agent. In addition this function is used in session key generation and in encrypting the key for the mobile node.

4.4.2 Public key cryptosystem using RSA

A publicly available RSA implementation will be selected by the programmer responsible for the implementation of the cryptographic parts of the software. A suggestion for the base code if Werner Koch's implementation of RSA (ftp://ftp.guug.de/pub/gcrypt/contrib/rsa.c). The routines use an internal presentation form of the public and private keys, but the external users of the module do not need to take this form into consideration. All the keys are provided as a binary data which can be sent to other modules.

The following functions will be used as an interface to the RSA functions.

void rsa_initialize(char const *public_key_file, char const *private_key_file);
int rsa_encrypt_len(unsigned char const *public_key,
                    unsigned int public_key_len);
int rsa_encrypt_session_key(unsigned char const *session_key,
                            unsigned char const *public_key,
                            unsigned int public_key_len,
                            unsigned char *encrypted_key);
void rsa_decrypt_session_key(unsigned char const *encrypted_key,
                             unsigned int encrypted_key_len,
                             unsigned char *session_key);
int rsa_get_public_key_len(void);
char const *rsa_get_public_key(void);

The function rsa_initialize() reads the public and private keys of a foreign agent and prepares the system for RSA encryption and decryption. It must be called before using the other functions of the RSA module. The names of the files containing the public and private keys are given as parameters (they are obtained from the config file).

rsa_encrypt_session_key() is used to encrypt a session key with public key of the following system in the tunnel. session_key is pointer to 128 bit session key to be encrypted. public_key is a pointer to public_key_len bytes of key used in the encryption. encrypted_key is a pointer to memory containing space for the encrypted key. It must contain enough space for the encrypted data. rsa_encrypt_len() can be used to find out how much memory is needed when using a particular public key. rsa_encrypt_session_key() returns the length of the encrypted key or -1 in case the encryption failed.

rsa_decrypt_session_key() is used to decrypt an encrypted session key. encrypted_key is a pointer to memory containing encrypted_key_len bytes of encrypted data. session_key is a pointer to 16 bytes of memory used for the decrypted key.

rsa_get_public_key_len() returns the length (in bytes) of the public key read from the key file. rsa_get_public_key() returns a pointer to the public key read from the key file. This can be used to generate the foreign agent public key extension of the registration request messages. The public key is provided as binary data in a format that can be sent in the registration messages.

4.4.2.1 RSA key generation utility

4.4.3 Session key generation

The following function operates as the interface to the session key generation.

void generate_session_key(unsigned char const *key, unsigned int key_len,
                          unsigned char *session_key);

The generate_session_key() function reads 16 bytes of pseudorandom data from /dev/random and calculates session_key by calling MD5_MAC(key, key_len, random_data, 16, session_key).

key is a pointer to memory containing key_len bytes of data (session key generation secret). The contents of the data is not modified by the function. session_key is a pointer to 128 bits (16 bytes) of memory which will be filled with the new pseudorandom session key.

The session key will be encrypted with RSA for the foreign agents on the tunnel. The key will be sent also encrypted with the secret shared by the mobile node and the home agent. The encrypted version is produced with help of MD5 by calculating session_key XOR MD5(secret | session_key | secret).

4.5. Mobility Bindings

Home and foreign agents keep track of registered mobile nodes with mobility bindings.

A mobility binding has the following structure:

struct mob_binding {
      __u32 mn_addr;     /* mobile node address */
      __u32 lower_addr   /* other end of the lower tunnel segment */
      __u32 id[2];       /* timestamp */
      time_t exp_time;   /* time when binding will expire */
      char key[16];      /* the session key for the binding
      int confirmed;     /* boolean value indicating if the binding is confirmed or not */
      int spi;           /* associated authentication method */
}

Bindings have a lifetime. The current time in seconds since 0:00:00 UTC, January 1, 1970 can be retrieved with the time system call (see man 2 time). The expiration time for a binding is set in exp_time. When the current time is equal to or more than exp_time the binding should be removed.

Both foreign and home agents need to know where to forward packets destined for the mobile node; this is indicated by the lower_addr field. The session key for the tunnel is stored in the key field. The corresponding security parameter index for authentication method used is stored in the spi field. Foreign agents need an additional field, confirmed, to keep track of confirmed and unconfirmed bindings.

The following functions will be used as an interface to the mobility bindings:

HASH binding_inithash();
void binding_destroyhash(HASH hash);
int binding_add(HASH hash, struct mob_binding);
void binding_fetch(HASH hash, __u32 mn_addr, struct mob_binding *b);
int binding_delete(HASH hash, __u32 mn_addr);
int binding_nextexpire(HASH hash, struct mob_binding *b);

binding_inithash() initializes a hash table for storing bindings. The function returns a reference that is used in further operations on the hash table.

binding_destroyhash() should be called to destroy a hash table when it is not needed any more.

binding_add() adds a binding to the hash table. The function returns 0 on success.

binding_fetch() fills in the mob_binding structure if any binding for the requested mobile node is found.

binding_delete() deletes a binding with the specified mobile node address. The function returns 0 if a binding was deleted.

binding_nextexpire() gets the binding that is next to expire. The function returns 0 if a binding is found, else -1.

4.6. Tunnels

The home agent, foreign agent and mobile node needs to generate tunnels. Tunnels are generated through kernel ioctl calls. A more simple interface to the tunnel device will be implemented.

This module keeps track of how many mobile nodes are handled by each tunnel. The tunnel will only be removed when the number of tunnel_delete calls are equal to the tunnel_add calls. The following functions will be provided:

HASH tunnel_inithash();
void tunnel_destroyhash(HASH hash);
int tunnel_add(HASH hash, __u32 src_addr, __u32 dst_addr, char *device);
int tunnel_delete(HASH hash, __u32 src_add, __u32 dst_addr);

The list of tunnels should be initialized with tunnel_inithash which returns a reference to the hash table. The hash table is destroyed with tunnel_destroyhash.

tunnel_add takes as argument the end points of the tunnel. It writes the name of the added tunnel device to the memory location pointed by device. At least 8 chars have to be reserved for device. tunnel_add and tunnel_delete both return 0 on success and -1 otherwise.

The internal data structure for the tunnel will be:

struct tunnel {
	char device[8];   /* tunnel device name */
        __u32 dst_addr;
        __u32 src_addr;
	int ref;          /* number of references to tunnel */
}

The implementation of the ip program (ip.c) in the iproute2 package could be used as an example in implementation our interface routines.

4.7. Routing

The routing module provides an interface to the advanced routing mechanisms of the kernel. This is needed for routing packets to and from the mobile node to the right tunnel devices. These routines will be used by all the main modules.

The routing module will provide the following functions:

int route_add(__u32 addr, const char *tunnel_dev)
int route_del(__u32 addr, const char *tunnel_dev)

route_add and route_del adds and deletes a route respectively to the mobile node with address addr through tunnel tunnel_dev. Both functions return 0 on success and -1 otherwise.

As with the tunneling module our implementation could use the ip program (ip.c) in the iproute2 package as an example implementation of our interface routines.

4.8 ARP interface

Arp command of net-tools manipulates the system ARP cache (see man 8 arp). An simple to use interface to the needed commands will be implemented as a part of the home agent software. Following functions will be provided:

int add_proxyarp_item(__u32 host_addr, char const *interface);
int del_proxyarp_item(__u32 host_addr, char const *interface);

These functions correspond to the following commands: arp -Ds host_addr interface pub and arp -i interface -d host_addr, respectively. In other words, they add (or deleat) a host address to the ARP cache as a static entry that is published by the kernel (it answers the who-has questions). The implementation of the arp(8) command (i.e. arp.c in the net-tools) could be used as an example in implementing our interface routines.

Both functions return 0 for successful operations and -1 if an error occurred in the ARP cache manipulation.

4.9. Logging (syslog)

       #include <syslog.h>
       void openlog( char *ident, int option, int  facility)
       void syslog( int priority, char *format, ...)
       void closelog( void )

The ident parameter includes the identity string added in beginning of each log message. It is set as home agent, foreign agent or mobile node depending on the module in question. The option parameter is set to LOG_PID which logs the process ID with each message. The facility parameter defines the type of the program logging the message. In order to be able to separate the log messages of the tunneling system to its own log file the facility parameter is made configurable. The default value for our system is LOG_LOCAL0 and it can be changed in the config file.

The openlog() function is called after the configuration file has been read. If there is a need to write some error messages before the configuration information has been read, the facility is set to LOG_LOCAL0 with an extra openlog() call just before writing the message with syslog() function.

The priority parameter defines the priority of the message. It can be used with syslogd to change the handling of messages (most important messages could be written directly to the system console and so on). The following priorities are used by the modules:

• LOG_DEBUG - any debugging information
• LOG_INFO - any informational message of normal function
• LOG_WARNING - any message warning about abnormal conditions, which the system is able to handle (e.g. authentication errors)
• LOG_ALERT - any message about condition that cannot be handled by the system (e.g. lack of resources)

Example use of syslog

syslog(LOG_INFO, "FA=%s, MN=%s, registration request received",
       inet_ntoa(fa_addr), inet_ntoa(mn_addr));

This example produces following message in the system log:
Nov 30 20:00:52 hostname home agent[459]: FA=127.0.0.1, MN=10.1.2.3, registration request received.

4.10. Configuration files

We will provide a configuration file parser module with sufficient functions for fetching the configuration data from the configuration file to the variables in memory.

Configuration files are described in detail in a separate Configuration file specification document, which also includes examples of the configuration files.

4.11. Application Programming Interface

4.11.1. Foreign Agent Library Functions

4.11.2. Home Agent Library Functions

4.11.3. Mobile Node Library Functions

4.11.4. Function parameters

Structures:

struct dynamics_tunnel_info {
      __u32 mn_addr;     /* mobile node address */
      __u32 lower_addr   /* other end of the lower tunnel segment */
      __u32 id[2];       /* timestamp */
      time_t exp_time;   /* time when binding will expire */
      int confirmed;     /* boolean value indicating if the binding is confirmed or not */
      int spi;           /* associated authentication method */
}

Return Values:

4.11.5. Socket interface

All mobility agents use similar socket interface to exchange information between agent and library functions. Functions first open socket connection and then send integer function code followed by possible parameter value. Then they will wait for results. Timeout specifies how long the function should wait for results. If Timeout is zero, function will wait forever. Results arrive in raw data, which is assigned directly to user supplied buffer. Data structures used in agents must be similar to ones used in mobility agents sending the data. To assure that all data will be received, the sending is preceded by length field.

Message format from library function to agent:
 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+---------------------------------------------------------------+
|Type = 0       | Function code                 | Param. Length |
+---------------+---------------+---------------+---------------+
. Parameters                                                    .
.                                                               .
+---------------------------------------------------------------+

Type
    Message type identifier, must be 0
Function code
    Code value for function to perform
Param. Length
    Length of additional parameters in bytes
Parameters
    Additional parameters to be passed to agent.

Message format from agent to library:

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+---------------------------------------------------------------+
|Type = 1       | Return value                  | Data Length   |
+---------------+---------------+---------------+---------------+
. Data                                                          .
.                                                               .
+---------------------------------------------------------------+

Type
    Message type identifier, must be 1
Return Value
    Return value from function call. One of the values specified in Error values table
Param. Length
    Length of additional parameters in bytes
Data
    Additional result data from function call
 

4.12. Support Tools

4.12.1. Commands

Following notation is used for commands:
<parameter>    User supplied parameter value
[parameter]    Optional parameter
 

5. Module implementation description

This section describes the three main modules, i.e. the mobile node, the foreign agent and the home agent, in greater detail.

5.1. Mobile Node

The Mobile Node runs a simple driver code for the state machine. This driver waits for inputs coming through various socket interfaces and timer. Processing of input depends on where the data is coming from. For data coming from other mobility agent, the incoming message is first parsed and then transition function is decided depending on message type, some field values and values of current state variables.

Same message construction and parsing functions, logging functions and tunnel manipulation functions are used as in other mobility agents.

Mobile Node Signaling Part is constructed as a state machine. The inputs to state machine consist of signaling messages, API calls and timer expirations. The library monitoring functions will not affect the state machine and therefore they will be processed beside the state machine. The textual state machine describes the states and effect of inputs in each state. Graphical version presents the states and transitions between them.

Tunneling part is provided by Linux kernel. The Signaling part will use add_tunnel(...) and remove_tunnel(...) functions to control tunneling. This part will be similar in all mobility agents.

Support part communicates with library functions through socket interface using methods and messages specified in API specification. This part consists of functions which respond to the library function calls (through socket interface), modify the agents data structures and trigger state transitions.

Functions Connect and Confirm are blocking functions. These functions will return their results when the machine reaches Connected state, an error occurs (including denials of registration) or call timer expires. Additional state variables api_call_progressing and api_call_socket are used to identify the caller when the target state is reached. Because a call lasts over several state changes and includes data, which affects to the sent messages, only one call to connect or confirm is allowed to progress. If other call to connect or confirm is made while a call is in progress, Call_In_Progress error message is returned. Because both calls intend to register a tunnel, the only way to cancel the API call is to use disconnect library function. The call timeouts if the caller closes the API socket.

Command: update_location

Apply Location_Update input to state machine

If api_call_progressing
    return In Progress
Else If machine is in Disconnect state
    Set API state variables to this call.
    Apply input Connect to state machine.
    If call timeouts
        Disconnect
        Return timeout.
Else return Operation not permitted.

Return: Success, Data: Current Status

Apply Disconnect input to state machine.
Return: Success

If we are connected
    Return: Success, Data: care of addr
Else Return: Data not available

Return value: Success, Data: Full Tunnel

If api_call_progressing
    Return In Progress
Else If machine is in Connected state
    Set API state variables to this call.
    Apply Confirm input to state machine
    Return: Success
    If call timeouts
        Return to Connected state
        Return timeout.
Else return operation Not permitted.

Note: We want to let the user to decide if tunnel should be closed, because we might just be temporarily out of radio coverage.

Apply Home_Update transition to state machine.
If state doesn't allow this input
   Return: Operation not permitted.
Else Return Success

5.2. Foreign Agent

The functionality of the foreign agent is described by a textual and graphical state machine. The state machine for a single binding is showed in another diagram. Detailed C-like pseudocode is given in the file fa.c.

5.3. Home Agent

An SDL-like state machine of the home agent is shown as a separate picture. A fairly detailed C-like pseudocode of the home agent is in the file ha.c.

5.4. Application Programming Interface

6. References

[REGKEY]

C. Perkins, Registration Keys for Route Optimization (work in progress)
<URL: ftp://ftp.ietf.org/internet-drafts/draft-ietf-mobileip-regkey-00.txt>

[RFC1256]

Stephen E. Deering, ICMP Router Discovery Messages
<URL: ftp://ftp.funet.fi/pub/standards/RFC/rfc1256.txt>

[RFC2002]

C. Perkins, RFC2002 IP Mobility Support
<URL: ftp://ftp.funet.fi/pub/standards/RFC/rfc2002.txt>

Appendix

The following mobile IP implementation were investigated:

• National University of Singapore Mobile IP Working Group
• MosquitoNet, The Mobile Computing Group at Stanford University
• Linux Mobile IP Home Page (temporarily? unreachable)
• The Carnegie Mellon University Monarch Project
• The Portland State University Secure Mobile Networking Project