idnits 2.17.1 draft-ietf-dime-diameter-api-08.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** The document seems to lack a License Notice according IETF Trust Provisions of 28 Dec 2009, Section 6.b.i or Provisions of 12 Sep 2009 Section 6.b -- however, there's a paragraph with a matching beginning. Boilerplate error? (You're using the IETF Trust Provisions' Section 6.b License Notice from 12 Feb 2009 rather than one of the newer Notices. See https://trustee.ietf.org/license-info/.) Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There is 1 instance of too long lines in the document, the longest one being 7 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (April 28, 2009) is 5477 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 3588 (Obsoleted by RFC 6733) Summary: 3 errors (**), 0 flaws (~~), 1 warning (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Diameter Maintenance and V. Fajardo, Ed. 3 Extensions (DIME) Toshiba America Research Inc. 4 Internet-Draft P. Calhoun 5 Intended status: Informational D. Frascone 6 Expires: October 30, 2009 Cisco Systems, Inc. 7 April 28, 2009 9 The Diameter API 10 draft-ietf-dime-diameter-api-08.txt 12 Status of this Memo 14 This Internet-Draft is submitted to IETF in full conformance with the 15 provisions of BCP 78 and BCP 79. 17 Internet-Drafts are working documents of the Internet Engineering 18 Task Force (IETF), its areas, and its working groups. Note that 19 other groups may also distribute working documents as Internet- 20 Drafts. 22 Internet-Drafts are draft documents valid for a maximum of six months 23 and may be updated, replaced, or obsoleted by other documents at any 24 time. It is inappropriate to use Internet-Drafts as reference 25 material or to cite them other than as "work in progress." 27 The list of current Internet-Drafts can be accessed at 28 http://www.ietf.org/ietf/1id-abstracts.txt. 30 The list of Internet-Draft Shadow Directories can be accessed at 31 http://www.ietf.org/shadow.html. 33 This Internet-Draft will expire on October 30, 2009. 35 Copyright Notice 37 Copyright (c) 2009 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents in effect on the date of 42 publication of this document (http://trustee.ietf.org/license-info). 43 Please review these documents carefully, as they describe your rights 44 and restrictions with respect to this document. 46 Abstract 48 The Diameter authentication, authorization, and accounting (AAA) 49 protocol provides support for peering AAA transactions across the 50 Internet. This document describes an API for the Diameter protocol. 51 The API is defined for the C language. The intent of the API is to 52 foster source code portability across multiple programming platforms. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 57 1.1. Conventions Used in This Document . . . . . . . . . . . . 4 58 2. Binding Independent Considerations . . . . . . . . . . . . . . 5 59 2.1. Multithreading . . . . . . . . . . . . . . . . . . . . . . 5 60 2.2. Error Reporting . . . . . . . . . . . . . . . . . . . . . 5 61 2.3. String Format . . . . . . . . . . . . . . . . . . . . . . 5 62 2.4. Handling Connections with Other Servers/Peers . . . . . . 5 63 2.5. Command Dictionary File . . . . . . . . . . . . . . . . . 5 64 2.6. Structure Member Visibility . . . . . . . . . . . . . . . 6 65 3. C API . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 66 3.1. Constant Types . . . . . . . . . . . . . . . . . . . . . . 7 67 3.1.1. IP Address and Port . . . . . . . . . . . . . . . . . 7 68 3.1.2. Command Code . . . . . . . . . . . . . . . . . . . . . 7 69 3.1.3. Vendor Identifier . . . . . . . . . . . . . . . . . . 7 70 3.1.4. Extension Identifier . . . . . . . . . . . . . . . . . 8 71 3.1.5. Attribute/Value Pair Code . . . . . . . . . . . . . . 8 72 3.1.6. Value Type Identifier . . . . . . . . . . . . . . . . 8 73 3.1.7. Server Identifier . . . . . . . . . . . . . . . . . . 8 74 3.1.8. Session Identifier . . . . . . . . . . . . . . . . . . 8 75 3.1.9. Message Identifier . . . . . . . . . . . . . . . . . . 8 76 3.1.10. Callback Handle . . . . . . . . . . . . . . . . . . . 9 77 3.1.11. Application Identifier . . . . . . . . . . . . . . . . 9 78 3.1.12. API Return Codes . . . . . . . . . . . . . . . . . . . 9 79 3.1.13. Callback Location Codes . . . . . . . . . . . . . . . 11 80 3.1.14. AVP Data Type Codes . . . . . . . . . . . . . . . . . 11 81 3.1.15. AVP Flags . . . . . . . . . . . . . . . . . . . . . . 12 82 3.1.16. Domain Interconnection Types . . . . . . . . . . . . . 12 83 3.1.17. Message Flags . . . . . . . . . . . . . . . . . . . . 13 84 3.1.18. Result Codes . . . . . . . . . . . . . . . . . . . . . 13 85 3.1.19. Search Direction Type . . . . . . . . . . . . . . . . 13 86 3.1.20. Accounting Types . . . . . . . . . . . . . . . . . . . 14 87 3.2. Structure Definitions . . . . . . . . . . . . . . . . . . 14 88 3.2.1. Dictionary Entry Definition . . . . . . . . . . . . . 14 89 3.2.2. AVP Definition . . . . . . . . . . . . . . . . . . . . 14 90 3.2.3. AVP List . . . . . . . . . . . . . . . . . . . . . . . 15 91 3.2.4. Message Definition . . . . . . . . . . . . . . . . . . 16 92 3.3. Macros and Preprocessor Definitions . . . . . . . . . . . 17 93 3.4. Functions . . . . . . . . . . . . . . . . . . . . . . . . 17 94 3.4.1. Initialization and Configuration . . . . . . . . . . . 17 95 3.4.2. Registering Commands . . . . . . . . . . . . . . . . . 18 96 3.4.3. Session and Server Management . . . . . . . . . . . . 21 97 3.4.4. Dictionary Lookup . . . . . . . . . . . . . . . . . . 24 98 3.4.5. Message Management . . . . . . . . . . . . . . . . . . 27 99 3.4.6. Message Control . . . . . . . . . . . . . . . . . . . 36 100 3.4.7. Accounting . . . . . . . . . . . . . . . . . . . . . . 37 101 3.5. Implementation Notes . . . . . . . . . . . . . . . . . . . 37 102 3.6. Grouped AVPs . . . . . . . . . . . . . . . . . . . . . . . 37 103 3.7. Extended AAA_AVP structure . . . . . . . . . . . . . . . . 40 104 3.8. Avoiding AVP Copying . . . . . . . . . . . . . . . . . . . 40 105 3.9. Callback Processing Order . . . . . . . . . . . . . . . . 40 106 4. Security Considerations . . . . . . . . . . . . . . . . . . . 42 107 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 43 108 6. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 44 109 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 45 110 7.1. Normative References . . . . . . . . . . . . . . . . . . . 45 111 7.2. Informative References . . . . . . . . . . . . . . . . . . 45 112 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 46 114 1. Introduction 116 The Diameter authentication, authorization and accounting (AAA) 117 protocol provides scale-able AAA support for peering transactions 118 across the Internet [RFC3588]. This document describes an API in C 119 for applications to access the Diameter protocol. While an API is 120 not strictly necessary for protocol interoperability, it does help to 121 promote the use and deployment of a protocol by reducing the amount 122 of work necessary to develop and access applications that use the 123 protocol. 125 The Diameter protocol provides a basic attribute/value pair (AVP) 126 data format, which particular application profiles extend. 127 Processing of the extensions is handled by code specific to the 128 application profile. Application profile customizability is 129 reflected into the API as callback functions for C. 131 The callbacks implement the application profile processing for 132 incoming messages. For outgoing calls, the C API provides an 133 asynchronous model, leaving processing of the return message to the 134 callbacks. 136 For the most part, the API hides the details of establishing peering 137 and redirect connections, parsing and creating Diameter messages, and 138 other work necessary to set up and maintain a redirect or peering 139 session. The application profile codes need only be concerned with 140 processing of the AVPs defined in the application profile. 142 1.1. Conventions Used in This Document 144 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 145 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 146 document are to be interpreted as described in [RFC2119]. 148 2. Binding Independent Considerations 150 This section discusses a number of implementation considerations for 151 bindings. 153 2.1. Multithreading 155 The C API is expected to be thread-safe. Access to data structures 156 shared among threads must be coordinated to avoid corruption or 157 invalid access. In addition, API implementers are encouraged to 158 provide the maximum amount of parallel processing within their 159 library implementations by allowing multiple threads in the API 160 library at once. 162 2.2. Error Reporting 164 The API reports errors resulting from client calls through language 165 specific mechanisms. All functions in the API return error codes. 166 API implementers are additionally encouraged to log errors using the 167 appropriate platform specific error logging technique, especially for 168 errors that result from network processing or other causes that are 169 not directly related to an API function or method call. 171 2.3. String Format 173 C API clients are required to format strings as UTF-8 if the string 174 contains 16 bit characters. Since the ASCII characters and the UTF-8 175 8 bit characters have the same codes, ASCII can be used for UTF-8 if 176 no wide characters are in the string. All strings passed through the 177 C API are standard null-terminated C strings. Processing to remove 178 the null terminator for transmission on the wire is done by the 179 library. 181 2.4. Handling Connections with Other Servers/Peers 183 The API supports making a connection with an arbitrary Diameter peer. 184 The API allows a client to set the server address in a message 185 (AAASetServer()). If a message is not sent to a particular server, 186 the API library is required to infer the servers by either looking in 187 the configuration files or dynamically determining the servers that 188 support the extension. 190 2.5. Command Dictionary File 192 The commands that can be parsed by the local Diameter client library 193 or server are defined in a command dictionary file containing the 194 command definitions including AVPs. The location and name of the 195 command dictionary file is platform-specific. This file is read and 196 parsed to drive creation of a command dictionary which is used by the 197 library to parse commands. The syntax for the command dictionary 198 file is in XML and a DTD describing it is available in [XML]. XML 199 was selected as the definition language because support for XML 200 parsing is available as an extension to the standard Java APIs and as 201 a wide variety of public-domain C libraries, simplifying 202 implementation. Both APIs also support programmatic definition of 203 commands, AVPs, and extensions so programs can add commands not in 204 the dictionary for purposes of experimentation and implementing the 205 library. 207 2.6. Structure Member Visibility 209 Some data structures defined in this document shows only the visible 210 or public member variables. Other internal or private member 211 variables that maybe necessary for the correct functioning of an 212 implementation are left for the implementors to define. Note that 213 this document uses the C language (see Section 3) so there are no 214 formal ways to guarantee privacy of internal variables. It would be 215 up to careful documentation and the implementors discipline to 216 maintain the integrity of the internal variables privacy. An example 217 of this is shown in Sec Section 3.7. 219 3. C API 221 The C language API is designed around callbacks. An application 222 profile defines a collection of Diameter commands, and a library of 223 callbacks for processing those commands. Each command is processed 224 by a callback. Callbacks can also be defined that handle all 225 commands. The API provides functions for managing callbacks, 226 including registration and deregistration. 228 When an incoming Diameter command arrives, the command is parsed and 229 passed to the appropriate callback. The callback receives as a 230 parameter the message struct, which contains the AVPs for the 231 command. The callback code can process the command by stepping 232 through the AVPs. 234 For outgoing requests, the API provides functions for creating 235 messages and adding AVPs. A collection of functions also provides 236 access to the AVP dictionary. 238 Unless otherwise noted, parameters to API functions and callbacks are 239 non-NULL. Some parameters may have other restrictions. If a 240 parameter fails to satisfy the restrictions on its value, the 241 function returns AAA_ERR_PARAMETER. 243 3.1. Constant Types 245 3.1.1. IP Address and Port 247 typedef struct sockaddr_storage AAA_IP_ADDR; 249 AAA_IP_ADDR provides a way of referring to an IPv4 address, IPv6 250 address, and IP port. The default implementation (shown here) is 251 defined in the Basic Socket Interface Extensions for IPv6 [RFC3493] 253 3.1.2. Command Code 255 typedef uint32_t AAACommandCode; 257 AAACommandCode provides a way of referring to the AAA command code of 258 a command. It is used when registering callbacks, among others. 260 3.1.3. Vendor Identifier 262 typedef uint32_t AAAVendorId; 264 AAAVendorId provides a way of referring to the vendor identification 265 code. It is used when registering callbacks, among others. Note 266 that vendor id 0 is reserved and is defined by the preprocessor 267 constant AAA_NO_VENDOR_ID. 269 3.1.4. Extension Identifier 271 typedef uint32_t AAAExtensionId; 273 AAAExtensionId provides a way of referring to an application profile 274 extension, for registering callbacks and other purposes. 276 3.1.5. Attribute/Value Pair Code 278 typedef uint32_t AAA_AVPCode; 280 AAA_AVPCode provides a way of referring to the code number of an AVP. 281 It is used as a parameter to the dictionary functions, and a field in 282 the AVP struct. 284 3.1.6. Value Type Identifier 286 typedef int32_t AAAValue; 288 AAAValue provides a way of referring to particular dictionary-defined 289 values. It is used in the dictionary API. 291 3.1.7. Server Identifier 293 typedef void AAAServer; 295 AAAServer is an identifier for a particular serving peer. It is used 296 in the server access functions. 298 3.1.8. Session Identifier 300 typedef void AAASessionId; 302 AAASessionId is an identifier for a particular AAA session. It is 303 used in the session APIs and when a message is created. 305 3.1.9. Message Identifier 307 typedef uint32_t AAAMsgIdentifier; 309 AAAMsgIdentifier is a unique identifier for an AAA message. Each 310 individual message is marked with an identifier. 312 3.1.10. Callback Handle 314 typedef void AAACallbackHandle; 316 AAACallbackHandle is a type for representing the callback handle 317 returned to the client when a callback is registered. 319 3.1.11. Application Identifier 321 typedef void* AAAApplicationId; 323 AAAApplicationId identifies a particular client session to the API. 324 The application id is passed to AAAStartSession(), and is attached to 325 incoming messages, to indicate with which client session the message 326 is associated. 328 3.1.12. API Return Codes 330 The following status codes are returned by functions in the AAA API: 332 typedef enum { 333 AAA_ERR_NOT_FOUND = -2, 334 AAA_ERR_FAILURE = -1, 335 AAA_ERR_SUCCESS = 0, 336 AAA_ERR_NOMEM, 337 AAA_ERR_PROTO, 338 AAA_ERR_SECURITY, 339 AAA_ERR_PARAMETER, 340 AAA_ERR_CONFIG, 341 AAA_ERR_UNKNOWN_CMD, 342 AAA_ERR_MISSING_AVP, 343 AAA_ERR_ALREADY_INIT, 344 AAA_ERR_TIMED_OUT, 345 AAA_ERR_CANNOT_SEND_MSG, 346 AAA_ERR_ALREADY_REGISTERED, 347 AAA_ERR_CANNOT_REGISTER, 348 AAA_ERR_NOT_INITIALIZED, 349 AAA_ERR_NETWORK_ERROR 350 } AAAReturnCode; 352 Note that these status codes are separate from the codes returned by 353 remote AAA servers. 355 The following is a description of the error codes and the reasons why 356 they can be returned: 358 AAA_ERR_NOT_FOUND: This code is returned if a handle or id was not 359 found. 361 AAA_ERR_FAILURE: This code is returned if an unspecified failure 362 occurred during an AAA operation. 364 AAA_ERR_SUCCESS: This code is returned if the AAA operation 365 succeeded. 367 AAA_ERR_NOMEM: This code is returned if there is not enough memory 368 to execute the operation. 370 AAA_ERR_PROTO: This code is returned if a AAA protocol error 371 occurred. 373 AAA_ERR_SECURITY: This code is returned if a security check failed 374 or another security error occurred. 376 AAA_ERR_PARAMETER: This code is returned if an invalid parameter was 377 passed to an AAA function. 379 AAA_ERR_CONFIG: This code is returned if an error was encountered in 380 a configuration file during library initialization. 382 AAA_ERR_UNKNOWN_CMD: This code is returned if the library received a 383 AAA command that is not in the set of registered AAA commands. 385 AAA_ERR_MISSING_AVP: This code is returned if a command was received 386 without a required AVP. 388 AAA_ERR_ALREADY_INIT: This code is returned if an attempt is made to 389 initialize the AAA library when it has already been initialized. 391 AAA_ERR_TIMED_OUT: This code is returned when a network operation 392 times out. 394 AAA_ERR_CANNOT_SEND_MSG: This code is returned if the library can't 395 send a message. It is also of used to application profile 396 extensions that encounter the same error condition. 398 AAA_ERR_ALREADY_REGISTERED: This code is returned by the command 399 registration functions if the command was already registered. 401 AAA_ERR_CANNOT_REGISTER: This code is returned by the command 402 registration functions if the command could not be registered. 404 AAA_ERR_NOT_INITIALIZED: This code is returned by any function in 405 the API except AAAOpen() if the library hasn't been initialized. 407 AAA_ERR_NETWORK_ERROR: This code is returned by any function when an 408 error in networking occurs. 410 In addition to returning the error code, functions are required to 411 log errors using the platform dependent logging facility. 413 3.1.13. Callback Location Codes 415 The following are codes used to indicate where a callback should be 416 installed in callback chain for processing: 418 typedef enum { 419 AAA_APP_INSTALL_FIRST, 420 AAA_APP_INSTALL_ANYWHERE, 421 AAA_APP_INSTALL_LAST 422 } AAACallbackLocation; 424 Callbacks installed with AAA_APP_INSTALL_FIRST and 425 AAA_APP_INSTALL_LAST operate on all commands, callbacks installed 426 with AAA_APP_INSTALL_ANYWHERE just operate on the command for which 427 they are installed. 429 The codes have the following semantics: 431 AAA_APP_INSTALL_FIRST: Install this callback as the first callback 432 in the chain. If subsequent callbacks are installed with this 433 code, then AAA_ERR_ALREADY_REGISTERED is returned. 435 AAA_APP_INSTALL_ANYWHERE: Install this callback anywhere in the 436 callback chain. 438 AAA_APP_INSTALL_LAST: Install this callback as the last callback in 439 the chain. If subsequent callbacks are installed with this code, 440 then AAA_ERR_ALREADY_REGISTERED is returned. 442 3.1.14. AVP Data Type Codes 444 The following are AVP data type codes. They correspond directly to 445 the AVP data types outline in the Diameter specification [RFC3588]: 447 typedef enum { 448 AAA_AVP_OCTET_STRING_TYPE, 449 AAA_AVP_INTEGER32_TYPE, 450 AAA_AVP_INTEGER64_TYPE, 451 AAA_AVP_UNSIGNED32_TYPE, 452 AAA_AVP_UNSIGNED64_TYPE, 453 AAA_AVP_FLOAT32_TYPE, 454 AAA_AVP_FLOAT64_TYPE, 455 } AAA_AVPDataType; 457 3.1.15. AVP Flags 459 The following are used for AVP header flags and for flags in the AVP 460 wrapper struct and AVP dictionary definitions. The first four 461 correspond to the AVP flags defined in the Diameter specification 462 [RFC3588]. Some of these are also used in the wrapper struct and 463 dictionary definitions also. The last four are used only in AAA_AVP 464 and AAADictionaryEntry: 466 typedef enum { 467 AAA_AVP_FLAG_NONE = 0, 468 AAA_AVP_FLAG_MANDATORY = 0x1, 469 AAA_AVP_FLAG_RESERVED = 0x2, 470 AAA_AVP_FLAG_VENDOR_SPECIFIC = 0x4, 471 AAA_AVP_FLAG_UNKNOWN = 0x10000 472 } AAA_AVPFlag; 474 The semantics of the flags are as follows: 476 AAA_AVP_FLAG_NONE: Indicates that no AVP flags are set. 478 AAA_AVP_FLAG_MANDATORY: Represents the 'M' flag in the Diameter AVP 479 header [RFC3588], meaning the AVP is mandatory. 481 AAA_AVP_FLAG_VENDOR_SPECIFIC: Represents the 'V' flag in the 482 Diameter AVP header [RFC3588], meaning that the AVP is vendor 483 specific. If this flag is set, the header will contain a vendor 484 identifier. 486 AAA_AVP_FLAG_UNKNOWN: Indicates that the AVP was not located in the 487 AVP dictionary. This flag is only used in AAA_AVP. 489 3.1.16. Domain Interconnection Types 491 The following domain interconnection types are returned by 492 AAAGetDomainInterconnectType(). They indicate the type of domain 493 interconnection: 495 typedef enum { 496 AAA_DOMAIN_LOCAL, 497 AAA_DOMAIN_PROXY, 498 AAA_DOMAIN_BROKER, 499 AAA_DOMAIN_FORWARD 500 } AAADomainInterconnect; 502 The flags have the following semantics: 504 AAA_DOMAIN_LOCAL The domain name is for the local domain. 506 AAA_DOMAIN_PROXY The domain name is for a proxy domain. A proxy is 507 a server that simply forwards the request based on the user's 508 identity or through some other means. The routing method used for 509 a proxy is the Proxy-State method, requiring routing through a 510 fixed chain of proxies [RFC3588]. 512 AAA_DOMAIN_BROKER The domain name is for a broker domain. A broker 513 is a server that provides redirect services, allowing all servers 514 in a roaming consortium to interact directly. 516 AAA_DOMAIN_FORWARD The domain name is for a forwarding domain. A 517 forwarding domain is a proxy that uses Destination-NAI routing. 518 With Destination-NAI routing, there is no set sequence of proxies 519 through which messages must be routed [RFC3588]. 521 3.1.17. Message Flags 523 The following type is for the AAA message flags. Currently, there 524 are no message flags defined in the Diameter protocol [RFC3588]: 526 typedef uint8_t AAAMsgFlag; 528 3.1.18. Result Codes 530 Result codes will be returned by the remote server to indicate the 531 success or failure of the operation. Result code values are defined 532 in the Diameter specification. [RFC3588] 534 3.1.19. Search Direction Type 536 The following type allows the client to specify which direction to 537 search for an AVP in the AVP list: 539 typedef enum { 540 AAA_FORWARD_SEARCH = 0, 541 AAA_BACKWARD_SEARCH 542 } AAASearchType; 544 3.1.20. Accounting Types 546 The following specifies the type of accounting message: 548 typedef enum { 549 AAA_ACCT_EVENT = 1, 550 AAA_ACCT_START = 2, 551 AAA_ACCT_INTERIM = 3, 552 AAA_ACCT_STOP = 4 553 } AAAAcctMessageType; 555 The accounting types have the following semantics: 557 AAA_ACCT_EVENT The event type is used to indicate that a one-time 558 event has occurred. 560 AAA_ACCT_START The accounting start request is used to initiate an 561 accounting session. 563 AAA_ACCT_INTERIM Interim messages contains cumulative accounting 564 information for the existing accounting session (started with an 565 AAA_ACCT_START). Please refer to [RFC3588] for details on the 566 Diameter accounting mechanisms. 568 AAA_ACCT_STOP The Accounting stop request terminates a session 569 started with AAA_ACCT_START. 571 3.2. Structure Definitions 573 3.2.1. Dictionary Entry Definition 575 The following structure is returned by the dictionary entry lookup 576 functions. It contains information about a particular AVP in the 577 dictionary: 579 typedef struct dictionaryEntry { 580 AAA_AVPCode avpCode; 581 char* avpName; 582 AAA_AVPDataType avpType; 583 AAAVendorId vendorId; 584 AAA_AVPFlag flags; 585 } AAADictionaryEntry; 587 3.2.2. AVP Definition 589 The following structure contains a message AVP in parsed form: 591 typedef struct avp { 592 enum { 593 AAA_RADIUS, 594 AAA_DIAMETER 595 } packetType; 596 AAA_AVPCode code; 597 uint16_t length; 598 AAA_AVPFlag flags; 599 AAA_AVPDataType type; 600 AAAVendorId vendorId; 601 void* data; 602 } AAA_AVP; 604 The fields have the following definitions: 606 packetType: Indicates whether the message is for Diameter or for 607 Radius compatibility. If the AVP is for Radius, then the code, 608 length, type, and data fields are the only valid fields in the 609 structure; the other fields are all null. 611 code: The AVP code. The type of the AVP can be determined by 612 matching the AVP code with an AVP description from the dictionary. 614 length: The length of the AVP's data field. 616 flags: The AVP flags. 618 type: The data type of the AVP's data. 620 vendorId: The vendor id, if the AVP is vendor-specific. If the AVP 621 is standardized, the vendorId field is set to AAA_NO_VENDOR_ID. 623 data: The AVP data, in host byte order. 625 3.2.3. AVP List 627 The following structure is used for representing lists of AVPs on the 628 message: 630 typedef struct avpList{ 631 // API Private variables. Dependent on link list implementation 632 } AAA_AVP_LIST; 634 AVPs are kept in ordered lists. The client can use a search 635 direction to indicated in which direction to search when trying to 636 find an AVP. 638 3.2.4. Message Definition 640 The following structure contains the full AAA message: 642 typedef struct message { 643 AAAMsgFlag flags; 644 AAACommandCode commandCode; 645 AAAVendorId vendorId; 646 AAAResultCode resultCode; 647 AAA_IP_ADDR originator; 648 AAA_IP_ADDR sender; 649 AAA_AVP_LIST *avpList; 650 AAA_AVP *proxyAVP; 651 AAAMsgIdentifier identifier; 652 time_t secondsTillExpire; 653 time_t startTime; 654 void *appHandle; 655 } AAAMessage; 657 The fields have the following definition: 659 flags: The message flags. Currently this field is always zero, 660 since there are no flags defined for a Diameter message at this 661 time. 663 commandCode: The command's message code. 665 vendorId: The vendor id of the vendor that defined the message. 667 resultCode: Code indicating the result of the client's request. 668 This code is sent by the peer over the wire. 670 originator: The IP address of the message's originator. 672 sender: The IP address of the message's previous hop sender. This 673 is only the same as originator if no proxy or broker peers are 674 being used. 676 avpList: The list of AVPs in the message. 678 proxyAVP: The proxy's AVP, if any. Otherwise NULL. 680 identifier: The message's unique identifier. 682 secondsTillExpire: Number of seconds until the message expires. 684 startTime: The number of seconds at which the message was started. 686 appHandle: An identifier indicating for which client session the 687 message is. 689 3.3. Macros and Preprocessor Definitions 691 The following definition reserves the vendor id of 0: 693 #define AAA_NO_VENDOR_ID 0 695 3.4. Functions 697 3.4.1. Initialization and Configuration 699 This section contains definitions that perform initialization and 700 configuration of the AAA library. 702 3.4.1.1. AAAOpen() 704 The following function is used to open and configure the AAA library: 706 AAAReturnCode AAAOpen(char *configFileName); 708 This function must be called before any other AAA function is called. 709 Some of the operations that may be performed by AAAOpen() are: 710 opening and loading the AVP and vendor dictionaries, opening 711 connections with Diameter peers, loading Diameter extension 712 libraries, and registering Diameter callbacks. After AAAOpen() 713 returns, the library must be ready for the client to open a session. 715 The parameters are: 717 configFileName: The global configuration file name. If NULL or the 718 empty string, use the default for this platform. The global 719 configuration file must contain the vendor and AVP dictionary file 720 names, and may contain other platform-specific information needed 721 to initialize and configure the Diameter peer. 723 Return values are: 725 AAA_ERR_SUCCESS: If initialization succeeded. 727 AAA_ERR_ALREADY_INIT: If the library is already initialized. 729 AAA_ERR_NETWORK_ERROR: If the host name can't be determined. 731 AAA_ERR_NOMEM: If no memory was available. 733 AAA_ERR_CONFIG: If processing the dictionary or configuration 734 information failed. 736 3.4.1.2. AAAClose() 738 The following function closes the AAA library: 740 AAAReturnCode 741 AAAClose(); 743 After this function is called, all other AAA functions are no longer 744 operative. 746 Return values are: 748 AAA_ERR_SUCCESS: If finalization succeeded. 750 AAA_ERR_NOT_INITIALIZED: If AAA was not initialized. 752 3.4.1.3. AAAGetDefaultConfigFileName() 754 The following returns the default configuration file name on the 755 platform: 757 const char * 758 AAAGetDefaultConfigFileName(); 760 The return value is a pointer to the full pathname for the file. The 761 pointer value should not be deallocated because it is constant and 762 does not change. 764 3.4.2. Registering Commands 766 The functions in this section are used to register callback functions 767 defined in a Diameter application profile extension library. The 768 following typedef defines the interface between callback functions 769 and the AAA library functions: 771 typedef AAAReturnCode (*AAACallback)(AAAMessage *message); 773 Authors of Diameter extensions must define command callback functions 774 having this interface. 776 The parameters are: 778 message: The AAAMessage to be processed. 780 The return value is a status code giving the operation status. 782 3.4.2.1. AAARegisterCommandCallback() 784 The following function is used to register command callbacks for 785 processing AAA commands: 787 AAACallbackHandle * 788 AAARegisterCommandCallback(AAACommandCode commandCode, 789 AAAVendorId vendorId, 790 char *commandName, 791 AAAExtensionId extensionId, 792 AAACallback callback, 793 AAACallbackLocation position); 795 The parameters are: 797 commandCode: The code of the command processed by the callback. 799 vendorId: The vendor id of the command. 801 commandName: A pointer to the name of the command. 803 extensionId: The id of the extension to which this command belongs. 805 callback: The callback function to perform processing. 807 position: The position of the callback in the chain. 809 The return value is a handle used when deregistering the callback, or 810 NULL if an error occurred while registering the callback. 812 3.4.2.2. AAARegisterNoncommandCallback() 814 The following callback registers an AAA callback to process all 815 messages. The callback is not associated with any command, but 816 rather will process all messages as they come down the callback 817 chain: 819 AAACallbackHandle 820 AAARegisterNoncommandCallback(AAACallback callback, 821 AAACallbackLocation position); 823 The parameters are: 825 callback: The callback function to perform processing. 827 position: The position of the callback in the chain. 829 The return value is a handle used when deregistering the callback, or 830 NULL if an error occurred while registering the callback. 832 3.4.2.3. AAADeregisterCommandCallback() 834 The following function deregisters a command callback: 836 AAAReturnCode 837 AAADeregisterCommandCallback(AAACallbackHandle *handle); 839 The parameters are: 841 handle: The handle returned when the callback was registered. 843 The return values are: 845 AAA_ERR_SUCCESS: Returned upon completion. 847 AAA_ERR_FAILURE: if the callback is not registered. 849 3.4.2.4. AAADeregisterNoncommandCallback() 851 The following function is used to deregister a noncommand callback: 853 AAAReturnCode 854 AAADeregisterNoncommandCallback(AAACallbackHandle *handle); 856 The parameters are: 858 handle: The handle returned when the callback was registered. 860 Return values are: 862 AAA_ERR_SUCCESS: Returned upon completion. 864 AAA_ERR_FAILURE: If the callback is not registered. 866 3.4.2.5. AAARegisterExtension() 868 The following function is used to register a Diameter extension id. 869 This function is typically called when registering non-command 870 specific callbacks. Extension ids for command-specific callbacks are 871 registered when the callback is registered: 873 AAAReturnCode 874 AAARegisterExtension(AAAExtensionId extensionId); 876 The parameters are: 878 extensionId: The extension id. 880 The return codes are: 882 AAA_ERR_SUCCESS: If the registration was successful. 884 AAA_ERR_NOMEM: if a memory allocation failure occurred. 886 3.4.3. Session and Server Management 888 The functions in this section allow the client to open, close, and 889 register sessions, and to obtain server identifiers. 891 3.4.3.1. AAAStartSession() 893 The following function allows a client to start a session and 894 identify it: 896 AAAReturnCode 897 AAAStartSession(AAASessionId **sessionId, 898 AAAApplicationId appHandle, 899 char *userName, 900 AAACallback abortCallback); 902 The parameters are: 904 sessionId: On return, a pointer to the session id for this session. 906 appHandle: An identifier for the client application starting the 907 session. This identifier is attached to messages so that the 908 client callbacks can tell which messages belong to it. 910 userName: - The NAI of the user. 912 abortCallback: A function to be called if this session is aborted by 913 the server. 915 Return values are: 917 AAA_ERR_SUCCESS: If the session was successfully started. 919 AAA_ERR_NOMEM: If a memory allocation failure occurred. 921 3.4.3.2. AAARegisterPeerSession() 923 The following function allows a client to register a peer session 924 that it has discovered through some other means, for example, by 925 receiving an unsolicited message. 927 AAAReturnCode 928 AAARegisterPeerSession(AAASessionId **sessionId, 929 AAAApplicationId *appHandle, 930 AAAMessage *message, 931 char *userName, 932 char *hostName); 934 The parameters are: 936 sessionId: On return, a pointer to the local session id for the 937 session. 939 appHandle: An identifier for the client application starting the 940 session. This identifier is attached to messages so that the 941 client callbacks can tell which messages belong to it. 943 message: The message from the peer containing the session id. 945 userName: - The NAI of the user. 947 hostName: The originator of the Diameter message 949 Return values are: 951 AAA_ERR_SUCCESS: If the session was successfully registered. 953 AAA_ERR_NOMEM: If a memory allocation failure occurred. 955 3.4.3.3. AAAEndSession() 957 The following function, sent by a client, terminates a session: 959 AAAReturnCode 960 AAAEndSession(AAASessionId *sessionId); 962 The parameters are: 964 sessionId: A pointer to the session id for the session. 966 Return values are: 968 AAA_ERR_SUCCESS: If the session was successfully closed. 970 AAA_ERR_NOT_FOUND: If the handle is invalid. 972 3.4.3.4. AAAAbortSession() 974 The following function, sent by the server, terminates a session: 976 AAAReturnCode 977 AAAAbortSession(AAASessionId *sessionId); 979 The parameters are: 981 sessionId: A pointer to the session id for the session. 983 Return values are: 985 AAA_ERR_SUCCESS: If the session was successfully closed. 987 AAA_ERR_NOT_FOUND: If the handle is invalid. 989 3.4.3.5. AAALookupServer() 991 The function looks up the AAA server based on IP address and port 992 number. Server connections are created from the configuration file: 994 AAAServer * 995 AAALookupServer(AAA_IP_ADDR ipAddr); 997 The parameters are: 999 ipAddr: The IP address/Port/Family of the server. 1001 The return value is either a valid server pointer or the NULL if the 1002 server can't be found. 1004 3.4.3.6. AAASetSessionMessageTimeout() 1006 The following function sets the timeout, in seconds, for all 1007 AAAMessages in a particular session: 1009 AAAReturnCode 1010 AAASetSessionMessageTimeout(AAASessionId *id, 1011 time_t timeout); 1013 The parameters are: 1015 id: The session id for the session whose timeout should be changed. 1017 timeout: The session timeout. The default timeout is 120 seconds. 1019 The return values are: 1021 AAA_ERR_SUCCESS: If setting the timeout succeeded. 1023 AAA_ERR_FAILURE: If the setting the timeout failed. 1025 3.4.3.7. AAAGetDomainInterconnectType() 1027 The following function returns the domain interconnect type for a 1028 particular domain name and type of service: 1030 AAADomainInterconnect 1031 AAAGetDomainInterconnectType(AAAMessage *message, 1032 char *domainName, 1033 char *type); 1035 The parameters are: 1037 domainName: The name of the domain. 1039 type: The type of service. This must be one of the strings "LOCAL", 1040 "PROXY", or "BROKER". 1042 The return values are: 1044 AAA_ERR_SUCCESS: If the domain interconnect type was retrieved. 1046 AAA_ERR_FAILURE: If the command failed. 1048 3.4.4. Dictionary Lookup 1050 The functions in this section are used to look up AVPs and commands 1051 in the dictionary. The client is responsible for supplying the 1052 structure memory into which the dictionary information is copied. 1054 3.4.4.1. AAADictionaryEntryFromAVPCode() 1056 This function looks up a dictionary entry using a command code and a 1057 vendor id: 1059 AAAReturnCode 1060 AAADictionaryEntryFromAVPCode(AAA_AVPCode avpCode, 1061 AAAVendorId vendorId, 1062 AAADictionaryEntry *Entry); 1064 The parameters are: 1066 avpCode: The code number of the AVP. 1068 vendorId: The vendor id of the AVP. 1070 Entry: an AAADictionaryEntry structure for returning the entry. 1072 The return value is one of: 1074 AAA_ERR_SUCCESS: If the query succeeded. 1076 AAA_ERR_FAILURE: If no matching dictionary entry was found. 1078 3.4.4.2. AAADictionaryEntryFromName() 1080 This function looks up a dictionary entry using command code name and 1081 vendor id: 1083 AAAReturnCode 1084 AAADictionaryEntryFromName(char *avpName, 1085 AAAVendorId vendorId, 1086 AAADictionaryEntry *Entry); 1088 The parameters are: 1090 avpName: The name of the AVP. 1092 vendorId: The vendor id of the AVP. 1094 Entry: an AAADictionaryEntry structure for returning the entry. 1096 The return value is one of: 1098 AAA_ERR_SUCCESS: If the query succeeded. 1100 AAA_ERR_FAILURE: If no matching dictionary entry was found. 1102 3.4.4.3. AAAValueFromName() 1104 This function looks up an AVP value using the AVP name and vendor 1105 name: 1107 AAAValue AAAValueFromName(char *avpName, 1108 char *vendorName, 1109 char *valueName); 1111 The parameters are: 1113 avpName: The name of the AVP. 1115 vendorName: The name of the vendor. 1117 valueName: The name of the value. 1119 The return value is the id of the AVP, or AAA_ERR_NOT_FOUND if no 1120 match was found. 1122 3.4.4.4. AAAValueFromAVPCode() 1124 This function looks up an AVP value using the AVP id and vendor id, 1125 and the value name: 1127 AAAValue AAAValueFromAVPCode(AAA_AVPCode avpCode, 1128 AAAVendorId vendorId, 1129 char *valueName); 1131 The parameters are: 1133 avpCode: The code of the AVP. 1135 vendorId: The id of the vendor. 1137 valueName: The name of the value. 1139 The return value is id of the AVP, or AAA_ERR_NOT_FOUND if no match 1140 was found. 1142 3.4.4.5. AAALookupValueNameUsingValue() 1144 This function returns the AVP value name: 1146 const char * 1147 AAALookupValueNameUsingValue(AAA_AVPCode avpCode, 1148 AAAVendorId vendorId, 1149 AAAValue value); 1151 The parameters are: 1153 avpCode: The code of the AVP. 1155 vendorId: The id of the vendor. 1157 value: The value. 1159 The value name is returned, or NULL if no match occurred. 1161 3.4.4.6. AAAGetCommandCode() 1163 This function returns the command code and vendor id based on a 1164 string: 1166 AAAReturnCode 1167 AAAGetCommandCode(char *commandName, 1168 AAACommandCode *commandCode, 1169 AAAVendorId *vendorId); 1171 The parameters are: 1173 commandName: A string containing the command name. 1175 commandCode: Pointer that on return holds the command code if the 1176 command was found. 1178 vendorId: Pointer that on return holds the vendor id if the command 1179 was found. 1181 The function returns AAA_ERR_SUCCESS when a command has been 1182 successfully retrieved, otherwise AAA_UNKNOWN_CMD is returned. 1184 3.4.5. Message Management 1186 The functions in this section allow the client to create messages, 1187 add AVPs, and traverse AVP lists. 1189 3.4.5.1. AAANewMessage() 1191 This function allocates an AAAMessage and returns a pointer to it. 1192 If a command code is provided, this function adds the command code 1193 AVP. If the session identifier handle is provided, the Session-Id 1194 AVP is also added. Lastly, if this message is allocated in response 1195 to a request, the request's message can be provided, and the new 1196 message is initialized to match the request, for fields such as the 1197 identifier, the server identifier, etc. If this is a new message, 1198 the request parameter is NULL: 1200 AAAMessage * 1201 AAANewMessage(AAACommandCode commandCode, 1202 AAAVendorId vendorId, 1203 AAASessionId *sessionId, 1204 AAAExtensionId extensionId, 1205 AAAMessage *request); 1207 The parameters are: 1209 commandCode: The command code. 1211 vendorId: The vendor identifier. 1213 sessionId: Session identifier. 1215 extensionId: The extension identifier. 1217 request: A pointer to a request message, if this message is being 1218 allocated in response to a request. 1220 The function returns a pointer to the message or NULL if a failure 1221 occurred. 1223 3.4.5.2. AAAFreeMessage() 1225 This function frees a message allocated through AAANewMessage(): 1227 AAAReturnCode 1228 AAAFreeMessage(AAAMessage **message); 1230 The parameters are: 1232 message: A pointer to a pointer to the allocated message. 1234 The return value is the AAA status code AAA_ERR_SUCCESS. 1236 3.4.5.3. AAARespondToMessage() 1238 This function is called to set the AAA Message to the appropriate 1239 values, and to inform the library that this message is a locally 1240 generated response 1242 AAAReturnCode 1243 AAARespondToMessage(AAAMessage* message, 1244 AAACommandCode commandCode, 1245 AAAVendorId vendorId, 1246 AAAResultCode resultCode); 1248 The parameters are: 1250 message: The AAAMessage to respond to. 1252 commandCode: The command code of the response. 1254 vendorId: The vendor identifier (of the command code). 1256 resultCode: The result code of the response. 1258 The function returns AAA_ERR_SUCCESS upon completion, or 1259 AAA_ERR_PARAMETER if a NULL pointer was provided. 1261 3.4.5.4. AAAAddProxyState() 1263 This function will add a Proxy-State AVP to a message, that contains 1264 the Fully Qualified Domain Name (FQDN) of the source of the message. 1266 AAAReturnCode 1267 AAAAddProxyState(AAAMessage *message); 1269 The parameters are: 1271 message: The AAAMessage to add state to. 1273 The function returns AAA_ERR_SUCCESS upon completion, or 1274 AAA_ERR_FAILURE if an error occurred. 1276 3.4.5.5. AAACreateAVP() 1278 This function creates an AVP and returns a pointer to it. The AVP is 1279 initialized from the arguments: 1281 AAAReturnCode 1282 AAACreateAVP(AAA_AVP **avp, 1283 AAA_AVPCode code, 1284 AAA_AVPFlag flags, 1285 AAAVendorId vendorId, 1286 char *data, 1287 size_t length); 1289 The parameters are: 1291 avp: On return, contains a pointer to the allocated AVP, or NULL if 1292 no AVP was allocated. 1294 code: The AVP's code. 1296 flags: Any AVP flags that must be passed. 1298 vendorId: The vendor id of the AVP. If no vendor id, then 1299 AAA_NO_VENDOR_ID. 1301 data: A buffer containing the AVP data. 1303 length: The length of the data buffer. 1305 Return values are: 1307 AAA_ERR_SUCCESS: Upon success. 1309 AAA_ERR_PARAMETER: If an invalid parameter was passed. 1311 AAA_ERR_PROTO: If a protocol error occurred. 1313 AAA_ERR_NOMEM: Indicating a memory failure. 1315 3.4.5.6. AAACreateAndAddAVPToList() 1317 This function creates an AVP and adds it to an AVP list. It returns 1318 a pointer to the list in the avpList argument. If the avpList is 1319 NULL a new list is created. The new AVP is always added to the end 1320 of the list. The AVP is initialized from the arguments: 1322 AAAReturnCode 1323 AAACreateAndAddAVPToList(AAA_AVP_LIST **avpList, 1324 AAA_AVPCode code, 1325 AAA_AVPFlag flags, 1326 AAAVendorId vendorId, 1327 char *data, 1328 size_t length); 1330 The parameters are: 1332 avpList: The list to which the AVP should be added. 1334 code: The AVP's code. 1336 flags: Any AVP flags that must be passed. 1338 vendorId: The vendor id of the AVP. If no vendor id, then 1339 AAA_NO_VENDOR_ID. 1341 data: A buffer containing the AVP data. 1343 length: The length of the data buffer. 1345 Return values are: 1347 AAA_ERR_SUCCESS: Upon success. 1349 AAA_ERR_PARAMETER: If an invalid parameter was passed. 1351 AAA_ERR_NOMEM: Indicating a memory failure. 1353 3.4.5.7. AAAAddAVPToList() 1355 AAAReturnCode 1356 AAAAddAVPToList(AAA_AVP_LIST **avpList, 1357 AAA_AVP *avp, AAA_AVP *position); 1359 Insert the AVP avp into this avpList after position. If position is 1360 NULL, the AVP is added to the beginning of the list. 1362 If *avpList is NULL, a list will be allocated, and *avpList will 1363 point to it. 1365 The parameters are: 1367 avpList: Pointer to a pointer for list. If *avpList is NULL, list 1368 memory is allocated. 1370 avp: AAA_AVP to add to list. 1372 position: AAA_AVP pointer to add data after, or NULL if the new AVP 1373 should go at the beginning of the list. 1375 The return value is one of: 1377 AAA_ERR_SUCCESS: Upon success. 1379 AAA_ERR_PARAMETER: If an invalid parameter was passed. 1381 AAA_ERR_NOMEM: Indicates a memory failure. 1383 3.4.5.8. AAAFindMatchingAVP() 1385 This function finds an AVP with matching code and vendor id. If none 1386 match, the function returns NULL: 1388 AAA_AVP * 1389 AAAFindMatchingAVP(AAA_AVP_LIST *avpList, 1390 AAA_AVP *startAvp, 1391 AAA_AVPCode avpCode, 1392 AAAVendorId vendorId, 1393 AAASearchType searchType); 1395 The parameters are: 1397 avp: A pointer to the head of the AVP list. 1399 avpCode: The code of the sought after AVP. 1401 vendorId: The vendor id of the sought after AVP. 1403 The return value is a pointer to the found AVP, or NULL if none is 1404 found. 1406 3.4.5.9. AAAJoinAVPLists() 1408 The following function joins together two AVP lists: 1410 AAAReturnCode AAAJoinAVPLists(AAA_AVP_LIST *dest, 1411 AAA_AVP_LIST *source, 1412 AAA_AVP *position); 1414 The parameters are: 1416 dest: The destination list (All of the AVPs in source will be moved 1417 here). 1419 source: The source list to be added to dest. 1421 position: The position to add the AVPs to, or NULL for the beginning 1422 of the list. 1424 The return value is one of: 1426 AAA_ERR_SUCCESS: Upon success. 1428 AAA_ERR_PARAMETER: If an invalid parameter was passed. 1430 3.4.5.10. AAARemoveAVPFromList() 1432 This function removes an AVP from a list: 1434 AAAReturnCode 1435 AAARemoveAVPFromList(AAA_AVP_LIST *avpList, 1436 AAA_AVP *avp); 1438 The parameters are: 1440 avpList: The head of the list from which to remove the AVP. 1442 avp: Contains a pointer to the AVP to remove. 1444 The return value is one of: 1446 AAA_ERR_SUCCESS: Upon success. 1448 AAA_ERR_PARAMETER: If an invalid parameter was passed. 1450 3.4.5.11. AAAFreeAVP() 1452 The function frees an AVP: 1454 AAAReturnCode 1455 AAAFreeAVP(AAA_AVP **avp); 1457 The parameters are: 1459 avp: Contains a pointer to a pointer to the AVP to free. 1461 The return value is one of: 1463 AAA_ERR_SUCCESS: Upon success. 1465 AAA_ERR_PARAMETER: If an invalid parameter was passed. 1467 3.4.5.12. AAAGetFirstAVP() 1469 This function returns a pointer to the first AVP in the list: 1471 AAA_AVP * 1472 AAAGetFirstAVP(AAA_AVP_LIST *avpList); 1474 The parameters are: 1476 avpList: A pointer to the list. 1478 The return value is a pointer to the found AVP, or NULL if none is 1479 found. 1481 3.4.5.13. AAAGetLastAVP() 1483 This function returns a pointer to the last AVP in the list: 1485 AAA_AVP * 1486 AAAGetLastAVP(AAA_AVP_LIST *avpList); 1488 The parameters are: 1490 avpList: A pointer to the list. 1492 The function returns a pointer to the found AVP, or NULL if none is 1493 found. 1495 3.4.5.14. AAAGetNextAVP() 1497 This function returns a pointer to the next AVP in the list. 1499 AAA_AVP * 1500 AAAGetNextAVP(AAA_AVP *avp); 1502 The parameters are: 1504 avp: A pointer to the AVP prior to the one sought. It is assumed 1505 that AAA_AVP has internal private members that keep track of the 1506 next AAA_AVP element in the list. 1508 The return value is the next AVP in the list, or NULL if the 1509 parameter is the last element in the list. 1511 3.4.5.15. AAAGetPrevAVP() 1513 This function returns a pointer to the previous AVP in the list. It 1514 is assumed that AAA_AVP has internal private members that keep track 1515 of the previous AAA_AVP element in the list. 1517 AAA_AVP * 1518 AAAGetPrevAVP(AAA_AVP *avp); 1520 The parameters are: 1522 avp: A pointer to the AVP after the one sought. 1524 The return value is the previous AVP in the list or NULL if the 1525 parameter is the first element in the list. 1527 3.4.5.16. AAAFreeAVPList() 1529 This function frees an AVP list structure including all contained 1530 AVPs if there are any. If the list is empty then only the AVP list 1531 data structure itself is deleted. If successful, the list will point 1532 to NULL on return. 1534 AAAReturnCode 1535 AAAFreeAVPList(AAA_AVP_LIST **avpList); 1537 The parameters are: 1539 avpList: The list to be freed. 1541 Return values are: 1543 AAA_ERR_SUCCESS: Upon success. 1545 AAA_ERR_PARAMETER: If an invalid parameter was passed. 1547 3.4.5.17. AAAConvertAVPToString() 1549 This function converts the data in the AVP to a format suitable for 1550 log or display functions. 1552 char * 1553 AAAConvertAVPToString(AAA_AVP *avp, 1554 char *dest, 1555 size_t destLen); 1557 The parameters are: 1559 avp: The AVP to display. 1561 dest: A used supplied destination buffer. 1563 destLen: The length of the user supplied buffer. 1565 The return value is the passed in destination buffer. 1567 3.4.5.18. AAASetMessageResultCode() 1569 This function decapsulates an encapsulated AVP, and populates the 1570 list with the correct pointers. 1572 AAAResultCode 1573 AAASetMessageResultCode(AAAMessage *message, 1574 AAAResultCode resultCode); 1576 The parameters are: 1578 message: A pointer to the allocated message. 1580 resultCode: The AAA Result Code 1582 The return value is one of: 1584 AAA_ERR_SUCCESS: Upon success. 1586 AAA_ERR_PARAMETER: If an invalid parameter was passed. 1588 3.4.6. Message Control 1590 The following functions allow the client to direct a message to a 1591 particular server, determine the server for a message, etc. 1593 3.4.6.1. AAASetServer() 1595 This function sets the server to which the message is sent: 1597 AAAReturnCode 1598 AAASetServer(AAAMessage *message, 1599 AAA_IP_ADDR host); 1601 The parameters are: 1603 message: The message to be sent. 1605 host: The IP address / port / family of the server. 1607 The return value is: 1609 AAA_ERR_SUCCESS: If the server was found. 1611 AAA_ERR_NOT_FOUND: If the server was not found. 1613 3.4.6.2. AAASendMessage() 1615 The following function transmitts a message. It will be sent to the 1616 server based on the routing criteria defined in [RFC3588]. 1618 AAAReturnCode 1619 AAASendMessage(AAAMessage *message); 1621 The parameter is the message to send. 1623 The return codes are: 1625 AAA_ERR_SUCCESS: Upon completion. 1627 AAA_ERR_FAILURE: If an error occurred. 1629 3.4.7. Accounting 1631 The following functions allow the client to direct a message to a 1632 particular server, determine the server for a message, etc. 1634 3.4.7.1. AAASendAcctRequest() 1636 The following function sends an accounting message to an accounting 1637 server. 1639 AAAReturnCode 1640 AAASendAcctRequest(AAASessionId *aaaSessionId, 1641 AAAExtensionId extensionId, 1642 AAA_AVP_LIST *acctAvpList, 1643 AAAAcctMessageType msgType); 1645 The parameters are: 1647 aaaSessionId: The session id that this accounting data corresponds 1648 to. 1650 extensionId: The extension type associated with this accounting 1651 message. 1653 acctAvpList: A list of AVPs to send in the accounting message. 1655 msgType: The type of accounting message. 1657 The return codes are: 1659 AAA_ERR_SUCCESS: Upon completion. 1661 AAA_ERR_PARAMETER: If a parameter is invalid. 1663 3.5. Implementation Notes 1665 The following are some implementation notes that library designers 1666 may want to keep in mind. 1668 3.6. Grouped AVPs 1670 In order to create grouped AVPs, an application creates an 1671 AAA_AVP_LIST that is not attached to an AAAMessage structure (also 1672 known as an orphaned AAA_AVP_LIST). All of the necessary AVPs within 1673 the Group are added to the orphaned AAA_AVP_LIST using the existing 1674 list manipulation functions. Lastly, the grouped AVP is added to the 1675 AAAMessage structure. 1677 The following is an example that adds a Proxy-State Grouped AVP to an 1678 existing AAAMessage structure. 1680 addProxyState(AAAMessage *message, ipaddr_t *ourAddress, 1681 void *state, size_t stateLen) 1682 { 1683 AAA_AVP_LIST *avpList = NULL; 1685 /* 1686 * Add the Proxy-Address AVP to the AAAList 1687 */ 1688 if (AAACreateAndAddAVPToList(&avpList, 1689 DIAM_AVP_PROXY_ADDRESS, AAA_AVPI_FLAG_NONE, 1690 NO_VENDOR_ID, (char *)ourAddress, 1691 sizeof (ipaddr_t))) { 1692 loggerSyslog(LOG_AVP_PROBLEMS, 1693 "Unable to add Proxy-Address AVP"); 1694 return (AAA_ERR_FAILURE); 1695 } 1696 /* 1697 * Now we add the Proxy-Info AVP to the AAAList 1698 */ 1699 if (AAACreateAndAddAVPToList(&avpList, 1700 DIAM_AVP_PROXY_INFO, AAA_AVPI_FLAG_NONE, 1701 NO_VENDOR_ID, state, stateLen)) { 1702 loggerSyslog(LOG_AVP_PROBLEMS, 1703 "Unable to add Proxy-Info AVP"); 1704 return (AAA_ERR_FAILURE); 1705 } 1706 /* 1707 * Now the AAAList is added to the AAAMessage as 1708 * a Proxy-State AVP. 1709 */ 1710 if (AAACreateAndAddAVPToList(&message->avpList, 1711 DIAM_AVP_PROXY_STATE, AAA_AVPI_FLAG_NONE, 1712 NO_VENDOR_ID, (char *)avpList, 1713 AAA_AVP_GROUPED_LENGTH)) { 1714 loggerSyslog(LOG_AVP_PROBLEMS, 1715 "Unable to add Proxy-State AVP"); 1716 return (AAA_ERR_FAILURE); 1717 } 1719 return (AAA_ERR_SUCCESS); 1721 } 1723 As shown above, the procedures is to create a new AAA_AVP_LIST 1724 structure, adding all of the necessary AVPs that are within the 1725 Grouped AVP, then calling AAACreateAndAddAVPToList() to add the 1726 AAA_AVP_LIST as a Grouped AVP to the AAAMessage. 1728 Note that the AAA_AVP_LIST pointed to by orphaned avpList MUST NOT be 1729 accessed by the application after the Grouped avp has been created. 1730 The list will be freed along with the AVP by the AAA Library. 1732 In order to parse a Grouped AVP, the AAA_AVP data field contains a 1733 pointer to an AAA_AVP_LIST, as shown below. 1735 boolean_t 1736 isProxyStateOurs(AAA_AVP *proxyState, ipaddr_t *ourAddress) 1737 { 1738 AAA_AVP_LIST *avpList; 1739 AAA_AVP *proxyAddress; 1740 AAA_AVP *proxyInfo; 1741 ipaddr_t *proxyAddress; 1743 /* 1744 * Get the pointer to the Grouped AAA_AVP_LIST 1745 */ 1746 avpList = (AAA_AVP_LIST *)proxyState->data; 1748 /* 1749 * First, for the Proxy-Address, and see if it is ours. 1750 */ 1751 if ((proxyAddress = AAAFindMatchingAVP(avpList, NULL, 1752 DIAM_AVP_PROXY_ADDRESS, NO_VENDOR_ID, 1753 AAA_FORWARD_SEARCH)) != NULL) { 1754 /* 1755 * Check if this one is ours. 1756 */ 1757 address2 = (ipaddr_t *)proxyAddress->data; 1758 if (*address2 == *address) { 1759 /* 1760 * This one is ours... return TRUE 1761 */ 1762 return (B_TRUE); 1763 } 1764 } 1766 return (B_FALSE); 1767 } 1769 3.7. Extended AAA_AVP structure 1771 The AAA_AVP structure that is defined in this specification is a 1772 subset of the structure used by the internal library. The internal 1773 structure, known as the extended AAA_AVP, may contain many private 1774 fields, such as pointers to AAA_AVPs. Applications do not directly 1775 access the next (and previous) AAA_AVP pointers but instead access 1776 them via the AAAGetNextAVP() and AAAGetPreviousAVP() functions (see 1777 Section 2.6). 1779 The following is an example of an extended AAA_AVP structure: 1781 typedef struct { 1782 // API Public variables here 1783 } AAA_AVP; 1785 typedef struct xavp { 1786 AAA_AVP avp; 1787 struct xavp *next; 1788 struct xavp *prev; 1789 int privateFlags; 1790 } Extended_AAA_Avp; 1792 Of course, when AAACreateAVP is called, sufficient memory is 1793 allocated for the extended AAA_AVP structure, however the function 1794 returns a pointer to the AAA_AVP. 1796 3.8. Avoiding AVP Copying 1798 The AAA_AVP struct does not provide an exact mapping to the Diameter 1799 protocol AVP packet format; however, library implementers can avoid 1800 having to copy the AVP data by putting a pointer to a packet format 1801 structure into a hidden part of the AAA_AVP struct. A pointer to the 1802 AVP data is then deposited into the AAA_AVP data field. This allows 1803 proper deallocation of the packet format structure when the AAA_AVP 1804 structure is deallocated. 1806 3.9. Callback Processing Order 1808 The C API allows API clients to register message processors, or 1809 callbacks, that are invoked before and after the bulk of the 1810 processing functions for a message. Only one pre- or post-processor 1811 is allowed for all incoming messages, regardless of command or 1812 extension type. If the API client adds another, any existing pre- 1813 and post-processors are removed. 1815 Message processing can be best explained by the following diagram: 1817 +-------+ +-------+ +-------+ +-------+ 1818 | First | | Any | | Any | | Last | Apps 1819 +-------+ +-------+ +-------+ +-------+ 1820 ^ ^ ^ ^ 1821 1 | 2 | 3 | 4 | 1822 +-------------------------------------------------+ 1823 | AAA Library | 1824 +-------------------------------------------------+ 1825 ^ 1826 | MSG 1828 In the above diagram, "First", "Any", and "Last" are added by the API 1829 client. The message processor labeled "First" is given access to the 1830 message before any other, the message processor "Last" after all 1831 others are finished. There is no guarantee on ordering for the other 1832 message processors. If the client adds a new "First" or "Last" 1833 message processor, AAA_ERR_ALREADY_REGISTERED error is returned. 1834 There is one "First" and "Last" processor for all commands regardless 1835 of type; whereas, the "Any" processors are command-specific. 1837 If one of the "Any" processors completes successfully, the message is 1838 not passed on any further. A successful completion means the success 1839 return code is returned from the C API callback, but the callback is 1840 responsible for freeing the message before returning. 1842 4. Security Considerations 1844 This document describes an API and therefore depends on the security 1845 mechanisms defined in the Diameter protocol [RFC3588]. 1847 5. IANA Considerations 1849 This document has no actions for IANA. 1851 6. Acknowledgments 1853 The authors would like to thank James Kempf for his input to this 1854 document. 1856 7. References 1858 7.1. Normative References 1860 [RFC3588] Calhoun, Loughney, Guttman, Zorn, and Arkko, "Diameter 1861 Base Protocol", RFC 3588, October 2002. 1863 [RFC3493] Gilligan, Thomson, Bound, McCann, and Stevens, "Basic 1864 Socket Interface Extensions for IPv6", rfc 3493, 1865 February 2003. 1867 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1868 Requirement Levels", BCP 14, RFC 2119, March 1997. 1870 7.2. Informative References 1872 [XML] Frascone, Jones, and Guttman, "Diameter XML Dictionary", 1873 draft-frascone-xml-dictionary-00 (work in progress), 1874 September 2007. 1876 Authors' Addresses 1878 Victor Fajardo (editor) 1879 Toshiba America Research Inc. 1880 One Telcordia Drive, #1S222 1881 Piscataway, NJ 08854 1883 Phone: +1 908-421-1845 1884 Fax: 1885 Email: vfajardo@tari.toshiba.com 1887 Pat R. Calhoun 1888 Cisco Systems, Inc. 1889 170 West Tasman 1890 San Jose, CA 95134 1892 Phone: +1 408-853-5269 1893 Email: pacalhou@cisco.com 1895 David Frascone 1896 Cisco Systems, Inc. 1897 500 Northridge Drive, Suite 800 1898 Atlanta, GA 30350 1900 Phone: +1 678-352-2764 1901 Fax: +1 978-334-0249 1902 Email: dave@frascone.com