architecture.txt

Diameter协议栈

/* BEGIN_COPYRIGHT                                                        */
/*                                                                        */
/* Open Diameter: Open-source software for the Diameter and               */
/*                Diameter related protocols                              */
/*                                                                        */
/* Copyright (C) 2002-2004 Open Diameter Project                          */
/*                                                                        */
/* This library is free software; you can redistribute it and/or modify   */
/* it under the terms of the GNU Lesser General Public License as         */
/* published by the Free Software Foundation; either version 2.1 of the   */
/* License, or (at your option) any later version.                        */
/*                                                                        */
/* This library is distributed in the hope that it will be useful,        */
/* but WITHOUT ANY WARRANTY; without even the implied warranty of         */
/* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU      */
/* Lesser General Public License for more details.                        */
/*                                                                        */
/* You should have received a copy of the GNU Lesser General Public       */
/* License along with this library; if not, write to the Free Software    */
/* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307    */
/* USA.                                                                   */
/*                                                                        */
/* In addition, when you copy and redistribute some or the entire part of */
/* the source code of this software with or without modification, you     */
/* MUST include this copyright notice in each copy.                       */
/*                                                                        */
/* If you make any changes that are appeared to be useful, please send    */
/* sources that include the changed part to                               */
/* [e-mail] so that we can reflect your  */
/* changes to one unified version of this software.                       */
/*                                                                        */
/* END_COPYRIGHT                                                          */
/*! 

\mainpage PANA Functional Architecture 
\author Victor I. Fajardo
\date July 21, 2004

The document is a architectural overview of the TARI 
implementation of PANA. This implementation currently 
adheres to existing PANA related drafts and will 
continue it's evolution as dictated by the drafts.

\section contents Overview Contents

-  Language
-  Tools
-  Platform Support
-  PANA API
-  Server Architecture
-  Client Architecture
-  Building, Installing and Running
-  Configuration Files
-  Source Distribution

\section language Language 

C++ is used to allow an object oriented design approach.
This also accomodates the preferred toolset used.

\section tools Tools

The following are tools used in the implementation:

- ACE Frameworks ver 5.3 April 2003
  (http://www.cs.wustl.edu/~schmidt/ACE.html)
- Xerces C++ XML lib, ver 2.2.0 April 2003
  (http://xml.apache.org/xerces-c/index.html)

ACE allows implementation of complex communications
and general software patterns. This package allows 
abstractions to threading, synchronization, queueing,
logging and other generalized implementation needs that
would otherwise have to be re-invented. Although, the PANA 
does not require complex communications architecture, the 
overall coverage of ACE beyond communication needs 
significantly eases the implementation efforts. This holds 
true especially when supporting multiple platforms (windows, 
unix, etc.) since cross platform compatability has already
been addressed by this toolset. Therefore, this allows 
developers to concentrate on the init PANA functionality. 

Currently, the chosen method for static configuration
storage is an XML file. This may change in the future. The design
allows for this flexibility since the configuration formats
is dictated by the internal data structures. Hence, the 
only required change would be the internal population of these
structures which can easily be segragated via a single
object interface. As of this writing, the backend implementation
for this interface is based on Xerces C++. It is used for parsing 
and loading the XML configuration file. This package has both
SAX and DOM based API's. The PANA implementation uses DOM.

\section platform Platform Support 

PANA protocol entities will be required to exists in different
platforms. The most likely of which are UNIX and Windows.

The Pac PANA entity has a high probability of residing under
a windows environment since the predominant client devices are
running unders a windows platform (Windows CE for PDA's, XP/NT/Win9X
flavors for tablets or desktops). In the PANA draft 3 specification,
it is assumed that PANA will operate with a valid IP address. Hence,
the unspecified IP support in previous implementation has now been
deprecated. There is no longer a need for NDIS based drivers for
windows or raw socket support in UNIX systems. There are still
system calls to query configuration of network interfaces but
they will require only user level system calls.

For the PAA, a server environment with the proper scalable capabilities
are required. The PANA server entity are also required to execute in 
privileged mode specifically because of it's interaction with
the EP as well as backend AAA entities. The most probable approach is to 
implement PAA as a "server/backend" processes specific to each platform.


\section api PANA API

The PANA API model is geared towards interacting with EAP modules.
The current PANA implementation does not have dependencies to
any single EAP implementation but rather defines an API that
will interface to any EAP implementation.

The PANA API is a simple session based API model. It comprises 
generally of two (2) C++ class definitions that users can instantiate.
These are PANA_Node, PANA_PacSession. Also, required are two (2) C++ 
classes that users must derived from. These are PANA_ClientEventInterface
and PANA_PaaEventInerface. These event interfaces follow a bridge or
abstract pattern implemenation. The PANA_PaaSession can also be inherited
by users depending on what is being accomplised. The PANA_Node instance
is required for all applications. For sessions, depending on whether 
an entity will behave as a Pac or a PAA, instantiaton follows 
different patters. These are as follows:

- Pac Session Pattern

A Pac session pattern is straight forward. A PANA_Node and PANA_PacSession
instance is required. An instance of the derived class is required for
each PANA Pac session. Each instance is required to register a user class
derived from PANA_ClientEventInterface. This class overrides event
handlers invoked by the PANA library. The following is an excerpt of the sample code which better describes the Pac API:

\verbatim

class PeerApplication : public PANA_ClientEventInterface
{
 public:
  PeerApplication(PANA_Node &n) : pacSession(n, *this),
    handle(EapJobHandle(AAA_GroupedJob::Create(n.Task().Job(), this, "peer"))),
    eap(boost::shared_ptr<MyPeerSwitchStateMachine>
	(new MyPeerSwitchStateMachine(*n.Task().reactor(), handle))),
    md5Method(EapContinuedPolicyElement(EapType(4)))
  {
    eap->Policy().CurrentPolicyElement(&md5Method);
  }
  virtual ~PeerApplication()  {
    pacSession.Stop();
  }
  void Start()
  { 
    pacSession.Start();
    eap->Start(); 
  }

  MyPeerSwitchStateMachine& Eap() { return *eap; }

  // called by PANA on incomming EAP request
  void EapRequest(AAAMessageBlock *request,
                  PANA_PINFO provider,
                  const PANA_CfgProviderInfo *pInfo) {     
     eap->Receive(request);
  }
  // called by PANA on incomming BIND request
  void EapRequest(AAAMessageBlock *request,
                  ACE_UINT32 resultCode,
                  ACE_UINT32 pcap) {
     eap->Receive(request);
  }
  // called by PANA on authorization of a peer 
  void Authorize(PANA_AuthorizationArgs &args) { 
      // contents of args is as follows:
      // typedef struct {
      //   AAA_ScholarAttribute<PANA_DeviceId> m_Paa;
      //   AAA_ScholarAttribute<PANA_DeviceId> m_Pac;
      //   AAA_ScholarAttribute<diameter_octetstring_t> m_Key;
      //   AAA_ScholarAttribute<ACE_UINT32> m_KeyId;
      //   AAA_ScholarAttribute<ACE_UINT32> m_Lifetime;
      //   AAA_ScholarAttribute<ACE_UINT32> m_ProtectionCapability;
      //   AAA_ScholarAttribute<PANA_DeviceId> m_Ep;
      //   AAA_ScholarAttribute<diameter_octetstring_t> m_DhcpKey;
      // } PANA_AuthorizationArgs;
  }
  // called by PANA on re-authentication request
  void ReAuthentication() { }
  // called by PANA on termination sequence
  void Disconnect(ACE_UINT32 cause) { }
  // called by PANA on session timeout
  void Timeout() { }
  // called by PANA on internal error or error message
  void Error(ACE_UINT32 resultCode) { }

 private:
  PANA_PacSession pacSession; // insance of PANA Pac
  EapJobHandle handle;
  boost::shared_ptr<MyPeerSwitchStateMachine> eap;
  EapContinuedPolicyElement md5Method;
};

\endverbatim

<B> Listing 1. PANA Pac API sample </B>

- PAA Session Pattern

The PAA session pattern is similar to the Pac except that the
derived auth agent objects are generated by a factory. As with the 
Pac, applications MUST derive from PANA_PaaEventInterface class and
provide application specific handlers for each session event.
The difference is in instantiation of PANA_PaaSession or classes
derived from it. PANA_PaaSession or classes derived from it MUST 
not be instantiated manually by the application but rather passed 
on as a template parameter to PANA_PacSessionFactoryAdapter<> class
or other forms of it. This class is responsible for creating instance 
of the PANA_PaaSession based object based on demand.

The following is an excerpt of the sample code which better describes
the Pac API:

\verbatim

class StandAloneAuthApplication : public PANA_PaaEventInterface
{

 public:
  StandAloneAuthApplication(PANA_Node &n) 
    : paaSession(n),
      handle(EapJobHandle(AAA_GroupedJob::Create(n.Task().Job(), this, "standalone"))),
      eap(boost::shared_ptr<MyStandAloneAuthSwitchStateMachine>
	  (new MyStandAloneAuthSwitchStateMachine(*n.Task().reactor(), handle))),
      identityMethod(EapContinuedPolicyElement(EapType(1))),
      md5Method(EapContinuedPolicyElement(EapType(4))),
      notificationMethod(EapContinuedPolicyElement(EapType(2)))
  {
    // start paa session
    paaSession.Start();
    // Policy settings for the authenticator
    identityMethod.AddContinuedPolicyElement
      (&md5Method, EapContinuedPolicyElement::PolicyOnSuccess);
    identityMethod.AddContinuedPolicyElement
      (&notificationMethod, EapContinuedPolicyElement::PolicyOnFailure);
    eap->Policy().CurrentPolicyElement(&identityMethod);
  }
  virtual ~StandAloneAuthApplication() {
    paaSession.Stop();
  }

  // called by PANA on accepting initial PANA start answer from peer
  void EapStart() {
     eap->Start();
  }
  // called by PANA on incomming EAP response
  void EapResponse(AAAMessageBlock *response, bool separate) { 
     eap->Receive(response);
  }
  // called by PANA on authorization of a peer 
  void Authorize(PANA_AuthorizationArgs &args) { 
      // contents of args is as follows:
      // typedef struct {
      //   AAA_ScholarAttribute<PANA_DeviceId> m_Paa;
      //   AAA_ScholarAttribute<PANA_DeviceId> m_Pac;
      //   AAA_ScholarAttribute<diameter_octetstring_t> m_Key;
      //   AAA_ScholarAttribute<ACE_UINT32> m_KeyId;
      //   AAA_ScholarAttribute<ACE_UINT32> m_Lifetime;
      //   AAA_ScholarAttribute<ACE_UINT32> m_ProtectionCapability;
      //   AAA_ScholarAttribute<PANA_DeviceId> m_Ep;
      //   AAA_ScholarAttribute<diameter_octetstring_t> m_DhcpKey;
      // } PANA_AuthorizationArgs;
  }
  // called by PANA on re-authentication request
  void ReAuthentication() { }
  // called by PANA on termination sequence
  void Disconnect(ACE_UINT32 cause) { }
  // called by PANA on session timeout
  void Timeout() { }
  // called by PANA on internal error or error message
  void Error(ACE_UINT32 resultCode) { }

  //  MyEapStandAloneAuthSession& Eap() { return eap; }
  MyStandAloneAuthSwitchStateMachine& Eap() { return *eap; }

  PANA_PaaSession &paa() { return paaSession; }

 private:
  PANA_PaaSession paaSession; // PAA session
  EapJobHandle handle;
  boost::shared_ptr<MyStandAloneAuthSwitchStateMachine> eap;
  EapContinuedPolicyElement identityMethod;
  EapContinuedPolicyElement md5Method;
  EapContinuedPolicyElement notificationMethod;
};

class StandAloneSessionFactoryAdapter : public PANA_PaaSessionFactory
{
   public:
      StandAloneSessionFactoryAdapter(PANA_Node &n) :
	PANA_PaaSessionFactory(n), node(n) { }
      // virtual abstract method that needs to be implemented by the user
      PANA_PaaSession *Create() {
         StandAloneAuthApplication *app = new StandAloneAuthApplication(node, sem);
         if (app) {
	    return &(app->paa());
	 }
         return (0);
      }
   protected:
      PANA_Node &node;
};

\endverbatim

<B> Listing 2. PANA PAA API sample </B>

\section server Server Architecture

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

- Core Module
This contains general process specific objects not necessarily