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

[Ballot discuss]
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).

[Ballot comment]
I agree with the other Discusses. The code must compile.

I did not understand what vendor names are, and how they should be mapped
to vendor IDs.

I did not understand how AAASetServer works if we are not sending to
a particular IP address but rather to an AAA server service example.com,
possibly behind a number of proxies.

I did not understand exactly how AAAValue works, but maybe I read the
document too fast.

I think the API could easily have incorporated some security functionality
as well, assuming TLS is used at the bottom.

[Ballot discuss]
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.

[Ballot discuss]
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.

[Ballot discuss]
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.

[Ballot comment]
0) I am agreeing with the GenArt reviewer that this document would benefit from having a complete .h file.

1)
2.3.  String Format

  C API clients are required to format strings as UTF-8 if the string
  contains 16 bit characters.

Did you mean "Unicode characters"? They are *not* 16 bits.

  Since the ASCII characters and the UTF-8
  8 bit characters have the same codes,

I think you meant to say something like:

  Since the US-ASCII characters have the same codes when encoded in UTF-8

or
  Since all 7-bit UTF-8 bytes represent US-ASCII characters

2) In general, I think most (all?) of "char *" input parameters in the document need to be changed to "const char *", otherwise you will get compiler warnings when passing constants.
For example:

3.4.1.1.  AAAOpen()

  The following function is used to open and configure the AAA library:

        AAAReturnCode AAAOpen(char *configFileName);

Should be:
        AAAReturnCode AAAOpen(const char *configFileName);

because:

3.4.1.3.  AAAGetDefaultConfigFileName()

  The following returns the default configuration file name on the
  platform:

        const char *
        AAAGetDefaultConfigFileName();

3)
3.4.3.4.  AAAAbortSession()

  The following function, sent by the server, terminates a session:

        AAAReturnCode
        AAAAbortSession(AAASessionId *sessionId);

Does this result in the abortCallback (registered in AAAStartSession) being called?

4)
3.4.3.5.  AAALookupServer()

  The function looks up the AAA server based on IP address and port
  number.  Server connections are created from the configuration file:

Can you explain the last sentence in a bit more details?

5)
3.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.

3.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);

This function and one above: what exactly do they do?
Maybe you can give an example?

6)
3.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.  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);

How is the exact error can be discovered on failure of this function?
(There is no AAAReturnCode output parameter anywhere)

7)
3.4.5.3.  AAARespondToMessage()

  This function is called to set the AAA Message to the appropriate
  values, and to inform the library that this message is a locally
  generated response

This might be my lack of familiarity with DIAMETER, but I don't think this text is clear. Does this function cause any IO?

        AAAReturnCode
        AAARespondToMessage(AAAMessage* message,
                            AAACommandCode commandCode,
                            AAAVendorId vendorId,
                            AAAResultCode resultCode);

8)
3.4.5.18.  AAASetMessageResultCode()

  This function decapsulates an encapsulated AVP, and populates the
  list with the correct pointers.

Can you elaborate on what this means?

        AAAResultCode
        AAASetMessageResultCode(AAAMessage *message,
                                AAAResultCode resultCode);

9)
3.4.6.1.  AAASetServer()

  This function sets the server to which the message is sent:

        AAAReturnCode
        AAASetServer(AAAMessage *message,
                      AAA_IP_ADDR host);

How is this function used?
In particular, it is not clear if AAASendMessage() is going to use information set by this function.

[Ballot discuss]
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.

[Ballot discuss]
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!)

[Ballot discuss]
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!)

[Ballot comment]
I fully agree with Alexey's discusses and comments. If you want to provide a C-language API, it must be syntactically and semantically correct. Otherwise, why bother?

Additionally, as a convenience to the reader/implementor, it'd be a really good idea if you formatted the draft in a way that made it easy to extract a complete C header file. Look at draft-ietf-nfsv4-minorversion1-dot-x, which did that for an XDR interface - it gives you the shell command to extract the XDR code which can then be directly fed into rpcgen.

