INTERNET DRAFT James Kempf Category: Informational Pat Calhoun Title: draft-kempf-diameter-api-01.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 May 2001 [Page 1] INTERNET DRAFT November 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 Extension 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 May 2001 [Page 2] INTERNET DRAFT November 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 Dictionary 5.3 Commands and AVPs 5.3.1 Interface AAAListener 5.3.2 Class AAACommand 5.3.3 Class AVP 5.3.4 Class EncapsulatingAVP 5.3.5 AAAExtension 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 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 Kempf, Calhoun, Frascone expires May 2001 [Page 3] INTERNET DRAFT November 2000 API as callback functions for C and as listener callback objects in Java. The callbacks and subclasses implement the application profile processing. 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. As mentioned, the C API supports application customizability through callback functions, while the Java API supports customizability through listener objects. 2.0 Configuration File Format The primary purpose of the file format is to allow AVPs and vendor definitions to be portably exchanges. 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, - 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, Kempf, Calhoun, Frascone expires May 2001 [Page 4] INTERNET DRAFT November 2000 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 values are not. 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, Kempf, Calhoun, Frascone expires May 2001 [Page 5] INTERNET DRAFT November 2000 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 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 extensions, and these are identified by a vendor extension tag. 2.2.3.1 AVP Definitions AVP definitions have the following format: Kempf, Calhoun, Frascone expires May 2001 [Page 6] INTERNET DRAFT November 2000 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-value-param = ws "Value" ws "=" ws numeric-id avp-type-param = ; Name of one of the standard Diameter types, see [1]. 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 = ; Value of one of the standard Diameter types, see [1]. 2.3 Examples This section contains a few example files to illustrate the format. 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 Kempf, Calhoun, Frascone expires May 2001 [Page 7] INTERNET DRAFT November 2000 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 telnet = 21 [Value Luna.Location] Copernicus-Crater = 1 Hadiley-Rill = 2 In this case, Joes-Fly-By-Nite.Trust-Me AVP is a vendor specific AVP and 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 Kempf, Calhoun, Frascone expires May 2001 [Page 8] INTERNET DRAFT November 2000 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. 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. 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. Kempf, Calhoun, Frascone expires May 2001 [Page 9] INTERNET DRAFT November 2000 Dynamic determination is possible using means such as SLP [6]. 3.5 Callback Processing Order Both APIs allow clients to register message processors (callbacks in C, listeners in Java) that are invoked before and after the bulk of the processing functions for a message. Only one pre- or post- processor is allowed. If the API client adds another, any existing pre- and post-processors are simply moved down or up the list. Message processing can be best explained by the following diagram: +-------+ +-------+ +-------+ +-------+ | First | | Any | | Any | | Last | Apps +-------+ +-------+ +-------+ +-------+ ^ ^ ^ ^ 1 | 2 | 3 | 4 | +-------------------------------------------------+ | AAA Library | +-------------------------------------------------+ ^ | MSG In the above diagram, "First", "Any", and "Last" are added by the API client. The message processor labeled "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 are moved to "Any". If one of the "Any" processors completes successfully, the message is not passed on any further. In the case of the C API, a successful completion means the success return code is returned, in the case of Java successful completion means no exception is thrown. In the C API, the callback is then responsible for freeing the message. 4.0 C API The C language API is designed around call backs. 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. Kempf, Calhoun, Frascone expires May 2001 [Page 10] INTERNET DRAFT November 2000 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; 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 Kempf, Calhoun, Frascone expires May 2001 [Page 11] INTERNET DRAFT November 2000 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 Extension 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 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 Kempf, Calhoun, Frascone expires May 2001 [Page 12] INTERNET DRAFT November 2000 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 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. Kempf, Calhoun, Frascone expires May 2001 [Page 13] INTERNET DRAFT November 2000 4.1.10 Callback Handle 4.1.10.1 Synopsis 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 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, Kempf, Calhoun, Frascone expires May 2001 [Page 14] INTERNET DRAFT November 2000 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 occurred 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. AAA_ERR_PROTO - This code is returned if a AAA protocol error occurred. 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. Kempf, Calhoun, Frascone expires May 2001 [Page 15] INTERNET DRAFT November 2000 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 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, Kempf, Calhoun, Frascone expires May 2001 [Page 16] INTERNET DRAFT November 2000 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; 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. Kempf, Calhoun, Frascone expires May 2001 [Page 17] INTERNET DRAFT November 2000 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 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; Kempf, Calhoun, Frascone expires May 2001 [Page 18] INTERNET DRAFT November 2000 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 The following type is for the AAA message flags. Currently, there are no message flags defined in the Diameter protocol [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, Kempf, Calhoun, Frascone expires May 2001 [Page 19] INTERNET DRAFT November 2000 AAA_DOMAIN_NOT_SERVED, AAA_UNSUPPORTED_TRANSFORM, AAA_AUTHENTICATION_REJECTED, AAA_AUTHORIZATION_REJECTED, AAA_INVALID_AVP_VALUE, AAA_MISSING_AVP } 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 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; Kempf, Calhoun, Frascone expires May 2001 [Page 20] INTERNET DRAFT November 2000 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. 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 represnting 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 Kempf, Calhoun, Frascone expires May 2001 [Page 21] INTERNET DRAFT November 2000 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. 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. Kempf, Calhoun, Frascone expires May 2001 [Page 22] INTERNET DRAFT November 2000 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. 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. Kempf, Calhoun, Frascone expires May 2001 [Page 23] INTERNET DRAFT November 2000 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: 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: Kempf, Calhoun, Frascone expires May 2001 [Page 24] INTERNET DRAFT November 2000 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); 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 occurred while registering the callback. 4.4.2.2 AAARegisterNoncommandCallback() The following callback registers an AAA callback to process all messages. The callback is not associated with any command, but rather Kempf, Calhoun, Frascone expires May 2001 [Page 25] INTERNET DRAFT November 2000 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 occurred while registering the callback. 4.4.2.3 AAADeregisterCommandCallback() The following function deregisters a command callback: AAAReturnCode AAADeregisterCommandCallback(AAACallbackHandle *handle); Parameters are: 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. Kempf, Calhoun, Frascone expires May 2001 [Page 26] INTERNET DRAFT November 2000 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 occurred. 4.4.3 Session and Server Management 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. Kempf, Calhoun, Frascone expires May 2001 [Page 27] INTERNET DRAFT November 2000 AAA_ERR_NOMEM - If a memory allocation failure occurred. 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. AAA_ERR_NOMEM - If a memory allocation failure occurred. 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: Kempf, Calhoun, Frascone expires May 2001 [Page 28] INTERNET DRAFT November 2000 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 particular session: AAAReturnCode AAASetSessionMessageTimeout(AAASessionId *id, time_t timeout); The parameters are: id - The session id for the session whose timeout should be changed. 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". Kempf, Calhoun, Frascone expires May 2001 [Page 29] INTERNET DRAFT November 2000 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. 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. Kempf, Calhoun, Frascone expires May 2001 [Page 30] INTERNET DRAFT November 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.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. 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 Kempf, Calhoun, Frascone expires May 2001 [Page 31] INTERNET DRAFT November 2000 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 occurred. 4.4.4.6 AAAGetCommandCode() 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. Kempf, Calhoun, Frascone expires May 2001 [Page 32] INTERNET DRAFT November 2000 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. 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 occurred. 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() Kempf, Calhoun, Frascone expires May 2001 [Page 33] INTERNET DRAFT November 2000 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. 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, Kempf, Calhoun, Frascone expires May 2001 [Page 34] INTERNET DRAFT November 2000 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. 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. Kempf, Calhoun, Frascone expires May 2001 [Page 35] INTERNET DRAFT November 2000 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. 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. Kempf, Calhoun, Frascone expires May 2001 [Page 36] INTERNET DRAFT November 2000 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: 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. Kempf, Calhoun, Frascone expires May 2001 [Page 37] INTERNET DRAFT November 2000 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: 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() Kempf, Calhoun, Frascone expires May 2001 [Page 38] INTERNET DRAFT November 2000 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: 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. Kempf, Calhoun, Frascone expires May 2001 [Page 39] INTERNET DRAFT November 2000 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 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 occurred. Kempf, Calhoun, Frascone expires May 2001 [Page 40] INTERNET DRAFT November 2000 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 The Java API is designed around listener callback objects for application profiles. APIs are provided to access the basic AAA capability to register listener objects to handle messages, to create and send messages, and to model AVPs. Classes also provide access to the AAA AVP and vendor dictionaries. 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. 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. 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 Kempf, Calhoun, Frascone expires May 2001 [Page 41] INTERNET DRAFT November 2000 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 DiameterException class is the class for returning all Diameter 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 PROTO = 2; public static final short SECURITY = 3; public static final short UNKNOWN_CMD = 4; public static final short MISSING_AVP = 5; public static final short TIMED_OUT = 6; public static final short INIT_FAILURE = 7; public static final short CANNOT_SEND_MSG = 8; public static final short NETWORK_ERROR = 9; public static final short SESSION_INVALID = 10; Note that these status codes are separate from the codes returned by remote AAA servers. FAILURE - This code indicates an unspecified failure occurred during an AAA operation. PROTO - This code indicates a AAA protocol error occurred. 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. Kempf, Calhoun, Frascone expires May 2001 [Page 42] INTERNET DRAFT November 2000 TIMED_OUT - This code indicates that a network operation timed out. INIT_FAILURE - This code is thrown by the initialization if some problem occurred 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. It is also of use to application profile extensions that encounter the same error condition. NETWORK_ERROR - This code indicates that an error in networking occurred. In addition to returning the error code, functions are required to log errors using the platform dependent logging facility. 5.2 Library Management and Dictionary Management 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 automatic library initialization, extension registration, session handling, and miscellaneous information on AAA configuration. It also contains a few useful constants. During library initialization, the following Java properties (accessible through the java.util.Properties class) are used. These properties must be set before the AAA class 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 pathname of Kempf, Calhoun, Frascone expires May 2001 [Page 43] INTERNET DRAFT November 2000 the configuration file. Default is system dependent. org.ietf.aaa.defaultConfigFileName - A String containing the platform specific default configuration file name. Upon being loaded, the AAA class loads any configuration files, including the dictionary and vendor files, establishes connections with AAA servers and domains listed in the configuration files, loads any application profile extensions listed in the configuration files, and does any other initialization needed to start the AAA client. After the AAA library is loaded, the program can register additional application profile extensions and commands and send messages to AAA peers. The library handles processing of incoming commands. 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 getSessionId() to return the session id associated with a particular host. 5.2.1.3 Fields public static final int NO_SESSION_ID = 0; A constant which will never be returned as a session id. public static final int NO_VENDOR_ID = 0; A constant which will never be returned as a vendor id. public static final int NO_COMMAND_ID = 0; A constant which will never be used as a command code id. public static final int NO_AVP_ID = 0; A constant which will never be used as an AVP id. public static final int DEFAULT_PORT = 1812; The default AAA port number. public static final int UNKNOWN_DOMAIN = 0; public static final int LOCAL_DOMAIN = 1; public static final int PROXY_DOMAIN = 2; public static final int BROKER_DOMAIN = 3; Kempf, Calhoun, Frascone expires May 2001 [Page 44] INTERNET DRAFT November 2000 public static final int FORWARD_DOMAIN = 4; These flags are used to indicate the AAA domain interconnect type. The flags have the following semantics: UNKNOWN_DOMAIN - The domain interconnect type is unknown. LOCAL_DOMAIN - The domain is for the local. PROXY_DOMAIN - The domain is a prox. 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]. BROKER_DOMAIN - The domain is a broker. A broker is a server that provides redirect services, allowing all servers in a roaming consortium to interact directly. FORWARD_DOMAIN - The domain is 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]. 5.2.1.4 Class 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 configured. Sessions can be established with dynamically discovered hosts. Parameters: hosts - An array of InetAddress objects for hosts that should be included in the session. Return value is the session id. public static void endSession(int sessionId); Close the indicated session. Kempf, Calhoun, Frascone expires May 2001 [Page 45] INTERNET DRAFT November 2000 Parameters: public static int getSessionId(InetAddress host); Return the session id corresponding to the host. If no session is currently active with the host, return NO_SESSION_ID. Parameters: host - The host for which the session id is sought. Return value is the session id, or NO_SESSION_ID if none. public static void registerExtension(AAAExtension extension); Register the AAA application profile extension object. Registering the extension object registers all the command listeners in the commands registered with the extension. Parameters: extension - The extension object to register. sessionId - The session id of the session to close. If sessionId is not a valid id, java.lang.InvalidArgumentException is thrown. public static InetAddress[] getConfiguredHosts(); Return an array of InetAddress objects for configured AAA hosts. These hosts can be used to set up a session. public static int getConfiguredPort() Return the configured AAA port. This may differ from the default AAA port. public static short getHostDomainInterconnectType(InetAddress host); Return the domain AAA interconnect type for the host. The return value will be one of the constants UNKNOWN_DOMAIN, LOCAL_DOMAIN, PROXY_DOMAIN, BROKER_DOMAIN, or FORWARD_DOMAIN. 5.2.2 Class Dictionary Kempf, Calhoun, Frascone expires May 2001 [Page 46] INTERNET DRAFT November 2000 5.2.2.1 Synopsis public class Dictionary extends java.lang.Object 5.2.2.2 Description The Dictionary class provides a mapping between AVP names and codes and an AVPDescriptor. The AVPDescriptor provides a map of AVP values. Dictionaries are created for specific vendors, and a global dictionary is available for AVPs that are not vendor specific. 5.2.2.3 Constructors public Dictionary(String vendorName); Return an AVPDescriptor dictionary for the vendor. For the global dictionary, use a vendor name of the empty string, "". Parameters: vendorName - Name of the vendor for the dictionary. Use empty string, "", for the global dictionary. 5.2.2.4 Class Methods public static Vector getVendorNames(); Return a Vector of known vendor names. 5.2.2.5 Instance Methods public int getVendorId(); Return the vendor id for this Dictionary. public AVPDescriptor findByName(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. Kempf, Calhoun, Frascone expires May 2001 [Page 47] INTERNET DRAFT November 2000 public AVPDescriptor findByCode(int avpCode); Return an AVPDescriptor for the AVP matching the code, or NULL if none. Parameters: avpCode - The code of the AVP to match. 5.2.3 Class AVPDescriptor 5.2.3.1 Synopsis public class AVPDescriptor 5.2.3.2 Description An AVPDescriptor object contains a description of an AVP. It also includes a map containing AVPValue objects that describe notable AVP values. 5.2.3.3 Fields public int code; The AVP's code. public java.lang.String name; The AVP's name. 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. Kempf, Calhoun, Frascone expires May 2001 [Page 48] INTERNET DRAFT November 2000 "java.util.Date" - The AVP has date type. Note that if the AVP data type is byte array, it can hold a serialized Java object. public short flags; The AVP's flags. Flag values are defined in the AVP class. 5.2.3.4 Instance Methods public java.util.Map getAVPValueMap(); Return a Map with distinguished AVP value names as keys and AVPValue objects as values. 5.2.4 Class AVPValue 5.2.4.1 Synopsis public class AVPValue extends java.lang.Object 5.2.4.2 Description The AVPValue class describes a distinguished AVP value. 5.3.4.3 Fields public java.lang.String name; The distinguished value's name. public java.util.Map values A Map with names as keys and value objects as values. The names give distinguished names and the objects are the assigned values. 5.3 Commands and AVPs 5.3.1 Interface AAAListener Kempf, Calhoun, Frascone expires May 2001 [Page 49] INTERNET DRAFT November 2000 5.3.1.1 Synopsis public abstract interface AAAListener extends java.util.EventListener 5.3.1.2 Description AAAListener is an interface that processes incoming AAA messages. An AAAListener object can be added to a AAACommand subclass to listen for and process incoming command messages. 5.3.1.3 Instance Methods public void processCommand(AAACommand message) throws AAAException Process an incoming message. The implementation is supplied by the client. Parameters are: message - The incoming AAA message object. Exceptions thrown: AAAException - Thrown by the client code if any error occurs during processing. 5.3.2 Class AAACommand 5.3.2.1 Synopsis public class AAACommand extends java.lang.Object implements java.io.Serializable 5.3.2.2 Definition The AAACommand object represents a defined AAA command. An AAA command is defined within a AAA extension. An instance of an AAA command consists of a map with AVP names as keys and AVP objects as values. Accessors are also available for other command information (command code, status code, flags, identifier, extension, session id, origin address, and sender address). An AAACommand object can either be sent to another AAA peer with the Kempf, Calhoun, Frascone expires May 2001 [Page 50] INTERNET DRAFT November 2000 send() message or received through a callback. Received commands are matched to sent commands using the identifier value obtained with the getIdentifier() method. AAA application profile extensions typically create one AAACommand per message and register AAAListener objects with the command object to handle incoming messages. Clients can also register global pre- or posthandlers that run before or after (respectively) the command handers. 5.3.2.3 Constructor public AAACommand(int flags, java.lang.String name, java.lang.String vendor, int statusCode) Create an AAACommand object. Parameters are: flags -The message flags. name - The message name. vendor - The message's vendor name, empty string if none. statusCode - The status code of the message. 5.3.2.4 Fields public static final short FAILURE = 0; public static final short POOR_REQUEST = 1; public static final short INVALID_AUTH = 2; public static final short UNKNOWN_SESSION_ID = 3; public static final short USER_UNKNOWN = 4; public static final short COMMAND_UNSUPPORTED = 5; public static final short TIMEOUT = 6; public static final short AVP_UNSUPPORTED = 7; public static final short REDIRECT_INDICATION = 8; public static final short DOMAIN_NOT_SERVED = 9; public static final short UNSUPPORTED_TRANSFORM = 10; public static final short AUTHENTICATION_REJECTED = 11; public static final short AUTHORIZATION_REJECTED = 13; public static final short INVALID_AVP_VALUE = 14; public static final short MISSING_AVP = 15; These constants are status codes returned from remote servers and Kempf, Calhoun, Frascone expires May 2001 [Page 51] INTERNET DRAFT November 2000 correspond directly to the result codes in the Diameter specification [1]. 5.3.2.5 Class Methods public static void addPrenotificationListener(AAAListener listener) Register a prenotification AAAListener. The prenotification listener processes all incoming Diameter messages before any command-specific listener does any processing. Prenotification listeners are added sequentially, and an existing listener is moved up the list. If the listener is already present and is a prenotification listener, the method performs no action. The parameters are: listener - The new prenotification listener. public static void addPostnotificationListener(AAAListener listener) Register a postnotification AAAListener. The postnotification listener processes all incoming Diameter messages after all command- specific listener do. Postnotification listeners are added sequentially, and an existing listener is moved down the list. If the listener is already present and is a postnotification listener, the method performs no action. listener - The new postnotification listener. public static void addNotificationListener(AAAListener listener) Register a notification AAAListener. The notification listener is added at the beginning of the list but behind any prenotification listeners. If the listener is already present as a notification listener, the method performs no action. no action. The parameters are: listener - The new notification listener. public static void removeNotificationListener(AAAListener listener) Remove the listener from the list. This method handles pre-, post-, Kempf, Calhoun, Frascone expires May 2001 [Page 52] INTERNET DRAFT November 2000 and regular notification listeners. The parameters are: listener - The notification listener to remove. 5.3.2.6 Instance Methods public String getName(); Return the command's name. public int getStatusCode(); Return the command's status code. public int getFlags(); Return the command'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 void synchronized send(int sessionId,InetAddress[] recipients) throws AAAException; Send this message to the session identified by the session id. The message will be 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 Kempf, Calhoun, Frascone expires May 2001 [Page 53] INTERNET DRAFT November 2000 participants in the session. The message is synchronized to avoid sending the message more than once. The parameters are: sessionId - The session id of the session to join. recipients - The message recipients. public java.lang.String toString() Return a nicely formatted string describing the object. The following error codes are possible if an exception is thrown: FAILURE, SECURITY, UNKNOWN_CMD, MISSING_AVP, TIMED_OUT, CANNOT_SEND_MSG, NETWORK_ERROR, SESSION_INVALID. 5.3.3 Class AVP 5.3.3.1 Synopsis public class AVP extends java.lang.Object implements java.io.Serializable 5.3.3.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. If an object of another type is provided to the constructor, the object is serialized into an array of bytes. Kempf, Calhoun, Frascone expires May 2001 [Page 54] INTERNET DRAFT November 2000 5.3.3.3 Constructor public AVP(int type, int flags, java.lang.String avpName, java.lang.String vendorName, java.lang.Object data); Create a new AVP object. Parameters are: type - One of the defined constants RADIUS or DIAMETER. flags - The AVP flags. avpName - The AVP name, excluding the vendor name. vendorName - The name of the vendor for this AVP. Empty string if none. data - The AVP's data. If data is not one of the standard types, the constructor attempts to serialize it and sends it as an array of bytes. If the object is not serializable or the object's type does not match the AVP's type, then IllegalArgumentException is thrown. 5.3.3.3 Fields public static final short RADIUS = 0; public static final short DIAMETER = 1; These indicate whether the AVP is for Diameter or for Radius compatibility. 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 TAG_PRESENT_FLAG = 0x00008; public static final int END_TO_END_ENCRYPT_FLAG = 0x00010; public static final int LOCAL_FLAG = 0x10000; public static final int UNKNOWN_FLAG = 0x20000; public static final int ENCRYPT_FLAG = 0x40000; These constants are used for AVP and AVPDescriptor flags. The Kempf, Calhoun, Frascone expires May 2001 [Page 55] INTERNET DRAFT November 2000 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 will contain a vendor identifier. TAG_PRESENT_FLAG - Represents the 'T' flag in the Diameter AVP header [1], meaning that the AVP is tagged. If this flag is set, the header will contain a tag. 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]. LOCAL_FLAG - Indicates that the AVP was locally generated and not received from a remote server. This flag is only used in AAA_AVP. UNKNOWN_FLAG - Indicates that the AVP was not located in the AVP dictionary. This flag is only used in AAA_AVP. ENCRYPT_FLAG - Indicates that the AVP was either marked as AAA_AVPI_FLAG_END_TO_END_ENCRYPT or that it was hop-by-hop encrypted (and thus that the AAA_AVPI_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. 5.3.3.4 Instance Methods public short getType(); Return an indicator of whether the AVP is either a Radius Kempf, Calhoun, Frascone expires May 2001 [Page 56] INTERNET DRAFT November 2000 compatibility or Diameter AVP. The return value is one of the constants RADIUS or DIAMETER. public java.lang.String getName(); Return the AVP's name. public java.lang.String getVendorName(); Return the name of the vendor defining the AVP. If this is a globally defined AVP, the empty string, "", is returned. public int getFlags(); Return the AVP flags. public java.lang.object getData(); Return the AVP data as the appropriate Java object. java.lang.String toString(); Return a string representation of the AVP. 5.3.4 Class EncapsulatingAVP 5.3.4.1 Synopsis public class EncapsulatingAVP extends AVP 5.3.4.1 Description The EncapsulatingAVP models the Encapsulating-AVP type. It extends AVP with a method to allow decapsulation of the contents. 5.3.4.2 Constructor public EncapsulatingAVP(java.util.Map avpMap); Create an encapsulating AVP from the AVPs in the map. The parameters are: Kempf, Calhoun, Frascone expires May 2001 [Page 57] INTERNET DRAFT November 2000 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. 5.3.4.3 InstanceMethods public java.util.Map decapsulate(); Return a map containing the encapsulating AVP's contents, decapsulated. 5.3.5 AAAExtension 5.3.5.1 Synopsis public class AAAExtension extends java.lang.Object 5.3.5.2 Description The AAAExtension class provides a model for an AAA application profile extension. AAAExtension maintains a singleton pattern, so there is only one instance of each AAAExtension object defined per virtual machine. 5.3.5.3 Class methods public AAAExtension getAAAExtension(int id, java.lang.String name, java.lang.String vendorName); The parameters are: id - Positive integer giving the Diameter extension id. name - The extension name. vendorName - Name of the vendor for this extension, or empty string if global. public static AAAExtension lookup(java.lang.String name); Lookup an extension by its name. Primarily for outside clients. Kempf, Calhoun, Frascone expires May 2001 [Page 58] INTERNET DRAFT November 2000 The parameter is: name - The extension name. The return value is the extension object, or null if none. 5.3.5.4 Instance Methods public int getId(); Return the extension id 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 void registerCommand(AAACommand command) Register the command object as belonging to this extension. The command is registered under its own name. A command can belong to only one extension, and the method throws java.lang.IllegalArgumentException if an attempt is made to register an already registered command. The parameter is: command - The command object to register. public AAAACommand deregisterCommand(java.lang.String name) Deregister the command object having the given name. Return the command object. If no command object is registered under the name, return null. The parameter is: name - Name of the command object to deregister The return value is the registered command object, or null if none. public AAACommand getCommand(java.lang.String name) Kempf, Calhoun, Frascone expires May 2001 [Page 59] INTERNET DRAFT November 2000 Get the command 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.lang.String toString() Return a nicely formatted description of the object. 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-16.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: James Kempf Kempf, Calhoun, Frascone expires May 2001 [Page 60] INTERNET DRAFT November 2000 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 perpetual and will not be revoked by the Internet Society or Kempf, Calhoun, Frascone expires May 2001 [Page 61] INTERNET DRAFT November 2000 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 May 2001 [Page 62] INTERNET DRAFT November 2000 Appendix A. List of changes from Version -00 - Substituted the word Directory for Dictionary. Some places in the spec, the word Directory was used instead of Dictionary. Kempf, Calhoun, Frascone expires May 2001 [Page 63]