7.1 Introduction

This chapter discusses an advanced topic of interest to those who have worked in standardization, have written Diameter implementations, or who have used Diameter to solve specific business problems. As discussed throughout this book, standardization efforts in Diameter have led to a number of specifications that cover a wide range of use cases. Still, you may have reached a point where the existing functionality does not cover your use case or it does not completely fulfill your requirements. You may have come to the conclusion that you need to extend the Diameter protocol. You are most likely asking yourself the following question: “Why cannot I extend the protocol in any way I want?”

To answer that question it is useful to provide some background information about the work in the Internet Engineering Task Force Diameter Maintenance and Extensions (DIME) working group. The working group suggests reusing as much as possible for the following reasons:

• The time to finalize a specification writing effort is significantly reduced since prior work can be taken into account. While it appears that writing specifications is fairly easy it still requires several months to years. The 80/20 rule applies: 80% of the time is spent on 20% of the specification.
• Reuse will lead to a smaller implementation effort. You will be able to make use of existing libraries (such as parsers). This does, however, require that your Diameter stack is written in modular fashion.
• The amount of testing (such as penetration testing) is significantly reduced since extensive testing has been conducted for existing modules and functionality already.

The most important reason, however, is to avoid interoperability problems, which was the main motivation for standardizing the Diameter protocol in the IETF. What does this mean? Imagine that you have Diameter deployed in your network (most likely involving products from different vendors) and, after some time, you would like to introduce another Diameter application into your network. Without following the extensibility guidelines outlined in the Diameter specification, problems may occur, such as the incorrect processing of messages. Imagine the following scenario where two companies independently develop a Diameter application and select the same Diameter Application‐Id without registering these Application‐Ids via the Internet Assigned Numbers Authority (IANA) registry. As a consequence, Diameter proxies and Diameter servers will be confused when they receive messages where they recognize the Application‐Id but not the message's content. Even worse are cases where Diameter applications using the same Application‐Id differ slightly in their functionality. With errors occurring only occasionally, these conditions will be difficult to diagnose.

Since you do not want these unnecessary problems, we give you the necessary background knowledge about Diameter extensibility.

7.2 Registration Policies

Before going into details of extending Diameter, we need to discuss the registration policies for extensions. At the end of a protocol design, you will most likely have new functionality that needs to be registered with IANA. The Diameter IANA registry contains pointers to AVPs, command codes, and Diameter applications. It not only collects a list of specifications developed in the IETF but also gathers specifications developed by other standards development organizations (SDOs). As such, it provides a wealth of information for supporting interoperability. The IANA registry webpage for Diameter can be found at http://www.iana.org/assignments/aaa‐parameters/aaa‐parameters.xhtml. Table 7.1 shows a snapshot of the Diameter Application‐Id registry maintained by IANA.

In order to get your extension added to the IANA registry, certain requirements, often in terms of the amount of review, must be met. These requirements are called registration policies. The IETF has published a document listing a number of possible registration policies (RFC 5226 [1]), and for the purpose of this chapter the relevant policies are:

• Standards Action: Values are only added to the registry with IETF Standards Track RFCs.
• IETF Review: Values are only added to the registry through RFCs that have been shepherded through the Internet Engineering Steering Group (IESG) as Area Director‐Sponsored or IETF working group documents.
• Specification Required: Values and their meanings must be documented in a permanent and readily available public specification, in sufficient detail so that interoperability between independent implementations is possible. Specification Required also implies use of a Designated Expert, who will review the public specification and evaluate whether it is sufficiently clear to allow interoperable implementations.

Each section of the Diameter IANA registry has a specific registration policy associated with it. This policy dictates what requirements an extension has to meet in order for the requested code point to be added. This might give the impression that different code point numbers are “more valuable” than others since the difficulty for obtaining them varies. However, this segmentation of the available code space only aims to ensure that the space is not exhausted quickly while maintaining some flexibility. As long as a code point has been obtained for the respective Diameter extension, it does not matter from which range it came.

The amount of work needed to register a new Diameter extension varies with the policy. Standards Action, for example, typically requires more work than an IETF Review. More extensive review is useful when the available code space is close to exhaustion or if the extension has significant impact on other vendors. Note that registering your extension with IANA does not mean that you have to publish an RFC. You do not even have to publish an IETF specification at all. Various examples outlined in this book illustrate how standards development organizations and vendors have developed Diameter extensions and registered them with IANA. See, for example, Application‐Id 16777251, which is assigned to the 3GPP S6a interface.

