Subject: diameter grammar proposal

From: "Erik Guttman" <[email-masked]>
Date: Wed, 10 Jan 2001 13:55:02 +0100

Folks,

I propose the following section be added to the DIAMETER base spec.
This will allow us to specify DIAMETER in a more formal way.  This is
unfortunately not as formal as a BNF would be, but DIAMETER messages
allow for arbitrary ordering of many elements.   Still, we need to
be able to specify that some elements may appear only once, and some
have to appear in fixed positions.  I believe this grammar suffices
to do this.  Please send comments.

(Randy, does this hold water?)

Erik
---------------------------------------------------------------------

1.3 Notation

   The DIAMETER protocol is composed of messages which have three
   components - a message header, a command code and a set of AVPs.
   Each message type is distinguished by a single command code.
   Command are specified using the following notation.

     Command-Code-Name ::= <DIAMETER-Header: #>
                          { qual AVP }
                          qual [ qual AVP ]
                          qual < AVP >

   The symbol # will be replaced by the command Id which is to be
   placed in the message header.  The symbol AVP MAY be replaced
   by the names of any specific AVP.  
 
   Elements surrounded by less than, greater than '<' and '>' are
   FIXED in sequence.   For example, the DIAMETER header MUST
   precede all AVPs.

   Elements surrounded by set brackets '{' and '}' are REQUIRED
   to be present in the message.  They MAY be in any order within
   the message provided they do not violate order imposed by message
   fixed elements in the grammar (which are defined between '<' 
   and '>' brackets.)

   Elements surrounded by square brackets '[' and ']' are OPTIONAL.
   AVPs which are listed in this section MAY be included in the
   message, in any order, provided they do not violate order imposed
   by fixed message elements in the grammar.  AVPs listed in FIXED
   or REQUIRED sections MUST NOT be considered OPTIONAL as well.  
   An AVP required to appear once in one section MUST NOT, therefor,
   be included as the result of an 'OPTIONAL AVP' rule.

   The token 'qual' can be the following:
     
     omitted    One instance of the following entry is required.
      '*'       Zero or more instances of the following entry are 
                required.
      '+'       One or more of instances of the following entry
                are required.
      '?'       Zero or one of instances of the following entry
                are required.
 
     Example-Command ::= <DIAMETER-Header: 9999999>
                        { User-Name *Host-Name }
                        * [ AVP ]
                        ? < Integrity-Check-Vector >

   The command defined by the preceding grammar MUST begin with a
   DIAMETER header, with the command code Id set to 9999999.  There
   follows a User-Name AVP, zero or more Host-Name AVPs and zero or
   more arbitrary other AVPs (but not User-Name, Host-Name or 
   Integrity-Check-Vector AVPs).  The REQUIRED and OPTIONAL AVPs
   can be permuted into any order, provided that none of them come 
   before the Header. 

   DIAMETER messages which violate the grammar defined for the
   command code are considered malformed and are rejected.  See
   Section 5.0.

---

From: Mark Eklund <[email-masked]>
Date: Wed, 10 Jan 2001 13:01:06 -0500 (EST)

A few questions/comments.

1. I am used to seeing qualifiers after the argument like in
regular expressions.  For example Host-Name* instead of
*Host-Name.  This is a personal preference.

2. Why do you need the optional brackets [] when you have the
'*' and '?' operators.  I.E. what is the difference in
*[Host-Name] and *Host-Name?

3. Do you plan to define Grouped-AVP in the specifications?

-mark

---

From: "Mark Jones" <[email-masked]>
Date: Wed, 10 Jan 2001 14:03:05 -0500

Erik,

Aren't the {} and [] brackets redundant given the 'qual' token definitions?

i.e.
	'*'  = Zero or more instances MAY be present in the packet = OPTIONAL AVP
	'+'  = At least one instance MUST be present in the packet = MANDATORY AVP
	'?'  = Zero or one instances MAY be present in the packet  = OPTIONAL AVP
   omitted = Exactly one instance MUST be present in the packet  = MANDATORY
