Subject: Re: [Dime] Diameter API draft

From: Hannes Tschofenig <[email-masked]>
Date: Sun, 04 May 2008 20:25:28 +0300

Hi Sebastien,

I guess nobody so far responded to your question.

Sebastien Decugis wrote:
> Hello,
>
> I am starting an implementation of Diameter API in a library.
Very good!
>  I have a 
> couple of question about the draft-ietf-dime-diameter-api-06 [1] document.
>
> - There are some editorial issues with this document (one example: in 
> the ToC 3.1.6 and 3.1.7 have the same label). The document is claimed to 
> be sent to IESG in [2]. Does it mean that it will no more be updated?
>   
There are no problems updating editorial issues. In this case that could 
be done in AUTH48.

> - Is there any plan to update the API with regards to rfc3588bis (new 
> datatypes, etc...)?
>   
I don't think that there is anything in the draft that would be impacted 
by RFC 3588bis.

Ciao
Hannes

> Thank you!
> Sebastien.
>
> [1] http://tools.ietf.org/html/draft-ietf-dime-diameter-api-06
> [2] http://www.shingou.info/twiki/bin/view/Dime/DimeStatusUpdate
>
>   

_______________________________________________
DiME mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/dime

---

From: Sebastien Decugis <[email-masked]>
Date: Fri, 09 May 2008 15:15:25 +0900

Thank you Hannes for your answers. Please find my comments bellow.

>> the ToC 3.1.6 and 3.1.7 have the same label). The document is claimed 
>> to be sent to IESG in [2]. Does it mean that it will no more be updated?
>>   
> There are no problems updating editorial issues. In this case that 
> could be done in AUTH48.
>
> I don't think that there is anything in the draft that would be 
> impacted by RFC 3588bis.

I have built a (sorry, long) list of editorial and content issues and 
questions about the draft-ietf-dime-diameter-api-06 document. I hope 
this will be useful for a possible later revision.

Best regards,
Sebastien.

"1. Introduction"
[General comment] The introduction should state what kind of Diameter 
entity the API is meant for (client, server, agents?) For example, if 
the API is to be used on a relay agent, what kind of processing is 
managed by the library and what kind of processing is left to 
application (i.e. routing loop detection, adding the Route-Record AVP, 
Failover retransmissions, ...)? Otherwise two libraries conforming to 
this API may not be equivalent.

"3.1.7. Value Type Identifier"
[edito] The title of this subsection is erroneous. It should be "Peer 
Identifier" or "Server Identifier".

"3.1.12. API Return Codes"
[edito] Copy and paste error: the typedef block starts twice, and does 
not end.

"3.1.14. AVP Data Type Codes "
[remark] The text tells that the types "correspond directly" to the AVP 
data types. This mapping is not obvious and may be more explicit:
- Types in the API:
AAA_AVP_DATA_TYPE,
AAA_AVP_STRING_TYPE,
AAA_AVP_ADDRESS_TYPE,
AAA_AVP_INTEGER32_TYPE,
AAA_AVP_INTEGER64_TYPE,
AAA_AVP_TIME_TYPE
- Types in Diameter:
(base types)
OctetString
Integer32
Integer64
Unsigned32
Unsigned64
Float32
Float64
Grouped
(extended types derived from base types)
Address
Time
UTF8String
DiameterIdentity
DiameterURI
Enumerated
IPFilterRule
QoSFilterRule (* not in 3588bis)

"3.1.15. AVP Flags"
[edito] The text refers to "the first six" values but only five values 
are defined.
[edito] The description of AAA_AVP_FLAG_RESERVED is missing.
[edito] The description of AAA_AVP_FLAG_UNKNOWN is unclear. It refers to 
functions for dictionnary lookup, but these functions do not use the AVP 
flags.
[question] Would it not be more efficient and extensible to define the 
flag constants to the same values as the flags in the Diameter protocol 
on this model:
        AAA_AVP_FLAG_VENDOR_SPECIFIC = 0x80
        AAA_AVP_FLAG_MANDATORY       = 0x40

"3.1.16. Domain Interconnection Types"
[edito] Typo in "AAAGetDomainInternconnectType". Note also that the type 
defined here is not used by the function AAAGetDomainInterconnectType.

"3.1.17. Message Flags"
"Currently, there are no message flags defined in the Diameter protocol 
[RFC3588]"
[question] Do the message flags refer to the command flags 'R', 'P', 
'E', 'T'? In this case, it may be useful to have names defined for these 
flags.

"3.1.18. Result Codes"
[remark] The Diameter RFC already defines different error codes for most 
of these error conditions (names are DIAMETER_*). Redefinition of the 
error values means that the library will have to do the mapping, which 
is not very efficient (and means that if new error codes are defined, 
the library must be updated)

"3.1.20. Accounting Types"
[edito] The first paragraph is erroneously copied from previous subsection.
[remark] The values may be defined to match EVENT_RECORD, EVENT_START, 
... from RFC, or be treated as enumerator values defined in the Diameter 
dictionnary (values found with function AAAValueFromName) since these 
are the values for the Accounting-Record-Type AVP.

"3.2.1. Dictionary Entry Definition"
[remark] Since the avpType is an enumerator, it can not contain a new 
extended type defined in the dictionnary. Therefore the application 
using the API can not determine the exact type of an AVP, only the basic 
type that it was derived from.
[edito] Since AAA_AVPFlag is an enumerated type, we cannot store more 
that one flag here. For example, AAA_AVP_FLAG_VENDOR_SPECIFIC | 
AAA_AVP_FLAG_MANDATORY is not valid value. The type shoud be "unsigned 
char" or equivalent.

