The Diameter API
draft-ietf-dime-diameter-api-08

3.4.3.7.  AAAGetDomainInterconnectType()

   The following function returns the domain interconnect type for a
   particular domain name and type of service:

         AAADomainInterconnect
         AAAGetDomainInterconnectType(AAAMessage *message,
                                      char *domainName,
                                      char *type);

   The parameters are:

"AAAMessage *message" is not described.

   domainName:  The name of the domain.

   type:  The type of service.  This must be one of the strings "LOCAL",
      "PROXY", or "BROKER".

   The return values are:

   AAA_ERR_SUCCESS:  If the domain interconnect type was retrieved.

   AAA_ERR_FAILURE:  If the command failed.

The described return values don't match the actual return type.


3.4.5.8.  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.

This parameter doesn't match the function prototype. Also, one of the first 2 parameters is not described.



3.4.5.17.  AAAConvertAVPToString()

   This function converts the data in the AVP to a format suitable for
   log or display functions.

         char *
         AAAConvertAVPToString(AAA_AVP *avp,
                               char *dest,
                               size_t destLen);

   The parameters are:

   avp:  The AVP to display.

   dest:  A used supplied destination buffer.

   destLen:  The length of the user supplied buffer.

   The return value is the passed in destination buffer.

How is output truncation due to small destLen value can be discovered
by the caller? Is the returned value always NUL terminated?


In Section 3.6:

        boolean_t
        isProxyStateOurs(AAA_AVP *proxyState, ipaddr_t *ourAddress)
        {
                AAA_AVP_LIST *avpList;
                AAA_AVP *proxyAddress;
                AAA_AVP *proxyInfo;
                ipaddr_t *proxyAddress;

proxyAddress is defined twice using 2 different data types.

                /*
                 * Get the pointer to the Grouped AAA_AVP_LIST
                 */
                avpList = (AAA_AVP_LIST *)proxyState->data;

                /*
                 * First, for the Proxy-Address, and see if it is ours.
                 */
                if ((proxyAddress = AAAFindMatchingAVP(avpList, NULL,
                    DIAM_AVP_PROXY_ADDRESS, NO_VENDOR_ID,
                    AAA_FORWARD_SEARCH)) != NULL) {
                        /*
                         * Check if this one is ours.
                         */
                        address2 = (ipaddr_t *)proxyAddress->data;
                        if (*address2 == *address) {

Neither of these variables is defined in the function, as far as I can see.

                                /*
                                 * This one is ours... return TRUE
                                 */
                                return (B_TRUE);
                        }
                }

                return (B_FALSE);
        }


3.9.  Callback Processing Order

   The C API allows API clients to register message processors, or
   callbacks, that are invoked before and after the bulk of the
   processing functions for a message.  Only one pre- or post-processor
   is allowed for all incoming messages, regardless of command or
   extension type.  If the API client adds another, any existing pre-
   and post-processors are removed.

The last sentence is in conflict with another sentence in the following paragraph:

   If the client adds a new "First" or "Last"
   message processor, AAA_ERR_ALREADY_REGISTERED error is returned.

The current IETF license rules around code fragments are very frustrating and hopefully they will change but until they do, this document needs a bit more to address them the current requirements around code in specification. As a side topic, I think it would be highly useful to the the .h file version of this API in an appendix. If you did this, then you could just put the IETF code license on that .h file and solve the code licensing problems.

This is a useful piece of work, thanks! Some issues, however:

AAAServer is returned by one function, but not used anywhere else.
As far as I can tell, this seems to be an error.

>         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. 

Isn't the registering of callbacks a task for the caller, i.e., first
you call AAAOpen and THEN you register callbacks. I do not understand
how AAAOpen itself would be registering callbacks automatically.
But maybe I am missing something.

I'd like to discuss with other ADs during the telechat whether this 
is something IETF wants to publish at all, or perhaps publish as
Historic.

The writeup mentions there being two implementations, but apparently
both of them are prototype code from around 2001 that have been
abandoned >5 years ago. OpenDiameter (an open source Diameter
implementation by the main author of this draft) does not
use this API, and to me it looks very unlikely that anyone would 
ever implement this (and it's questionable whether anyone should
even attempt).

  I could not find any record that the authors ever responded to the
  Gen-ART Review by Francis Dupont; However, I see that the review was
  forwarded to WG mailing list:

    http://www.ietf.org/mail-archive/web/dime/current/msg02782.html

  From a quick look at the diff between -08 and the version that was
  reviewed, it does not seem that the comments have been addressed:

    http://tools.ietf.org/rfcdiff?url2=http://tools.ietf.org/id/
    draft-ietf-dime-diameter-api-08.txt

This is a discuss-discuss.  To be clear, I am not requesting any changes in the document at 
this time, just to discuss it on the telechat.

Sean Turner raised the issue of API-specific security considerations in his secdir review.  In
many cases, APIs do not introduce additional security issues, as observed in the subsequent
email thread.  I am unsure if that is true in this case, however, so I would like to discuss
it on the call.

For example, it is unclear how (if?) an application would indicate whether to TCP or SCTP
should (must?) be used as the transport.  This is security relevant since SCTP has arguably
enhanced security and reliability.  There may be other security relevant features that are
obscured or cannot easily be set, but I am not savvy enough to know.  (I tried to map
3588 to the API and realized I don't have enough Diameter clue to do so quickly!)