Open Diameter Documentation Page

SourceForge.net Logo


 

 

 

 

 

 

Welcome to the Open Diameter project documentation page ! This site contains a collection of the misc. documentation for the Open Diameter project in sourceforge. The documents reference here are up-to-date as of release version is 1.0.7.

 

Available Documents:

 

 

General documentation for Open Diameter Developers:

 

 

General Installation Notes:

 

    1. GNU g++ versions

 

We have successfully compiled the Open Diameter libraries with the following g++ versions:

 

3.2.1, 3.2.2 and 3.3.1

 

Note that when using a particular version of g++, it is recommended that the ACE library as well as the Xerces C++ library that your linking with is also compile with the same version of g++. If not, then linking errors migth occur. See gcc notes on version compatability issues.

 

    1. Xerces C++ XML Parser

 

Open diameter uses Xerces C++ 2.1.0 and higher. It is recommended that Xerces C++ 2.4.0 is used on non-FreeBSD systems. Version 2.1.0 support is maintained because it is the latest version to have FreeBSD support.

Xerces C++ XML Parser's home is: http://xml.aparche.org/xerces-c

 

Acknowledgment:

This product includes software developed by the Apache Software Foundation (http://www.apache.org/).

 

    1. ACE library

 

Open diameter makes extensive use of the ACE framework including threading, communications, logging etc. The latest ACE version that has been tested with Open Diameter is ACE Release 5.4.0. As of release 1.0.7, ACE 5.4.1 beta kit has not been tested and is not recommended.

 

You can get the source code of the ACE library from: http://www.cs.wustl.edu/%7Eschmidt/ACE.html

 

Acknowledgment:

The members of the Open Diameter project thank the ACE project for developing the ACE library for providing OS independency and useful design patterns.

 

    1. Boost library

 

Beginning version 1.0.4, the use bison and flex for parser generators haved been obsoleted. It has been replaced by the Spirit parser framework contained in the Boost library set. This resolves the frequent compile issues that results from incompatible flex and bison version (which was very restrictive in porting to Windows OS). In addition, the Diameter message parser has made extensive use of the Boost libraries functor defintions as well as other advanced C++ design patterns such as Type2Type template.

 

Boost URL is: http://www.boost.org

 

Compiler Notes: Pls. note that there has been compilation issues with regards to boost and gcc (especially with gcc version older than 3.0.0). For the latest information in compiler version compatibility pls see the boost compiler/build status available in thier website.

 

Acknowledgment: The members of the Open Diameter project thank the Boost library maintainers for providing a robust and extensive collection of library toolsets.

 

 

    1. OpenSSL library

 

It is recommended that you use the latest version of OpenSSL Specifically, a version which includes aes in it's crypto package. In addition, it is required that the OpenSSL libraries has the cipher specifications built into it (i.e. DO NOT use no-cipher parameter in building OpenSSL). This is required by EAP libraries. If building OpenSSL, make sure that the shared libraries version is also build. For win32 systems, OpenSSL has extensive build instructions. You will most likely need active perl or other win32 perl packages to build OpenSSL properly on win32 systems.

Acknowledgment: This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org/).

 

This product includes cryptographic software written by Eric Young (mailto:eay@cryptsoft.com).

 

This product includes software written by Tim Hudson (mailto:tjh@cryptsoft.com).

    1. Autoconf/Automake versions

 

It is recommended that you use the latest version of autoconf and automake. The configure scripts uses later versions of macros calls that might not be present in older versions. The following are tested versions of autoconf and automake.

 

        Autoconf - version 2.57

        Automake - version 1.7.6

 

General Compilation Notes

 

1.      Open diameter libraries

 

As of version 1.0.7, the Open Diameter build will result in eight (8) libraries:

 

        libdiamparser - Diameter message parser

        libdiameter - Diameter base protocol

        libeap - EAP protocol implementation

        libeaparchie - EAP Archie implementation

        libeaptls - EAP TLS implementation (Linux/FreeBSD only)

        libpana - PANA protocol implementation

        libdiametereap - Diameter/EAP library

        libdiameternasreq - Diameter/NASREQ library

Note that libeap-archie and libeap-tls are built inside the libeap directory. The Test programs for each library are also built. To compile libeaptls, specify --with-eap-tls configuration switch when running "configure" command.

 

2.      Supported platforms

 

Open diameter libraries has support for the following OS:

 

        Linux - tested distrubutions include redhat and debian. Kernel version restrictions are dictated by the ACE library.

        FreeBSD - tested versions include 4.8 and 5.0

        Win 2000/XP - The open diameter set of libraries are built as DLL's. Export libraries are provided as well.

 