Sometimes, however, vendors do not want to make their specifications available nor are they willing to make any changes. In such a case, it is more useful to follow the path of vendor‐specific extensions. Section 7.8 discusses vendor‐specific extensions in detail and provides guidance for the interaction with IANA to make a smooth and quick registration.

7.3 Overview of Extension Strategies

To make it easier to add new features incrementally to the installed base, Section 1.3 of RFC 6733 [2] outlines a number of extension strategies. The Diameter design guidelines document, a companion document [3], covers the topic of extensibility in even greater detail.

Although reuse should be your guiding principle, we would like to point out that it should not be pushed too far. When the semantics of existing functionality differ from the envisioned new feature then it is better to define a new extension (even if it is largely a copy‐and‐paste of an already existing specification text).

The Diameter extensions are a direct consequence of the Diameter layers, as shown in Figure 7.1. The outermost layer in Diameter is the application concept, which encapsulates everything else. The next layer inside is the command. Finally, the innermost layer is the AVP. We start our description with the least intrusive and simplest extension, the AVP. Next, the extensions of commands are explained followed by applications.

An important design decision for extending Diameter is whether Diameter nodes are required to understand the new functionality or whether the newly defined features are purely optional. Whenever it is mandatory for Diameter clients, Diameter agents (except for relays and redirect agents) or Diameter servers to understand new functionality, a new Diameter application has to be defined.

7.4 Extending Attribute–Value Pairs

       From-Spec ::= < AVP Header: 515 >            * [ IP-Address ]            * [ IP-Address-Range ]            * [ IP-Address-Mask ]            * [ MAC-Address ]            * [ MAC-Address-Mask]            * [ EUI64-Address ]            * [ EUI64-Address-Mask]            * [ Port ]            * [ Port-Range ]             [ Negated ]             [ Use-Assigned-Address ]            * [ AVP ]  

7.5 Extending Commands

Most Diameter commands are specified so that they can to be extended. Multiple ways for extending commands are possible, namely:

• allocating new Command flags
• adding AVPs
• creating new Commands.

     NAT-Internal-Address ::= < AVP Header: 599 >                 [ Framed-IP-Address ]                 [ Framed-IPv6-Prefix ]                 [ Port]                * [ AVP ]  

            * [ Route-Record ] 

7.6 Creating New Applications

What is the line between just extending an AVP or command and having to define a new Diameter application? When your Diameter extension does at least one of the following, then you have created a new application:

• Adds an AVP with the “M” bit in the MUST column or in the MAY column to an existing command or application.
• Adds a new command to an existing application.
• Modifies an existing command such that a new command code has to be registered. Note that removing the Error‐Message AVP from a command's CCF does not count as a modification since the Error‐Message AVP is for human consumption only and is not parsed by Diameter nodes.
• Deletes a command from an existing application.
• Modifies the meaning or semantics of an existing application's AVP Flags.
• Adds a new flag bit.

If your extension just adds optional AVPs with the “M” bit cleared to a command that has a CCF definition containing * [ AVP ] then you do not need to define a new application.

7.7 Lessons Learned

From our own experience co‐authoring Diameter specifications we would like to offer you ten lessons for your work on Diameter specifications.

1. 1. UNDERSTAND THE BASIC DIAMETER CONCEPTS

   The most important starting point for your work on Diameter is to understand it first before writing your own specification. While this suggestion may seem obvious, we recognize that some people who write technical specifications do it as a learning‐by‐doing exercise before understanding the Diameter base specification. You will save yourself and others a lot of time by doing your homework first. If you have read the earlier sections of the book you are familiar with the concepts already and you should be doing fine.

2. 2. YOU DON'T NEED TO USE THE CCF SYNTAX

   When you read the IETF Diameter specifications, you will notice that many of them define Diameter AVPs and Diameter commands using the Command Code Format (CCF) syntax. We provide an overview of the syntax in Section 2.6.1 and the formal definition of the syntax is given in the base specification [2]. It is, however, not a requirement to use CCF in your specification if you do not feel comfortable with it. In fact, the formal notation of CCF does not capture the nuances of protocol specification. For example, the specification text, and not the CCF, provides the information on when to use or not to use optional AVPs. The CCF syntax by itself is often insufficient to express the syntax of the commands. A good description can be better than correct CCF. If you feel uncomfortable writing CCF or if you readers are likely unfamiliar with it, you don't need to use it.