"3.2.3. AVP List"
[remark] The content of the avpList structure should be opaque and not 
defined. The content of the structure is always accessed through 
functions (AAAGetFirstAVP, ...) and moreover the structure will contain 
pointers to "Extended_AAA_Avp"  structures as defined in 3.7, and not 
directly AAA_AVP structures that cannot be chained.

"3.2.4. Message Definition"
[edito] originatorVersion and SenderVersion fields are described but are 
not in the structure.
[question] Is AAAMsgIdentifier related to Hop by hop ID or End to end ID?
[question] Since ResultCode is in the structure, does the Result-Code 
AVP appear in the AVP list?
[question] a Diameter message may have several Proxy-Info AVP, therefore 
the proxyAVP pointer should be of type AAA_AVP_LIST, or does it point 
only to the latest Proxy AVP in the message? Are these Proxy-Info AVP 
also present in the AVP list?
[question] The Diameter RFC does not introduce a concept of timer per 
message. What are the two timers in the structure?

"3.4.1.1. AAAOpen()"
[question] Calling AAAOpen() must result in the callbacks to be 
registered, so what is the use of the functions to register the 
callbacks (AAARegisterCommandCallback...)?

"3.4.2.1. AAARegisterCommandCallback()"
[question] What does a AAAExtensionId extensionId represents exactly? It 
is not clearly defined in the document.
[remark] Providing both commandName and {commandCode + VendorID} is 
redundant.
[remark] position can only be AAA_APP_INSTALL_ANYWHERE, so it is not needed.

"3.4.2.2. AAARegisterNoncommandCallback()"
[remark] The error AAA_ERR_ALREADY_REGISTERED defined in 3.1.13 cannot 
be returned by this function prototype.

"3.4.3.5. AAALookupServer()"
[remark] AAALookupServer with this prototype cannot be used to refer a 
server that has been dynamically discovered. Using a DiameterIdentity 
may be preferred.

"3.4.3.6. AAASetSessionMessageTimeout()"
[remark] The concept of timeout in this function is different from the 
description of Session-Timeout AVP in Diameter RFC. Does the API adds a 
new timeout ? (this is related to last question for item 3.2.4 in this list)

"3.4.3.7. AAAGetDomainInterconnectType()"
[edito] A type AAADomainInterconnect is defined in the document for this 
function, but not used here.
[question] How does a peer can discover how it is connected to another 
domain? If querying for the next-hop server, the CER/CEA exchange may 
have provided a few information (through relay application id support 
information), but for other peers this is not clear. The next hop may be 
a relay, and then somewhere in the path there may be a redirect and/or a 
proxy.

"3.4.4.3. AAAValueFromName()"
[edito] The return value is the enumerator value, and not "the id of the 
AVP".
[question] Is it not possible that an enumerator value is equal to 
AAA_ERR_NOT_FOUND ?
* same for 3.4.4.4

"3.4.4.6. AAAGetCommandCode()"
[edito] the return value _B_TRUE is not defined (and the function should 
return a AAAReturnCode for coherency).

"3.4.5.3. AAARespondToMessage()"
[question] From my understanding of Diameter protocol, answers always 
have the same command code as corresponding requests. Can you provide 
examples where it is not the case? Otherwise, the commandcode parameter 
is not needed.

"3.4.5.4. AAAAddProxyState()"
[remark] From Diameter RFC, the Proxy-State AVP contains local opaque 
data. Therefore, the function should have a second parameter to pass the 
data to be stored in the AVP (and maybe a third for the size of data).

"3.4.5.6. AAACreateAndAddAVPToList()"
[edito] The position where the new AVP must be inserted in the list 
should be specified (either fixed or as new parameter to the function).

"3.4.5.8. AAAFindMatchingAVP()"
[edito] The description of the parameters does not match the function 
prototype.

"3.4.5.16. AAAConvertAVPToString()"
[remark] It would be useful to know the amount of data that was actually 
written in the buffer on function return.

"3.4.5.17. AAASetMessageResultCode()"
[edito] The description of the function is not related to the function.

"3.4.6.1. AAASetServer()"
[edito] There is no ipVersion parameter in the function prototype.
[question] Does this sets the next-hop or the final destination of the 
message? In both cases, the DiameterIdentity should be used instead of 
ip/port/familly (and protocol?) to include the case where the peer is 
dynamically discovered.

"3.4.6.2. AAASendMessage()"
[remark] The Diameter behavior when a peer is not reachable is to return 
an error DIAMETER_UNABLE_TO_DELIVER. The API should conform to this 
behavior and return an error when no peer is active, instead of queuing 
the message. This allows for faster detection of the problem at 
application level, and the possibility to take actions (changing the 
destination server, informing the user...)

"3.4.7. Accounting"
[edito] The description is copied from 3.4.6 and not accurate for this 
section.

"3.4.7.1. AAASendAcctRequest()"
[remark] The accounting msgType is normally contained in an AVP 
Accounting-Record-Type inside acctAvpList. This parameter may therefore 
be redundant.

"3.6. Grouped AVPs"
[edito] In the example, a Proxy-State AVP is built as a grouped AVP 
containing Proxy-Info and Proxy-Address AVPs. But the Diameter RFC 
defines Proxy-Info AVP as a grouped AVP containing Proxy-Host and 
Proxy-State AVPs. This example may be confusing.

"3.9. Callback Processing Order"
"If the API client adds another, any existing pre- and post-processors 
are removed."
[edito] This conflicts with previous text (3.1.13) that states that an 
error is returned if a callback is already registered.

-- 
Sebastien Decugis
Research fellow
Network Architecture Group
NICT (nict.go.jp)
_______________________________________________
DiME mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/dime