\documentclass{article}\usepackage{graphicx}\usepackage{times}\begin{document}\title{Open Diameter Software Architecture}\author{Victor Fajardo and Yoshihiro Ohba}\date{August 26, 2002}\maketitleThis white paper describes the software architecture taken by OpenDiameter in implementing the Diameter base protocol\cite{basep}.  Thisarchitecutre is geared towards achieving a modular, extensible andthread-safe solution for Diameter implementation.\tableofcontents\pagenumbering{arabic}\pagebreak\section{Overview\label{sec:overview}}The architecture of the Open Diameter implementation borrows heavilyfrom the design patterns developed in ACE \cite{ace}. In particular, thesocket acceptor, connector and thread pooling patterns are employed. Inaddition to using ACE based patterns, the OS abstraction layer providedby the ACE library is heavily utilized in this implementation. Thisdocument will concentrate on the overall architecture of the OpenDiameter libraries and detailed implementation is not described in thisdocument.  Especially, the focus will be on the ACE patterns used in theOpen Diameter implementation.\subsection{Programming Language\label{sec:language}}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.  C++ alsobecomes a necessity to support highly preferred development tools suchas ACE which is implemented only in C++.\subsection{Platform/System Support\label{sec:platform}}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. With theintegral use of ACE, supported platforms for the Open Diameter librarywill fall within the supported platforms of ACE.%\section{Diameter Implementation\label{sec:implementation}}\section{Modules and Libraries\label{sec:modules}}The current architecture of Open Diameter software is divided into four(4) logical modules. An application core, a session management module, atransport management module and a message parsing module. These first(3) modules comprise a Diameter base protocol engine and is containedwithin a single library (libdiameter). The message parsing module isimplemented as a separate library (libdiamparser) so that it can be usedfor application programs that utilize AAA services to communicate withthe Open Diameter program by using the Diameter message format.These two libraries are written in C++ and provide the Diameter C++ API\cite{api} to provide applications the functionalities of the Diameterbase protocol \cite{basep}.Figure~\ref{fig:modules} shows the relationship between the logicalmodules and applications.\begin{figure}[htbp]\center{\leavevmode\includegraphics[scale=0.8]{figs/modules.eps}\caption{Diameter Library Modules\label{fig:modules}}}\end{figure}As shown in Figure~\ref{fig:modules}, the Diameter message parserlibrary (libdiamparser) is implemented as a separate library from thelibrary for the Diameter base protocol engine (libdiameter).  Bothlibraries are common to any client or server authentication applicationthat uses them. Details of all logical modules are described in thesucceeding sections.\subsection{Application Core\label{sec:appcore}}The application core is a central storage for all global data and forinitialization and termination services for the entire Diameterlibrary. For each application wishing to use the library, an instance ofthe application core has to be created. This is reflected in the designof the draft API \cite{api}. As shown in Figure~\ref{fig:modules}, whetherthe user application is a client or server authentication application ora mere proxy/relay application, an instance of the application core isrequired. Since an application core is heap based memory, it is possiblein certain cases to create multiple instances of an application coreswithin a single program. However, it is recommended that a singleapplication core be created for each software program since there willbe a likely contentions over the transport level listening ports withwhich each application core needs to listen to.Included in the global data store of the application core are all thestatic data contained in the XML configuration files(Section~\ref{sec:configuration}). The session database, peer serviceswhich houses the peer and routing tables, application subscription listand the factory are all referenced here.  The initialization of theapplication core is achieved via its encompassing class(AAAApplicationCore) as specified in the draft API\cite{api}. Initialization involves startup of the factory (masterthread, Section~\ref{sec:mastert}), loading of configuration files,etc. Termination of the application core would be the symmetric oppositeof the operations in initialization. However, some wait states areneeded in termination to ensure that all existing threads exitsproperly.\subsection{Transport Manager\label{sec:transport}}The transport manager is an integral partner of the applicationcore. Its main responsibility is to maintain connection states withother Diameter peers (which includes recovery) as well as routing anddelivery of Diameter messages. Delivery of local Diameter messages,i.e. those for local sessions, means that the transport managementmodule passes the message to the session manager.With the introduction of ACE communications acceptor/connector pattern,the implementation of the transport manager revolves around ACE servicehandler classes (Section~\ref{sec:peert}). As noted inSection~\ref{sec:peert}, the factory resides in the application core andhence the ACE acceptor and connector object are actually serviced withinthe factory (master thread, Section~\ref{sec:mastert}). A singletonclass acts as initializer and terminator for the transport managementmodule (Section~\ref{sec:peert}). Since connection activity detailsreside within ACE, the service handlers can concentrate on the mainfunctions that the transport manager is responsible for.As shown in Figure~\ref{fig:modules}, in using the Diameter library, thetransport management module will always be required by the applicationcore no matter what type of application uses the library. Since there isno need for the application to interact with this module the draft API\cite{api} has no direct reference to this module. It is a hidden yetintegral module which all upper level modules require.\subsection{Session Manager\label{sec:session}}The session management module is responsible for storing and maintainingDiameter sessions for client/server authentication application using theDiameter library. A red-black tree serves as a database of sessionskeyed by session id's \cite{basep}. Each session stores the currentsession state, active timers and other session relatedinformation. Since an application relates to the Diameter library viasessions, the draft API \cite{api} exposes necessary functionality inmanipulating a session. It also relates transmission of messages fromthe an application via an existing session hence associate everyapplication generated message will be associated with a session.As noted in Section~\ref{sec:pool}, the execution context of thesession manager is based upon a thread pool. So each session in thedatabase also contains a job queue that enables the thread pool toserially execute all the necessary events for a given session. Thesession database itself as well as the job queues(Section~\ref{sec:session}) for each session is protected by mutexlocks. As noted in Section~\ref{sec:appcore}, the session database ispart of the application core but the underlying methods and functions tomaintain the state of each session are in the session managementmodule. Interaction between session manager and transport manager isdiscussed in detail in Section~\ref{sec:msgtransport}.\subsection{Message Parser\label{sec:msgparser}}The message parser module is used for parsing Diameter messagesincluding header and payload, where the payload part is consist of Diameter AVP(s).In the message parser module, 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. It is open source library which isheavily utilized in the apache web environment.  Extendibility of thedictionary will be provided with the use of XML.Mutual exclusion protection is not necessary for the runtime dictionarydatabase despite serving a threaded environment since all access to it'sruntime database is read-only.\section{Threaded View of the Architecture\label{sec:architecture}}The threaded view of the entire architecture for the Open Diameterimplementation is shown in Figure~\ref{fig:architecture}.\begin{figure}[htbp]\center{\leavevmode\includegraphics[scale=0.8]{figs/architecture.eps}\caption{Threaded View of Open Diameter Architecture\label{fig:architecture}}}\end{figure}As shown in the Figure~\ref{fig:architecture}, the execution context for