Subject: [Dime] comments on Diameter Guidelines draft

From: <[email-masked]>
Date: Sat, 2 Aug 2008 13:56:34 +0200

here is my review of the last version of the guidelines documents.
A mix between editorial nits and proposal for
enhancements/clarification.
 
BR,
 
Lionel
 
**************************************
[LM] Beginning of the review. [end]

1.  Introduction

   The Diameter Base protocol document defines rules on how one would
   extend Diameter (see Section 1.2 of [1]).  In the context of this
   document, extending Diameter means one of the following:

   1.  A new functionality is being added to an existing Diameter
       application without defining a new application.

   2.  A new Diameter application is being defined by reusing an
       existing application.

[LM] instead of "reusing", I would say "by extending an existing
application". [end]

   3.  A completely new application is being defined that has nothing in
       common with existing applications.

   4.  A new generic functionality is being defined that can be reused
       across different applications.

   All of these choices are design decisions that can done by any
   combination of reusing existing or defining new commands, AVPs or AVP
   values.  Protocol designers do, however, not have total freedom when
   making their design.  A number of rules defined in [1] place
   constraints on when an extension demands a new Diameter Application
   to be defined or a new Command Code to be registered.  The objective
   of this document is the following:

   o  Clarify updated Diameter extensibility rules in the Diameter Base
      Protocol.

   o  Clarify usage of certain Diameter functionality which are not
      explicitly described in the Diameter Base specification.

[LM] "functionality" --> "functionalities [end]

   o  Discuss design choices and provide guidelines when defining
      applications.

   o  Present tradeoffs of design choices.

[skip]

3.  Overview

[skip]

   When reusing existing applications, the requirements of the new
   applications are typically not completely unique and hence a lot can
   be re-used from existing specifications.  Therefore, there is a
   greater likelihood of ambiguity on how much of the existing
   application can be reused and what would be the implications for both
   the new and existing application.  To broadly categorize, the rules
   for reusing existing applications can fall into two categories, as
   listed below.

   Minor Extension:  This, for example, is the case when optional AVPs
      are being defined.  In general, this includes everything that is
      not covered by the next category.  The standardization effort will
      be fairly small.

   Major Extension:  Such an extension requires the definition of a new
      Diameter application.  The rules outlined in Section 1.2 of [1]
      indicate when an extension is significant enough to require a new
      Command Code to be registered and when new Diameter applications
      have to be defined.  Typically, these extensions require a longer
      standardization effort, a little bit depending on the depending on
      the degree of re-use, since additional aspects have to be taken
      into consideration.

[LM] "significant enough" and "little bit" should be prohibited in a
specification documentation. But I think that there is already a comment
on this.
[LM] I don't see how is used the wording "standardization effort". The
same "effort" will be needed in case of vendor-specific extension (e.g.
SDO specific extensions or vendor-specific extensions). Could it be
replaced by "specification effort"? [end]

   The subsequent sections provide discussions about the specific
   Diameter Base protocol rules.

4.  Adding a new command

   The rules are strict in this case.  Adding a command to an
   application requires a new Diameter application to be defined.l

[LM] remove "l" after "defined." [end]
[LM] could we add that: "This falls into the "Major Extensions"
category."?

   However, if this is the intent, then the new application can be
   created by defining a new command for an existing application or
   importing an existing command from another application so as to
   inherit some or all of the functionality of that application.  

[LM] For this part of the text, I would propose to clarify the text as
follow:

"Adding a new command to an application means either defining a new
command for an existing application or importing an existing command
from another application, the new application inheriting then some or
all of the functionality of the existing application" [end]

   In the
   former case, the decision is straightforward since this is typically
   a result of adding new functionality that does not yet exist.  The
   latter case would result in a new application but it has a more
   subtle issue such as deciding whether importing of commands and
   functionality is really better than simply using the existing
   application as it is in conjunction with any new application.

   In general, it is difficult to come to a hard guideline, and so a
   case by case study of each application requirement should be applied.

[LM] proposed text, for seek of clarity:

"In the former case, the decision to create an new application is
straightforward since this is typically a result of adding a new
functionality that does not exist yet. For the latter, the decision will
depend on whether importing the command in a new application is more
suitable than simply using the existing application as it is in
conjunction with any other application (a new one or an existing one).
Therefore, a case by case study of each application requirement should
be applied. [end]

   Before adding or importing a command, application designers should
   consider the following:

   o  Can the new functionality be fulfilled by creating a new
      application independent from the existing applications?  In this
      case, a deployment architecture could be designed such that both
      old and new application can work independent of, but cooperating
      with each other.

[LM] remove reference to "deployment architecture" out of scope here.
Just say: "In this case, both old and new applications..." with "s" at
the end of applications [end]

   o  Can the existing application be reused as is without fundamental
      changes; e.g., a non-mandatory optional AVP is sufficient to
      indicate support for new optional functionality, if any.