[Ballot discuss]
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

[Ballot comment]
1)
2.3.  String Format

  C API clients are required to format strings as UTF-8 if the string
  contains 16 bit characters.

Did you mean "Unicode characters"? They are *not* 16 bits.

  Since the ASCII characters and the UTF-8
  8 bit characters have the same codes,

I think you meant to say something like:

  Since the US-ASCII characters have the same codes when encoded in UTF-8

or
  Since all 7-bit UTF-8 bytes represent US-ASCII characters

2) In general, I think most (all?) of "char *" input parameters in the document need to be changed to "const char *", otherwise you will get compiler warnings when passing constants.
For example:

3.4.1.1.  AAAOpen()

  The following function is used to open and configure the AAA library:

        AAAReturnCode AAAOpen(char *configFileName);

Should be:
        AAAReturnCode AAAOpen(const char *configFileName);

because:

3.4.1.3.  AAAGetDefaultConfigFileName()

  The following returns the default configuration file name on the
  platform:

        const char *
        AAAGetDefaultConfigFileName();

3)
3.4.3.4.  AAAAbortSession()

  The following function, sent by the server, terminates a session:

        AAAReturnCode
        AAAAbortSession(AAASessionId *sessionId);

Does this result in the abortCallback (registered in AAAStartSession) being called?

4)
3.4.3.5.  AAALookupServer()

  The function looks up the AAA server based on IP address and port
  number.  Server connections are created from the configuration file:

Can you explain the last sentence in a bit more details?

5)
3.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.

3.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);

This function and one above: what exactly do they do?
Maybe you can give an example?

6)
3.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.  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);

How is the exact error can be discovered on failure of this function?
(There is no AAAReturnCode output parameter anywhere)

7)
3.4.5.3.  AAARespondToMessage()

  This function is called to set the AAA Message to the appropriate
  values, and to inform the library that this message is a locally
  generated response

This might be my lack of familiarity with DIAMETER, but I don't think this text is clear. Does this function cause any IO?

        AAAReturnCode
        AAARespondToMessage(AAAMessage* message,
                            AAACommandCode commandCode,
                            AAAVendorId vendorId,
                            AAAResultCode resultCode);

8)
3.4.5.18.  AAASetMessageResultCode()

  This function decapsulates an encapsulated AVP, and populates the
  list with the correct pointers.

Can you elaborate on what this means?

        AAAResultCode
        AAASetMessageResultCode(AAAMessage *message,
                                AAAResultCode resultCode);

9)
3.4.6.1.  AAASetServer()

  This function sets the server to which the message is sent:

        AAAReturnCode
        AAASetServer(AAAMessage *message,
                      AAA_IP_ADDR host);

How is this function used?
In particular, it is not clear if AAASendMessage() is going to use information set by this function.

[Ballot discuss]
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.

Gen-ART review by Francis.Dupont

Summary: Not Ready

Comments: my main concern is the API as it is described up to section 3.7 is clearly impossible to implement so I strongly suggest to add soon (in section 2 for instance) some text explaining the document only specifies the visible/public part of some structures.
Another issue is most of the "include" part is missing.

Detailed comments:
- 1 page 4: code need only -> code needs only
- 2.2 page 6: All of the functions -> All functions ?
- 2.5 page 6: a DTD described it -> a DTD describing it
- 2 page 6: IMHO this is the right place to explain the structs
  defined in the document are the visible/public part of the real/internal
  structs with a reference to section 3.7
- 3.1.12 page 10: if -> when ?
- 3.1.15 page 12: the header (six, four) is obviously about a previous
  version...
- 3.1.15 page 12: IMHO you should explain why, despite the name "flags",
  it is right to use an enumeration here (exclusive values, etc).
