architecture.txt

Diameter协议栈

related to protocol features. It is responsible for loading
and maintaining configuration data extracted from an XML 
configuration file. It also contains general system facilities required
by the implementation such as logging and timer services. There
are two (2) key facilities provided by the init module that pertains
directly to a scalable and optimized performace of PANA entity. The 
first is a task object. The server design relies heavily
on parallelized execution of all internal functions. This means
that all logical functionality within the server is granulated
into jobs and distributed among threads in the pool for execution. 
Note also that the task object's job queue is a priority queue
and job entries can contain weights. This introduces a primitive
scheduler to the task objects job queue. Care MUST be taken in 
ensuring that no low priority jobs are starved (left in the queue) 
because of to many high priority jobs being enqueued. The number of threads 
within the task object can be controlled via configuration files. 
The second facility is the use of a memory pool. This has the 
effect of minimizing context switching due to system call when 
the PAA request for memory from the system. In addition, it 
provides a more optimal use of memory since it is a re-use algorithm. 

In addition to these generalized services, the init module
also manages interfaces (API's) to entities outside of the PAA. These 
interfaces are required by PANA to operate properly. The 
first of which is the EP interface. Based on the PANA draft,
communication with the PAA and the EP may be based on a
separate protocol (if EP is remote) or an API call (if EP
is co-located). In either case, a generic EP interface MUST
be implemented to shield the init PANA modules from this
diverse linkage. The next interface is the AAA interface which would
allow the PAA to pass EAP traffic to any type of backend
AAA entity. As with the EP interface, a generic AAA interface
MUST be implemented to shield the init PANA modules. In addition,
this interface must allow for the flexibility of one or more
backend AAA entities to exists. Both these interfaces must be
configurable via the configuration file.

A timer queue is also present in the init module. It has it's
own thread that efficiently triggers on the next calculated
timing request for the PANA entity. An independent timer thread
was chosen so as not to produce latency in any timing request.
The handler for an expired timer, however, is still executed 
within the task object thread context.

- Transport Module

The transport module consist of an egress scheduler
(message transmission), and ingress scheduler. The functions 
of each can be described using ingress and egress traffic. 

There exists a listener job to service incomming PANA traffic.
This job performs a blocking read on the libraries UDP socket.
PANA traffic can come either in UDP or multicast forms. In both
cases, once a complete message is received by packet filter, the
message is immediately queued for ingress scheduling. Queueing
is done by passing raw buffered data into the task's job
queue to be picked up by the next available thread. Once it's
processed, the message is parsed into an internal message data
structure. A partial check for validity (See 4.1.6 of the PANA
draft) is made before being queued for processing by the ingress
scheduler. The logical boundary of the transport module is the
ingress scheduler. 

For the egress traffic, all entities within the PAA queues thier
outgoing pre-composed message into the egress scheduler. As with any
other jobs in the software, queueing is done by passing the message
along with the job to the thread pool. The first available thread
would then provide an execution context for the transmission of the
message.

- Session Module

The session module consist of the session resolution, message validation
and state machine hanlders (discovery, authorization and termination handler).
As with the other modules, execution context is provided by the thread pool. 

The session resolution is the boundary of the session module
as seen from the transport module. All PANA traffic is received by 
the session resolution. Messages are parsed messages (from raw buffers) 
passed in by the transport module. The session resolutin makes queries 
to the session database to determine the session object the message 
belongs to. If found, full validation of the message is then made 
(See 4.1.6 of PANA draft). If it passes validation, the messages 
will then be queued to the proper state machine handlers (discover, 
authoriation and termination).

A special case is made for PANA start answer message since a new session 
has to be created for this newly verified client. PANA discover 
messages are passed on to the discovery handler in a stateless manner.
The server does not store state information but merely generates a
cookie based on the Pac device id. On a successful discovery phase,
an attempt is made to add a new session to the session databas 
upon receipt of a valid start answer message.
(See Fig 2. and Fig 3. of Sec. 4.2 of the PANA Draft).

The state machine handlers, implements Sec. 4.2, 4.3, 4.4 and 4.5 
of the PANA Draft.  Details of it's functioning is best describe 
in the draft itself. Note that internal auxiallry functions exists 
in composing egress messages generated by these handlers.  

\image html server_architecture.jpeg
\image latex server_architecture.eps
<B> Figure 1. PANA Server Functional Architecture </B>

Note that the session database is necessary to manage simultaneous 
ongoing peer sessions. It is recommended that a fast access database
structure be used in implementing the session database. Current
implementation uses an Red-Black tree for storing session entries.
The current state plus all other functional data required to maintain
a PANA session will be stored in these session entries. In addtion,
SA (security association) data will also be stored in these entries.

\section client Client Architecture

The client architecture as shown in Fig. 2 is subdivided into the 
following functional modules. Note that this current descriptions
are depiction of the initial design elements and maybe subject to
change in future revisions.

- Core Module

The init module for the Pac is exactly the same as for the PAA. 
All auxillary features such as thread and memory pooling present.
As describe in the server architecture, the excution context for
all logical functions of the Pac will also be provided by the
thread pool. The major differences in the Pac init module is 
that the management of EP and AAA interface is not present. What is
present is an API that exposes the PANA client entity to the system.
(which is also present in the PAA). 

- Transport Module

The transport module of Pac is similar to that of the PAA. The only 
difference is the validation of PANA messages which may have Pac
specific checks. The egress scheduler as well as the ingress scheduler
remains the same. The egress scheduler still functions as a broker for 
transmitting composed PANA messages. It also uses the low level packet 
filters exclusively for sending and receiving PANA traffic. For the 
incomming message processing, the functions are similar to the PAA
except that the received message is passed on immediately to the 
state machine handlers instead of having an additional session resolution
entity. 

- Session Module

The session module is composed simply of the state machine handlers. 
As with the PAA, the state machine handlers is responsible for implementing 
the init PANA functionality as it relates to a Pac. Sec. 4 or the PANA draft 
describes this in detail. However, unlike the PAA session module which has 
a session resolution entity  responsible for matching ingress messages to existing 
sessions, a PANA client entity has at most one active session at any given 
moment (this may change in the future). Message validity checking is done 
by auxillary objects within the state machine handler.  A session database 
does not exist in the PANA client entity. It does not have significant use at 
this time.

\image html client_architecture.jpeg
\image latex client_architecture.eps
<B> Figure 2. PANA Client Functional Architecture </B>

\section build Building, Installing and Running

As noted above, PANA can be built in both windows and linux. Instructions
for both are as follows:

1. Linux/UNIX: There is an autconf script at the root the PANA library
   directory. To build, simply run the configure script, <b>./configure</b>.
   This will check for all necessary third-party libraries and environment
   settings. If configuration is successful, simply run <b>make</b> to build
   the library. Installation can be done by running <b>make install</b> although
   this can be done manually to suit the users environment (i.e. copying
   the source and headers to a directory appropriate for the user).
   You can also run the sample code pana_test1 from a user command line.

2. Win32: Installation under windows consist of a <b>Windows Installer</b>
   program that is downloaded from the distribution site. The windows
   installer currently install only source and header files for PANA 
   plus pre-built binaries (DLL's and sample code only). The installer
   is a standard windows installer that allows you flexibility on the
   target directory where the PANA files will be installed. The installer
   also registers with the <b>Add/Remove Programs</b> list in the windows
   <b>Control Panel</b> for easy removal/re-installation. If you wish to
   rebuild the DLL's and sample code, the use of VC++ 7.1 (.NET 2003) is 
   required. There is a Solutions directory directly under the PANA
   library root. Under this directory, there is a solutions file PANA.sln
   that contains references to all the project files that PANA requires. 
   It also includes the project file for the "Windows Installer" itself. 
   When running VC++ 7.1, you can selectively build whichever target 
   you wish but the base dependencies is the PANA DLL.

\section config Configuration Files

The configuation files for both Pac and PAA are XML based. Most entries
in the configuration file are self explanatory and hence an excerpt of
a sample configuration file are shown here. Note that the difference
between the Pac and PAA configuration is that the Pac has an extra
configuration section. Differences are noted below:

\verbatim

<pana_configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                    xsi:noNamespaceSchemaLocation='config.xsd'>

    <!-- General configuration section
         common to both PAA and Pac -->
    <general>

        <!-- Number of threads to start in the thread pool -->
        <thread_count>5</thread_count>
    
        <!-- PANA UDP listening port -->
        <listen_port>1001</listen_port>
    
        <!-- Interface name to bind the driver to
             For windows, this is the adapter name (i.e. Intel(R) PRO ...)
             For linux, this is the interface name (i.e. eth0, eth1) -->
        <interface_name>Intel(R) PRO/1000 MT Mobile Connection</interface_name>
    
        <!-- Message re-transmission interval -->
        <retransmission_interval>3</retransmission_interval>
    
        <!-- Maximum message re-transmission before error notification -->
        <max_retransmission_count>3</max_retransmission_count>
    
        <!-- Local session lifetime -->
        <session_lifetime>60</session_lifetime>
    
        <!-- Locally configured protection capability -->
        <protection_capability>1</protection_capability>
    
        <!-- Dictionary file used by message parser -->
        <dictionary_filename>dictionary.xml</dictionary_filename>

        <!-- Session resumption flags -->
        <session_resumption>1</session_resumption>

    </general>
    
</pana_configuration>

\endverbatim

<B> Listing 3. PANA PAA sample configuration </B>

\verbatim

<pana_configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                    xsi:noNamespaceSchemaLocation='config.xsd'>

    <!-- General section. Same entries and
         definitions as PAA -->

    <general>

        ....
        ....

    </general>

    <!-- Pac specific session, relevant only
         to Pac entities -->
    <client>

        <!-- Pre-configured IP address of PAA if any -->
        <paa_ip_address>192.168.1.1</paa_ip_address>

        <!-- Pre-configured multicast address of PAA if any -->
        <paa_mcast_address>244.0.0.100</paa_mcast_address>

        <!-- PAA listener port number -->
        <paa_port_number>1001</paa_port_number>
        
    </client>
    
</pana_configuration>

\endverbatim

\section source Source Distribution
 
The current implementation of PANA entities (client and server) involves
support for multiple platforms as stated in Sec. 3 of this document. The
directory structure below shows the outline of the source tree.

\verbatim

PANA_ROOT
    |
   \docs                 # documentation
      \win32             # object files and executables
      \linux             # object files and binaries 
       ...
   \include              # API's for accessing PANA entity from the device 
   \src                  # PANA init source code
      \linux             # Linux specific transport source code
      \win32             # Windows specific transport source code
   \config               # Configuration files
   \drivers              # Packet filtering drivers
   \Solutions            # Solutions directory for VC++ .NET files
       ...

Notes: UNIX autoconf files exist in the PANA_ROOT directory.
       All source code that implements the init PANA functionality resides
       in PANA_ROOT\src. All header files exposed to the system (via DLL
       in windows) are in PANA_ROOT\include. PANA_ROOT\config
       will contain XML configuration files for linux based systems.
       
       For unix systems, autoconf was used to generate makefiles. Therefore,
       you need to run the 'configure' script from builds/$OS directory to
       allow a clean cross compile environment. You may run configure from
       the PANA_ROOT directory but it will distribute the build the binaries
       inside the source directories.

\endverbatim

Note that the include directories exposes the EP interface and the 
AAA interface for PAA and the PANA API for the Pac. RADIUS and
DIAMETER modules (and others) are backend hooks to for the AAA 
interface and allows the PAA to interact with various AAA entities.
These modules are also configurable via entries in the XML configuration
files.

\section bibliography Bibliography

[PANA Draft] D. Forsber, Y. Ohba, B Pati, H. Tschofenig, A. Yegin: "Protocol
for carrying Authentication for Network Access", PANA Working Group Draft,
March 2003

*/