[Dime] WGLC review of draft-ietf-dime-app-design-guide-15

["A. Jean Mahoney" <[e-mail]>]

Hi all,

I didn't find any major issues while reviewing the document. However, I 
did come up with a long list of nits.

The first part of the review offers suggested wording changes to 
sentences and paragraphs. The second section covers typographical and 
punctuation errors.

Jean



4. p1 s1 (Section 4, paragraph 1, sentence 1):

Current:

… protocol designers are advised to try to re-use as
much as possible existing Diameter applications to simplify
standardization, implementation and avoid potential interoperability
issues.

Suggested:

… protocol designers are advised to reuse as
much as possible existing Diameter applications in order to simplify
standardization and implementation, and to avoid potential
interoperability issues.


4.3 p2 s3:

Current:

Therefore, if it is still recommended to re-use as much as possible
existing commands, protocol designers can consider more easily the
definition of a new command when it is a solution more suitable than
twisting existing command use and applications.

Suggested:

Although reuse of existing commands is still recommended, protocol
designers can consider defining a new command when it provides
a solution more suitable than the twisting of an existing command's
use and applications.


4.3.1 p2 s5:

Current:
Here is a list of few
common questions that application designers should wonder when trying
to decide:

Suggested:

Application designers should consider the following questions when
deciding to set the M-bit for a new AVP:


4.3.2 p1 s1:

Current:

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

Suggested:

The impacts of deleting an AVP from a command depend on its
command code format specification and M-bit setting:


5.4 p1 s2:

Current:
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 state machine.
The existing session state machines defined by
[I-D.ietf-dime-rfc3588bis] is not intended for general use beyond AAA
services, therefore any behavior not covered by that category would
not fit well.

Suggested:
If a new application cannot clearly be categorized into any
of these services, it is recommended that the application define its
own session state machine. The session state machines defined by
[I-D.ietf-dime-rfc3588bis] are not intended to cover behavior outside
of AAA.


5.6 p2 s2:

Current:
This has to be
considered as a sub-optimal design as this limits the extensibility
of the application: any new capability/permission would have to be
supported by a new AVP or new Enumerated value of the already defined
AVP that would cause in consequence backwards compatibility issues
with existing implementations.

Suggested:
This is a
sub-optimal design since it limits the extensibility of the application:
any new capability/permission would have to be supported by a new AVP
or new Enumerated value of the already defined AVP, causing backwards
compatibility issues with existing implementations.


5.6 p3:

Current:

Instead of defining Enumerated AVP when the AVP simply used as a
Boolean flag, protocol designers are encouraged to rely on AVP
defined in the form of a bit mask with the interpretation of the
setting of each bit described in the relevant Diameter application
specification. Such AVPs can be reused and extended to multiplex
several indications without major impact on the Diameter application.
The bit-mask should be therefore long enough to leave room for future
additions. Examples of AVP defined as bit mask are the Session-
Binding AVP defined in [I-D.ietf-dime-rfc3588bis] and the MIP6-
Feature-Vector AVP defined in [RFC5447]

Suggested:

Instead of using an Enumerated AVP for a Boolean flag, protocol
designers are encouraged to use a bit mask AVP whose bit settings
are described in the relevant Diameter application specification.
Such AVPs can be reused and extended without major impact on the
Diameter application. The bit mask AVP should leave room for future
additions. Examples of bit mask AVPs are the Session-Binding AVP
[I-D.ietf-dime-rfc3588bis] and the MIP6-Feature-Vector AVP [RFC5447].


5.7 p3:

Current:

Example of such specific routing function can be found the
applications defined for the IP Multimedia Subsystem of 3GPP, i.e.
Cx/Dx applications ([TS29.228] and [TS29.229]) in which the
Subscriber Location Function (SLF) is defined a proxy agent (or
enhanced Redirect agent) using specific application-level identities
found in the request to determine the final destination of the
message.

Suggested:

Examples of such application-specific routing functions can be found
in the Cx/Dx applications ([TS29.228] and [TS29.229]) of the 3GPP
IP Multimedia Subsystem, in which the proxy agent (Subscriber Location
Function) uses application-level identities found in the request to
determine the final destination of the message.


5.7 p4 s2:

Current:

In particular, this
ensures that Diameter agents in the request routing path (Relay or
Proxy agents) will be able to correctly release the transaction state
associated to the request upon receipt of the answer, avoiding thus
unnecessary failover triggering due to non reception of the answer
corresponding to the request. Application designers are strongly
recommended to not attempt to modify the answer routing principles
described in [I-D.ietf-dime-rfc3588bis] when defining a new
application.

Suggested:

In particular, this
ensures that the Diameter Relay or Proxy agents in the request routing
path will be able to release the transaction state upon receipt of the
corresponding answer, avoiding unnecessary failovers. Application
designers are strongly dissuaded from modifying the answer-routing
principles described in [I-D.ietf-dime-rfc3588bis] when defining a new
application.


5.8 p2:

Current:

