/*!\mainpage Open Diameter Software Architecture\author Victor I. Fajardo\date June 25, 2004This document describes the software architecture used by OpenDiameter for implementing the diameter base protocol library. It is designed to be modular, thread safe and scalable.\section overView OverviewThe architecture of the Open Diameter implementation is based heavilyon the design patterns discussed in [FRAMEWORK] as well as thosedefined in [ACE]. The socket acceptor and connector patterns are borrowed from [ACE] and extended to employ AAAMessage collectiontechniques. In addition, the OS abstraction layer provided by ACE allows for a certain degree of portability. This document will concentrate on the overall architecture of the diameter library.Detailed implementation is not described in this document.  The programming language of choice is C++. It is our intent to takeadvantage of object methodology, widespread familiarity and abundantsupport offered by C++. In addition, a decision was made to utilizestandard C++ libraries to allow for speed of development.  Care has been given to allow the code to be as platform independent aspossible. All system calls are abstracted by an utilities provided byACE. In addition all system calls not covered within the base ACE OSabstraction layer are made as POSIX compliant as possible. \image html architecture.jpeg\image latex architecture.eps<B> Figure 1. Software Architecture </B>The figure above shows a general overview of the implementation.Each box below the API boundary with the exception of the routing engine, is contained within it's own AAA_Job instance.Each box or module is thread independent and are createdon demand. For details on AAA_Job, see [FRAMEWORK]. All databasesare global singleton entities. All of which are thread safe/protectedwith the exception of the configuration database which is a read-onlydatabase.\subsection io Peer with IO ObjectsThe peer objects are instances of diameter peer information as known to the local diameter entity. These instances are generatedbased on the locally configure peer table. Currently, there is nosupport for dynamically learned peers but the model allows itselfto accommodate such feature. In addition to peer information, the IO objects are class abstractions to underlying transports. Thesetransports are defined in [RFC3588] as system specific transports (any of the required or optional transport) that must be used with diameter. The base IO objects defines a specific asynchronous behavior that each of the underlying transport must support. During initialization, instances of the Peer IO objects are created and asynchronous connection attempts to the known peers aremade. The result of this connection attempt will be passed onthe a Peer FSM object associated with this IO object. The IOobject also exposes send and receive functions to the Peer FSMto provide generic IO services to a connected peer.\subsection fsm Peer FSM ObjectsA Peer FSM object implements the peer state machine as describedin Sec. 5.6 of [RFC3588]. It strictly follows all state transitionprocedures including election. Since this object is also contained within an AAA_Job, all state transitions are thread safe and atomicfrom an external point of view. To facilitate election, each FSMobject has references to two (2) Peer IO objects. One for an initiatorand one for a responder. Initiator objects are IO objects thathas successfully completed an asynchronous connection attempt toa peer. Responder objects are IO objects that has been createdby an IO acceptor factory as described below. During election,both of these IO objects maybe active until the result of theelection deactivate one of them. Deactivation will result indeletion of the IO object.\subsection sdelivery Session Delivery ObjectsThe session delivery objects are responsible for deliveringall incomming AAAMessage to a specific AAA session. The messagesthat the Peer FSM Objects have deemed to be incomming sessionmessages are consumed by this object. The session delivery objectdetermines the AAASession object that the message belongs to byquerying the message's session id AVP. The delivery object searchesthe local session database for a matching session. If no matching sessionis found, the delivery object will lookup a matching sessionfactory object that has an application id matching the applicationid of the message. If there is a registered session factory, thenthe delivery object will ask the factory to create a new sessionand delivery the message to the newly created session. If nonof these lookup's are successful, the session delivery objectwill silently discard the message. As with FSM objects, the session delivery objects are derived from AAA_Job hence they are thread independent. \subsection sfsm Session FSM ObjectThe session FSM objects are responsible for implementing theauthorization and accounting state machine as described inDiameter User Session, Sec 8. of [RFC3588]. The user sessionsare all based on AAASession objects defined in the Open DiameterAPI. Dervied objects specializing in client/server authorizationsessions and client/server accounting sessions also exists inthe API definitions. As discussed in the API, session ojbects allowsusers to registering event handlers on a per-session basis. Thesession FSM object is the holder of all registered event handersfor a particular session. The implementation is straight forward and follows Sec 8. of [RFC3588] consistenly. This object is the consumer of all AAAMessage that passed through the session delivery object. After some perfoming pre-processing on each message to update it's internal  state, the Session FSM object will eventually pass all non-base protocol session messages to registered event handlers.As with the Peer FSM objects, this object also derives from AAA_Job and hence it is thread safe. As of this writing, the session objects are still in thier original linear implementation (i.e. only switch statements are used for state transition) and has not been migrated to the the Open Diameter Framework FSM. \subsection sApplication Application Session OjbectsApplication session objects are authorization or accounting objects instantiated by the user or by an session factory onbehalf of the user. These objects are defined in the Open DiameterAPI and used by the user application to interact with the library.Details of these objects are found in the Opne Diameter API.\subsection Routing EngineThe routing engine is documented in discussed in detail in[DIAMETER ROUTING].\subsection Run-time Persistent TablesThe following are run-time persistent tables that exists withinthe diameter library:\li \c Route \c Table Constitute the realm routing table as defined in [RFC3588]. Route entries are discussed in detail in [DIAMETER CONFIG].\li \c Peer \c Table Constitues the peer table as defined in [RFC3588]. Peer table entries are discussed in detail in [DIAMETER CONFIG].\li \c Configuration \c Database Represents a run-time mirror of all configuration entries defined in [DIAMETER CONFIG] with the exception of the route and peer table.\subsection parser Message ParserThe Diameter message parser (libdiamparser) is implemented as a separate library from the library for the Diameter base protocol (libdiameter). Both libraries are common to any client or server authentication application that uses them. The message parser library is a generic message parser that can be used byany protocol with a packet format of a message header with trailingAVP's. Under Open Diameter, the message parser library is usedby other protocols for packet composition and decomposition.In the message parser library, all known AVP's and command codes areloaded into memory during initialization phase via the dictionary filesto construct a runtime dictionary database.  These dictionary files,like configuration files, are XML based. The XML format is well knownand hence very well supported.  Apache's Xerces C++ XML library is usedto parse the dictionary files. Thread protection is not provided in the runtime dictionary database since all access are required to beread-only. The diameter architecture is designed such that a message isalways exclusively processed by a single thread. Ownership ofan AAAMessage is passed on in source-sink model from one AAA_Jobto the next. The data structures used for message parsing are container list AAAAvpContainerList, container AAAAvpContainer and containerentry AAAAvpContainerEntry.  An example pointer chains of thosedata structures are shown in Figure 2.When assembling or disassembling a message, a container is assigned foreach type of AVP and attached to a container list.  Also, a distinctcontainer entry is assigned for each AVP that is included (whendisassembling) or to be included (when assembling) in the message andattached to the container of the corresponding AVP type.  The parentcontainer list needs to be provided by the application.  Whendisassembling a message, either the application or the parser module hasthe responsibility of assignment and attachment of containers, but onlythe parser module has the responsibility of assignment and attachment ofcontainer entries.  On the other hand, when assembling a message,applications have the responsibility of assignment and attachment ofcontainers and container entries.  In any cases, application is the onlyentity that have the responsibility of releasing and detachingcontainers and container entries.Assignment and release of containers and container entries is done viacontainer manager AAAAvpContainerManager and container entrymanager AAAAvpContainerEntryManager, respectively.  Resourcemanagement for containers and container entries is based onpre-allocation (instead of on-demand allocation via malloc() systemcall) in order to avoid frequent memory allocation/deallocation.AVP data in a Grouped AVP is stored in a distinct container list forwhich a pointer is stored in the container entry for the Grouped AVP.In other words, a Diameter message payload and a Grouped AVP is treatedin the same manner.  It is also possible to process nested Grouped AVPsin which a Grouped AVP contains another Grouped AVP as its element AVP.\image html parser_structure.jpeg\image latex parser_structure.eps<B> Figure 2. Diameter Message Payload Parsing Structure</B>Diameter parser defines a template parser class named AAAParserwhich provides a unified way to parse any data structure.  AnyAAAParser class object consists of the following members.\li \c Raw \c Data Less-structured data such as string buffers.\li \c Application \c Data Structured representation of raw data, such as AVP container list.\li \c Dictionary \c Data Data that describes a rule for data conversion  between raw data and application data.  Dictionary data can be null.\li \c Data \c Set/Get \c Functions A set of functions used for setting/getting raw data, application data and dictionary data to/from  the parser.\li \c Message \c Parsing \c and \c Data \c Conversion \c FunctionsA pair of functions used for data parsing and conversion between raw data and  application data. A number of parser classes are defined for parsing different objects including Diameter header, Diameter payload, AVP header and AVP payload of each data type, by specializing the template AAAParser class.\subsection avp Registering New AVP TypesThe diameter parser library defines an API to define a new AVP type anda parser to parse the new type, in addition to the default supported AVPtypes such as Integer32, Unsigned32, OctetString, UTF8String, Groupedand IPAddress.  This feature is particularly important not only fordeveloping new Diameter applications and but also for developing a newprotocol that uses Diameter AVP formats.  PANA (Protocol for carryingAuthentication for Network Access) is an example of the latter case.Registration of a new AVP type can be done via adding a new AVP typeentry called AvpType, where an AVP type entry consists of thefollowing members.\li \c Type \c Name The name of this AVP type.\li \c Type \c Code An integer that is used by the parser library fordistinguishing this AVP type.  The type code must be unique among allthe types in the system.  The type code is used only inside the libraryand never carried in Diameter messages.\li \c Type \c Size The minimum size of the data of this AVP type.  Thisinformation is used for creating an placeholder AVP when a certainclass of error occurs.\li \c Dictionary \c Data Data that describes a rule for data conversionbetween raw data and application data.  Dictionary data can be null.\li \c Parser \c Creator A function object or a functor that is used forcreating a parser class instance that parses the data of the AVP type.\li \c Container \c Entry \c Creator A function object or a functor that isused for creating a container entry that contains the data of the AVPtype.The list of AVPType instances are retained in an AVP type listAAAAvpTypeList, which is a singleton.\subsection thebibliography Bibliography\li \c [ACE] \anchor ace Douglas C. Schmidt, ``The ADAPTIVE CommunicationsEnvironment, An Object-Oriented Network Programming Toolkit forDeveloping Communications Software,'' June 1993.\li \c [RFC3588] \anchor rfc3588 P. Calhoun, et al., ``Diameter Base Protocol,''Request for Comments, Standards Track, September 2003.\li \c [FRAMEWORK] \anchor framework Y. Ohba, ``Open Diameter Framework Architecture,'', January 2004.\li \c [DIAMETER ROUTING] \anchor routing V. Fajardo, ``Open Diameter Routing Architecture,'', June 2004.\li \c [DIAMETER CONFIG] \anchor config . Fajardo, ``Open Diameter Sample Configuration,'', June 2004.*/