AVP

Regards,
       Mark

> -----Original Message-----
> From: [email-masked] [mailto:[email-masked]]On Behalf
> Of Erik Guttman
> Sent: January 10, 2001 7:55 AM
> To: [email-masked]; Randy Bush
> Cc: Erik Guttman
> Subject: diameter grammar proposal
>
>
>
>
> Folks,
>

---

From: Erik Guttman <[email-masked]>
Date: Thu, 11 Jan 2001 11:20:56 +0100 (MET)

Mark,

Thanks for your questions, they helped me see where my grammar
proposal was weak.  I attempt to strengthen  it below.  Please
let me know if this answers your question and meets our needs.
 
> *Host-Name.  This is a personal preference.

The *, ? and + are in the spirit of ABNF (see RFC 2234) rather
than as glob or regular expressions.  They precede the grammar 
element they qualify.

> *[Host-Name] and *Host-Name?

The grammar conventions I proposed were not formally specified.  That
made it confusing, as you point out.  How about the following ABNF for
all diameter message definitions:

   command-def      = command-name "::=" diameter-message

   diameter-name    = ALPHA *(ALPHA / DIGIT / "-")

   command-name     = diameter-name
                      ; The command-name has to be Command name, defined in
                      ; the base or exteneded DIAMETER specifications.

   diameter-message = header  [ *fixed] [ *required] [ *optional] [ *fixed]

   header           = "<DIAMETER-Header:" command-id ">"

   fixed            = [qual] "<" avp-spec ">"

   required         = [qual] "{" avp-spec "}"

   optional         = [qual] "[" avp-name "]"
                      ; The avp-name in the 'optional' rule cannot evaluate 
                      ; to any AVP Name which is included in a fixed or 
                      ; required rule.              

   qual             = [min] "*" [max]
                      ; Rather than the confusing '?', '+' and '*' 
                      ; use ABNF conventions, RFC 2234 section 3.6.
                      ;  
                      ; NOTE:  "[" and "]" have a different meaning than
                      ; in ABNF (see the optional rule, above).  These 
                      ; braces cannot be used to express an optional fixed
                      ; rules (such as an optional ICV at the end.)  To do 
                      ; this, the convention is '0*1fixed'.

   min              = 1*DIGIT
                      ; The minimum number of times the element may be
                      ; present.

   max              = 1*DIGIT
                      ; The maximum number of times the element may be
                      ; present.

   avp-spec         = diameter-name
                      ; The avp-spec has to be an AVP Name, defined in the 
                      ; base or extended DIAMETER specifications.

   avp-name         = avp-spec | "AVP"
                      ; The string "AVP" stands for *any* arbitrary AVP Name.

This is more restricted than the grammar I described (but did not specify)
in my previous email.  

  (1) You can only put fixed rules at the beginning or end of the message.  
      This limits the possible command grammars you can produce, but I 
      think this is OK.  

  (2) You can only specify one AVP per fixed, required or optional rule, 
      where I indicated you could have any number AVPs in them.  This 
      will make the grammar specifications more verbose.  

  (3) Since you only have one AVP per rule, you only need the 'qual' 
      outside the braces, which eliminates the ambiguity of my initial
      proposal (where you could ask "Where do you put the qual?  What 
      is the meaning of putting it one place instead of the other?  
      What does it mean if you put it in both places? etc.)

The revised 'example' would look like:

     Example-Command ::= <DIAMETER-Header: 9999999>
                         { User-Name }
                        *{ Host-Name }
                        *[ AVP ]
                        0*1< Integrity-Check-Vector >

   before the Header or after the Integrity-Check Vector.

> 3. Do you plan to define Grouped-AVP in the specifications?

