eap_fsm.hxx

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                                                          */
// $Id: eap_fsm.hxx,v 1.42 2006/03/16 17:01:51 vfajardo Exp $

// eap_fsm.hxx:  header file for EAP finite state machine
// Written by Yoshihiro Ohba

#ifndef __EAP_FSM_HXX__
#define __EAP_FSM_HXX__

#include <ace/Basic_Types.h>
#include <ace/Singleton.h>
#include <ace/Synch.h>
#include <ace/Event_Handler.h>
#include <list>
#include <utility>
#include "framework.h"
#include "eap.hxx"
#include "eap_log.hxx"
#include "eap_policy.hxx"

typedef AAA_JobHandle< AAA_GroupedJob > EapJobHandle;

/// This class defines a job that are used by both switch state
/// machine and method state machine to schedule an event.  The
/// scheduling is based on storing a pointer to state machines which
/// themself are jobs to be multiplexed by this class object.
class EapJobMultiplexor : public AAA_JobQueueJob
{
 public:
  EapJobMultiplexor(EapJobHandle& h) : handle(h)
  {}
  ~EapJobMultiplexor() { handle.Job().Remove(this); }

  void Flush()
  {
    AAA_JobQueueJob::Flush();
    handle.Job().Remove(this);
  }

  int Serve() 
  {
    if (!ExistBacklog())
      {
	EAP_LOG(LM_ERROR, "%N: no backlog to serve.");
	return 0;
      }

    AAA_Job *job = 0;
    Dequeue(job);
    bool existBacklog = ExistBacklog();
    job->Serve();
    return existBacklog;
  }

  // Reimplementedf from AAA_JobQueueJob
  int Schedule(AAA_Job* job, size_t=1)
  {
    Enqueue(job);
    return handle.Job().Schedule(this);
  }

  inline AAA_JobData& JobData() { return *handle.Job().Data(); }

  template <class T> inline T& JobData(Type2Type<T>) 
  { return (T&)*handle.Job().Data(); }

 private:

  /// Job handle.
  EapJobHandle handle;
};

/// The functional model of EAP devides the protocol task into a part
/// that is commonly performed independent of any EAP authentication
/// method and a part that is specific to eap EAP authentication
/// method.  The former and the latter parts are refered to as
/// "switch" and "method", respectively.  State machines defined to
/// run switches and methods are refered to as <b>switch state
/// machines</b> (see \ref switchStateMachine) and <b>method state
/// machines</b> (see \ref methodStateMachine), respectively.  Both
/// switch and method state machines have the same EapStateMachine
/// structure in common.
template <class ARG>
class EapStateMachine : 
  public AAA_StateMachineWithTimer<ARG>, 
  private AAA_EventQueueJob
{
 public:
  /// Constructor.
  EapStateMachine(ARG& arg, AAA_StateTable<ARG> &table, ACE_Reactor &r, 
		  EapJobMultiplexor &mux, char *name=0)
    : AAA_StateMachineWithTimer<ARG>(arg, table, r, name),
      mux(mux)
  {}
  
  void Stop()
  {
    AAA_StateMachineWithTimer<ARG>::Stop();
    mux.Flush();
  }

  /// Inherited from AAA_EventQueueJob.
  inline int Serve()
  {
    // Obtain the event to execute.
    AAA_Event ev = 0;
    AAA_EventQueueJob::Dequeue(ev);

    bool existBacklog = AAA_EventQueueJob::ExistBacklog();

    // Execute it.
    AAA_StateMachineWithTimer<ARG>::Event(ev);
    return existBacklog ? 1 : 0;
  }

  /// Reimplemented from parent class.
  inline void Timeout(AAA_Event ev) { Notify(ev); }

  // Store an event and notify the session.  An integer -1 is thrown
  // when job scheduling fails.
  inline void Notify(AAA_Event ev) throw (int) {
    // Enqueue the event.
    if (AAA_EventQueueJob::Enqueue(ev) <= 0)
      throw -1;

    // Schedule me to the mux.
    if (mux.Schedule(this) < 0)
      throw -1;
  }

 private:

  int Schedule(AAA_Job*, size_t=1) { return (-1); }  // Not used.

  EapJobMultiplexor& mux;
};

typedef ACE_Message_Queue<ACE_MT_SYNCH> EapMessageQueue;

/// Forward declarations
class EapMethodStateMachine;

/*! \page switchStateMachine Switch State Machine

There are two types of switch state machines, <b>peer switch state
machine</b> and <b>authenticator switch state machine</b>.  Both peer
and authenticator state machines have the following attributes in common.

- A <b>method state machine</b> (see \ref methodStateMachine).

- An authentication policy that is used for creating a method state
machine of a particular EAP (authentication) method and describes
rules on how and by which order each (authentication) method is
performed to complete an EAP conversation.  Authentication policy is
explained in \ref authpolicy.

- A set of callback functions that are defined by applications and
called when the switch state machine needs to pass an asynchrounous
event and optional information associated with the event to the
applications.  The callback functionality is described in \ref
callback.

In the libeap library, a method state machine is defined as an
attribute of a switch state machine.

 */
/// The base class for switch state machines.
class EAP_EXPORTS EapSwitchStateMachine : public EapJobMultiplexor
{
public:

  /// Called by any switch or method state machine.
  virtual void Notify(AAA_Event ev)=0;

  /// This callback function is called when a message other than
  /// Success/Failure is sent from the session.  If further processing
  /// for the message is performed in other threads, the application
  /// must make a duplication of the message via
  /// AAAMessageBlock::Acquire(AAAMessageBlock*) so that the API will
  /// not release the message allocation until reference count becomes 0.
  virtual void Send(AAAMessageBlock *b)=0;

  /// This callback function is called when there is an internal error
  /// in a state machine.  The default action is to exit the program.
  /// Applications can replace the default behavior with more
  /// appropriate behavior such as deleting the errornous session.
  virtual void Abort()=0;

  /// Call this function to get the current method.
  inline EapType& CurrentMethod() { return currentMethod; }

  /// This function is called by EAP carrier protocol to input EAP message.
  virtual void Receive(AAAMessageBlock*)=0;

  /// This function is called by AAA protocol on passthrough
  /// authenticator to input EAP message.
  virtual void ReceiveFromAAA(AAAMessageBlock *msg) throw(int)
  {
    EAP_LOG(LM_ERROR, "ReceiveFromAAA Operation not allowed.");
    throw -1;
  }

  /// Call this function to get the currentIdentifier.
  inline ACE_Byte& CurrentIdentifier() { return currentIdentifier; }

  /// Call this function to get the pointer of rxMessage.  This
  /// function is typically called by switches.

  inline AAAMessageBlock* GetRxMessage() {return rxMessage; }

  /// Call this function to set the pointer to rxMessage.  This
  /// function is typically called by methods.
  inline void SetRxMessage(AAAMessageBlock *p) { 
    if (rxMessage) rxMessage->release();
    rxMessage=p; 
  }

  /// Call this function to delete rxMessage.  This function is