- 3.1.16 page 12: AAAGetDomainInterconnectType() doesn't return
  this type (cf. 3.4.3.7) and it is not AAAGetDomainInternconnectType()
                                                        ^
- 3.2.3 page 15: this type should be opaque, i.e., the name of the
  fields should be private. This has two consequences:
  * users don't know the names so can't misuse them (they have
  AAAGetFirstAVP() & co)
  * it justifies a bit the *avpList in the next section (in place
  of plain avpList)
BTW in a traditional double-linked list with tail pointer the  tail is a ** pointer
- 3.2.4 page 16: extra *Version fields (unneeded with AAA_IP_ADDR)
- 3.4.3.7 page 24: type should be a AAADomainInterconnect *
- 3.4.4.6 page 27: AAAGetCommandCode() must return an AAAReturnCode
  and the return value text be updated to the usual one
- 3.4.5.4 page 29: occured -> occurred
- 3.4.5.6 page 30: AAACreateAndAddAVPToList() is underspecified:
  * can be the avpList created when it points to NULL?
  (cf next section)
  * what is the position when the list is not empty?
- 3.4.5.[67] pages 30 & 31: there is no way to free an AAA_AVP_List
  so what to do if something fails? Obviously there are some use
  restrictions so at least a reference to 3.6 is wellcome
- 3.4.5.1[45] page 34 (comment): obviously AAAGet{Next,Prev}AVP()
  imply link fields in the real AVP struct!
- 3.4.6.1 page 36: extra ipVersion field
- 3.4.6.2 page 36 (comment): again the server id is an internal
  AAAMessage field
- 3.6 page 38: (for uniformity)
  (char *) ourAddress -> (char *)ourAddress