No - Grouped-AVP is going away, to be replaced by a Grouped value.
Other email on this was sent to the list with the subject

   "data type modifications to DIAMETER"

Erik

._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._.
E r i k   G u t t m a n         SHORT msgs: [email-masked]
Sr Staff Engineer, Sun Microsystems       Email: [email-masked]
Eichhoelzelstr. 7, 74915 Waibstadt Germany    Phone: +49 172 865 5497

---

From: Erik Guttman <[email-masked]>
Date: Thu, 11 Jan 2001 11:20:59 +0100 (MET)

Mark,
 
>    omitted = Exactly one instance MUST be present in the packet = MANDATORY

First - I suggest we get rid of the '+' and '?' qualifiers - they only
confuse the issue.  I suggest a grammar without them in a separate message
sent to the list.

Regarding the use of {} and [] for required and optional definitions:

It is important to distinguish between AVPs required by a command and
those which are optional.  For those that are required, we want to say
how many have to be there.  For those that are optional, we want to leave
things open. 

BUT we have to be sure that by leaving things open we don't allow the 
'optional' rules to collide with the 'required' rules.  Say you
MUST have one and only one 'Foo-AVP' in command X, and there is an
option rule, for sticking in any arbitrary AVP.   You could evaluate
that rule to allow N additional 'Foo-AVP's in the command X message.

That is why I want to separate optional and required AVPs in the 
message specifications.

This does NOT directly relate to the use of the term 'Mandatory' in 
DIAMETER.  Mandatory means the 'M' bit is set - which has consequences
if the receiver of a message doesn't have the ability to interpret the
AVP with the 'M' bit set.  This discussion has been pursued in other
threads.

Erik

---

From: "Mark Jones" <[email-masked]>
Date: Thu, 11 Jan 2001 10:30:08 -0500

Erik,

> 'optional' rules to collide with the 'required' rules.

Where 'optional' rules are those rules which refer to optional AVPs. The
rules themselves are NOT optional, correct?

> Say you

I see. You are concerned about conflicting rules. I am still not convinced
that ambiguity exists here. I had assumed that all rules MUST be satisfied
when evaluating whether a packet is valid. From your example, adding more
Foo-AVPs breaks the first rule and therefore would be illegal.

> AVP with the 'M' bit set.  This discussion has been pursued in other

Agreed. Lets never talk of it again :)

Regards,
       Mark

---

From: Mark Eklund <[email-masked]>
Date: Thu, 11 Jan 2001 10:28:11 -0500 (EST)

Erik, 

Thanks, that answers my earlier questions.  

Also, is there a need to support Command Flags like E, I, and R
in this specification?

-mark

---

From: Erik Guttman <[email-masked]>
Date: Thu, 11 Jan 2001 18:32:33 +0100 (MET)

> Also, is there a need to support Command Flags like E, I, and R

The grammar specification covers AVPs. The flags are specified 
for all commands (by their type -Ind, -Rqst, -Answer, -Query,
-Reply) and go into the DIAMETER header.

DIAMETER implementations will have to support those flags.  This
is useful for reasons pointed out in draft-ietf-aaa-issues-04.txt
and Pat's point that proxies can benefit from knowing a message
is an Indication, request/query or a reply/answer.

Erik

---

From: Erik Guttman <[email-masked]>
Date: Thu, 11 Jan 2001 18:38:05 +0100 (MET)

> rules themselves are NOT optional, correct?

Right.  I should've said the rules for 'optional AVPs'.

> Foo-AVPs breaks the first rule and therefore would be illegal.

The current diameter spec (which lists but doesn't constrain AVPs to
include) it is possible to put in WHATEVER, including more Foo-AVPs.  
There is no mechanism to describe as illegal putting in multiple AVPs 
of a given type (or ordering of AVPs in a message).  That is why I am 
proposing a more formal grammar, which still allows constrained, but 
still flexible inclusion of semi-arbitrary AVPs and reordering.

Erik