3. 3. OFFER EXAMPLES

   Many readers of specifications will look at examples to better understand your specification. Offering example message flows and example AVP instantiations will help them. Most likely the examples will also help you to verify whether every feature has indeed been included in the specification. Make sure that your examples are practical and realistic, which will often require some information about the network setup. Also, make sure your examples are correct. Readers have been known to follow examples more closely than specification text.

4. 4. DON'T FORGET THE ERROR CASES

   Your initial version of a specification is most likely very simple. Once additional use cases and requirements from stakeholders are included, the complexity will likely increase. In many cases all attention is focused on the positive use cases, which are the most likely ones. However, it is important to explore error situations as well to ensure that your protocol behaves properly when problems occur. Even if the error is not automatically recoverable, make sure that useful human‐readable error messages are returned so that developers are able to diagnose the problem quickly. In many cases, covering error cases requires you to have implementation experience with the specification you are developing. If you can create an implementation prototype, it will provide valuable feedback to the specification.

5. 5. REUSE AS MUCH AS POSSIBLE

   When you start writing your first specification it is often difficult to get started. You might be wondering how to translate your idea to an interoperable, technical specification. We recommend reusing an existing specification and letting it serve as a template. Of course, you will have to find a suitable starting point but Chapter 6 will walk you through a number of important specifications. It is common practice to reuse text from available RFCs.

6. 6. REGISTER YOUR EXTENSION WITH IANA

   Once you are finished with your Diameter protocol extension defining new AVPs, new Command Codes, or Diameter applications, register them with IANA. In the past various specification authors were reluctant to standardize Diameter applications since the allocation policy was rather strict. However, the registration policy was changed with the publication of RFC 5719 [9], and the policy was later incorporated into RFC 6733. Consequently, it became much easier to register AVPs, command codes, and Diameter applications. The benefit of registering extensions is that other vendors will know about the allocated code point and interoperability problems between two independent implementations that use the same code point will be avoided.

7. 7. NOT EVERY FEATURE NEEDS TO BE REGISTERED WITH IANA

   Despite the advice given in item 6, some vendors may be reluctant to register their Diameter protocol extension. Still, it makes a lot of sense to distinguish proprietary functionality from different vendors, particularly when telecommunication operators use Diameter in a multi‐vendor environment. The Diameter base specification allows vendor‐specific extensions, permitting vendors to allocate code points for their Diameter extensions without having to register them with IANA and without having to publish their specifications. Section 7.8 explains how vendor‐specific extensions can be specified.

8. 8. THINK ABOUT EXTENSIBILITY IN YOUR OWN APPLICATIONS

   You may think that you are covering all the functionality that you need when designing your Diameter extension. However, if your protocol design will be used widely, then new uses of your extension will likely emerge, and your extension may need to be extended further. As such, you will have to consider adding extension points to your application in the same way as you may have used them yourself. At a minimum, you should you consider allowing AVPs to be extended (by using data types that allow new values to be added and by the use of grouped AVPs with extension points). Additionally, it is highly recommended to also offer extension points with command codes. Designing for future use is, however, an art that requires the specification author to have a vision about the future use of the specification that goes beyond the requirements list derived from its current use cases.

9. 9. DUAL STRATEGY: DEFINING A DIAMETER APPLICATION AND AVPS

   When developing a new extension, it can be difficult to decide whether a new application should be defined or whether an existing application should be extended via a set of optional AVPs. In fact, the book authors have encountered this situation several times, and have concluded that sometimes it is better to define both. For example, RFC 5866 [10] defines a Diameter quality of service (QoS) application (Section 6.4), but RFC 5624 [11] provides QoS parameters that can be incorporated into other applications, like the Diameter Extensible Authentication Protocol (EAP) application [12]. The same approach has also been applied to Diameter Mobile IPv6, as described in RFC 5447 [13] and RFC 5778 [14]. RFC 5778 defines two Diameter applications, one for use with the custom Mobile IPv6 security protocol and the other for use with the Internet Key Exchange protocol. RFC 5447, on the other hand, only defines AVPs, which can be used with existing Diameter applications, such as Diameter EAP [12] and the Diameter Network Access Server Application [7]. While the design of the two specifications is quite different, various AVPs are shared by the two specifications.