[LM] "Can the existing application be reused as is without fundamental
changes" --> Can the existing application be reused without major
extensions requiring the definition of a new application, e.g. new
funtionality introduced by the creation of an new optinal AVP." [end]

   o  Care should be taken to avoid a liberal method of importing many
      commands that results in a monolithic and hard to manage
      application which supports many different functionalities.

[LM] proposed text:

"Care should be taken to avoid a liberal method of importing existing
commands in the same new application that would result in a monolithic
and complex application supporting many different functionalities" [end]

5.  Deleting a Command

   Although this is not typical, deleting an command from an existing
   application is fundamentally changing the application.  In general,
   the implications of this approach are the same as Section 4
   regardless of whether new commands will also be added to the
   resulting application.

[LM] What is the meaning of "In general" in the last sentence? Removing
of any command must result in the creation of a new application, isn't
it? I would just say: "Removing a command to an application requires a
new Diameter application to be defined. [end]

  In general, it is unusual to delete an
   existing command from an existing application for the sake of
   deleting it or the functionality it represents.  This design decision
   would normally be an indication of a flawed design.  An exception
   might be if the intent of the deletion is to create a newer version
   of the same application which is somehow simpler than the previous
   version.

6.  Reusing Existing Commands

   This section discusses rules in adding and/or deleting AVPs from an
   existing command of an existing application.  The cases described in
   this section may not necessarily result in the creation of new
   applications.

6.1.  Adding AVPs to a Command

   Based on the rules in [1], AVPs that are added to an existing command
   can be categorized into:

   o  Mandatory to understand AVPs.  As defined in [1], these are AVPs
      with the M-bit flag set, which means that a Diameter node
      receiving these AVPs has to understand not only their values but
      their semantics.  This is regardless of whether these AVPs are
      required or optional to appear in the command; as specified by the
      commands ABNF.

[LM] should we add that an AVP not understood will cause a failure in
the message handling? It's for me the main difference between mandatory
and optional AVP i.e. Optional AVP can be ignored without causing a
failure. [end]
[LM] use "," instead of ";" in the last sentance [end]

   o  Optional AVPs

[LM] text describing optional AVP is missing. Please cf. 3588bis and
Diameterextensibility text. [end]

   The rules are strict in the case where the AVPs to be added are
   mandatory.  A mandatory AVP cannot be added to or deleted from an
   existing command with defining a new Diameter application. [1] states
   that doing so would require the definition of a new application.
   This falls into the "Major Extensions" category.  Despite the clarity
   of the rule, ambiguity still arises when trying to decide whether a
   new AVP being added should be mandatory to begin with.  There are
   several questions that application designers should contemplate when
   trying to decide:

[LM] just clarify that the following list is not exhaustive but
illustrative.

   o  Is it necessary for the receiving side to be able to process and
      understand the AVP and its content (rather than just writing it's
      content into to a file)?

[LM] need for a separated line [end]
[LM] I would use "required" instead "necessary" [end]

   o  Do the AVPs change the state machine of the application ?

   o  Would the presence of the new AVPs (or the newly specified value
      contained in an existing AVP) lead to a different number of
      roundtrips; effectively changing the state machine of the
      application?

[LM] use "," instead of ";" [end]

   o  Would the AVP be used to differentiate between old and new
      versions of the same application whereby the two versions are not
      backward compatible?

   o  Will it have duality in meaning; i.e., be used to carry
      application related information as well as be used to indicate
      that the message is for a new application?

[LM] remove the ";" [end]

   When one of the above questions can be answered with 'yes' then the
   M-bit has to be set.

[LM] I would add an extra text that would introduce the second set of
questions, to make clearer that we are know considering use of optional
AVP. [end]

   o  Use of optional AVPs with intersecting meaning; one AVP has
      partially the same usage and meaning as another AVP.  The presence
      of both can lead to confusion.

   o  An optional AVPs with dual purpose; i.e.; to carry applications
      data as well as to indicate support for one or more features.
      This has a tendency to introduce interpretation issues.

   o  Adding one or more optional AVPs and indicating (usually within
      descriptive text for the command) that at least one of them has to
      be present in the command.  This essentially circumventing the
      ABNF and is equivalent to adding a mandatory AVPs to the command.

   All of these practices generally result in interoperability problems
   so they should be avoided as much as possible.

[LM] The conclusion being that a mandatory AVP is required, isn't it?
[end]

6.2.  Deleting AVPs from a Command

   Although this scenario is not as common, the deletion of AVPs from a
   command ABNF is significant when trying to extend an existing
   application.

[LM] strange to see in the same sentance "deletion" and "to extend an
existing application". Instead of "extend", I would use "modify" [end]

   When deleting an AVP from a Command the following cases need to be
   differentiated:

[LM] bullet point style missing below [end]

   An AVP that is indicated as {} in the ABNF in the Command (with the
   M-bit set)

      In this case the new Command Code and subsequently a new Diameter
      application has to be specified.