- 3.7 page 39: this is a key point but one has to read ~40 pages
  to find it. Note there are other ways to handle public/private
  fields in C (but no highly recommended ways):
  * the sub structure way (document's one)
  * private fields at the end of the definition with a comment
    explaining they are private
  * private fields at the end of the definition protected by a #ifdef
  I prefer the second one (no cast, sizeof() works but it relies
  on the programmer's discipline) but you should simply give the
  choice to implementors
- 3.9 page 41: 3.1.13 specifies there can be only one first/last,
  for instance:
  AAA_APP_INSTALL_FIRST:  Install this callback as the first callback
      in the chain.  If subsequent callbacks are installed with this
      code, then AAA_ERR_ALREADY_REGISTERED is returned.
  so 3.1.13 and 3.9 are in conflict (note I prefer 3.1.13)
- 7.2 page 45: where are the DIAM_AVP_* & co defined?
  I am afraid you have to add them...
- Author's Addresses page 46: please add the Contry (USA? :-)
- I'd like to have a .h in annex (note the names of the .h and
  of the DLL/library/... are part of the API)

IANA Last Call comments:

NOTE: this document contains a number of enumerated values
that either belong in their own registry or should map more
directly to the existing AAA registries located at
http://www.iana.org/assignments/aaa-parameters/aaa-parameters.xhtml

As described in the IANA Considerations section, we understand
this document to have NO IANA Actions.

PROTO WRITEUP for draft-ietf-dime-diameter-api-06.txt
======================================================

(1.a) Who is the Document Shepherd for this document? Has the
Document Shepherd personally reviewed this version of the
document and, in particular, does he or she believe this
version is ready for forwarding to the IESG for publication?

Hannes Tschofenig (Hannes.Tschofenig@gmx.net) is the Document Shepherd.
I have reviewed the document personally, and find it to be ready for
publication.

(1.b) Has the document had adequate review both from key WG members
and from key non-WG members? Does the Document Shepherd have
any concerns about the depth or breadth of the reviews that
have been performed?

The document has been in the IETF for a number of years. It has been
reviewed through several phases while it was in the AAA and subsequently
moved over to the DIME working group.

There are no concerns regarding the reviews.

(1.c) Does the Document Shepherd have concerns that the document
needs more review from a particular or broader perspective,
e.g., security, operational complexity, someone familiar with
AAA, internationalization or XML?

No further reviews are required.

(1.d) Does the Document Shepherd have any specific concerns or
issues with this document that the Responsible Area Director
and/or the IESG should be aware of? For example, perhaps he
or she is uncomfortable with certain parts of the document, or
has concerns whether there really is a need for it. In any
event, if the WG has discussed those issues and has indicated
that it still wishes to advance the document, detail those
concerns here. Has an IPR disclosure related to this document
been filed? If so, please include a reference to the
disclosure and summarize the WG discussion and conclusion on
this issue.

There are no current concerns.

(1.e) How solid is the WG consensus behind this document? Does it
represent the strong concurrence of a few individuals, with
others being silent, or does the WG as a whole understand and
agree with it?

There is consensus in the working group to publish the document.
Not everyone has, however, a strong opinion about publishing an
API document.


(1.f) Has anyone threatened an appeal or otherwise indicated extreme
discontent? If so, please summarize the areas of conflict in
separate email messages to the Responsible Area Director. (It
should be in a separate email because this questionnaire is
entered into the ID Tracker.)

No.

(1.g) Has the Document Shepherd personally verified that the
document satisfies all ID nits? (See
http://www.ietf.org/ID-Checklist.html and
http://tools.ietf.org/tools/idnits/). Boilerplate checks are
not enough; this check needs to be thorough. Has the document
met all formal review criteria it needs to, such as the MIB
Doctor, media type and URI type reviews?

ID nits got verified. There are no formal review criteria with regard to
this document.

The draft contains C-code. It came from Sun's working implementatation.
The document shepherd reviewed the C-code and additionally it was
reviewed by Victor Fajardo, our WG secretary and main developer of the
OpenDiameter stack.


(1.h) Has the document split its references into normative and
informative? Are there normative references to documents that
are not ready for advancement or are otherwise in an unclear
state? If such normative references exist, what is the
strategy for their completion? Are there normative references
that are downward references, as described in [RFC3967]? If
so, list these downward references to support the Area
Director in the Last Call procedure for them [RFC3967].

Yes. References are split into normative and informative references.

There is a normative reference to RFC 3493 "Basic Socket Interface
Extensions for IPv6" (an informational RFC). However, the Diameter
API document is an informational document.

(1.i) Has the Document Shepherd verified that the document IANA
consideration section exists and is consistent with the body
of the document? If the document specifies protocol
extensions, are reservations requested in appropriate IANA
registries? Are the IANA registries clearly identified? If
the document creates a new registry, does it define the
proposed initial contents of the registry and an allocation
procedure for future registrations? Does it suggest a
reasonable name for the new registry? See [RFC2434]. If the
document describes an Expert Review process has Shepherd
conferred with the Responsible Area Director so that the IESG
can appoint the needed Expert during the IESG Evaluation?

An IANA consideration section exists but there are no actions for IANA.

(1.j) Has the Document Shepherd verified that sections of the
document that are written in a formal language, such as XML
code, BNF rules, MIB definitions, etc., validate correctly in
an automated checker?

The document contains C-code (as noted already above).


(1.k) The IESG approval announcement includes a Document
Announcement Write-Up. Please provide such a Document
Announcement Write-Up? Recent examples can be found in the
"Action" announcements for approved documents. The approval
announcement contains the following sections:


Document Announcement Write-Up

Technical Summary


The Diameter authentication, authorization, and accounting (AAA)
protocol provides support for peering AAA transactions across the
Internet. This document describes an API for the
Diameter protocol. The API is defined for the C language. The
intent of the API is to foster source code portability across
multiple programming platforms.


Working Group Summary

There is consensus in the WG to publish this document.

Document Quality

There are two known deployments of Diameter servers using this
API. One of the implementation's maintainers has provided
many comments and contributions to the document.

Personnel

Hannes Tschofenig shepherded this document.