10. 10. TEST FOR EXTENSIBILITY

    Specifying extensibility in a specification is clearly important. However, it is not enough. Interoperability testing is even more important to ensure that the implementation does indeed conform to the specification. Interoperability testing ensures that functionality is verified. Testing how the Diameter protocol stack reacts when confronted with unknown extensions is often forgotten. This has, in other protocols (such as TLS), caused problems in real‐world deployments.

7.8 Vendor‐specific Extensions

This section describes vendor‐specific extensions and the steps to take to use them. Vendor‐specific extension makes use of Enterprise Numbers (also known as Structure of Management Information (SMI) Network Management Private Enterprise Codes). These Enterprise Numbers are allocated by IANA and be found at http://www.iana.org/assignments/enterprise‐numbers.

It is likely that your company is already on this list since this registry is used not only for Diameter but also for a number of other protocols (such as network management protocols). If your company does not yet have an Enterprise Number then one may be requested via the online form available at http://pen.iana.org/pen/PenApplication.page.

As described earlier in this chapter, not all Diameter extensions, for example AVP and Command flags, are suitable for vendor‐specific extensions. The process for using vendor‐specific AVPs, command codes, and Diameter applications is slightly different and described in the subsequent sub‐sections.

7.9 Prototyping with freeDiameter

A core belief of the IETF is “rough consensus and running code”. This is to highlight the importance of testing new ideas with real running code. freeDiameter has been created in particular to allow implementers to test their new ideas/applications relatively easily, without the need to worry about the base protocol implementation. The test_app.fdx extension can serve as a model of client‐server implementation to build upon, or for those who are not familiar with C language, the dbg_interactive.fdx extension can be a convenient tool to getting started quickly. Please refer to Appendix B for detailed information on these extensions.

References

1. 1 T. Narten and H. Alvestrand. Guidelines for Writing an IANA Considerations Section in RFCs. RFC 5226, Internet Engineering Task Force, May 2008.
2. 2 V. Fajardo, J. Arkko, J. Loughney, and G. Zorn. Diameter Base Protocol. RFC 6733, Internet Engineering Task Force, Oct. 2012.
3. 3 L. Morand, V. Fajardo, and H. Tschofenig. Diameter Applications Design Guidelines. RFC 7423, Internet Engineering Task Force, Nov. 2014.
4. 4 J. Korhonen, H. Tschofenig, M. Arumaithurai, M. Jones, and A. Lior. Traffic Classification and Quality of Service (QoS) Attributes for Diameter. RFC 5777, Internet Engineering Task Force, Feb. 2010.
5. 5 L. Bertz, S. Manning, and B. Hirschman. Diameter Congestion and Filter Attributes. RFC 7660, Internet Engineering Task Force, Oct. 2015.
6. 6 F. Brockners, S. Bhandari, V. Singh, and V. Fajardo. Diameter Network Address and Port Translation Control Application. RFC 6736, Internet Engineering Task Force, Oct. 2012.
7. 7 G. Zorn. Diameter Network Access Server Application. RFC 7155, Internet Engineering Task Force, Apr. 2014.
8. 8 P. Congdon, M. Sanchez, and B. Aboba. RADIUS Attributes for Virtual LAN and Priority Support. RFC 4675, Internet Engineering Task Force, Sept. 2006.
9. 9 D. Romascanu and H. Tschofenig. Updated IANA Considerations for Diameter Command Code Allocations. RFC 5719, Internet Engineering Task Force, Jan. 2010.
10. 10 D. Sun, P. McCann, H. Tschofenig, T. Tsou, A. Doria, and G. Zorn. Diameter Quality‐of‐Service Application. RFC 5866, Internet Engineering Task Force, May 2010.
11. 11 J. Korhonen, H. Tschofenig, and E. Davies. Quality of Service Parameters for Usage with Diameter. RFC 5624, Internet Engineering Task Force, Aug. 2009.
12. 12 P. Eronen, T. Hiller, and G. Zorn. Diameter Extensible Authentication Protocol (EAP) Application. RFC 4072, Internet Engineering Task Force, Aug. 2005.
13. 13 J. Korhonen, J. Bournelle, H. Tschofenig, C. Perkins, and K. Chowdhury. Diameter Mobile IPv6: Support for Network Access Server to Diameter Server Interaction. RFC 5447, Internet Engineering Task Force, Feb. 2009.
14. 14 J. Korhonen, H. Tschofenig, J. Bournelle, G. Giaretta, and M. Nakhjiri. Diameter Mobile IPv6: Support for Home Agent to Diameter Server Interaction. RFC 5778, Internet Engineering Task Force, Feb. 2010.