[next bullet point]
   An AVP that is indicated as {} in the ABNF in the Command (without
   the M-bit set)

      In this case the new Command Code and subsequently a new Diameter
      application has to be specified.

[LM] the two above cases are exactly the same. It would maybe better to
have only one bullet point, i.e. "An AVP that is indicated as {} in the
ABNF in the Command (with or without the M-bit set)" [end]

[LM] Am I wrong if i say that the following case is missing and should
be inserted before the "{}" case?
  "An AVP that is indicated as <> in the ABNF in the Command (with or
without the
   M-bit set)

      In this case the new Command Code and subsequently a new Diameter
      application has to be specified." [end]

[next bullet point]
   An AVP that is indicated as [] in the ABNF in the Command (with the
   M-bit set)

      No new Command Code has to be specified but the definition of a
      new Diameter application is required.

[next bullet point]
   An AVP that is indicated as [] in the ABNF in the Command (without
   the M-bit set)

      In this case the AVP can be deleted without consequences.

   If possible application designers should attempt the reuse the
   Command ABNF without modification and simply ignore (but not delete)
   any optional AVP that will not be used.  This is to maintain
   compatibility with existing applications that will not know about the
   new functionality as well as maintain the integrity of existing
   dictionaries.

7.  Reusing Existing AVPs

   This section discusses rules in adding, deleting or modifying the
   specified values of an AVP.

   When reusing AVPs in a new application, the AVP flag setting, such as
   the mandatory flag ('M'-bit), has to be re-evaluated for a new
   Diameter application and, if necessary, even for every Command within
   the application.  In general, for AVPs defined outside of the base
   protocol, its mandatory characteristics is tied to its role within an
   application and Command.

[LM] "characteristic is" or "characteristics are" [end]

8.  Rules for new Applications

   The general theme of Diameter extensibility is to reuse commands,
   AVPs and AVP values as much as possible.  However, some of the
   extensibility rules described in the previous section also apply to
   scenarios where a designer is trying to define a completely new
   Diameter application.

   This section discusses the case where new applications have
   requirements that cannot be filled by existing applications and would
   require definition of completely new commands, AVPs and/or AVP
   values.  Typically, there is little ambiguity about the decision to
   create these types of applications.  Some examples are the interfaces
   defined for the IP Multimedia Subsystem of 3GPP, i.e.; Cx/Dx ([2] and
   [3]), Sh ([4] and [5]) etc.

[LM] remove ";" in the last sentance. [end]

   Application design should also follow the theme of Diameter

[LM] I think that it is "Application designers" instead of "Application
design" [end]

   extensibility which in this case means to import existing AVPs and
   AVP values for any newly defined commands.  In certain cases where
   accounting will be used, the models described in Section 10 should
   also be considered.  Though some decisions may be clear, designers
   should also consider certain aspects of defining a new application.
   Some of these are described in following sections.

[LM] "some of these aspects" or "some of them" instead of "some of
these". [end]

8.1.  Use of Application-Id in a Message

[skip]

8.2.  Application Specific Session Statemachine

[LM] "State machine" instead of "statemachine". Apply also to the text
below [end]
   
   Section 8 of [1] provides session statemachines for authentication,
   authorization and accounting (AAA) services.  When a new application
   is being defined that cannot clearly be categorized into any of these
   services it is recommended that the application itself define its own
   session statemachine.  The existing session statemachines defined by
   [1] is not intended for general use beyond AAA services, therefore

[LM] "state machines... are" instead of "statemachines... is" [end]
 
   any behavior not covered by that category would not fit well.
   Support for server initiated request is a clear example where an
   application specific session statemachine would be needed, for
   example, the Rw interface for ITU-T push model.

9.  End-to-End Applications Capabilities Exchange

   It is also possible that applications can use optional AVPs to
   exchange application specific capabilities and features.  These AVPs
   are exchanged on an end-to-end basis.  Examples of this can be found
   in [6] and [7].

   The end-to-end capabilities AVPs can aid in the following cases:

   o  Formalizing the way new functionality is added to existing
      applications by announcing support for it.

   o  Applications that do not understand these AVP can discard it upon
      receipt.  In such case, senders of the AVP can also safely assume
      the receiving end-point does not support any functionality carried
      by the AVP if it is not present in subsequent responses.

   o  Useful in cases where deployment choices are offered and the
      generic design can be made available for a number of applications.

[LM] inserte separation line [end]

Note that this list is not meant to be comprehensive.

10.  Diameter Accounting Support

[skip]

11.  Generic Diameter Extensions

[skip]

   In most cases, these optional AVPs piggybacked by applications would
   be defined as a Grouped AVP and it would encapsulate all the
   functionality of the generic extension.  In practice, it is not
   uncommon that the Grouped AVP will encapsulate an existing AVP that
   has previously been defined as mandatory ('M'-bit set); e.g., 3GPP
   IMS Cx / Dx interfaces ([2] and [3]).

[LM] remove the ";" in the last sentance. [end]

[LM] End of the rewiew [end]

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