| Diameter Maintenance and Extensions | L. Bertz |
| Internet-Draft | Sprint |
| Intended status: Standards Track | December 30, 2017 |
| Expires: July 3, 2018 |
Diameter Specification Recommendations
draft-bertz-dime-diamimpr-01
This document reports on formatting errors, uses cases, and inconsistencies found in various standards specifications related to the Diameter interface requirements. Recommendations are made to reduce errors, support common use cases and build specifications in such a way that programmatic verification of Diameter specifications can be done with minimal to no errors.
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."
This Internet-Draft will expire on July 3, 2018.
Copyright (c) 2017 IETF Trust and the persons identified as the document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
This document may contain material from IETF Documents or IETF Contributions published or made publicly available before November 10, 2008. The person(s) controlling the copyright in some of this material may not have granted the IETF Trust the right to allow modifications of such material outside the IETF Standards Process. Without obtaining an adequate license from the person(s) controlling the copyright in such materials, this document may not be modified outside the IETF Standards Process, and derivative works of it may not be created outside the IETF Standards Process, except to format it for publication as an RFC or to translate it into languages other than English.
This document identifies common errors and uses of Diameter in order to document requirements and possible extensions to the Diameter Command Code Format (CCF) and other formats, e.g. Grouped Attribute Value Pair (AVP) format defined in [RFC6733]. It is by no means an exhaustive analysis of all Diameter specifications but provides a survey of a few dozen RFCs and 3GPP Technical Specifications to determine what improvements can be made in Diameter specifications.
There are no issues with respect to over the wire communication of Diameter as evidenced by the successful implementation of Diameter applications based upon the specifications surveyed in this document. However, the development and implementation time of Diameter applications can be significantly improved when errors and inconsistencies of the message format as documented in the specifications are minimized or non-existent. An automated tool was developed and used to perform the survey analysis of the technical specifications. The tool would perform automated checking, syntax validation, and language generation and was ran against the various specifications to set a benchmark on the current state and quality of the Diameter specifications. The '.dia' format of a fork of the diafuzzer project (https://github.com/Orange-OpenSource/diafuzzer) was used. It is a simple, deterministic format that provides semantic cross checks of Diameter specifications.
With the goal of automated '.dia' format in mind a survey of various Diameter related RFCs and 3GPP Technical Specifications was executed. During the process several issues, errors, omissions and usage patterns were discovered, and they are outlined in section 4 (Specification Survey) of this document.
Diameter Applications Design Guidelines [RFC7423] does an excellent job of noting common diameter desing use cases but it does not describe how the CCF or related grammers may represent some of these scenarios. To do this the '.dia' format was extended. A few new use cases were also identified that were not covered in [RFC7423].
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
The tool was ran against the following standards specifications for diameter applications:
Enumeration issues have their own section below. General issues include but are not limited to:
Enumerations do not have a specific format in the base specificaton [RFC6733]. Over the wire the labels themselves are not used as the value is transported in integer formats. When received by a Client or Server the value is checked against a list of valid values. The label only appears in displayed information for errors, logging, etc. However, many of the specifications used varying case, spaces and formats such as parenthesis around numbers, tables, numbers then labels, labels then numbers, etc.
An algorithm keying off of the expression 'is of type Enumerated' was used to figure out the text between enumerations. A function was then used to attempt to parse various label patterns, generate a label that may be acceptable to a coding language and capture the value assigned to the label. This yielded partial success. In some cases, especially billing in 3GPP, hand edits were required to fix duplicate labels and formats that were inconsistent with the rest of the document's enumerations.
A few cases even referenced their values as coming from other enums or registries associated with the IETF or other standards organizations. These were removed in some cases due to their size while others were copied from the existing enumeration file in the diafuzzer project if it had already been generated.
Although enumerations are now available in the intermediate '.dia' format, many of the labels will not be valid in specific programming languages. More work is required regarding enumerations to accommodate these situations.
Several Use Cases appeared that where the dia format was extended to capture them.
Refinement (Extension) of Commands and Grouped AVPs. This is a case where the same AVP/Command is referenced, i.e. same code or vendor/code combination but the underlying members of the structure are different. Two variants of this were found:
Note: this is not inheritance. In inheritance the children also inherit the attributes (AVPs) of the parent. In many cases the new definition removed some of the parents AVPs or further limited the occurrence amount of the AVPs.
Refinements can only occur if the Command/Grouped AVP is extensible, i.e. it includes *[AVP] in its definition.
The rationale for this can be shown by example. A value of 2[AVP] would not be considered extensible and its behavior is undefined. Can someone limit the number of AVPs present in a Command/Grouped AVP when that value is less than the total sum of the upper bounds of all member AVPs. For example, if a Grouped AVP permits at most 2 occurrences of AVP member "X" and 2 of AVP member "Y", how/why could/would one limit the Grouped AVP to no more than 3 AVPs?
In the dia format Refinement is captured by adding 'Refines [application id]' at the end of the header/Grouped AVP definition.
Enumeration use cases included definitions that referenced
In the second case the Enumeration was typically removed.
In a few cases Enumerations referenced other enumerations and then, in Notes, limited the values (was a proper subset). The opposite case (a proper superset) never presented itself.
Later specifications assigned Unsigned32 as a value in what appears to be an attempt to avoid registries or provide some pseudo extensibility. The exact purpose is actually unclear.
Errors, inconsistencies and Use Cases that could not be easily fulfilled aside. Format differences hampered our ability to quickly ingest Diameter strcutures from specifications. The following is a list of patterns for just AVP header tables:
Pattern 1: Parses the original table format for AVPs defined in an
IETF spec.
The header for an RFC is
AVP Section | | |SHLD|MUST| |
Attribute Name Code Defined Data Type |MUST| MAY | NOT|NOT |Encr|
Pattern 2: Parses the original table format for AVPs defined in a
3GPP spec
Attribute Name|AVP Code|Section defined|Value Type|Must|May|Should -
not| Must not | May Encr. |
Pattern 3: Parses the original table format for AVPs defined for
freediameter is BUT some rows define a spec boundary
such as the row below the header in this example
|Attribute Name|Code|Section|Data|MUST|MAY|SHLD NOT|MUST NOT|Encr|
Pattern 4: Parses the original table format for AVPs defined in
later IETF specs.
The header for an RFC is
| | AVP | Section | | |MUST |
| Attribute Name | Code | Defined | Data Type |MUST| NOT |
An AVP can be 2-line
Accounting- 483 9.8.7 Enumerated | M | V |
Realtime-Required | | |
Pattern 5: Parses the original table format for AVPs defined in
some IETF specs like RFC 7155.
The header for an RFC is
| | Section | |MUST |
| Attribute Name | Defined |MUST| NOT |
Pattern 6: Parses the original table format for AVPs defined in some
IETF specs that don't define applications..
The header for an RFC is
| | AVP | Section | |
| Attribute Name | Code | Defined | Data Type |
Pattern 7: Parses the original table format for AVPs defined in
an IETF spec.
The header for an RFC is
AVP Section | |MUST|
Attribute Name Code Defined Data Type |MUST| NOT|
Pattern 8: Parses the original table format for AVPs defined in
later IETF specs.
The header for an RFC is
| | AVP | Section | | | MAY |MUST |
| Attribute Name | Code | Defined | Data Type |MUST| | NOT |
An AVP can be 2-line
Accounting- 483 9.8.7 Enumerated | M | V |
Realtime-Required | | |
Pattern 9: Parses the original table format for AVPs defined in a
3GPP spec
Attribute Name|AVP Code|Clause defined|Value Type|Must|May|Should -
not|Must not|
Pattern 10: Parses the original table format for AVPs defined in a
3GPP spec
Attribute Name|AVP Code|Value Type|Must|May|Should not|Must not|
Figure 1: Table Patterns
Even with the patterns present some cleanup for "Notes..." was required to get the headers parsable.
Not all specifications used an import table. In fact some inter-mixed the tables used to note AVPs defined in the spec and those that were referenced. Some columns were removed to ensure that they fit within known formats as well. In other words, there are more formats in the specifications than shown here but with some manipulation they can be reduced to this core set.
For AVP imports a 3-column and 4-column format were common. Further they often had references that needed to be removed (an enhancement is planned to overcome this in the test code.
Multiple application specific AVP tables that occurred in a single spec and unified. This was for research convenience but will hamper the generation of small dictionaries.
Command codes have a long name and three letter acronym typically in a table. However, neither of those were used in the definition. For example, it is quite common to see Re-Authorization-Request and RAR but Re-Auth-Request in the command code definition.
There is no easy, programmatic way to identify an application and relations to command codes or result codes.
The current process for performing validation is to perform the following tasks:
The time spent for each document is the total amount of time from start to finish where the various files were split as described above and the software was then ran. As errors were discovered they were documented and then, as required, repaired. In some cases new software was developed to accommodate new use cases or formats. That was added to the total processing time for the document unless otherwise noted.
For RFC 4004 [RFC4004], processing took approximately 20 minutes. Defect corrections were approximately an hour.
For RFC 4006 bis [I-D.bertz-dime-rfc4006bis], processing took approximately 25 minutes.
For RFC 4950 [RFC4950], processing took approximately 15 minutes. No major issues were found.
For RFC 5447 [RFC5447], processing took approximately 10 minutes. No major issues were found.
For RFC 5777 [RFC5777], processing took approximately 3 hours.
For RFC 5778 [RFC5778], processing took 24 minutes.
For Diameter Load [I-D.ietf-dime-load], processing completed by hand in 10 minutes. IANA allocations have occurred but the document has not left editors queue which means scripts would not work anyway
For RFC 6733 [RFC6733], processing took approximately 15 minutes.
For RFC 7155 [RFC7155], processing took several hours. The original RFC was used to fill in many of the gaps in the AVP table code.
For RFC 7683 [RFC7683], processing took approximately 40 minutes.
For RFC 7944 [RFC7944], processing took approximately 10 minutes. No major issues were found.
For TS 29.214 [TGPP.29.214], processing took approximately 45 minutes.
For TS 29.229 [TGPP.29.229], processing this took 2 hours; 20 minutes.
For TS 29.468 [TGPP.29.468], processing took approximately 60 minutes
For TS 29.345 [TGPP.29.345], processing took approximately 70 minutes
For TS 29.344 [TGPP.29.344], processing took approximately 50 minutes
For TS 29.343 [TGPP.29.343], processing took approximately 10 minutes
For TS 29.338 [TGPP.29.338], processing took approximately 55 minutes
For TS 29.337 [TGPP.29.337], processing took approximately 20 minutes
For TS 29.336 [TGPP.29.336], processing took approximately 9 hours as it was used for testing.
For TS 29.329 [TGPP.29.329], processing took approximately a billion minutes
For TS 32.399 [TGPP.32.299], processing took approximately 9 hours
For TS 29.154 [TGPP.29.154], processing took approximately 10 minutes
For TS 29.215 [TGPP.29.215], processing took approximately 60 minutes
For TS 29.368 [TGPP.29.368], processing took approximately 20 minutes
For TS 29.128 [TGPP.29.128], processing took approximately 30 minutes
For TS 29.173 [TGPP.29.173], processing took approximately 25 minutes
Processing took approximately 43 minutes.
The Modify-Uecontext-Request / Answer command definitions did not match anything in the Command Table.
For TS 29.273 [TGPP.29.273], processing took 60 minutes.
For TS 29.272 [TGPP.29.272], processing took approximately 3 hours. Multiple issues were found but this document was used as a reference for development and not considered in processing efficiencies calculations.
For TS 29.2061 [TGPP.29.061], processing took approximately 2 hours.
For TS 29.212 [TGPP.29.212], processing took approximately 7 hours.
The overall recommendations are as follows:
This section addresses AVPs defined in the specification. The following recommendations are made:
Example One
AVP Section | |MUST |
Attribute Name Code Defined Data Type |MUST| NOT |
-----------------------------------------|----+-----|
AVP-Name 85 9.8.2 Unsigned32 | M | V |
Example Two
| AVP | Section | | |MUST |
Attribute Name | Code | Defined | Data Type |MUST| NOT |
---------------|------+---------+------------+----+-----|
AVP-Name | 85 | 9.8.2 | Unsigned32 | M | V |
Figure 2: Accepted Table Patterns
An open question exists when multiple AVPs tables are present and associated with a specific application within the specification. How the application can be associated to the table is an open question.
Imported or Re-used AVPs MUST be included in the specification. A table MUST be present if AVPs are re-used/imported.
The table MUST include the AVP and Source document columns.
The table MAY include a Comment column.
An M-bit column MAY be present as required.
The table MUST be pipe delimited when in text format.
When a Grouped AVP is refined a Refine keyword is appended to the end of the header. It MUST include an application identifier of the Grouped AVP it refines if that application was not the original specification or 'version' of the Grouped AVP. When the Grouped AVP refines the original definition of the Gropued AVP it SHOULD include the referenced application identifier.
The refined Grouped AVP MUST be included in the AVP Import table and NOT in the defined AVPs table.
Open question, should the vendor and application identifiers of the application that created be in the Grouped AVP header?
When refining a Grouped AVP the following conditions apply:
Open question, can a Grouped AVP have a range limited [AVP] member, e.g. *5[AVP]?
Figure Figure 3 shows an example refinement. In it all but the User-Name AVP are dropped in the new definition.
From TS 29.336
User-Identifier ::= <AVP-Header: 3102, 10415>
[User-Name]
[MSISDN]
[External-Identifier]
[LMSI]
*[AVP]
From TS 29.128
User-Identifier ::= <AVP-Header: 3102, 10415, Refines>
[User-Name]
*[AVP]
Figure 3: Refined AVP from TS 29.128 and TS 29.336
The largest issue with Commands is the inconsistent values between the name, three letter acronym defined in the table and the actual name used in the command definition. Maintaining consistency will resolve this issue.
Like Grouped AVP refinement, a Refine keyword is appended to the end of the header. It MUST include an application identifier of the Command it refines if that application was not the original specification or 'version' of the Command. When the Command refines the original definition of the Command it SHOULD include its application identifier.
When refining a Command the following conditions apply:
Enumeration Value Names MUST adhere to alphanumeric and underscore characters.
Enumeration Value Names MUST not begin with an underscore.
When being defined the format MUST include the label and the value assigned with the label enclosed in parenthesis on a single. Otherwise, this will confusion when the label values end in integers and are close to the numeric value. For example, 'speed_10 10' is okay, 'speed_1010' is a error. This can be avoided by requiring the enclosure of the values in parenthesis, e.g. 'speed_10 (10)' and 'speed_10(10)'. The last example may not be as readable as desired but it can be understood.
This section discusses ways by which further clarity can be defined in a specification and automated validation can occur for a diameter application.
Following the recommendations in the previous section will reduce errors but there are still many pieces of information that cannot be programmatically validated. This includes the following:
The following formats show an example of how information could be added to an Appendix to close these gaps.
1: AppFoo ::= <Diameter Application: 10415 101010>
2: Command1-Name-Request C1R
3: Command1-Name-Answer C1A
4:
5: Result-Codes ::= <Diameter Result-Codes: 101010>
6: NEW_RESULT (4999)
7: IMPORTED_RESULT IMPORT (4010)
Figure 4: Example Application and Result Code Formats
GAP 1 is closed in line 1. GAP 3 is closed in lines 1 through 3 while GAP 4 is closed by lines 5 through 7.
GAP 2 can be closed by using a common discernable Table Name format, e.g. AppFoo defined AVPs. In this case the Application Name can be looked up and associated to the defined AVP table.
Gap 5 can be partially closed by following a pattern similar to Result-Codes but this does not resolve all uses cases.
Result-Codes ::= <Diameter Enumeration: 123, 45678>
Label_1 (0)
LABEL_Two (2)
Figure 5: Example Enumeration AVP
Further work is required to comprehensively cover all Enumeration Use Cases.
This document is informational and provides some guidance on issues related to formatting and possible extensions of the Diameter CCF to improve understanding and code generation capabilities. It has no impact to the Security of Diameter or Diameter applications.
| [RFC2119] | Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997. |
| [RFC6733] | Fajardo, V., Arkko, J., Loughney, J. and G. Zorn, "Diameter Base Protocol", RFC 6733, DOI 10.17487/RFC6733, October 2012. |