In the specific case of RADIUS, it was initially foreseen that the
translation function would have been straightforward to define and
deploy by adopting few basic principles e.g. use of a shared range of
code values for RADIUS attributes and Diameter AVPs, some guidelines
on translation and management of key information (such as
authentication parameter, routing/accounting or states), etc. And
all this material was put in the RFC 4005 ([RFC4005]) to be used as
generic guideline for implementation of RADIUS-Diameter translation
agent.

Suggested:

In the case of RADIUS, it was initially thought that defining the
translation function would be straightforward. Guidelines for
implementing a RADIUS-Diameter translation agent were put into
RFC 4005 ([RFC4005]).


5.8 p4 s1:

Current:

Therefore, when interoperability with RADIUS infrastructure is
foreseen, protocol designers are advised that they cannot assume the
availability of "standard" Diameter-to-RADIUS gateways agent and the
required translation mechanism should be then specified along with
the Diameter application. And the recommendation in the case of
RADIUS-Diameter interworking applies of course for any other kind of
translation (e.g. Diameter/MAP).

Suggested:

Therefore, protocol designers cannot assume the availability of a
"standard" Diameter-to-RADIUS gateways agent when planning to
interoperate with the RADIUS infrastructure. They should specify
the required translation mechanism along with the Diameter application.
This recommendation applies for any kind of translation (e.g.
Diameter/MAP).


5.9 p2 and bullets:

Current:

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.


Suggested:

The end-to-end capabilities AVPs formalize the addition of new
functionality to existing applications by announcing support for it.
Applications that do not understand these AVPs can discard them upon
receipt. Senders of the AVP can safely assume the receiving end-point
does not support any functionality carried by the AVP if it is not
present in subsequent responses. This is useful in cases where
deployment choices are offered, and the generic design can be made
available for a number of applications.


6. p2 b3 s3:

Current:

However, the drawback is that the timing of sending extension data
will be tied to when the application would be sending a message.
This has consequences if the application and the extensions have
different timing requirements.

Suggested:

However, this ties the sending of extension data to the application's
transmission of a message. This has consequences if the application
and the extensions have different timing requirements.


6. p3 s1:

Current:

In practice, it is often the case that the generic extensions use
optional AVPs because it's simple and not intrusive to the
application that would carry it.

Suggested:

In practice, generic extensions often use optional AVPs because
they are simple and nonintrusive to the application that would carry
them.


Nits:

3. p2 s2: "completly" -> "completely"

4.1 p1 s3: "create an new" -> "create a new"

4.1 p3 s1: "case by case" -> "case-by-base"

4.1 p3 b3 s1: "importing existing" -> "importing an existing"

4.1 p3 b3 s2: "applications" -> "application"
remove the stray period at the end.

4.2 p1 s1: "to an application" -> "from an application"

4.2 p1 s2: "this" -> "This"

4.2 p2 s3: "which" -> "that"

4.3.1 heading: "ommand" -> "Command"

4.3.1 p1 b1 s2: "node receiving are" -> "node receiving them is"

4.3.1 p1 b2 s1: "receiving these AVP" -> "receiving these AVPs"

4.3.1 p2 b4 s1: "application related" -> "application-related"

4.3.1 p4 s1: "contemplating on the" -> "contemplating the"

4.3.1 p4 b2: "applications data" -> "application data"

4.3.1 p4 b3: "a mandatory AVPs" -> "a mandatory AVP"

4.4.1 p2 s1: add period after "unchanged"

5.1 p3 s1: add comma after "extensibility"

5.2 p1 s1: "Reusing" -> "reusing"

5.2 p1 s3: "pratices" -> "practices"

5.3 p1 s1 and s2: "session level" -> "session-level"

5.4 p1 s4: "server initiated" -> "server-initiated"

5.5 p3 s1: delete "really"

5.5 p3 s3: "by the application the" -> "by the application, the"

5.6 p1 s1: "provide list" -> "provide a list"

5.6 p1 s2: "perform on" -> "perform upon"

5.6 p2 s1: "as simple" -> "as a simple"

5.7 p2 s1: add comma after "suitable"

5.7 p4 s1: ", the answer" -> ", with the answer"
"Hop-by-hop" -> "hop-by-hop"

5.8 p3 s2: remove "will likely"
add comma after "specification"

5.10 p1 s1: "which" -> "that"

5.10 p2 s4: delete "generally"

5.10 p3 s2: delete "somehow"

5.10 p3 s3: "to be have" -> "to have"
delete "uniquely"

5.10 p3 s4: add comma after "existing AVPs"
"records" -> "record"

5.11 p1 s2: "However, IPsec Additional" -> "However, additional"

5.11 p2 s3: add comma after "pre-shared key"

5.11 p3 s1: "as security mechanisms" -> "as the security mechanism"

6 p2 b3 s2: "applications; However" -> "applications. However"

6 p2 b3 s5: add comma after "issue"

6 p3 s4: add comma after "set of applications"

8 p1 s1: delete "does"

8 p1 s2: "security related" -> "security-related"

Throughout the document:
"Diameter Base protocol" -> "Diameter base protocol"
"application specific" -> application-specific"
"tradeoff" -> "trade-off"