INTERNET DRAFT James Kempf
Category: Informational Pat Calhoun
Title: draft-kempf-diameter-api-03.txt David Frascone
Date: November 2000 Sun Microsystems, Inc.
The DIAMETER API
Status of this Memo
This document is an individual contribution for consideration by the
AAA Working Group of the Internet Engineering Task Force.
Distribution of this memo is unlimited.
This document is an Internet-Draft and is in full conformance with
all provisions of Section 10 of RFC2026. Internet-Drafts are working
documents of the Internet Engineering Task Force (IETF), its areas,
and its working groups. Note that other groups may also distribute
working documents as Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at:
http://www.ietf.org/ietf/1id-abstracts.txt
The list of Internet-Draft Shadow Directories can be accessed at:
http://www.ietf.org/shadow.html.
Copyright (C) The Internet Society 2000. All Rights Reserved.
Abstract
The Diameter authentication, authorization, and accounting (AAA)
protocol provides support for peering AAA transactions across the
Internet. This document describes a standardized API for the Diameter
protocol. The API is defined in both the C and Java languages. In
addition, a standardized file format is described for some Diameter
configuration data. The intent of the API and standardized file
Kempf, Calhoun, Frascone expires June 2001 [Page 1]
INTERNET DRAFT December 2000
formats is to foster source code portability across multiple
programming platforms.
Table of Contents
1.0 Introduction
2.0 Configuration File Formats
2.1 Basic File Format
2.2 Defined Configuration Files
2.2.1 Global Configuration File
2.2.2 Vendors File
2.2.3 Dictionary File
2.3 Examples
2.3.1 Example Global Configuration File
2.3.2 Example Vendors File
2.3.3 Example Dictionary File
2.4 Processing Configuration Files
3.0 Binding Independent Considerations
3.1 Multithreading
3.2 Error Reporting
3.3 String Format
3.4 Handling Connections with Other Servers/Peers
3.5 Callback Processing Order
4.0 C API
4.1 Constant Types
4.1.1 IP Address and Port
4.1.2 Command Code
4.1.3 Vendor Identifier
4.1.4 Extention Identifier
4.1.5 Attribute/Value Pair Code
4.1.6 Value Type Identifier
4.1.7 Server Type
4.1.8 Session Identifier
4.1.9 Message Identifier
4.1.10 Callback Handle
4.1.11 Application Identifier
4.1.12 API Return Codes
4.1.13 Callback Location Codes
4.1.14 AVP Data Type Codes
4.1.15 AVP Flags
4.1.16 Domain Interconnection Types
4.1.17 Message Flags
4.1.18 Result Codes
4.1.19 Search Direction Type
4.2 Structure Definitions
4.2.1 Dictionary Entry Definition
4.2.2 AVP Definition
4.2.3 AVP List
Kempf, Calhoun, Frascone expires June 2001 [Page 2]
INTERNET DRAFT December 2000
4.2.4 Message Definition
4.3 Macros and Preprocessor Definitions
4.4 Functions
4.4.1 Initialization and Configuration
4.4.2 Registering Commands
4.4.3 Session and Server Management
4.4.4 Dictionary Lookup
4.4.5 Message Management
4.4.6 Message Control
4.5 Implementation Notes
4.5.1 Avoiding AVP Copying
5.0 Java API
5.1 Errors and Exceptions
5.1.1 Class AAAException
5.2 Library Management and Dictionary Management
5.2.1 Class AAA
5.2.2 Class AVPDictionary
5.2.3 Class AVPDescriptor
5.2.4 Class AVPValue
5.2.5 Interface AAAListener
5.2.6 Class AAACommandDescriptor
5.2.7 Class AAAExtension
5.3 Messages and AVPs
5.3.1 Class AAAMessage
5.3.2 Class AVP
5.3.3 Class EncapsulatingAVP
5.4 Session Management
5.4.1 Class AAASessionManager
5.4.2 Class UnsolicitedMessageListener
6.0 Security Considerations
7.0 References
8.0 Authors' Addresses
9.0 Full Copyright Statement
A. List of changes from -00
1.0 Introduction
The Diameter authentication, authorization and accounting (AAA)
protocol provides scalable AAA support for peering transactions
across the Internet [1] [2]. This document describes standardized
APIs in C and Java for applications to access the Diameter protocol.
A standardized configuration file format is also defined for some
configuration data. The intent of the API and standardized file
formats is to foster source code portability across multiple
programming platforms. While a standardized API is not strictly
necessary for protocol interoperability, it does help to promote the
use and deployment of a protocol by reducing the amount of work
Kempf, Calhoun, Frascone expires June 2001 [Page 3]
INTERNET DRAFT December 2000
necessary to develop and access applications that use the protocol.
The Diameter protocol provides a basic attribute/value pair (AVP)
data format, which particular application profiles extend. Processing
of the extensions is handled by code specific to the application
profile. Application profile customizability is reflected into the
API as callback functions for C. The callbacks implement the
application profile processing for incoming messages. For outgoing
calls, the C API provides an asynchronous model, leaving processing
of the return message to the callbacks. In the Java API, the
outgoing message and incoming reply are processed synchronously, and
there are no callbacks. The application code is responsible for
processing the returned message. The design of the C API facilitates
implementation of extensible Diameter servers because asynchronous
message processing allows handling of unsolicited messages. The
design of the Java API is more conducive to clients, because
synchronous message processing is easier for clients to handle.
For the most part, the API hides the details of establishing peering
connections, parsing and unparsing Diameter messages, and other work
necessary to set up and maintain a peering session. The application
profile code need only be concerned with processing of the AVPs
defined in the application profile. The configuration file helps
automate DIAMETER parameter configuration by removing the need for
the application code to deal with commonly exchanged DIAMETER
configuration parameters.
The next section describes the configuration file format. The format
is based on the standard Microsoft .INI initialization file format
[3], which is simple to edit and parse. Section 4 contains the C API,
while Section 5 contains the Java API.
2.0 Configuration File Format
The primary purpose of the file format is to allow AVPs and vendor
definitions to be portably exchanged. An additional use is to provide
library implementations that use files to initialize configurations
with a standardized format.
In general, there is a wide variety of data that can potentially be
involved in configuring a Diameter peering server. Examples include:
- Allowable peering clients,
- Domains with which the server can connect,
- Diameter extension libraries,
Kempf, Calhoun, Frascone expires June 2001 [Page 4]
INTERNET DRAFT December 2000
- A public key ring,
- A private key ring,
- A list of standardized Diameter AVPs and values,
- A list of identified vendors with vendor extensions.
Of these, the first four are likely to be very platform specific in
how they are represented. The last two, the list of defined Diameter
AVPs and values and the list of identified vendors with vendor
extensions, contain configuration data that represents application
profile extensions to Diameter. For interoperability reasons,
application profile extensions are likely to be subject to
standardization, and therefore having a standardized file format
whereby applications on different platforms can exchange
configuration data seems appropriate. We therefore define a
dictionary file for standardized Diameter AVPs and values, and a file
for identified vendors. We also define a global configuration file
that contains the names of the dictionary and vendor files, plus any
implementation specific configuration information. The global
configuration file is required as a parameter to the API operations
that open and initialize the DIAMETER library.
2.1 Basic File Format
The basic file format follows the .INI initialization format used in
Microsoft Windows 3.1 [3]. This format is easy to parse and easy for
a human to edit. The basic file format defined in ABNF notation [4]
is as follows:
file = section / section NL file
section = header plist
header = "[" htag "]" NL
htag = ; File dependent, see Section 2.2.
plist = cparam / cparam plist
cparam = ; File dependent, see Section 2.2.
ws = *WS
tag = 1*stdchar
stdchar = ALPHA / DIGIT / "-"
numeric-id = "1" / "2" / "3" / "4" / "5" / "6" / "7" / "8" / "9"
*DIGIT
NL = CRLF / LF
Comments start with a "#" and can be included at any position on a
line. The parser reads all characters between "#" and the end of the
line as a comment. Tags are case insensitive, but most values are
Kempf, Calhoun, Frascone expires June 2001 [Page 5]
INTERNET DRAFT December 2000
not. The exceptions are the Diameter type names and the Boolean
constants "true" and "false", which are not case sensitive.
2.2 Defined Configuration Files
Three standardized configuration files are defined:
- A global configuration file including the dictionary and vendor
files and any other configuration information required of the
implementation.
- A configuration file for defined vendors,
- A dictionary file for AVP and value definitions,
2.2.1 Global Configuration File
The global configuration file has only a single required section,
"General". Other sections are optional. Depending on the
implementation, there may be additional sections, or additional
cparam definitions in General. Here are the required definitions for
the global configuration file:
htag = "General"
cparam = dictionary-file-param / vendor-file-param
dictionary-param = ws "dictionary-file" ws "=" ws filepath
vendor-file-param = ws "vendors-file" ws "=" ws filepath
filepath = ; File pathname for the respective file.
The global configuration file is used as a parameter to the API
operations that open and initialize the AAA library.
2.2.2 Vendors File
The vendors file contains vendor definitions for those vendors that
have registered vendor extensions to DIAMETER. The vendors file
assures that all applications implementing the standardized API have
access to the vendor codes and names. Here are the definitions for
the vendors file:
htag = vendor-name-tag
vendor-name-tag = tag
cparam = vendor-id-param / vendor-name-param
vendor-id-param = ws "vendor-id" ws "=" ws vendor-id-value
vendor-id-value = numeric-id
Kempf, Calhoun, Frascone expires June 2001 [Page 6]
INTERNET DRAFT December 2000
vendor-name-param = ws "vendor-name" ws "=" ws vendor-name-value
vendor-name-value = "
The Vendor-Id tag defines a numeric vendor identification number
assigned to the vendor
2.2.3 Dictionary File
The dictionary file consists of sections that either define an AVP or
a value. Some of the AVPs and values may be vendor extentions, and
these are identified by a vendor extension tag.
2.2.3.1 AVP Definitions
AVP definitions have the following format:
htag = "AVP" 1*WS avp-name
avp-name = tag / vendor-tag-name
vendor-tag-name = tag "." tag
cparam = avp-value-param / avp-type-param / avp-encrypt-param
avp-value-param = ws "value" ws "=" ws numeric-id
avp-type-param = ws "type" ws "=" ws type-name
avp-encrypt-param = ws "encrypt" ws "=" boolean
boolean = "true" / "false"
type-name = "Data" | "String" | "Address" | "Integer32" |
"Integer64" | "Time" | "Complex"
Note that boolean and type-name are not case sensitive.
2.2.3.2 Value Definitions
Value definitions have the following format:
htag = "value" 1*WS value-name
value-name = tag / vendor-tag-name
vendor-tag-name = tag "." tag
cparam = ws value-name ws "=" value
value-name = tag
value = ; String containing a value of one of the standard Diameter
; types, see [1].
2.3 Examples
This section contains a few example files to illustrate the format.
Kempf, Calhoun, Frascone expires June 2001 [Page 7]
INTERNET DRAFT December 2000
2.3.1 Example Global Configuration File
In the following global configuration file, the vendors file is in
/etc/aaa/vendors.cfg and the AVP dictionary is in
/etc/aaa/dictionary.cfg. Note that these names are just examples,
the actual names will be platform specific:
[General]
Dictionary-File = /etc/aaa/vendors.cfg
Vendors-File = /etc/aaa/dictionary.cfg
2.3.2 Example Vendors File
The following is an example of a vendor file:
[Luna]
Vendor-Name = "Luna Microsystems, Inc."
Vendor-Id = 42
[Joes-Fly-By-Nite]
Vendor-Name = "Joe's Fly By Nite, LLP"
Vendor-Id = 666
2.3.3 Example Dictionary File
The following is an example of a dictionary file:
[AVP User-Name]
Value = 1
Type = string
[AVP NAS-IP-Address]
Value = 2
Type = address
[AVP NAS-Port]
Value = 3
Type = integer32
[AVP Encrypted-Payload]
Value = 5
Type = data
[Value Source-Port]
ftp = 23
Kempf, Calhoun, Frascone expires June 2001 [Page 8]
INTERNET DRAFT December 2000
telnet = 21
[Value Luna.Location]
Copernicus-Crater = 1
Hadilley-Rille = 2
In this case, Luna.Location is a vendor specific value.
2.4 Processing Configuration Files
Compliant implementations are expected to process configuration files
prior to accepting any AAA requests. Errors in processing of
configuration files should be reported using the logging technique
appropriate to the platform. The AAA library initialization functions
require the name of a global configuration file to be passed, but
also provide a means of discovering the default global configuration
file name for the platform. This allows API clients to default the
configuration file name, or provide a custom name for testing and
other purposes.
3.0 Binding Independent Considerations
This section discusses a number of implementation considerations for
both the C and Java language bindings with language specific notes
where appropriate.
3.1 Multithreading
Both C and Java APIs are expected to be thread-safe. Access to data
structures shared among threads must be co-ordinated to avoid
corruption or invalid access. In addition, API implementors are
encouraged to provide the maximum amount of parallel processing
within their library implementations by allowing multiple threads in
the API library at once.
3.2 Error Reporting
The APIs report errors resulting from client calls through language
specific mechanisms. The functions in the C API return a error code,
while the Java methods throw exceptions. API implementors are
additionally encouraged to log errors using the appropriate platform
specific error logging technique, especially for errors that result
from network processing or other causes that are not directly related
to an API function or method call.
Kempf, Calhoun, Frascone expires June 2001 [Page 9]
INTERNET DRAFT December 2000
3.3 String Format
C API clients are required to format strings as UTF-8 if the string
contains 16 bit characters. Since the ASCII characters and the UTF-8
8 bit characters have the same codes, ASCII can be used for UTF-8 if
no wide characters are in the string. All strings passed through the
C API are standard null-terminated C strings. Processing to remove
the null terminator for transmission on the wire is done by the
library. Strings passed through the Java API are Unicode strings. The
library takes care of conversion to UTF-8.
3.4 Handling Connections with Other Servers/Peers
Both the C and Java API contain support for making a connection with
an arbitrary Diameter peer. The C API support allows an API client to
set the server address in a message (AAASetServer()) while the Java
API allows the client to specify the IP addresses of the
servers/peers to which a message should be sent (AAACommand.send()).
If a message is not sent to a particular server, the API library is
required to infer the servers by either looking in the configuration
files or dynamically determining the servers that support the
extension. Dynamic determination is possible using means such as SLP
[6].
3.5 Callback Processing Order
The C API allows API clients to register message processors, or
callbacks, that are invoked before and after the bulk of the
processing functions for a message. Only one pre- or post-processor
is allowed for all incoming messages, regardless of command or
extension type. If the API client adds another, any existing pre- and
post-processors are removed.
Message processing can be best explained by the following diagram:
+-------+ +-------+ +-------+ +-------+
| First | | Any | | Any | | Last | Apps
+-------+ +-------+ +-------+ +-------+
^ ^ ^ ^
1 | 2 | 3 | 4 |
+-------------------------------------------------+
| AAA Library |
+-------------------------------------------------+
^
| MSG
Kempf, Calhoun, Frascone expires June 2001 [Page 10]
INTERNET DRAFT December 2000
In the above diagram, "First", "Any", and "Last" are added by the API
client. The message processor labelled "First" is given access to the
message before any other, the message processor "Last" after all
others are finished. There is no guarantee on ordering for the other
message processors. If the client adds a new "First" or "Last"
message processor, the existing ones removed. There is one "First"
and "Last" processor for all commands regardless of type; whereas,
the "Any" processors are command-specific.
If one of the "Any" processors completes successfully, the message is
not passed on any further. A successful completion means the success
return code is returned from the C API callback, but the callback is
responsible for freeing the message before returning.
4.0 C API
The C language API is designed around callbacks. An application
profile defines a collection of Diameter commands, and a library of
callbacks for processing those commands. Each command is processed by
a callback. Callbacks can also be defined that handle all commands.
The API provides functions for managing callbacks, including
registration and deregistration.
When an incoming Diameter command arrives, the command is parsed and
passed to the appropriate callback. The callback receives as a
parameter the message struct, which contains the AVPs for the
command. The callback code can process the command by stepping
through the AVPs.
For outgoing requests, the API provides functions for creating
messages and adding AVPs. A collection of functions also provides
access to the AVP dictionary.
Unless otherwise noted, parameters to API functions and callbacks are
non-NULL. Some parameters may have other restrictions. If a parameter
fails to satisfy the restrictions on its value, the function returns
AAA_ERR_PARAMETER.
4.1 Constant Types
4.1.1 IP Address and Port
4.1.1.1 Synopsis
typedef sockaddr_storage IP_ADDR;
Kempf, Calhoun, Frascone expires June 2001 [Page 11]
INTERNET DRAFT December 2000
4.1.1.2 Description
IP_ADDR provides a way of referring to an IPv4 address, IPv6 address,
and IP port. The default implementation (shown here) is for the POSIX
Sockets API.
4.1.2 Command Code
4.1.2.1 Synopsis
typedef uint32_t AAACommandCode;
4.1.2.2 Description
AAACommandCode provides a way of referring to the AAA command code of
a command. It is used when registering callbacks, among others.
4.1.3 Vendor Identifier
4.1.3.1 Synopsis
typedef uint32_t AAAVendorId;
4.1.3.2 Description
AAAVendorId provides a way of referring to the vendor identification
code. It is used when registering callbacks, among others. Note that
vendor id 0 is reserved and is defined by the preprocessor constant
AAA_NO_VENDOR_ID.
4.1.4 Extention Identifier
4.1.4.1 Synopsis
typedef uint32_t AAAExtensionId;
4.1.4.2 Description
AAAExtensionId provides a way of referring to an application profile
Kempf, Calhoun, Frascone expires June 2001 [Page 12]
INTERNET DRAFT December 2000
extension, for registering callbacks and other purposes.
4.1.5 Attribute/Value Pair Code
4.1.5.1 Synopsis
typedef uint32_t AAA_AVPCode;
4.1.5.2 Description
AAA_AVPCode provides a way of referring to the code number of an AVP.
It is used as a parameter to the dictionary functions, and a field in
the AVP struct.
4.1.6 Value Type Identifier
4.1.6.1 Synopsis
typedef int32_t AAAValue
4.1.6.2 Description
AAAValue provides a way of referring to particular dictionary-defined
values. It is used in the dictionary API.
4.1.7 Server Type
4.1.7.1 Synopsis
typedef void AAAServer;
4.1.7.2 Description
AAAServer is an identifier for a particular serving peer. It is used
in the server access functions.
4.1.8 Session Identifier
Kempf, Calhoun, Frascone expires June 2001 [Page 13]
INTERNET DRAFT December 2000
4.1.8.1 Synopsis
typedef void AAASessionId;
4.1.8.2 Description
AAASessionId is an identifier for a particular AAA session. It is
used in the session APIs and when a message is created.
4.1.9 Message Identifier
4.1.9.1 Synopsis
typedef uint32_t AAAMsgIdentifier;
4.1.9.2 Description
AAAMsgIdentifier is a unique identifier for an AAA message. Each
individual message is marked with an identifier.
4.1.10 Callback Handle
4.1.10.1 Synopsys
typedef void AAACallbackHandle;
4.1.10.2 Description
AAACallbackHandle is a type for representing the callback handle
returned to the client when a callback is registered.
4.1.11 Application Identifier
4.1.11.1 Synopsis
typedef void* AAAApplicationId;
4.1.11.2 Definition
Kempf, Calhoun, Frascone expires June 2001 [Page 14]
INTERNET DRAFT December 2000
AAAApplicationId identifies a particular client session to the API.
The application id is passed to AAAStartSession(), and is attached to
incoming messages, to indicate with which client session the message
is associated.
4.1.12 API Return Codes
The following status codes are returned by functions in the AAA API:
typedef enum {
AAA_ERR_NOT_FOUND = -2,
AAA_ERR_FAILURE = -1,
AAA_ERR_SUCCESS = 0,
AAA_ERR_NOMEM,
AAA_ERR_PROTO,
AAA_ERR_SECURITY,
AAA_ERR_PARAMETER,
AAA_ERR_CONFIG,
AAA_ERR_UNKNOWN_CMD,
AAA_ERR_MISSING_AVP,
AAA_ERR_ALREADY_INIT,
AAA_ERR_TIMED_OUT,
AAA_ERR_CANNOT_SEND_MSG,
AAA_ERR_ALREADY_REGISTERED,
AAA_ERR_CANNOT_REGISTER,
AAA_ERR_NOT_INITIALIZED,
AAA_ERR_NETWORK_ERROR,
} AAAReturnCode;
Note that these status codes are separate from the codes returned by
remote AAA servers.
The following is a description of the error codes and the reasons why
they can be returned:
AAA_ERR_NOT_FOUND - This code is returned if a handle or id was
not found.
AAA_ERR_FAILURE - This code is returned if an unspecified failure
occured during an AAA operation.
AAA_ERR_SUCCESS - This code is returned if the AAA operation
succeeded.
AAA_ERR_NOMEM - This code is returned if the operation caused
memory to be exhausted.
Kempf, Calhoun, Frascone expires June 2001 [Page 15]
INTERNET DRAFT December 2000
AAA_ERR_PROTO - This code is returned if a AAA protocol error
occured.
AAA_ERR_SECURITY - This code is returned if a security check
failed or another security error occurred.
AAA_ERR_PARAMETER - This code is returned if an invalid parameter
was passed to an AAA function.
AAA_ERR_CONFIG - This code is returned if an error was encountered
in a configuration file during library
initialization.
AAA_ERR_UNKNOWN_CMD - This code is returned if the library
received a AAA command that is not in the
set of registered AAA commands.
AAA_ERR_MISSING_AVP - This code is returned if a command was
received without a required AVP.
AAA_ERR_ALREADY_INIT - This code is returned if an attempt is made
to initialize the AAA library when it has
already been initialized.
AAA_ERR_TIMED_OUT - This code is returned when a network operation
times out.
AAA_ERR_CANNOT_SEND_MSG - This code is returned if the library
can't send a message. It is also of used
to application profile extensions that
encounter the same error condition.
AAA_ERR_ALREADY_REGISTERED - This code is returned by the command
registration functions if the command
was already registered.
AAA_ERR_CANNOT_REGISTER - This code is returned by the command
registration functions if the command
could not be registered.
AAA_ERR_NOT_INITIALIZED - This code is returned by any function in
the API except AAAOpen() if the library
hasn't been initialized.
AAA_ERR_NETWORK_ERROR - This code is returned by any function if
an error in networking occurs.
In addition to returning the error code, functions are required to
Kempf, Calhoun, Frascone expires June 2001 [Page 16]
INTERNET DRAFT December 2000
log errors using the platform dependent logging facility.
4.1.13 Callback Location Codes
The following are codes used to indicate where a callback should be
installed in callback chain for processing:
typedef enum {
AAA_APP_INSTALL_FIRST,
AAA_APP_INSTALL_ANYWHERE,
AAA_APP_INSTALL_LAST
} AAACallbackLocation;
Callbacks installed with AAA_APP_INSTALL_FIRST and
AAA_APP_INSTALL_LAST operate on all commands, callbacks installed
with AAA_APP_INSTALL_ANYWHERE just operate on the command for which
they are installed.
The codes have the following semantics:
AAA_APP_INSTALL_FIRST - Install this callback as the first
callback in the chain. If subsequent
callbacks are installed with this code,
the callback is moved down the list.
AAA_APP_INSTALL_ANYWHERE - Install this callback anywhere in the
callback chain.
AAA_APP_INSTALL_LAST - Install this callback as the last callback
in the chain. If subsequent callbacks are
installed with this code, the callback is
moved up the list.
4.1.14 AVP Data Type Codes
The following are AVP data type codes. They correspond directly to
the AVP data types outline in the Diameter specification [1]:
typedef enum {
AAA_AVP_DATA_TYPE,
AAA_AVP_STRING_TYPE,
AAA_AVP_ADDRESS_TYPE,
AAA_AVP_INTEGER32_TYPE,
AAA_AVP_INTEGER64_TYPE,
AAA_AVP_TIME_TYPE,
} AAA_AVPDataType;
Kempf, Calhoun, Frascone expires June 2001 [Page 17]
INTERNET DRAFT December 2000
4.1.15 AVP Flags
The following are used for AVP header flags and for flags in the AVP
wrapper struct and AVP dictionary definitions. The first six
correspond to the AVP flags defined in the Diameter specification
[1]. Some of these are also used in the wrapper struct and dictionary
definitions also. The last four are used only in AAA_AVP and
AAADictionaryEntry:
typedef enum {
AAA_AVP_FLAG_NONE = 0,
AAA_AVP_FLAG_MANDATORY = 0x1,
AAA_AVP_FLAG_RESERVED = 0x2,
AAA_AVP_FLAG_VENDOR_SPECIFIC = 0x4,
AAA_AVP_FLAG_END_TO_END_ENCRYPT = 0x10,
AAA_AVP_FLAG_UNKNOWN = 0x10000,
AAA_AVP_FLAG_ENCRYPT = 0x40000,
} AAA_AVPFlag;
The semantics of the flags are as follows:
AAA_AVP_FLAG_NONE -Indicates that no AVP flags are set.
AAA_AVP_FLAG_MANDATORY - Represents the 'M' flag in the Diameter
AVP header [1], meaning the AVP is
mandatory.
AAA_AVP_FLAG_RESERVED - Represents the 'R' flag in the Diameter
AVP header [1]. This flag is reserved and
should not be set.
AAA_AVP_FLAG_VENDOR_SPECIFIC - Represents the 'V' flag in the
Diameter AVP header [1], meaning
that the AVP is vendor specific.
If this flag is set, the header
will contain a vendor identifier.
AAA_AVP_FLAG_END_TO_END_ENCRYPT - Represents the 'P' flag in the
Diameter AVP header [1], meaning
that the AVP is end-to-end
encrypted [5].
AAA_AVP_FLAG_UNKNOWN - Indicates that the AVP was not located in
the AVP dictionary. This flag is only used
in AAA_AVP.
AAA_AVP_FLAG_ENCRYPT - Indicates that the AVP was either marked as
AAA_AVP_FLAG_END_TO_END_ENCRYPT or that it
Kempf, Calhoun, Frascone expires June 2001 [Page 18]
INTERNET DRAFT December 2000
was hop-by-hop encrypted (and thus that the
AAA_AVP_FLAG_END_TO_END_ENCRYPT flag is not
set on in the AVP header). If the AVP is
not end-to-end encrypted, then it will be
either one of the two standard hop-by-hop
encrypted AVPs, Integrity-Check-Value and
Encrypted-Payload [1]. This flag is only
used in AAA_AVP.
4.1.16 Domain Interconnection Types
The following domain interconnection types are returned by
AAAGetDomainInternconnectType(). They indicate the type of domain
interconnection:
typedef enum {
AAA_DOMAIN_LOCAL,
AAA_DOMAIN_PROXY,
AAA_DOMAIN_BROKER,
AAA_DOMAIN_FORWARD
} AAADomainInterconnect;
The flags have the following semantics:
AAA_DOMAIN_LOCAL - The domain name is for the local domain.
AAA_DOMAIN_PROXY - The domain name is for a proxy domain. A proxy
is a server that simply forwards the request
based on the user's identity or through some
other means. The routing method used for a
proxy is the Proxy-State method, requiring
routing through a fixed chain of proxies [1].
AAA_DOMAIN_BROKER - The domain name is for a broker domain. A
broker is a server that provides redirect
services, allowing all servers in a roaming
consortium to interact directly.
AAA_DOMAIN_FORWARD - The domain name is for a forwarding domain. A
forwarding domain is a proxy that uses
Destination-NAI routing. With Destination-NAI
routing, there is no set sequence of proxies
through which messages must be routed [1].
4.1.17 Message Flags
Kempf, Calhoun, Frascone expires June 2001 [Page 19]
INTERNET DRAFT December 2000
The following type is for the AAA message flags. Currently, there are
no message flags defined in the Diameter prototcol [1]:
typedef uint8_t AAAMsgFlag;
4.1.18 Result Codes
The following are the result codes returned from remote servers as
part of messages. They correspond directly to the result codes in the
Diameter specification [1]:
typedef enum {
AAA_SUCCESS = 0,
AAA_FAILURE,
AAA_POOR_REQUEST,
AAA_INVALID_AUTH,
AAA_UNKNOWN_SESSION_ID,
AAA_USER_UNKNOWN,
AAA_COMMAND_UNSUPPORTED,
AAA_TIMEOUT,
AAA_AVP_UNSUPPORTED,
AAA_REDIRECT_INDICATION,
AAA_REALM_NOT_SERVED,
AAA_UNSUPPORTED_TRANSFORM,
AAA_AUTHENTICATION_REJECTED,
AAA_AUTHORIZATION_REJECTED,
AAA_INVALID_AVP_VALUE,
AAA_MISSING_AVP,
AAA_UNABLE_TO_DELIVER
} AAAResultCode;
4.1.19 Search Direction Type
The following type allows the client to specify which direction to
search for an AVP in the AVP list:
typedef enum {
AAA_FORWARD_SEARCH = 0,
AAA_BACKWARD_SEARCH
} AAASearchType;
4.2 Structure Definitions
4.2.1 Dictionary Entry Definition
Kempf, Calhoun, Frascone expires June 2001 [Page 20]
INTERNET DRAFT December 2000
The following structure is returned by the dictionary entry lookup
functions. It contains information about a particular AVP in the
dictionary:
typedef struct dictionaryEntry {
AAA_AVPCode avpCode;
char* avpName;
AAA_AVPDataType avpType;
AAAVendorId vendorId;
AAA_AVPFlag flags;
} AAADictionaryEntry;
4.2.2 AVP Definition
The following structure contains a message AVP in parsed form:
typedef struct avp {
enum {
AAA_RADIUS,
AAA_DIAMETER
} packetType;
AAA_AVPCode code;
uint16_t length;
AAA_AVPFlag flags;
AAA_AVPDataType type;
AAAVendorId vendorId;
void* data;
} AAA_AVP;
The fields have the following definitions:
packetType - Indicates whether the message is for Diameter or for
Radius compatibility. If the AVP is for Radius, then
the code, length, type, and data fields are the only
valid fields in the structure; the other fields are
all null.
code - The AVP code. The type of the AVP can be determined by
matching the AVP code with an AVP description from the
dictionary.
length - The length of the AVP's data field.
flags - The AVP flags.
type - The data type of the AVP's data.
Kempf, Calhoun, Frascone expires June 2001 [Page 21]
INTERNET DRAFT December 2000
vendorId - The vendor id, if the AVP is vendor-specific. If the
AVP is standardized, the vendorId field is set to
AAA_NO_VENDOR_ID.
data - The AVP data, in host byte order.
4.2.3 AVP List
The following structure is used for reprsenting lists of AVPs on the
message:
typedef struct avpList{
AAA_AVP *head;
AAA_AVP *tail;
} AAA_AVP_LIST;
AVPs are kept in ordered lists. The client can use a search direction
to indicated in which direction to search when trying to find an AVP.
4.2.4 Message Definition
The following structure contains the full AAA message:
typedef struct message {
AAAMsgFlag flags;
AAACommandCode commandCode;
AAAVendorId vendorId;
AAAResultCode resultCode;
IP_ADDR originator;
IP_ADDR sender;
AAA_AVP_LIST *avpList;
AAA_AVP *proxyAVP;
AAAMsgIdentifier identifier;
time_t secondsTillExpire;
time_t startTime;
void *appHandle;
} AAAMessage;
The fields have the following definition:
flags - The message flags. Currently this field is always zero,
since there are no flags defined for a Diameter message at
this time.
commandCode - The command's message code.
Kempf, Calhoun, Frascone expires June 2001 [Page 22]
INTERNET DRAFT December 2000
vendorId - The vendor id of the vendor that defined the message.
resultCode - Code indicating the result of the client's request.
This code is sent by the peer over the wire.
originatorVersion - The IP version of the originator's address.
originator - The IP address of the message's originator.
senderVersion - The IP version of the sender's address.
sender - The IP address of the message's previous hop sender. This
is only the same as originator if no proxy or broker
peers are being used.
port - The port on which the message was received.
avpList - The list of AVPs in the message.
proxyAVP - The proxy's AVP, if any. Otherwise NULL.
identifier - The message's unique identifier.
secondsTillExpire - Number of seconds until the message expires.
startTime - The number of seconds at which the message was
started.
appHandle - An identifier indicating for which client session the
message is.
4.3 Macros and Preprocessor Definitions
The following definition reserves the vendor id of 0:
#define AAA_NO_VENDOR_ID 0
4.4 Functions
4.4.1 Initialization and Configuration
This section contains definitions that perform initialization and
configuration of the AAA library.
Kempf, Calhoun, Frascone expires June 2001 [Page 23]
INTERNET DRAFT December 2000
4.4.1.1 AAAOpen()
The following function is used to open and configure the AAA library:
AAAReturnCode AAAOpen(char *configFileName);
This function must be called before any other AAA function is called.
Some of the operations that may be performed by AAAOpen() are:
opening and loading the AVP and vendor dictionaries, opening
connections with Diameter peers, loading Diameter extension
libraries, and registering Diameter callbacks. After AAAOpen()
returns, the library must be ready for the client to open a session.
Parameters are:
configFileName - The global configuration file name. If NULL or
the empty string, use the default for this
platform. The global configuration file must
contain the vendor and AVP dictionary file
names, and may contain other platform-specific
information needed to initialize and configure
the Diameter peer.
Return values are:
AAA_ERR_SUCCESS - If initialization succeeded.
AAA_ERR_ALREADY_INIT - If the library is already initialized.
AAA_ERR_NETWORK_ERROR - If the host name can't be determined.
AAA_ERR_NOMEM - If no memory was available.
AAA_ERR_CONFIG - If processing the dictionary or configuration
information failed.
4.4.1.2 AAAClose()
The following function closes the AAA library:
AAAReturnCode AAAClose();
After this function is called, all other AAA functions are no longer
operative.
Return values are:
Kempf, Calhoun, Frascone expires June 2001 [Page 24]
INTERNET DRAFT December 2000
AAA_ERR_SUCCESS - If finalization succeeded.
AAA_ERR_NOT_INIITIALIZED - If AAA was not initialized.
4.4.1.3 AAAGetDefaultConfigFileName()
The following returns the default configuration file name on the
platform:
const char *AAAGetDefaultConfigFileName();
The return value is a pointer to the full pathname for the file. The
pointer value should not be deallocated because it is constant and
does not change.
4.4.2 Registering Commands
The functions in this section are used to register callback functions
defined in a Diameter application profile extension library. The
following typedef defines the interface between callback functions
and the AAA library functions:
typedef AAAReturnCode (*func)(AAAMessage *message) AAACallback;
Authors of Diameter extensions must define command callback
functions having this interface.
Parameters are:
message - The AAAMessage to be processed.
The return value is a status code giving the operation status.
4.4.2.1 AAARegisterCommandCallback()
The following function is used to register command callbacks for
processing AAA commands:
AAACallbackHandle *
AAARegisterCommandCallback(AAACommandCode commandCode,
AAAVendorId vendorId,
char *commandName,
AAAExtensionId extensionId,
AAACallback callback,
AAACallbackLocation position);
Kempf, Calhoun, Frascone expires June 2001 [Page 25]
INTERNET DRAFT December 2000
Parameters are:
commandCode - The code of the command processed by the callback.
vendorId - The vendor id of the command.
commandName - A pointer to the name of the command.
extensionId - The id of the extension to which this command
belongs.
callback - The callback function to perform processing.
position - The position of the callback in the chain.
The return value is a handle used when deregistering the callback, or
NULL if an error occured while registering the callback.
4.4.2.2 AAARegisterNoncommandCallback()
The following callback registesr an AAA callback to process all
messages. The callback is not associated with any command, but rather
will process all messages as they come down the callback chain:
AAACallbackHandle
AAARegisterNoncommandCallback(AAACallback callback,
AAACallbackLocation position);
Parameters are:
callback - The callback function to perform processing.
position - The position of the callback in the chain.
The return value is a handle used when deregistering the callback, or
NULL if an error occured while registering the callback.
4.4.2.3 AAADeregisterCommandCallback()
The following function deregisters a command callback:
AAAReturnCode
AAADeregisterCommandCallback(AAACallbackHandle *handle);
Parameters are:
Kempf, Calhoun, Frascone expires June 2001 [Page 26]
INTERNET DRAFT December 2000
handle - The handle returned when the callback was registered.
The return values are:
AAA_ERR_SUCCESS - Returned upon completion.
AAA_ERR_FAILURE - if the callback is not registered.
4.4.2.4 AAADeregisterNoncommandCallback()
The following function is used to deregister a noncommand callback:
AAAReturnCode
AAADeregisterNoncommandCallback(AAACallbackHandle *handle);
handle - The handle returned when the callback was registered.
Return values are:
AAA_ERR_SUCCESS - Returned upon completion.
AAA_ERR_FAILURE - If the callback is not registered.
4.4.2.5 AAARegisterExtension()
The following function is used to register a Diameter extension id.
This function is typically called when registering non-command
specific callbacks. Extension ids for c ommand-specific callbacks are
registered when the callback is registered:
AAAReturnCode AAARegisterExtension(AAAExtensionId extensionId);
The parameters are:
extensionId - The extension id.
The return codes are:
AAA_ERR_SUCCESS - If the registration was successful.
AAA_ERR_NOMEM - if a memory allocation failure occured.
4.4.3 Session and Server Management
Kempf, Calhoun, Frascone expires June 2001 [Page 27]
INTERNET DRAFT December 2000
The functions in this section allow the client to open, close, and
register sessions, and to obtain server identifiers.
4.4.3.1 AAAStartSession()
The following function allows a client to start a session and
identify it:
AAAReturnCode AAAStartSession(AAASessionId **sessionId,
AAAApplicationId appHandle);
Parameters are:
sessionId - On return, a pointer to the session id for this
session.
appHandle - An identifier for the client application starting the
session. This identifier is attached to messages so
that the client callbacks can tell which messages
belong to it.
Return values are:
AAA_ERR_SUCCESS - If the session was successfully started.
AAA_ERR_NOMEM - If a memory allocation failure occured.
4.4.3.2 AAARegisterPeerSession()
The following function allows a client to register a peer session
that it has discovered through some other means, for example, by
receiving an unsolicited message.
AAAReturnCode AAARegisterPeerSession(AAASessionId **sessionId,
AAAMessage *message);
The parameters are:
sessionId - On return, a pointer to the local session id for the
session.
message - The message from the peer containing the session id.
Return values are:
AAA_ERR_SUCCESS - If the session was successfully registered.
Kempf, Calhoun, Frascone expires June 2001 [Page 28]
INTERNET DRAFT December 2000
AAA_ERR_NOMEM - If a memory allocation failure occured.
4.4.3.3 AAAEndSession()
The following function terminates a session:
AAAReturnCode AAAEndSession(AAASessionId *sessionId);
The parameters are:
sessionId - A pointer to the session id for the session.
Return values are:
AAA_ERR_SUCCESS - If the session was successfully closed.
AAA_ERR_NOT_FOUND - If the handle is invalid.
4.4.3.4 AAALookupServer()
The function looks up the AAA server based on IP address and port
number. Server connections are created from the configuration file:
AAAServer *AAALookupServer(IP_ADDR ipAddr);
The parameters are:
ipAddr - The IP address/Port/Family of the server.
The return value is either a valid server pointer or the NULL if the
server can't be found.
4.4.3.5 AAASetSessionMessageTimeout()
The following function sets the timeout, in seconds, for all
AAAMessages in a particualr session:
AAAReturnCode AAASetSessionMessageTimeout(AAASessionId *id,
time_t timeout);
The parameters are:
id - The session id for the session whose timeout should be
changed.
Kempf, Calhoun, Frascone expires June 2001 [Page 29]
INTERNET DRAFT December 2000
timeout - The session timeout. The default timeout is 120 seconds.
The return values are:
AAA_ERR_SUCCESS - If setting the timeout succeeded.
AAA_ERR_FAILURE - If the setting the timeout failed.
4.4.3.6 AAAGetDomainInterconnectType()
The following function returns the domain interconnect type for a
particular domain name and type of service:
AAAResultCode
AAAGetDomainInterconnectType(AAAMessage *message, char *domainName,
char *type);
The parameters are:
domainName - The name of the domain.
type - The type of service. This must be one of the strings
"LOCAL", "PROXY", or "BROKER".
4.4.4 Dictionary Lookup
The functions in this section are used to look up AVPs and commands
in the dictionary. The client is responsible for supplying the
structure memory into which the dictionary information is copied.
4.4.4.1 AAADictionaryEntryFromAVPCode()
This function looks up a dictionary entry using a command code and a
vendor id:
AAAReturnCode
AAAADictionaryEntryFromAVPCode(AAA_AVPCode avpCode,
AAAVendorId vendorId,
AAADictionaryEntry *entry);
The parameters are:
avpCode - The code number of the AVP.
vendorId - The vendor id of the AVP.
Kempf, Calhoun, Frascone expires June 2001 [Page 30]
INTERNET DRAFT December 2000
entry - an AAADictionaryEntry structure for returning the entry.
The return value is one of:
AAA_ERR_SUCCESS - If the query succeeded.
AAA_ERR_FAILURE - If no matching dictionary entry was found.
4.4.4.2 AAADictionaryEntryFromName()
This function looks up a dictionary entry using command code name and
vendor id:
AAAReturnCode
AAADictionaryEntryFromName(char *avpName,
AAAVendorId vendorId,
AAADictionaryEntry *entry);
The parameters are:
avpName - The name of the AVP.
vendorId - The vendor id of the AVP.
entry - an AAADictionaryEntry structure for returning the entry.
The return value is one of:
AAA_ERR_SUCCESS - If the query succeeded.
AAA_ERR_FAILURE - If no matching dictionary entry was found.
4.4.4.3 AAAValueFromName()
This function looks up an AVP value using the AVP name and vendor
name:
AAAValue AAAValueFromName(char *avpName,
char *vendorName,
char *valueName);
The parameters are:
avpName - The name of the AVP.
vendorName - The name of the vendor.
Kempf, Calhoun, Frascone expires June 2001 [Page 31]
INTERNET DRAFT December 2000
valueName - The name of the value.
The return value is the id of the AVP, or AAA_ERR_NOT_FOUND if no
match was found.
4.4.4.4 AAAValueFromAVPCode()
This function looks up an AVP value using the AVP id and vendor id,
and the value name:
AAAValue AAAValueFromAVPCode(AAA_AVPCode avpCode,
AAAVendorId vendorId,
char *valueName);
The parameters are:
avpCode - The code of the AVP.
vendorId - The id of the vendor.
valueName - The name of the value.
The return value is id of the AVP, or AAA_ERR_NOT_FOUND if no match
was found.
4.4.4.5 AAALookupValueNameUsingValue()
This function returns the AVP value name:
const char *AAALookupValueNameUsingValue(AAA_AVPCode avpCode,
AAAVendorId vendorId,
AAAValue value);
The parameters are:
avpCode - The code of the AVP.
vendorId - The id of the vendor.
value - The value.
The value name is returned, or NULL if no match occured.
4.4.4.6 AAAGetCommandCode()
Kempf, Calhoun, Frascone expires June 2001 [Page 32]
INTERNET DRAFT December 2000
This function returns the command code and vendor id based on a
string:
boolean_t AAAGetCommandCode(char *commandName,
AAACommandCode *commandCode,
AAAVendorId *vendorId);
The parameters are:
commandName - A string containing the command name.
commandCode - Pointer that on return holds the command code if the
command was found.
vendorId - Pointer that on return holds the vendor id if the
command was found.
The return value is _B_TRUE if the command was found.
4.4.5 Message Management
The functions in this section allow the client to create messages,
add AVPs, and traverse AVP lists.
4.4.5.1 AAANewMessage()
This function allocates an AAAMessage and returns a pointer to it. If
a command code is provided, this function adds the command code AVP
and the Initialization-Vector AVP. If the session identifier handle
is provided, the Session-Id AVP is also added. Lastly, if this
message is allocated in response to a request, the request's message
can be provided, and the new message is initialized to match the
request, for fields such as the identifier, the server identifier,
etc. If this is a new message, the request parameter is NULL:
AAAMessage *AAANewMessage(AAACommandCode commandCode,
AAAVendorId vendorId,
AAASessionId *sessionId,
AAAExtensionId extensionId,
AAAMessage *request);
The parameters are:
commandCode - The command code.
vendorId - The vendor identifier.
Kempf, Calhoun, Frascone expires June 2001 [Page 33]
INTERNET DRAFT December 2000
sessionId - Session identifier.
extensionId - The extension identifier.
request - A pointer to a request message, if this message is being
allocated in response to a request.
The function returns a pointer to the message or NULL if a failure
occured.
4.4.5.2 AAAFreeMessage()
This function frees a message allocated through AAANewMessage():
AAAReturnCode AAAFreeMessage(AAAMessage *message);
The parameters are:
message - A pointer to the allocated message.
The return value is the AAA status code AAA_ERR_SUCCESS.
4.4.5.3 AAAACreateAVP()
This function creates an AVP and returns a pointer to it. The AVP is
initialized from the arguments:
AAAReturnCode AAAACreateAVP(AAA_AVP **avp,
AAA_AVPCode code,
AAA_AVPFlag flags,
AAAVendorId vendorId,
char *data,
size_t length);
The parameters are:
avp - On return, contains a pointer to the allocated AVP, or NULL
if no AVP was allocated.
code - The AVP's code.
flags - Any AVP flags that must be passed.
vendorId - The vendor id of the AVP. If no vendor id, then
AAA_NO_VENDOR_ID.
Kempf, Calhoun, Frascone expires June 2001 [Page 34]
INTERNET DRAFT December 2000
data - A buffer containing the AVP data.
length - The length of the data buffer.
Return values are:
AAA_ERR_SUCCESS - Upon success.
AAA_ERR_PARAMETER - If an invalid parameter was passed.
AAA_ERR_PROTO - If a protocol error occurred.
AAA_ERR_NOMEM - Indicating a memory failure.
4.4.5.4 AAACreateAndAddAVPToList()
This function creates an AVP and adds it to an AVP list. It returns a
pointer to the list in the avpList argument. The AVP is initialized
from the arguments:
AAAReturnCode AAACreateAndAddAVPToList(AAA_AVP_LIST **avpList,
AAA_AVPCode code,
AAA_AVPFlag flags,
AAAVendorId vendorId,
char *data,
size_t length);
The parameters are:
avpList - The list to which the AVP should be added.
code - The AVP's code.
flags - Any AVP flags that must be passed.
vendorId - The vendor id of the AVP. If no vendor id, then
AAA_NO_VENDOR_ID.
data - A buffer containing the AVP data.
length - The length of the data buffer.
Return values are:
AAA_ERR_SUCCESS - Upon success.
AAA_ERR_PARAMETER - If an invalid parameter was passed.
Kempf, Calhoun, Frascone expires June 2001 [Page 35]
INTERNET DRAFT December 2000
AAA_ERR_NOMEM - Indicating a memory failure.
4.4.5.5 AAAAddAVPToList()
AAAReturnCode AAAAddAVPToList(AAA_AVP_LIST **avpList,
AAA_AVP *avp, AAA_AVP *position);
Insert the AVP avp into this avpList after position. If position is
NULL, the AVP is added to the end of the list.
The parameters are:
avpList - Pointer to a pointer for list. If NULL, list memory is
allocated.
avp - AAA_AVP to add to list.
position - AAA_AVP pointer to add data after, or NULL if the new
AVP should go at the end of the list.
The return value is one of:
AAA_ERR_SUCCESS - Upon success.
AAA_ERR_PARAMETER - If an invalid parameter was passed.
AAA_ERR_NOMEM - Indicates a memory failure.
4.4.5.6 AAAFindMatchingAVP()
This function finds an AVP with matching code and vendor id. If none
match, the function returns NULL:
AAA_AVP *AAAFindMatchingAVP(AAA_AVP_LIST *avpList,
AAA_AVP *startAvp,
AAA_AVPCode avpCode,
AAAVendorId vendorId,
AAASearchType searchType);
The parameters are:
avp - A pointer to the head of the AVP list.
avpCode - The code of the sought after AVP.
vendorId - The vendor id of the sought after AVP.
Kempf, Calhoun, Frascone expires June 2001 [Page 36]
INTERNET DRAFT December 2000
The return value is a pointer to the found AVP, or NULL if none is
found.
4.4.5.7 AAAJoinAVPLists()
The following function joins together two AVP lists:
AAAReturnCode AAAJoinAVPLists(AAA_AVP *dest,
AAA_AVP *source);
The parameters are:
dest - The position of the join in the destination list.
source - The position of the join in the source list.
The return value is one of:
AAA_ERR_SUCCESS - Upon success.
AAA_ERR_PARAMETER - If an invalid parameter was passed.
4.4.5.8 AAARemoveAVPFromList()
This function removes an AVP from a list:
AAAReturnCode AAARemoveAVPFromList(AAA_AVP_LIST *avpList,
AAA_AVP *avp);
The parameters are:
avpList - The head of the list from which to remove the AVP.
avp - Contains a pointer to the AVP to remove.
The return value is one of:
AAA_ERR_SUCCESS - Upon success.
AAA_ERR_PARAMETER - If an invalid parameter was passed.
4.4.5.9 AAAFreeAVP()
The function frees an AVP:
Kempf, Calhoun, Frascone expires June 2001 [Page 37]
INTERNET DRAFT December 2000
AAAReturnCode AAAFreeAVP(AAA_AVP *avp);
The parameters are:
avp - Contains a pointer to the AVP to free.
The return value is one of:
AAA_ERR_SUCCESS - Upon success.
AAA_ERR_PARAMETER - If an invalid parameter was passed.
4.4.5.10 AAAGetFirstAVP()
This function returns a pointer to the first AVP in the list:
AAA_AVP *AAAGetFirstAVP(AAA_AVP_LIST *avpList);
The parameters are:
avpList - A pointer to the list.
The return value is a pointer to the found AVP, or NULL if none is
found.
4.4.5.11 AAAGetLastAVP()
This function returns a pointer to the last AVP in the list:
AAA_AVP *AAAGetLastAVP(AAA_AVP_LIST *avpList);
The parameters are:
avpList - A pointer to the list.
The function returns a pointer to the found AVP, or NULL if none is
found.
4.4.5.12 AAAGetNextAVP()
This function returns a pointer to the next AVP in the list.
AAA_AVP *AAAGetNextAVP(AAA_AVP *avp);
The parameters are:
Kempf, Calhoun, Frascone expires June 2001 [Page 38]
INTERNET DRAFT December 2000
avp - A pointer to the AVP prior to the one sought.
The return value is the next AVP in the list, or NULL if the
parameter is the last element in the list.
4.4.5.13 AAAGetPrevAVP()
This function returns a pointer to the previous AVP in the list:
AAA_AVP *AAAGetPrevAVP(AAA_AVP *avp);
The parameters are:
avp - A pointer to the AVP after the one sought.
The return value is the previous AVP in the list or NULL if the
parameter is the first element in the list.
4.4.5.14 AAAEncapsulateList()
This function returns an AVP that encapsulates a list of AVPs:
AAA_AVP *AAAEncapsulateList(AAA_AVP_LIST *avpList);
The parameter is:
avpList - Pointer to list of AVPs to encapsulate.
The return value is a pointer to an AVP encapsulating the list.
4.4.5.15 AAADecapsulateList()
This function decapsulates an encapsulated AVP, and populates the
list with the correct pointers.
AAAReturnCode AAADecapsulateList(AAA_AVP *avp, AAA_AVP_LIST *);
The parameters are:
avp - The encapsulating AVP.
avpList - Pointer to the list structure
The return value is one of:
Kempf, Calhoun, Frascone expires June 2001 [Page 39]
INTERNET DRAFT December 2000
AAA_ERR_SUCCESS - Upon success.
AAA_ERR_PARAMETER - If an invalid parameter was passed.
4.4.5.16 AAASetMessageResultCode()
This function decapsulates an encapsulated AVP, and populates the
list with the correct pointers.
AAAResultCode AAASetMessageResultCode(AAAMessage *message,
AAAResultCode resultCode);
The parameters are:
message - A pointer to the allocated message.
resultCode - The AAA Result Code
The return value is one of:
AAA_ERR_SUCCESS - Upon success.
AAA_ERR_PARAMETER - If an invalid parameter was passed.
4.4.6 Message Control
The following functions allow the client to direct a message to a
particular server, determine the server for a message, etc.
4.4.6.1 AAASetServer()
This function sets the server to which the message is sent:
AAAReturnCode AAASetServer(AAAMessage *message,
IP_ADDR host);
The parameters are:
message - The message to be sent.
ipVersion - The version number of the IP address.
host - The IP address / port / family of the server.
The return value is
Kempf, Calhoun, Frascone expires June 2001 [Page 40]
INTERNET DRAFT December 2000
AAA_ERR_SUCCESS - If the server was found.
AAA_ERR_NOT_FOUND - If the server was not found.
4.4.6.2 AAASendMessage()
The following function sends a message to the server assigned to the
message by AAASetServer(). The message identifier is assigned to the
message. If no server id has been assigned to the message, a server
id is selected. If no servers are currently active, the message is
queued for later sending.
AAAReturnCode AAASendMessage(AAAMessage *message);
The parameter is the message to send.
The return codes are:
AAA_ERR_SUCCESS - Upon completion.
AAA_ERR_FAILURE - If an error occured.
4.5 Implementation Notes
The following are some implementation notes that library implementors
may want to keep in mind.
4.5.1 Avoiding AVP Copying
The AAA_AVP struct does not provide an exact mapping to the Diameter
protocol AVP packet format; however, library implementors can avoid
having to copy the AVP data by putting a pointer to a packet format
structure into a hidden part of the AAA_AVP struct. A pointer to the
AVP data is then deposited into the AAA_AVP data field. This allows
proper deallocation of the packet format structure when the AAA_AVP
structure is deallocated.
5.0 Java API
Unlike the C API, the Java API is not designed around callbacks.
Instead, the Java API provides a synchronous message sending model. A
Java class, AAAMessage, models a Diameter message. The class
supports an instance method, AAAMessage.send(), that synchronously
sends the message, and waits until reply messages are received,
Kempf, Calhoun, Frascone expires June 2001 [Page 41]
INTERNET DRAFT December 2000
returning the reply messages to the client. No callback functions are
required in this case. The API client can register callbacks to
handle unsolicited messages that arrive for a particular session,
however, unsolicited messages are considered the exception rather
than the rule. Since this API is fairly low level, it is anticipated
that application profiles will build their own higher level APIs on
top.
All AAA classes are within the same package. The package name is
org.ietf.aaa. This follows the Java convention of prepending the
name of the organization responsible for the API to the package. A
single package name for all AAA implementations precludes running
multiple AAA implementations within a single Java virtual machine.
The following Java properties (accessable through the
java.lang.System.getProperties()) are used to locate files during
initialization. These properties must be set before the API library
is loaded, and remain valid throughout the session:
org.ietf.aaa.appName - A String containing the name of the
application. Default is "DiameterClient".
org.ietf.aaa.configFileName - A String containing the platform
specific global configuration file
name.
org.ietf.aaa.defaultConfigFileName - A String containing the
platform specific default
global configuration file
name.
org.ietf.aaa.defaultVendorFileName - A String containing the
platform specfic default
vendor file name.
org.ietf.aaa.defaultDictionaryFileName - A String containing the
platform specific default
AVP Dictionary file name.
During intialization, the API library loads any configuration files,
including the dictionary and vendor files, starts sessions for
statically configured servers, and does any other initialization
needed to start the AAA client.
Peer sessions discovered by the AAA server are automatically
registered by the AAA library upon receipt of a message containing
the session id. Client code can use the
AAASessionManager.getSessionId() to return the session id associated
Kempf, Calhoun, Frascone expires June 2001 [Page 42]
INTERNET DRAFT December 2000
with a particular host.
5.1 Errors and Exceptions
In general, parameters to API methods are required to be non-null,
but the API description indicates if a null parameter is acceptable.
Parameters must be checked by the API library before use and a
java.lang.IllegalArgumentException exception thrown if any parameter
is not acceptable. Since this class is a subclass of
java.lang.RuntimeException, clients are reminded to check for
IllegalArgumentException even though it is not listed in the method
API description. The documentation below only lists
IllegalArgumentException if it is returned for a reason other than a
null parameter.
Unlike most Java packages, the AAA API does not encode every error
condition into a separate subclass of java.lang.Exception. When there
are a large number of exceptional conditions (as in the AAA API), the
result is a proliferation of exception classes. In the AAA API, the
exception conditions are represented by error codes that are defined
as constants in the org.ietf.aaa.AAAException class.
5.1.1 Class AAAException
5.1.1.1 Synopsis
public class AAAException extends java.lang.Exception
5.1.1.2 Description
The AAAException class is the class for returning all AAA exceptions.
The error code indicates the exact nature of the exception, along
with text in the exception message.
5.1.1.3 Fields
public static final short FAILURE = 1
public static final short SECURITY = 2
public static final short UNKNOWN_CMD = 3
public static final short MISSING_AVP = 4
public static final short TIMED_OUT = 5
public static final short INIT_FAILURE = 6
public static final short CANNOT_SEND_MSG = 7
public static final short NETWORK_ERROR = 8
public static final short SESSION_INVALID = 9
Kempf, Calhoun, Frascone expires June 2001 [Page 43]
INTERNET DRAFT December 2000
public static final short PARSE_ERROR = 10
public static final short VERSION_ERROR = 11
Note that these status codes are separate from the codes returned by
remote AAA servers.
FAILURE - This code indicates an unspecified failure occured
during an AAA operation.
SECURITY - This code indicates a security check failed or another
security error occurred.
UNKNOWN_CMD - This code indicates the library received a AAA
command that is not in the set of registered AAA
commands.
MISSING_AVP - This code indicates a command was received without a
required AVP.
TIMED_OUT - This code indicates that a network operation timed
out.
INIT_FAILURE - This code is thrown by the initialization if some
problem occured initializing the library. Such
problems may include a missing or syntactically
incorrect configuration file, missing transport
layer module, inability to determine the host name,
etc.
CANNOT_SEND_MSG - This code indicates the library can't send a
message.
NETWORK_ERROR - This code indicates that an error in networking
occured, other than a timeout.
PARSE_ERROR - This code indicates that a parse error occured
during input deserialization of a message or AVP.
VERSION_ERROR - This code indicates that the version number on an
incoming message does not correspond to a version
number that this library handles.
In addition to returning the error code, the library is required to
log errors using the platform dependent logging facility.
5.1.4 Instance Methods
public short getCode()
Kempf, Calhoun, Frascone expires June 2001 [Page 44]
INTERNET DRAFT December 2000
Return the exception error code.
5.2 Library Management and Dictionary Management
The Java API provides a set of reflective classes that model Diameter
extensions, commands, and AVP descriptions. These classes are used by
the API itself to perform checking, and they are available to the
clients that want to do additional checking or discover what commands
and extensions are available.
5.2.1 Class AAA
5.2.1.1 Synopsis
abstract public class AAA extends java.lang.Object
5.2.1.2 Description
The AAA class provides useful constants for the Diameter Java API.
5.2.1.3 Fields
public static final int NO_SESSION_CODE = 0
A constant which will never be returned as a session code.
public static final int NO_VENDOR_CODE = 0
A constant which will never be returned as a vendor code.
public static final int NO_COMMAND_CODE = 0
A constant which will never be used as a command code code.
public static final int NO_EXTENSION_CODE = 0
A constant which will never be used as an extension code
public static final int NO_AVP_CODE = 0
A constant which will never be used as an AVP code.
The following constants are used for AAAMessage status codes:
public static final short SUCCESS = 0
public static final short FAILURE = 1
public static final short POOR_REQUEST = 2
Kempf, Calhoun, Frascone expires June 2001 [Page 45]
INTERNET DRAFT December 2000
public static final short INVALID_AUTH = 3
public static final short UNKNOWN_SESSION_ID = 4
public static final short USER_UNKNOWN = 5
public static final short COMMAND_UNSUPPORTED = 6
public static final short TIMEOUT = 7
public static final short AVP_UNSUPPORTED = 8
public static final short REALM_NOT_SERVED = 9
public static final short UNSUPPORTED_TRANSFORM = 10
public static final short AUTHENTICATION_REJECTED = 11
public static final short AUTHORIZATION_REJECTED = 12
public static final short INVALID_AVP_VALUE = 13
public static final short MISSING_AVP = 14
public static final short UNABLE_TO_DELIVER = 15
These constands are returned from remote servers and correspond
directly to the result codes in the Diameter specification [1]. Note
that the above list does not contain the REDIRECT_INDICATION status
code. The API library is required to handle redirects transparently
to the client, so the client does not have to become involved in the
details of handling brokering.
Currently, there are no message flags defined for Diameter in [1], so
the only legal flag value is the following:
public static final short NO_MSG_FLAG = 0
The following constants are used for AVPDescriptor flags:
public static final int EMPTY_FLAG = 0x00000
public static final int MANDATORY_FLAG = 0x00001
public static final int RESERVED_FLAG = 0x00002
public static final int VENDOR_SPECIFIC_FLAG = 0x00004
public static final int END_TO_END_ENCRYPT_FLAG = 0x00010
The semantics of the flags are:
EMPTY_FLAG -Indicates that no AVP flags are set.
MANDATORY_FLAG - Represents the 'M' flag in the Diameter AVP
header [1], meaning the AVP is mandatory.
RESERVED-RESERVED - Represents the 'R' flag in the Diameter AVP
header [1]. This flag is reserved and should
not be set.
VENDOR_SPECIFIC_FLAG - Represents the 'V' flag in the Diameter AVP
header [1], meaning that the AVP is vendor
specific. If this flag is set, the header
Kempf, Calhoun, Frascone expires June 2001 [Page 46]
INTERNET DRAFT December 2000
will contain a vendor identifier.
END_TO_END_ENCRYPT_FLAG - Represents the 'P' flag in the Diameter
AVP header [1], meaning that the AVP is
end-to-end encrypted [5].
5.2.2 Class AVPDictionary
5.2.2.1 Synopsis
public class AVPDictionary extends java.lang.Object
5.2.2.2 Description
The AVPDictionary class provides a mapping between AVP names and
codes and an AVPDescriptor. Methods are also provided to return
distinguished values that can be used like C enum type values to
limit or check the values of incoming or outgoing AVPs. Dictionaries
are created for specific vendors, and a global dictionary is
available for AVPs that are not vendor specific.
5.2.2.3 Class Methods
public AVPDictionary getAVPDictionary(String vendorName)
Return an AVPDescriptor dictionary for the vendor. For the global
dictionary, use a vendor name of the empty string, "". If the
dictionary doesn't exist yet, create it.
Parameters:
vendorName - Name of the vendor for the dictionary. Use empty
string, "", for the global dictionary.
public static java.util.Iterator getVendorNames()
Return an iterator of known vendor names.
5.2.2.4 Instance Methods
public int getVendorName()
Return the vendor name for this dictionary.
Kempf, Calhoun, Frascone expires June 2001 [Page 47]
INTERNET DRAFT December 2000
public int getVendorId()
Return the vendor id for this dictionary.
public AVPDescriptor findAVPByName(java.lang.String avpName)
Return an AVPDescriptor for the AVP matching the name, or null if
none.
Parameters:
avpName - The name of the AVP to match.
The return value is the AVPDescriptor matching the name, or null if
none.
public AVPDescriptor findAVPByCode(int avpCode)
Return an AVPDescriptor for the AVP matching the code, or null if
none.
Parameters:
avpCode - The code of the AVP to match.
The return value is the AVPDescriptor matching the code, or null if
none.
public AVPValueDescriptor findValueByName(java.lang.String valueName)
Find distinguished value by name.
Parameters are:
valueName - Name of distinguished value.
The return value is the AVPValueDescriptor object or null if none.
5.2.3 Class AVPDescriptor
5.2.3.1 Synopsis
public class AVPDescriptor extends java.lang.Object
5.2.3.2 Description
An AVPDescriptor object contains a description of an AVP.
Kempf, Calhoun, Frascone expires June 2001 [Page 48]
INTERNET DRAFT December 2000
5.2.3.3 Fields
public int code
The AVP's code.
public int vendorCode
The AVP vendor's code. If global, the NO_VENDOR_CODE.
public java.lang.String name
The AVP's name.
public java.lang.String vendorName
The AVP's vendor name, or empty string ("") if none.
public java.lang.String type
The name of the Java class for the AVP's type. This will be one of:
"java.lang.String" - The AVP has string type.
"java.net.InetAddress" - The AVP has address type.
"B[" - The AVP has byte array type.
"java.lang.Integer" - The AVP has integer (32 bit) type.
"java.lang.Long" - The AVP has long (64 bit) type.
"java.util.Date" - The AVP has date type.
"java.io.Externalizable" - The AVP has COMPLEX type.
public short flags
The AVP's flags. Flag values are defined in the AAA class.
5.2.3.4 Instance Methods
public void registerComplexDataClass(java.lang.String complexClassName)
Register a class for creating a COMPLEX AVP. The class must implement
the java.io.Externalizable interface, and the
Externalizable.writeExternal() and Externalizable.readExternal()
Kempf, Calhoun, Frascone expires June 2001 [Page 49]
INTERNET DRAFT December 2000
methods must implement serialization and deserialization of the AVP
value to the input and output streams. The Class.newInstance()
method is called to create an instance when an incoming message must
be processed, so the class must additionally implement a no-argument
constructor.
Parameters are:
complexClassName - The name of the class to register.
Exceptions are:
java.lang.IllegalArgumentException - Thrown if the argument is
null, if the name does not
correspond to a defined
class, if the class does not
implement the
java.io.Externalizable
interface, or if the class
does not implement a no
argument constructor.
java.lang.IllegalStateException - Thrown if the AVP is not of
COMPLEX type.
public java.lang.String toString()
Return a nicely formatted string describing the object.
5.2.4 Class AVPValueDescriptor
5.2.4.1 Synopsis
public class AVPValueDescriptor extends java.lang.Object
5.2.4.2 Description
The AVPValueDescriptor class describes a distinguished AVP value.
Application profile extensions can use this class to limit the values
of incoming or outgoing AVPs, similar to the C enum type.
5.2.4.3 Fields
public java.lang.String name
The distinguished value's name.
public java.lang.String vendorName
Kempf, Calhoun, Frascone expires June 2001 [Page 50]
INTERNET DRAFT December 2000
The distinguished value's vendor name.
public java.util.Map values
A Map with name Strings as keys and value Strings as values. The
value Strings are the values to which the AVP should be restricted.
5.2.4.4 Instance Methods
public java.lang.String toString()
Return a nicely formatted string describing the object.
5.2.5 Class AAACommandDescriptor
5.2.5.1 Synopsis
public class AAACommandDescriptor
extends java.lang.Object
5.2.5.2 Definition
The AAACommandDescriptor class describes an AAA command in an
application profile extension. The AAACommandDescriptor maintains the
singleton pattern. There is only one command descriptor object per
registered command, and command descriptor objects can only be
created through the AAAExtensionDescriptor object.
5.2.5.3 Instance Methods
public String getName()
Return the command's name.
public int getCode()
Return the command's code.
public String getVendorName()
Return the command's vendor name.
public int getVendorCode()
Return the command's vendor code.
public AAAExtensionDescriptor getExtension()
Kempf, Calhoun, Frascone expires June 2001 [Page 51]
INTERNET DRAFT December 2000
Return the extension descriptor with which the command is registered.
public java.util.Iterator getMandatoryAVPNames()
Return an iterator of mandatory AVP names.
public java.lang.String toString()
Return a nicely formatted string describing the object.
5.2.6 AAAExtensionDescriptor
5.2.6.1 Synopsis
public class AAAExtensionDescriptor extends java.lang.Object
5.2.6.2 Description
The AAAExtensionDescriptor class provides a model for an AAA
application profile extension. AAAExtensionDescriptor maintains a
singleton pattern, so there is only one instance of each
AAAExtensionDescriptor object defined per virtual machine.
AAAExtensionDescriptor manages AAACommandDescriptor objects
describing the messages that make up the extension.
5.2.6.3 Class Methods
public static AAAExtensionDescriptor getExtension(java.lang.String name)
Return the extension descriptor corresponding to the name, or null if
none.
Parameters are:
name - The name of the extension to return.
public static java.util.Iterator getRegisteredExtensions()
Return an iterator containing all the registered extension
descriptors.
public static
AAAExtensionDescriptor registerExtension(int code,
java.lang.String name,
java.lang.String vendorName)
Kempf, Calhoun, Frascone expires June 2001 [Page 52]
INTERNET DRAFT December 2000
Return an extension descriptor matching the parameters. The object is
created if it does not yet exist.
The parameters are:
code -Integer giving the Diameter extension code.
name - The extension name.
vendorName - Name of the vendor for this extension, or empty
string if global.
5.2.6.4 Instance Methods
public int getCode()
Return the extension code for this extension.
public java.lang.String getName()
Return the extension name.
public java.lang.String getVendorName()
Return the vendor name for this extension, or the empty string if the
extension is global.
public AAACommandDescriptor
registerCommand(int code,
java.lang.String name,
java.util.Collection mandatoryAVPNames)
Register the command with name and code as belonging to this
extension. Returns the AAACommandDescriptor object describing the
command. If the command has already been registered, the existing
object is returned. If not, the object is created.
The parameter is:
code - The integer command code.
name - String with the command's name.
mandatoryAVPNames - Collection of Strings giving the names of
mandatory AVPs.
The return value is the registered command object.
Kempf, Calhoun, Frascone expires June 2001 [Page 53]
INTERNET DRAFT December 2000
public void deregisterCommand(java.lang.String name)
Deregister the command object having the given name. If no command
having the given name is registered,
java.lang.IllegalArgumentException is thrown.
The parameter is:
name - Name of the command to deregister
Exceptions thrown:
java.lang.IllegalArgumentException - Thrown if the name is not
registered.
public AAACommandDescriptor getCommand(java.lang.String name)
Get the command descriptor object corresponding to the name. If no
such command is registered, return null.
The parameter is:
name - Name of the command.
The return value is the command object, or null if none.
public java.util.Iterator getRegisteredCommandNames()
Return an iterator of names for registered commands. If no commands
are registered, then return an empty Iterator.
public java.lang.String toString()
Return a nicely formatted description of the extension descriptor.
5.3 Messages and AVPs
5.3.1 Class AAAMessage
5.3.1.1 Synopsis
public class AAAMessage
extends java.lang.Object implements java.io.Externalizable
Kempf, Calhoun, Frascone expires June 2001 [Page 54]
INTERNET DRAFT December 2000
5.3.1.2 Definition
The AAAMessage object represents an incoming or outgoing message. An
instance of an AAAMessage consists of a map with AVP names as keys
and AVP objects as values. Accessors are also available for other
information, including the AAACommandDescriptor that describes the
message.
An AAAMessage object is sent to the AAA server using the
AAAMessage.send() method. The AAAMessage.send() method is
synchronous, and returns the reply message from the server, or an
AAAException is thrown if the server does not reply within the
timeout. The API library uses the java.io.Externalizable interface
methods Externalizable.writeExternal() and
Externalizable.readExternal() internally to serialize and deserialize
the message in the proper Diameter format.
5.3.1.3 Constructor
public AAAMessage(AAACommandDescriptor descriptor,
int flags,
int statusCode)
Create an AAAMessage object.
Parameters are:
descriptor - The AAACommandDescriptor object giving the message's
command type.
flags - The message flags. Currently there are no flags defined
for Diameter so the only legal value is NO_MSG_FLAG.
statusCode - The status code of the message, which is one of the
status code constants defined in class AAA.
5.3.1.5 Instance Methods
public int getIdentifier()
Return the message's identifier.
public String getCommandDescriptor()
Return the message's command descriptor.
public int getStatusCode()
Kempf, Calhoun, Frascone expires June 2001 [Page 55]
INTERNET DRAFT December 2000
Return the message's status code.
public int getFlags()
Return the message's flags.
public java.util.Map getAVPMap()
Returns a Map of AVP objects for the message. Keys are the AVP names.
public java.net.InetAddress getOriginAddress()
Return the IP address of the machine where the message originated.
For messages created on this machine, it will be the localhost IP
address. The AAA library code sets it to the correct interface
address on multihomed machines.
public java.net.InetAddress getSenderAddress()
Return the IP address of the machine where the message was sent. For
messages created on this machine, it will be the localhost IP
address. The AAA library sets it to the correct interface address on
multihomed machines. For incoming messages, this will be the same as
the address of origin, unless the message was proxied.
public AAAMessage[]
synchronized send(int sessionId,InetAddress[] recipients)
throws AAAException
Send this message to the session identified by the session id, wait
for return messages, and return them as an array. The outgoing
message is sent to the recipients. If any recipient is not a
participant in the session, java.lang.IllegalArgumentException is
thrown. If recipients is null, then the message is sent to all
participants in the session. The method is synchronized to prevent
two different threads from sending the same message at the same time.
Note that the AAAMessage.send() method is required to handle the
details of redirection. If the return message contains the
REDIRECT_INDICATION [1] status code set, then the API library must
perform the redirection transparently to the API client. The API
library may also update the session description associated with the
session id in order to avoid incurring the overhead of a redirection
on future attempts involving the session.
Parameters are:
sessionId - The session id of the session to join.
Kempf, Calhoun, Frascone expires June 2001 [Page 56]
INTERNET DRAFT December 2000
recipients - The message recipients.
The return value is an array of return messages.
Exceptions thrown:
AAAException - Thrown with one of the following error codes:
FAILURE, SECURITY, UNKNOWN_CMD, MISSING_AVP,
TIMED_OUT, CANNOT_SEND_MSG, NETWORK_ERROR,
SESSION_INVALID.
public java.lang.String toString()
Return a nicely formatted string describing the object.
5.3.2 Class AVP
5.3.2.1 Synopsis
public class AVP
extends java.lang.Object implements java.io.Externalizable
5.3.2.2 Description
The AVP class models an AAA AVP (attribute/value pair) object. An AVP
may be created with data having one of the following Java types:
java.lang.String - String data.
java.net.InetAddress - An IP address.
byte[] - An array of bytes.
java.lang.Integer - An integer.
java.lang.Long - A long.
java.util.Date - A date object.
java.io.Externalizable - A data object of Diameter type COMPLEX.
The java.io.Externalizable interface methods
Externalizable.writeExternal() Exernalizable.readExternal() on AVP
are used internally to serialize and deserialize the AVP into the
proper Diameter format. If the AVP is of type COMPLEX, a data class
must be registered with the AVPDescriptor. The data class must
Kempf, Calhoun, Frascone expires June 2001 [Page 57]
INTERNET DRAFT December 2000
implement the java.io.Externalizable interface for serializing and
deserializing the data object.
5.3.2.3 Constructor
public AVP(AVPDescriptor descriptor,
java.lang.Object data)
Create a new AVP object.
Parameters are:
descriptor - An AVPDescriptor object describing the AVP.
data - The AVP's data. If data is not one of the standard types,
java.lang.IllegalArgumentException is thrown. The data
parameter's class is checked against the registered class.
Exceptions thrown:
java.lang.IllegalArgumentException - Thrown if either parameter is
null, if the data type does
not match the descriptor's
AVP type, or if the data
class does not implement the
java.io.Externalizable
interface and does not
support a no argument
constructor.
5.3.2.4 Instance Methods
public AVPDescriptor getDescriptor()
Return the AVP's descriptor.
public java.lang.Object getData()
Return the AVP data as the appropriate Java object.
java.lang.String toString()
Return a nicely formatted string describing the object.
5.3.3 Class EncapsulatingAVP
Kempf, Calhoun, Frascone expires June 2001 [Page 58]
INTERNET DRAFT December 2000
5.3.3.1 Synopsis
public class EncapsulatingAVP extends AVP
5.3.3.2 Description
The EncapsulatingAVP models the Encapsulating-AVP type. It extends
AVP with methods to allow encapsulation and decapsulation of the
contents.
5.3.3.3 Constructor
public EncapsulatingAVP(java.util.Map avpMap)
Create an encapsulating AVP from the AVPs in the map.
Parameters are:
avpMap - a java.util.Map object containing the AVPs to be
encapsulated. The map keys are the AVP names, the values
are the AVP objects.
Exceptions thrown:
java.lang.IllegalArgumentException - Thrown if the map is null,
empty, or of the wrong
contents type.
5.3.3.4 Instance Methods
public java.util.Map decapsulate()
Return a map containing the encapsulating AVP's contents,
decapsulated.
5.4 Session Management
5.4.1 Class AAASessionManager
5.4.1.1 Synopsis
public class AAASessionManager extends java.lang.Object
5.4.1.2 Description
Kempf, Calhoun, Frascone expires June 2001 [Page 59]
INTERNET DRAFT December 2000
The AAASessionManager class provides a session manager object that
allows clients to establish sessions with Diameter servers and to
access sessions established during startup from static configuration
information. The class maintains a singleton pattern for the session
manager object.
5.4.1.3 Class Methods
public static AAASessionManager getSessionManager()
Return the distinguished session manager object for the Diameter API
library.
5.4.1.4 Instance Methods
public static int startSession(InetAddress[] hosts)
Open a new AAA session. The session is established over the list of
hosts in the parameter. Note that the host do not need to be included
in the configuration file. Sessions can be established with
dynamically discovered hosts.
Parameters:
hosts - An array of InetAddress objects for hosts that should be
included in the session. If any of the hosts already have
a session open, the method throws
IllegalArgumentException.
Return value is the session code.
Exceptions thrown:
java.lang.IllegalArgumentException - Thrown if any of the hosts
have a session already open.
public static void endSession(int sessionCode)
Close the indicated session.
Parameters:
sessionId - The session code of the session to close.
Exceptions thrown:
java.lang.IllegalArgumentException - Thrown if sessionCode is not
valid.
Kempf, Calhoun, Frascone expires June 2001 [Page 60]
INTERNET DRAFT December 2000
public static int getSessionCode(InetAddress host)
Return the session code corresponding to the host. If no session is
currently active with the host, return NO_SESSION_CODE.
Parameters:
host - The host for which the session code is sought.
Return value is the session code, or NO_SESSION_CODE if none.
public static InetAddress[] getConfiguredHosts()
Return an array of InetAddress objects for configured AAA hosts.
public void setSessionTimeout(int sessionCode,int timeout)
Set the timeout on a particular session. The timeout determines how
long the session manager waits for a reply before giving up.
Parameters are:
sessionCode - The session code.
timeout - The new timeout, in milliseconds.
public static void
registerUnsolicitedMessageListener(int sessionCode,
UnsolicitedMessageListener listener)
Register a listener for handling unsolicited messages associated with
a particular session. If a listener already exists for this session,
replace it.
Parameters are:
sessionCode - The session code.
listener - The listener.
5.4.2 Interface UnsolicitedMessageListener
5.4.2.1 Synopsis
public interface UnsolicitedMessageListener
5.4.2.2 Description
Kempf, Calhoun, Frascone expires June 2001 [Page 61]
INTERNET DRAFT December 2000
Instances of classes that implement the UnsolicitedMessageListener
interface handle unsolicited messages on a particular session
connection.
5.4.2.3 Instance Methods
public void processUnsolicitedMessage(int sessionCode,
AAAMessage message);
Process an unsolicited message for a particular session.
Parameters are:
sessionId - The session id.
message - The message.
6.0 Security Considerations
This document describes an API and therefore depends on the security
mechanisms defined in the Diameter protocol [1].
7.0 References
[1] Calhoun, P., Rubens, A., Akhtar, H., and Guttman, E., "The DIAMETER
Base Protocol," draft-calhoun-diameter-17.txt, a work in progress.
[2] Calhoun, P., Zorn, G., Pan, P., and Akhtar, H. "Diameter Framework
Document," draft-calhoun-diameter-framework-08.txt, a work in pro-
gress.
[3] Microsoft Windows 3.1 Reference Manual, Microsoft Corp., 1992.
[4] Crocker, D. and Overell, P., "Augmented BNF Syntax Specifications:
ABNF", RFC 2234, November, 1997.
[5] Calhoun, P., Bulley, W., and Farrell, S. "DIAMETER Strong Security
Extension", draft-calhoun-diameter-strong-crypto-03.txt, a work in
progress.
[6] Guttman, E., Perkins, C., Veizades, J., and Day, M., "Service Loca-
tion Protocol, Version 2," RFC 2608, June, 1999.
8.0 Authors' Addresses
Questions about this memo can be directed to:
Kempf, Calhoun, Frascone expires June 2001 [Page 62]
INTERNET DRAFT December 2000
James Kempf
Sun Labs California
Sun Microsystems, Inc.
901 San Antonio Rd., UMPK15-214
Palo Alto, CA, 94303
USA
Phone: +1 650 786 5890
Fax: +1 650 786 6445
E-Mail: james.kempf@sun.com
Pat Calhoun
Sun Labs California
Sun Microsystems, Inc.
901 San Antonio Rd., UMPK15-214
Palo Alto, CA, 94303
USA
Phone: +1 650 786 7733
Fax: +1 650 786 6445
E-Mail: pat.calhoun@sun.com
David Frascone
Sun Labs California
1600 North Dallas Parkway, Suite 700
Dallas, TX 75248
Phone: +1 972 386 1283
E-Mail: codemonkey@sun.com
9.0 Full Copyright Statement
Copyright (C) The Internet Society (2000). All Rights Reserved.
This document and translations of it may be copied and furnished
to others, and derivative works that comment on or otherwise
explain it or assist in its implementation may be prepared, copied,
published and distributed, in whole or in part, without restric-
tion of any kind, provided that the above copyright notice and
this paragraph are included on all such copies and derivative
works. However, this docu- ment itself may not be modified in any
way, such as by removing the copyright notice or references to the
Internet Society or other Inter- net organizations, except as needed
for the purpose of developing Internet standards in which case
the procedures for copyrights defined in the Internet Standards pro-
cess must be followed, or as required to translate it into languages
other than English. The limited permis- sions granted above are
Kempf, Calhoun, Frascone expires June 2001 [Page 63]
INTERNET DRAFT December 2000
perpetual and will not be revoked by the Internet Society or
its successors or assigns. This document and the information con-
tained herein is provided on an "AS IS" basis and THE INTERNET
SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRAN-
TIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WAR-
RANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE
ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS
FOR A PARTICULAR PURPOSE."
Kempf, Calhoun, Frascone expires June 2001 [Page 64]