Build environment

 

Linux/FreeBSD

 

In order to build the open diameter set of libraries, there are a few environment variables that need to be set. This applies to unix systems only.

 

        XERCESCROOT - must be set to the proper Xerces C++ root directory. See Sec. 1.2 for details.

        ACE_ROOT - must be set to the root directory of the ACE installation. This is also required before building ACE. See Sec. 1.3 for details.

        BOOST_ROOT - must be set to the root directory of the boost installation. See Sec. 1.4 for details.

 

To build opendiameter on unix systems, type "./configure" from the open diameter root directory then type "make". After building, the libraries will be located under thier respective directory. Note that as of this writing, only static libraries are built. A complete options list for the configure scripts is located in the INSTALL doc.

 

Win32

 

As of release 1.0.5, building on win32 platforms requires the use of Microsoft .NET 2003 version (VC++ 7.1). A "Solutions" directory has been provided which mimics the Open Diameter directory structur. At the root of the Solutions directory is a .NET solutions object file OpenDiameter.sln). This references all other VC++ 7.1 project files residing in their respective sub-directory. With the use of .NET environment, third-party libraries and include paths can now be set as a .NET environment option. This can be accessed under Tools->Options->Projects->VC++ Directories. Therefore, the include and library paths in each project file does not need to be adjusted. Further details can be found in the docs directory under msvc-solution-usage.txt.

General Usage Instructions

 

The Diameter parser library is maintained in libdiamparser directory. It is a generic AVP based parser that is used by all other libraries under Open Diameter. Valid AVP's and commands are defined inside an XML dictionary file dictionary.xml and it's corresponding DTD dictionary.dtd. As of version 1.0.7, the dictionary files are partitioned on a per protocol basis using the <dictionary> tags. Each <dictionary> tag has a required 'protocol' attribute that dictates which protocol the section belongs too. The following is a table of currently assigned protocol values:

 

        0 - Diameter base protocol

        1 - PANA protocol

 

Future assignments will be made depending on the protocol implementation if it will use libdiamparser. For the diameter base protocol section, there is <base> section which defines base protocol AVP's and commands and an <application> section which defines diameter application AVP's and commands. The <application> section has an id attribute which defines the diameter application id. User applications wishing to add thier own AVP's and commands MUST edit the dictionary file.

 

General Diameter Library Notes

 

For libdiameter, the configuration files are in libdiameter/config. As of version 1.0.7, there has been many changes and additions to the configuration file. Pls. see the sample configuration file config/configuration.xml for details.

 

Sample programs

 

All libraries in Open Diameter maintains a test directory which contains sample programs. The sample code shows how to use the API's for that library. Since, Open Diameter does not currently provide extensive documentation on usage of every API, the sample code is the best source for usage reference.

 

Parser Usage Notes for String Container

 

The libdiamparser relies heavily on the STL string class to represent diameter data types. However, there has been usage issues with regards to c_str() and data() methods of the STL string class. This section is an overview of the recommended usage for these methods. The use of the following examples provide a clear scenario on the issue as it pertains to libdiamparser.

 

rdta->dest_string = source_string->data();

 

and

 

rdata->dest_string = source_string->c_str();

 

Both invocation will give the same result only when the data contained in source_string is null-terminated but in many cases it is not null-terminated when source_string data is set as a result of parseRawToApp() [Both OctetString and UTF8String allows a null character to appear in the middle of the data]. When using c_str(), a null character is prepended at the end of the data but length() value does not change before and after the call to c_str(). Hence, the former example will show an unexpected behavior if the source_string data is not null-terminated. The use of data() in such scenario is not recommended.

 

Top Level Include directory

 

All header files specific to each library are now maintained in each librarie's source and include directory. Each libraries API is located in thier respective include directory. The top level include directory contians a set of headers that are used globally by all libraries and applications. This includes the following:

 

        framework.h - Header file for the Open diameter framework architecture. See Open Diameter C++ framework documentation for details.

        callback_patterns.h - Generic C++ callback patterns used by some libraries

        resultcodes.h - Defines all the diameter base protocol result codes.

Contact Information

 

If you have any questions and comments, please send email to mailto:diameter-developers@lists.sourceforge.net.

 

General information about the mailing list is at: http://lists.sourceforge.net/lists/listinfo/diameter-developers.

 

The Open Diameter Project home page is at: http://www.opendiameter.org.

 

If you have any questions and comments, please send email to the Open Diameter developers' mailing list in sourceforge.

Last updated: June 25, 2004

Copyright (C) 2002-2004, Open Diameter Project