RFC 7423

Diameter Applications Design Guidelines

📅 published November 2014, from ietf

Title Block 🎀

Okay bestie, let's get the facts straight first! 💖 This is RFC 7423, a Best Current Practice (BCP 193) 👑 called Diameter Applications Design Guidelines, published in November 2014 by the Internet Engineering Task Force (IETF). Its ISSN is 2070-1721.

The authors are L. Morand, Ed. (Orange Labs), V. Fajardo (Fluke Networks), and H. Tschofenig, who has no affiliation listed. The title block doesn't list anything it obsoletes or updates. 🦋

Abstract 💅

The Diameter base protocol gives you tools to extend it, so you can make brand-new Diameter applications or tweak the ones that already exist. 🌈 This doc is a companion to the base protocol, and it explains and clarifies the rules for extending Diameter. It also gives guidelines for application designers who want to reuse or define Diameter applications, or make generic Diameter extensions. ✨

Status of This Memo 🧚

This memo documents an Internet Best Current Practice. 🌸

This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It went through public review and was approved for publication by the Internet Engineering Steering Group (IESG). More info on BCPs is in Section 2 of RFC 5741. 💜

For the latest status of this document, any errata, and how to send feedback, check http://www.rfc-editor.org/info/rfc7423. 🍓

Copyright (c) 2014 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 (http://trustee.ietf.org/license-info), as in effect on the publication date. Please read these carefully, because they spell out your rights and restrictions for this document. Code Components pulled out of this document need to include Simplified BSD License text, as described in Section 4.e of the Trust Legal Provisions, and they come with no 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 people who control the copyright in some of that material may not have given the IETF Trust permission to allow modifications outside the IETF Standards Process. Without an adequate license from those copyright holders, 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. The one exceptions are formatting it for publication as an RFC or translating it into languages other than English. 🌷

Table of Contents 📚

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   4
   2.  Terminology . . . . . . . . . . . . . . . . . . . . . . . . .   5
   3.  Overview  . . . . . . . . . . . . . . . . . . . . . . . . . .   5
   4.  Reusing Existing Diameter Applications  . . . . . . . . . . .   6
     4.1.  Adding a New Command  . . . . . . . . . . . . . . . . . .   7
     4.2.  Deleting an Existing Command  . . . . . . . . . . . . . .   8
     4.3.  Reusing Existing Commands . . . . . . . . . . . . . . . .   8
       4.3.1.  Adding AVPs to a Command  . . . . . . . . . . . . . .   8
       4.3.2.  Deleting AVPs from a Command  . . . . . . . . . . . .  10
       4.3.3.  Changing the Flag Settings of AVP in Existing
               Commands  . . . . . . . . . . . . . . . . . . . . . .  11
     4.4.  Reusing Existing AVPs . . . . . . . . . . . . . . . . . .  11
       4.4.1.  Setting of the AVP Flags  . . . . . . . . . . . . . .  11
       4.4.2.  Reuse of AVP of Type Enumerated . . . . . . . . . . .  12
   5.  Defining New Diameter Applications  . . . . . . . . . . . . .  12
     5.1.  Introduction  . . . . . . . . . . . . . . . . . . . . . .  12
     5.2.  Defining New Commands . . . . . . . . . . . . . . . . . .  12
     5.3.  Use of Application Id in a Message  . . . . . . . . . . .  13
     5.4.  Application-Specific Session State Machines . . . . . . .  14
     5.5.  Session-Id AVP and Session Management . . . . . . . . . .  14
     5.6.  Use of Enumerated Type AVPs . . . . . . . . . . . . . . .  15
     5.7.  Application-Specific Message Routing  . . . . . . . . . .  17
     5.8.  Translation Agents  . . . . . . . . . . . . . . . . . . .  18
     5.9.  End-to-End Application Capabilities Exchange  . . . . . .  18
     5.10. Diameter Accounting Support . . . . . . . . . . . . . . .  19
     5.11. Diameter Security Mechanisms  . . . . . . . . . . . . . .  21
   6.  Defining Generic Diameter Extensions  . . . . . . . . . . . .  21
   7.  Guidelines for Registrations of Diameter Values . . . . . . .  23
   8.  Security Considerations . . . . . . . . . . . . . . . . . . .  25
   9.  References  . . . . . . . . . . . . . . . . . . . . . . . . .  25
     9.1.  Normative References  . . . . . . . . . . . . . . . . . .  25
     9.2.  Informative References  . . . . . . . . . . . . . . . . .  25
   Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
   Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . .  28
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  29

1. Introduction 🌟

Okay so the Diameter base protocol [RFC6733] is built to give you an Authentication, Authorization, and Accounting (AAA) framework for apps like network access or IP mobility, both at home and while roaming. ✈️ It lets Diameter peers swap messages that carry data in Attribute-Value Pairs (AVPs). 💅

The base protocol also gives you ways to extend Diameter (see Section 1.3 of [RFC6733]) so it can do new stuff. In this doc, extending Diameter means one of these four things: 🦋

  1. Adding new functionality to an existing Diameter application without defining a new application.
  2. Adding new functionality to an existing Diameter application in a way that requires defining a new application.
  3. Defining a whole new Diameter application to offer functionality that existing applications don't support.
  4. Defining new generic functionality that can be reused across different applications.

All of these are design decisions, and you can do them by any mix of reusing existing commands, defining new ones, reusing AVPs, or defining new AVPs or AVP values. 🎀 But designers don't get total freedom! [RFC6733] has a bunch of rules that limit when an extension needs a new Diameter application identifier or a new command code value. 🙈 So this doc is here to:

  • Clarify the Diameter extensibility rules from the Diameter base protocol. 📖
  • Talk about design choices and give guidelines for when you're defining new applications. 🧭
  • Lay out the trade-off choices. ⚖️

2. Terminology 🧠

This document reuses the terminology defined in [RFC6733]. On top of that, this application uses these terms and acronyms: 🌈

  • Application: An extension of the Diameter base protocol [RFC6733] through the addition of new commands or AVPs. Each application is uniquely identified by an IANA-allocated application identifier value. 👑
  • Command: A Diameter request or answer carrying AVPs between Diameter endpoints. Each command is uniquely identified by an IANA-allocated Command Code value and is described for an application by a Command Code Format (CCF). 💜

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 [RFC2119]. ✨

3. Overview 🗺️

As designed, the Diameter base protocol [RFC6733] can be seen as a two-layer protocol. 🍰 The lower layer mostly handles connections between neighboring peers and message routing. The upper layer is where the Diameter applications live. 🏠 This setup matches a Diameter node that has an application layer and a peer-to-peer delivery layer. The Diameter base protocol doc defines the architecture and behavior of the message delivery layer, then gives you the framework for designing Diameter applications on the application layer. That framework includes definitions of application sessions and accounting support (see Sections 8 and 9 of [RFC6733]). So in this doc, a Diameter node is one instance of a Diameter message delivery layer plus one or more Diameter applications using it. 🫧

The Diameter base protocol is built to be extensible, and the principles are in Section 1.3 of [RFC6733]. Basically, Diameter can be extended by: 🌷

  1. Defining new AVP values
  2. Creating new AVPs
  3. Creating new commands
  4. Creating new applications

Here's the big guiding principle: application designers SHOULD follow this recommendation: "try to reuse as much as possible!" 🔁 It cuts down the time it takes to finish the spec, means less implementation effort, and reduces the need for testing. Honestly, avoiding duplicate effort whenever you can is just smart. 🧠✨

Reuse isn't the right move, though, when the existing functionality doesn't fit the new requirement, or when reusing it would cause ambiguity. 🚫

Extending existing applications can be sorted into two groups: 🌸

Minor Extension: This enhances the functional scope of an existing application by adding optional features to support it. There's no backward-compatibility issue with the existing application. 🌼

A typical example is defining a new optional AVP for use in an existing command. Diameter implementations that support the existing application but not the new AVP will just ignore it, with no consequences for Diameter message handling, as described in [RFC6733]. The standardization effort is pretty small. 💖

Major Extension: This enhances an application in a way that requires defining a new Diameter application. It causes a backward-compatibility issue with existing implementations that support the application. 😬

Typical examples are creating a new command to provide functionality that existing applications don't support, or defining a new AVP to be carried in an existing command with the M-bit set in the AVP flags (see Section 4.1 of [RFC6733] for the definition of "M-bit"). For this kind of extension, a big specification effort is required, and a careful approach is recommended. 🚨

4. Reusing Existing Diameter Applications 🔄

An existing application might need an upgrade to meet new requirements, and these changes can happen at the command level, the AVP level, or both. 🧩 The following sections describe the possible modifications you can make to existing applications and their related impact. 💅

4.1. Adding a New Command ✨

okay so adding a new command to an existing application counts as a major extension 💅 which means you need to define a brand new Diameter application, as Section 1.3.4 of [RFC6733] spells out. why?? because a Diameter node that hasn't been upgraded to support the new command(s) inside that (existing) application would reject any unknown command with the protocol error DIAMETER_COMMAND_UNSUPPORTED, and the transaction would just fail 💀. the new application makes sure nodes only ever get commands for applications they actually support 🫶

adding a new command can mean either defining a totally new command, or importing the command's Command Code Format (CCF) syntax from another application, so the new application inherits some or all of the functionality of the application the command came from 🦋. with a brand new command, making a new application is pretty straightforward, since that usually happens when you're adding functionality that doesn't exist yet. with an imported command, it depends on whether importing it into a new application is more suitable than just using the existing application as it is, alongside any other application ✨

here's an example 🎀 the Diameter Extensible Authentication Protocol (EAP) application [RFC4072] and the Diameter Network Access Server application [RFC7155]. when network access authentication using EAP is needed, the Diameter EAP commands (Diameter-EAP-Request/Diameter-EAP-Answer) are used; otherwise, the Diameter Network Access Server application is used. and when the Diameter EAP application is in use, the accounting exchanges defined in the Diameter Network Access Server may be used 🧚

ngl it's hard to make one hard rule for this, so you do a case-by-case study of each application requirement. before adding or importing a command, designers should consider the following:

  • Can the new functionality be fulfilled by creating a new command independent from any existing command? In this case, the resulting new application and the existing application can work independent of, but cooperating with, each other. 🌸
  • Can the existing command be reused without major extensions and, therefore, without the need for the definition of a new application, e.g., new functionality introduced by the creation of new optional AVPs? 🍓

it's important to note that importing commands too liberally could result in a monolithic and hard-to-manage application supporting too many different features 😭

4.2. Deleting an Existing Command 🙈

this one isn't typical, but removing a command from an application needs a new Diameter application to be defined, and then it's considered a major extension too. the reason is that receiving the deleted command would systematically result in a protocol error (i.e., DIAMETER_COMMAND_UNSUPPORTED).

it's really unusual to delete an existing command from an application just for the sake of deleting it or the functionality it represents. the exception might be if the goal is to create a newer variance of the same application that's somehow simpler than the application initially specified 💜

4.3. Reusing Existing Commands 🌈

this section covers the rules for adding and/or deleting AVPs from an existing command of an existing application. the cases described here may not necessarily lead to the creation of new applications 👑

historically speaking, [RFC3588] gave a strong recommendation to reuse existing commands, so that code values for vendor-specific commands wouldn't run out super fast. then [RFC6733] relaxed the allocation policy and enlarged the range of available code values for vendor-specific applications. reuse of existing commands is still RECOMMENDED, but protocol designers can consider defining a new command when it provides a solution that's more suitable than the twisting of an existing command's use and applications 🔥

4.3.1. Adding AVPs to a Command 🦋

based on the rules in [RFC6733], AVPs that get added to an existing command can be categorized as either:

  • Mandatory (to understand) AVPs. As defined in [RFC6733], these are AVPs with the M-bit flag set in this command, which means the Diameter node receiving them is required to understand not only their values but also their semantics. failing to do so will cause a message handling error: either an error message with the result-code set to DIAMETER_AVP_UNSUPPORTED if the AVP is not understood in a request, or an application-specific error handling if the given AVP is in an answer. 😤
  • Optional (to understand) AVPs. As defined in [RFC6733], these are AVPs with the M-bit flag cleared in this command. a Diameter node receiving these AVPs can simply ignore them if it doesn't support them. 🫧

it's important to note that these definitions are independent of whether the AVPs are required or optional in the command as specified by the command's CCF syntax [RFC6733].

NOTE: As stated in [RFC6733], the M-bit setting for a given AVP is relevant to an application and each command within that application that includes the AVP. ⚠️

the rules are strict when the AVPs being added to an existing command are mandatory to understand, i.e., they have the M-bit set. a mandatory AVP MUST NOT be added to an existing command without defining a new Diameter application, as stated in [RFC6733]. this falls into the "Major Extensions" category 🚫 even though the rule is crystal clear, ambiguity still pops up when you're deciding whether a new AVP should be mandatory to begin with. designers should consider the following questions when deciding about the M-bit for a new AVP:

  • Would it be required for the receiving side to be able to process and understand the AVP and its content?
  • Would the new AVPs change the state machine of the application?
  • Would the presence of the new AVP lead to a different number of round trips, effectively changing the state machine of the application?
  • Would the new AVP be used to differentiate between old and new variances of the same application whereby the two variances are not backward compatible?
  • Would the new AVP have duality in meaning, i.e., be used to carry application-related information as well as to indicate that the message is for a new application?

if the answer to at least one of the questions is "yes", then the M-bit MUST be set for the new AVP, and a new Diameter application MUST be defined. this list of questions is non-exhaustive, and other criteria MAY be taken into account in the decision process 💖

if designers are instead contemplating the use of optional AVPs, i.e., with the M-bit cleared, there are still pitfalls that will cause interoperability problems, so they must be avoided 🥺 some examples of these pitfalls are:

  • 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. 🌀
  • Optional AVPs with dual purpose, i.e., to carry application data as well as to indicate support for one or more features. this has a tendency to introduce interpretation issues. 🎭
  • Adding one or more optional AVPs and indicating (usually within descriptive text for the command) that at least one of them has to be understood by the receiver of the command. this would be equivalent to adding a mandatory AVP, i.e., an AVP with the M-bit set, to the command. 🚨

4.3.2. Deleting AVPs from a Command 🗑️

application designers may want to reuse an existing command, but some of the AVPs present in the command's CCF syntax specification may be irrelevant for the functionality they want this command to support. so it may be tempting to delete those AVPs from the command 👀

the impact of deleting an AVP from a command depends on its Command Code format specification and M-bit setting:

  • Case 1: Deleting an AVP that is indicated as a required AVP (noted as {AVP}) in the command's CCF syntax specification (regardless of the M-bit setting).

In this case, a new Command Code, and subsequently a new Diameter application, MUST be specified. 🚫

  • Case 2: Deleting an AVP, which has the M-bit set, and is indicated as an optional AVP (noted as [AVP] in the command CCF) in the command's CCF syntax specification.

In this case, no new Command Code has to be specified, but the definition of a new Diameter application is REQUIRED. 📛

  • Case 3: Deleting an AVP, which has the M-bit cleared, and is indicated as [AVP] in the command's CCF syntax specification.

In this case, the AVP can be deleted without consequences. ✅

application designers SHOULD attempt to reuse the command's CCF syntax specification without modification, and simply ignore (but not delete) any optional AVPs that won't be used. this is to maintain compatibility with existing applications that won't know about the new functionality, as well as to maintain the integrity of existing dictionaries 🧸

4.3.3. Changing the Flag Settings of AVP in Existing Commands 🎀

although unusual, implementors may want to change the setting of the AVP flags for an AVP used in a command 🤔

into an existing command, an AVP that was initially defined as a mandatory AVP to understand, i.e., an AVP with the M-bit flag set in the command, MAY be safely turned into an optional AVP, i.e., with the M-bit cleared. any node supporting the existing application will still understand the AVP, whatever the setting of the M-bit. on the contrary, an AVP initially defined as an optional AVP to understand, i.e., an AVP with the M-bit flag cleared in the command, MUST NOT be changed into a mandatory AVP with the M-bit flag set without defining a new Diameter application. setting the M-bit for an AVP that was defined as an optional AVP is equivalent to adding a new mandatory AVP to an existing command, and the rules given in Section 4.3.1 apply 🙅‍♀️

all other AVP flags (V-bit, P-bit, reserved bits) MUST remain unchanged. 🔒

4.4. Reusing Existing AVPs 🫶

this section covers the rules for reusing existing AVPs, whether you're reusing an existing command or defining a new command in a new application 💫

4.4.1. Setting of the AVP Flags ✨

when reusing existing AVPs in a new application, application designers MUST specify the setting of the M-bit flag for the new Diameter application and, if necessary, for every command of the application that can carry these AVPs. in general, for AVPs defined outside of the Diameter base protocol, the characteristics of an AVP are tied to its role within a given application and the commands used in this application 🧠

all other AVP flags (V-bit, P-bit, reserved bits) MUST remain unchanged. 💅

4.4.2. Reuse of AVP of Type Enumerated 💅

okay bestie, so when you reuse an AVP of type Enumerated in a command for a new application, it is RECOMMENDED to avoid messing with the set of valid values defined for that AVP 🙈 Changing the set means either adding a value or deprecating a value that was defined originally for the AVP. ngl this is a big deal because every application that uses this AVP gets affected, not just the one defining it 😭 So if a peer sends a value that some of the nodes between the client and the server don't recognize, that gets an error response with the Result-Code AVP set to DIAMETER_INVALID_AVP_VALUE. Yikes 💀 If the full range of values in this Enumerated AVP doesn't fit the new application, it is RECOMMENDED that you define a new AVP instead, so you don't cause backward-compatibility problems for existing implementations 🫶

5. Defining New Diameter Applications ✨

5.1. Introduction

this section is about the situation where a new application needs stuff that existing applications just can't give it. Like, it needs brand-new commands, AVPs, and/or AVP values 🦋 Usually there's zero debate about making a new application in this case. Think of the interfaces in the IP Multimedia Subsystem of 3GPP, like Cx/Dx ([TS29.228] and [TS29.229]), Sh ([TS29.328] and [TS29.329]), and so on 🌸

Application designers SHOULD try to import existing AVPs and AVP values for any newly defined commands 💖 And if accounting is involved, the models in Section 5.10 SHOULD also be considered 📊

There are more considerations in the sections below 👑

5.2. Defining New Commands

the big general rule here: commands SHOULD NOT be defined from scratch 🙅‍♀️ Instead, it is RECOMMENDED to reuse an existing command that does something similar and start from there. Reusing code means less implementation work and less testing, which is literally the dream ✨

Also, the new command's CCF syntax specification SHOULD be carefully defined, with applicability and extensibility of the application in mind 🧚 If most of the AVPs in the command are fixed or required, it gets hard to reuse that command, and therefore that application, in a slightly different environment 😬 Making most AVPs optional is a good design choice in many cases, even though it adds flexibility to the protocol 🌈 Protocol designers MUST clearly state why these optional AVPs might or might not be there, and properly define how Diameter nodes should behave when those AVPs are absent from the command 🎀

NOTE: As a hint for protocol designers, it is not sufficient to just look at the command's CCF syntax specification. You also need to read the text around it in the specification, carefully 🤓

Along the same lines, the CCF syntax specification SHOULD be defined so that any arbitrary optional AVPs with the M-bit cleared (including vendor-specific AVPs) can be added without modifying the application 🦋 To make that work, * [AVP] SHOULD be added in the command's CCF. That allows any number of optional AVPs, as described in [RFC6733] ✨

5.3. Use of Application Id in a Message

when you're designing a new application, application designers SHOULD specify that the Application Id in all session-level messages is the Application Id of the application using them 💅 That includes the session-level messages from the Diameter base protocol: Re-Auth-Request (RAR) / Re-Auth-Answer (RAA), Session-Termination-Request (STR) / Session-Termination-Answer (STA), Abort-Session-Request (ASR) / Abort-Session-Answer (ASA), and maybe Accounting-Request (ACR) / Accounting Answer (ACA) in the coupled accounting model (see Section 5.10) 🍓 Some existing specs don't follow this for historical reasons, but new applications SHOULD still follow it to avoid routing problems 🚦

If a new application gets a new Application Id and also reuses existing commands (with or without changes), the commands SHOULD use the newly allocated Application Id in the header and in all the relevant Application-Id AVPs (Auth-Application-Id or Acct-Application-Id) in the message body 🎀

Also, if you're using a vendor-specific Application-Id AVP, application designers SHOULD NOT use the Vendor-Id AVP to further split up or tell apart the vendor-specific Application Id 🙅‍♀️ Diameter routing doesn't look at the Vendor Id at all, so the Vendor Id SHOULD NOT be used as an extra input for routing or delivering messages. The Vendor-Id AVP is informational only and only kept around for backward compatibility 🫶

5.4. Application-Specific Session State Machines

Section 8 of [RFC6733] has session state machines for AAA services, and those aren't meant to cover behavior outside of AAA 🧚 If a new application can't clearly fit into one of those AAA services, it is RECOMMENDED that the application define its own session state machine 💜 Server-initiated requests are the classic example where you'd need an application-specific session state machine, like the Rw interface for the ITU-T push model (cf. [Q.3303.3]) 🔥

5.5. Session-Id AVP and Session Management

Diameter applications are usually built to manage user sessions (like the Diameter Network Access Server (NAS) application [RFC4005]) or a specific service access session (like the Diameter SIP application [RFC4740]) 🌸 In the Diameter base protocol, session state is tracked with the Session-Id AVP. Every Diameter message with the same Session-Id is bound to the same session. Diameter-based session management also means that both the Diameter client and server (and maybe proxy agents along the path) keep session state info 👑

BUT some applications don't need the Session-Id to identify and manage sessions, because other info can be used to match up Diameter messages instead 🙈 The User-Name AVP, or any other specific AVP, can show up in every Diameter message and be used for message correlation. Some applications don't need the concept of a Diameter session at all. For those, the Auth-Session-State AVP is usually set to NO_STATE_MAINTAINED in every Diameter message, so they're basically a bunch of stand-alone transactions 🦋 Even when an explicit access session termination is needed, they define and use application-specific commands instead of the STR/STA or ASR/ASA from the Diameter base protocol [RFC6733]. In that case, the Session-Id isn't significant 💀

So, based on all that, protocol designers should carefully figure out whether the Diameter application being defined relies on the session management specified in the Diameter base protocol 🧠

  • If it does, the Diameter command defined for the new application MUST include the Session-Id AVP defined in the Diameter base protocol [RFC6733], and the Session-Id AVP MUST be used to correlate messages for the same session 💖 Guidance on using the Auth-Session-State AVP is also in the Diameter base protocol [RFC6733] ✨
  • Otherwise, since session management isn't needed or the application uses its own session management mechanism, Diameter commands for the application don't need to include the Session-Id AVP 🌈 If the application supports any specific session management concept, the application documentation MUST clearly specify how the session is handled between the client and server (and possibly Diameter agents on the path) 🎀 And because the application isn't maintaining session state at the Diameter base protocol level, the Auth-Session-State AVP MUST be included in all Diameter commands for the application and MUST be set to NO_STATE_MAINTAINED 🔥

5.6. Use of Enumerated Type AVPs ✨

okay so the Enumerated type was originally cooked up to give you a list of allowed values for an AVP, with the meaning of each one spelled out in the spec 🎀 like, Enumerated AVPs are how you say why a session ended or what the server should do when it gets a request 💅

but remember from Section 4.4.2 that Enumerated AVPs are kinda rigid 🙈 once the list of values is set, you can't just add new ones later without breaking existing implementations 💀 so: AVPs of type Enumerated MUST NOT be extended by adding new values to support new capabilities. designers SHOULD think really hard before making an Enumerated AVP, asking whether the set of values will stay the same or whether new values are coming soon 🔮 if an extension is foreseeable or unavoidable, it is RECOMMENDED to use an Unsigned32 or Unsigned64 AVP instead, where the data field holds an address space that acts like Enumerated values 🌈 only the initial values from the Enumerated definition are valid per Section 4.4.2, but any value from 0 to 2^32 - 1 (Unsigned32) or 0 to 2^64 - 1 (Unsigned64) is valid at the Diameter base protocol level and won't cause interop problems for intermediary nodes between clients and servers 🫶 only the clients and servers actually process those values at the application layer 💜

here's an example to make it click 🦋

Access-Network-Type AVP (XXX) is of type Unsigned32 and
contains a 32-bit address space representing types of access
networks.  This application defines the following classes of access
networks, all identified by the thousands digit in the decimal
notation:

o  1xxx (Mobile Access Networks)

o  2xxx (Fixed Access Networks)

o  3xxx (Wireless Access Networks)

Values that fall within the Mobile Access Networks category are used
to inform a peer that a request has been sent for a user attached to
a mobile access network.  The following values are defined in this
application:

1001: 3GPP-GERAN

   The user is attached to a Global System for Mobile Communications
   (GSM) Enhanced Data rates for GSM Evolution (EDGE) Radio Access
   Network.

1002: 3GPP-UTRAN-FDD

   The user is attached to a Universal Mobile Telecommunications
   System (UMTS) access network that uses frequency-division
   duplexing for duplexing.

the whole point is that you can add a new value to this Unsigned32 AVP without touching the AVP's definition at all 🙌 no backward-compatibility drama, especially when intermediate nodes sit between Diameter endpoints 💖

now, Enumerated AVPs get misused as simple Boolean flags way too often 😭 like, they only define three values, e.g., TRUE/FALSE, AUTHORIZED/UNAUTHORIZED, or SUPPORTED/UNSUPPORTED 🙄 this is sub-optimal because it limits the application: any new capability or permission would need a brand-new AVP or a new Enumerated value on an existing AVP, and we already know how that goes 💀 so instead of an Enumerated AVP for a Boolean flag, protocol designers SHOULD use Unsigned32 or Unsigned64 AVPs where the data field is a bit mask, and the meaning of each bit is described in the relevant Diameter application specification 🧚 these can be reused and extended without a major impact on the application ✨ the bit mask SHOULD leave room for future additions 🌸 real examples are the Session-Binding AVP defined in [RFC6733] and the MIP6-Feature-Vector AVP defined in [RFC5447] 👑

5.7. Application-Specific Message Routing 🦋

okay so, as [RFC6733] explains, a Diameter request that needs to reach a home server serving a specific realm, but not one particular server (like the first request in a series of round trips), will carry a Destination-Realm AVP and no Destination-Host AVP 💌

for these requests, routing usually only depends on the Destination-Realm AVP and the Application Id in the message header 🗺️ but some applications need more info, like the User-Name AVP or other application-specific AVPs, to figure out where the request should really go 🔍 for example, finding the right AAA server holding authorization info for a user when a realm has multiple AAA servers 🏠

in that situation, the basic routing from [RFC6733] isn't fully suitable 😬 so additional application-level routing mechanisms MUST be described in the application documentation to do AVP-based routing 💅 this is basically handled by an application-specific proxy agent that makes routing decisions from the specific AVPs it receives 🫶

some examples live in the Cx/Dx applications ([TS29.228] and [TS29.229]) of the 3GPP IP Multimedia Subsystem 🌈 there the proxy agent (the Subscriber Location Function, aka SLF) uses application-level identities in the request to find the message's final destination 🎀

no matter what criteria set the request's path, the answer MUST follow the reverse path of the request, as described in [RFC6733], going back to the source of the received request, using transaction states and hop-by-hop identifier matching 🔁 this way, relay or proxy agents on the request path can release the transaction state once the matching answer arrives, which avoids unnecessary failover 🙌 and especially in roaming cases, proxy agents on the path need to apply local policies when the answer comes back from the server during authentication/authorization and/or accounting procedures, and keep up-to-date session state by tracking all authorized active sessions 🧠 so application designers MUST NOT modify the answer-routing principles described in [RFC6733] when defining a new application 🔒

5.8. Translation Agents 🔄

as defined in [RFC6733], a translation agent is a device that provides interworking between Diameter and another AAA protocol, such as RADIUS 🤝

back in the day it was thought that RADIUS-to-Diameter translation would be pretty straightforward, using basic principles like a shared range of code values for RADIUS attributes and Diameter AVPs 🙈 guidelines for building a RADIUS-Diameter translation agent were put into the Diameter NAS Application [RFC4005] 📚

but then it was acknowledged that translation isn't that obvious 😭 deeper protocol analysis is needed for efficient interworking between RADIUS and Diameter 🔬 plus the interworking requirements depend on what the Diameter application being specified actually does, so it needs a case-by-case analysis 🧐 so all the RADIUS-to-Diameter translation material was removed from the new version of the Diameter NAS Application specification [RFC7155], which deprecates RFC 4005 [RFC4005] 🗑️

therefore, protocol designers SHOULD NOT assume a "standard" Diameter-to-RADIUS gateway agent is available when planning to interoperate with the RADIUS infrastructure 🚫 they SHOULD specify the required translation mechanism along with the Diameter application, if needed 📝 this recommendation applies to any kind of translation 💖

5.9. End-to-End Application Capabilities Exchange 🎁

Diameter applications can rely on optional AVPs to swap application-specific capabilities and features 🛍️ these AVPs can be exchanged end-to-end at the application layer 💫 examples are the MIP6-Feature-Vector AVP in [RFC5447] and the QoS-Capability AVP in [RFC5777] 🦋

end-to-end capabilities AVPs can be added as optional AVPs with the M-bit cleared to existing applications, to announce support for new functionality 📣 receivers that don't understand these AVPs or their values can simply ignore them, as stated in [RFC6733] 🙈 when supported, receivers can discover the extra functionality the originating Diameter endpoint supports and behave accordingly when processing the request ✨ senders can safely assume the receiving endpoint doesn't support any functionality carried by the AVP if it's not in the corresponding response 🫶 this is super useful when deployment choices are offered and the generic design can be made available for a bunch of applications 🌈

when used in a new application, these end-to-end capabilities AVPs SHOULD be added as an optional AVP into the CCF of the commands used by the new application 💅 protocol designers SHOULD clearly specify this end-to-end capabilities exchange and the matching behavior of Diameter nodes supporting the application 📋

and it's important to note that this capabilities exchange, which relies on optional AVPs, is NOT meant to be a generic way to extend Diameter applications with arbitrary functionality 🚫 when the added features drastically change the Diameter application, or when Diameter agents must be upgraded to support them, a new application SHOULD be defined, as recommended in [RFC6733] 👑

5.10. Diameter Accounting Support ✨

Okay so accounting is basically an auxiliary app that helps out other apps 💅 In most cases, accounting support is required when you're defining new applications. This doc gives you two possible models to choose from 🎀

Split Accounting Model 🦋

In this model, the accounting messages use the Diameter base accounting Application Id (value of 3). The design vibe here is that accounting is its own independent app, especially for Diameter routing 🧚 That means accounting commands coming from an application may get routed separately from the rest of that app's messages. It may also mean the messages end up at a central accounting server 🏢 A split accounting model is a good pick when:

  • The application itself doesn't define its own accounting commands.
  • The overall system architecture allows centralized accounting for one or more Diameter applications.

Centralizing accounting has perks, but it also comes with drawbacks, bestie 🥺 This model assumes the accounting server can tell the received accounting messages apart. Since those messages can be for any application and/or service, the accounting server MUST have a method to match each accounting message with the application and/or service being accounted for 🔥 That could mean defining new AVPs, checking whether existing AVPs are present, absent, or what they contain, or checking the contents of the accounting record itself. One option is to stick an Auth-Application-Id AVP into the request sent to the accounting server, containing the identifier of the application the accounting request is for. But honestly? There's no clean, generic scheme for sorting these messages in general 💀 So this model SHOULD NOT be used when all received accounting messages can't be clearly identified and sorted. For most cases, the Coupled Accounting Model is RECOMMENDED 👑

Coupled Accounting Model 🌸

In this model, the accounting messages use the Application Id of the application that's using the accounting service. The design implication is that the accounting messages are tightly coupled with the application itself, so they get routed just like the application's other messages 🦋 It's then the job of the application server (the application entity receiving the ACR message) to send the accounting records carried by those messages to the proper accounting server. The application server is also responsible for putting together a proper response (ACA) ✨ A coupled accounting model is a good design choice when:

  • The system architecture or deployment doesn't provide an accounting server that supports Diameter. As a result, the application server MUST be provisioned to use a different protocol to reach the accounting server, e.g., the Lightweight Directory Access Protocol (LDAP), SOAP, etc. This includes support for older accounting systems that aren't Diameter aware 🙈
  • The system architecture or deployment requires that the accounting service for the specific application be handled by the application itself.

In all the cases above, there will generally be no direct Diameter access to the accounting server 🫶

These models give you a basis for using accounting messages. Application designers can totally deviate from them, provided the factors discussed here have also been taken into account 💅 As a general recommendation, application designers SHOULD NOT define a new set of commands to carry application-specific accounting records 💜

5.11. Diameter Security Mechanisms 🔐

As specified in [RFC6733], the Diameter message exchange SHOULD be secured between neighboring Diameter peers using Transport Layer Security (TLS) / TCP or Datagram Transport Layer Security (DTLS) / Stream Control Transmission Protocol (SCTP) 🔒 However, IPsec MAY also be deployed to secure communication between Diameter peers. When IPsec is used instead of TLS or DTLS, the following recommendations apply 🌈

IPsec Encapsulating Security Payload (ESP) [RFC4301] in transport mode with non-null encryption and authentication algorithms MUST be used to provide per-packet authentication, integrity protection, and confidentiality, and to support the replay protection mechanisms of IPsec 🛡️ Internet Key Exchange Protocol Version 2 (IKEv2) [RFC7296] SHOULD be used for performing mutual authentication and for establishing and maintaining security associations (SAs) 🗝️

Version 1 of IKE (IKEv1), defined in [RFC2409], was originally used for peer authentication, negotiating security associations, and key management in RFC 3588 [RFC3588]. To make migration from the obsoleted IKEv1-based implementations to IKEv2 easier, both RSA digital signatures and pre-shared keys SHOULD be supported in IKEv2 ✨ However, if IKEv1 is used, implementors SHOULD follow the guidelines given in Section 13.1 of RFC 3588 [RFC3588] 🙏

6. Defining Generic Diameter Extensions 🧩

Generic Diameter extensions are AVPs, commands, or applications designed to support other Diameter applications. They're auxiliary applications meant to improve or enhance the Diameter protocol itself, or Diameter applications and their functionality 💖 Some examples are the extensions that support realm-based redirection of Diameter requests (see [RFC7075]), conveying a specific set of priority parameters that influence how resources get distributed (see [RFC6735]), and support for QoS AVPs (see [RFC5777]) 🌟

Generic extensions can cover a lot of ground across Diameter and Diameter applications, so it's not possible to list every scenario 😭 That said, here are some of the most common considerations:

Backward Compatibility 🕰️

When you're defining generic extensions meant to be supported by existing Diameter applications, protocol designers MUST consider the potential impacts that introducing the new extension has on nodes that haven't been upgraded to support or understand it yet 🙈 Designers MUST also ensure that new extensions don't break expected message delivery layer behavior 📬

Forward Compatibility 🔮

Protocol designers MUST ensure that their design doesn't introduce undue restrictions for future applications 🦋

Trade-off in Signaling ⚖️

Designers may have to choose between using optional AVPs piggybacked onto existing commands and defining new commands and applications. Optional AVPs are simpler to implement and may not need changes to existing applications. But this ties the sending of extension data to the application's transmission of a message, which has consequences if the application and the extensions have different timing requirements 😬 Using commands and applications solves that issue, but the trade-off is the extra complexity of defining and deploying a new application. It's left up to the designer to find a good balance among these trade-offs based on the requirements of the extension 💅

In practice, generic extensions often use optional AVPs because they're simple and non-intrusive to the application that would carry them 🌸 Peers that don't support the generic extensions don't need to understand or recognize these optional AVPs. However, it is RECOMMENDED that the authors of the extension specify the context or usage of the optional AVPs 📝 For example, if an AVP can only be used by a specific set of applications, then the specification MUST enumerate those applications and the scenarios in which the optional AVPs will be used 🎯 If the optional AVPs can be carried by any application, it should be enough to specify that use case and perhaps give specific examples of applications using them ✨

Most of the time, these optional AVPs piggybacked by applications would be defined as a Grouped AVP, and that Grouped AVP would encapsulate all the functionality of the generic extension 🧁 In practice, it's not uncommon for the Grouped AVP to encapsulate an existing AVP that was previously defined as mandatory ('M'-bit set), e.g., the 3GPP IP Multimedia Subsystem (IMS) Cx/Dx interfaces ([TS29.228] and [TS29.229]) 💜

7. Guidelines for Registrations of Diameter Values 🎀

Okay bestie, so as summarized in Section 3 of this document and further described in Section 1.3 of [RFC6733], there are four main ways to extend Diameter 💖 The process for defining new functionality kinda changes depending on which kind of extension you're making. This section gives protocol designers some guidance on defining values for possible Diameter extensions, plus the IANA paperwork needed to register everything ✨

a. Defining New AVP Values 🌸

The specifications defining AVPs and AVP values MUST provide guidance for defining new values and the corresponding policy for adding these values. For example, RFC 5777 [RFC5777] defines the Treatment-Action AVP, which contains a list of valid values for predefined actions (drop, shape, mark, permit). This set of values can be extended following the Specification Required policy defined in [RFC5226]. As a second example, the Diameter base specification [RFC6733] defines the Result-Code AVP, which holds a 32-bit address space used to identify possible errors. According to Section 11.3.2 of [RFC6733], new values can be assigned by IANA via an IETF Review process [RFC5226] 🧚

b. Creating New AVPs 💅

Two different types of AVP Codes namespaces can be used to create a new AVP:

  • IETF AVP Codes namespace.
  • Vendor-specific AVP Codes namespace.

In the latter case, a vendor first needs to be assigned by IANA a private enterprise number, which can be used in the Vendor-Id field of the vendor-specific AVP. That enterprise number marks off a private namespace where the vendor is responsible for assigning its own AVP code values 🦋 The absence of a Vendor Id, or a Vendor-Id value of zero (0) in the AVP header, identifies standard AVPs from the IETF AVP Codes namespace managed by IANA. Allocating code values from the IANA-managed namespace needs Expert Review of the specification defining the AVPs, or an IETF Review if a whole block of AVPs needs to be assigned. Also, the remaining bits of the AVP Flags field in the AVP header are assigned via Standards Action if you want to create new AVP flags 🔥

c. Creating New Commands 🍓

Unlike the AVP Codes namespace, the Command Code namespace is flat, but its range of values is split into three chunks, each with its own IANA registration policy:

  • A range of standard Command Code values that are allocated via IETF Review;
  • A range of vendor-specific Command Code values that are allocated on a first-come, first-served basis; and
  • A range of values reserved only for experimental and testing purposes.

Same deal as AVP flags: the remaining bits of the Command Flags field in the Diameter header are assigned via a Standards Action if you need new Command flags 👑

d. Creating New Applications 🌈

Similar to the Command Code namespace, the Application-Id namespace is flat but divided into two distinct ranges:

  • A range of values reserved for standard Application Ids, allocated after Expert Review of the specification defining the standard application.
  • A range of values for vendor-specific applications, allocated by IANA on a first-come, first-served basis.

The IANA AAA parameters page lives at http://www.iana.org/assignments/aaa-parameters, and the enterprise number IANA page is at http://www.iana.org/assignments/enterprise-numbers. If you want more details on how IANA handles namespace management (first-come, first-served, Expert Review, IETF Review, etc.), check out [RFC5226] 📚

NOTE: When the same functionality/extension is used by more than one vendor, it is RECOMMENDED that a standard extension be defined. Moreover, a vendor-specific extension SHOULD be registered to avoid interoperability issues in the same network. With this aim, the registration policy of a vendor-specific extension has been simplified with the publication of [RFC6733], and the namespace reserved for vendor-specific extensions is large enough to avoid exhaustion. 🫶

8. Security Considerations 💀

This document provides guidelines and considerations for extending Diameter and Diameter applications. Even though an extension might be related to a security functionality, the document doesn't explicitly give extra guidance on enhancing Diameter with respect to security. However, as a general guideline, it's recommended that any Diameter extension SHOULD NOT break the security concept given in [RFC6733]. In particular, it's reiterated here that any command defined or reused in a new Diameter application SHOULD be secured by using TLS [RFC5246] or DTLS/SCTP [RFC6083], and MUST NOT be used without one of the following: TLS, DTLS, or IPsec [RFC4301]. When defining a new Diameter extension, any possible impact on the existing security principles described in [RFC6733] MUST be carefully appraised and documented in the Diameter application specification.

🚨 Security is not the place to freestyle, bestie. Read the whole thing before you ship anything 🚨

9. References 📚

9.1. Normative References

[RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
           Requirement Levels", BCP 14, RFC 2119, March 1997,
           <http://www.rfc-editor.org/info/rfc2119>.

[RFC6733]  Fajardo, V., Arkko, J., Loughney, J., and G. Zorn,
           "Diameter Base Protocol", RFC 6733, October 2012,
           <http://www.rfc-editor.org/info/rfc6733>.

9.2. Informative References

[Q.3303.3] International Telecommunications Union, "Resource control
           protocol No.  3: Protocols at the Rw interface between the
           policy decision physical entity (PD-PE) and a policy
           enforcement physical entity (PE-PE): Diameter profile
           version 3", ITU-T Recommendation Q.3303.3, August 2008.

[RFC2409]  Harkins, D. and D. Carrel, "The Internet Key Exchange
           (IKE)", RFC 2409, November 1998,
           <http://xml.resource.org/public/rfc/info/rfc2409>.

[RFC3588]  Calhoun, P., Loughney, J., Guttman, E., Zorn, G., and J.
           Arkko, "Diameter Base Protocol", RFC 3588, September 2003,
           <http://www.rfc-editor.org/info/rfc3588>.

[RFC4005]  Calhoun, P., Zorn, G., Spence, D., and D. Mitton,
           "Diameter Network Access Server Application", RFC 4005,
           August 2005, <http://www.rfc-editor.org/info/rfc4005>.

[RFC4072]  Eronen, P., Hiller, T., and G. Zorn, "Diameter Extensible
           Authentication Protocol (EAP) Application", RFC 4072,
           August 2005, <http://www.rfc-editor.org/info/rfc4072>.

[RFC4301]  Kent, S. and K. Seo, "Security Architecture for the
           Internet Protocol", RFC 4301, December 2005,
           <http://www.rfc-editor.org/info/rfc4301>.

[RFC4740]  Garcia-Martin, M., Belinchon, M., Pallares-Lopez, M.,
           Canales-Valenzuela, C., and K. Tammi, "Diameter Session
           Initiation Protocol (SIP) Application", RFC 4740, November
           2006, <http://www.rfc-editor.org/info/rfc4740>.

[RFC5226]  Narten, T. and H. Alvestrand, "Guidelines for Writing an
           IANA Considerations Section in RFCs", BCP 26, RFC 5226,
           May 2008, <http://www.rfc-editor.org/info/rfc5226>.

[RFC5246]  Dierks, T. and E. Rescorla, "The Transport Layer Security
           (TLS) Protocol Version 1.2", RFC 5246, August 2008,
           <http://www.rfc-editor.org/info/rfc5246>.

[RFC5447]  Korhonen, J., Bournelle, J., Tschofenig, H., Perkins, C.,
           and K. Chowdhury, "Diameter Mobile IPv6: Support for
           Network Access Server to Diameter Server Interaction", RFC
           5447, February 2009,
           <http://www.rfc-editor.org/info/rfc5447>.

[RFC5777]  Korhonen, J., Tschofenig, H., Arumaithurai, M., Jones, M.,
           and A. Lior, "Traffic Classification and Quality of
           Service (QoS) Attributes for Diameter", RFC 5777, February
           2010, <http://www.rfc-editor.org/info/rfc5777>.

[RFC6083]  Tuexen, M., Seggelmann, R., and E. Rescorla, "Datagram
           Transport Layer Security (DTLS) for Stream Control
           Transmission Protocol (SCTP)", RFC 6083, January 2011,
           <http://www.rfc-editor.org/info/rfc6083>.

[RFC6735]  Carlberg, K. and T. Taylor, "Diameter Priority Attribute-
           Value Pairs", RFC 6735, October 2012,
           <http://www.rfc-editor.org/info/rfc6735>.

[RFC7075]  Tsou, T., Hao, R., and T. Taylor, "Realm-Based Redirection
           In Diameter", RFC 7075, November 2013,
           <http://www.rfc-editor.org/info/rfc7075>.

[RFC7155]  Zorn, G., "Diameter Network Access Server Application",
           RFC 7155, April 2014,
           <http://www.rfc-editor.org/info/rfc7155>.

[RFC7296]  Kaufman, C., Hoffman, P., Nir, Y., Eronen, P., and T.
           Kivinen, "Internet Key Exchange Protocol Version 2
           (IKEv2)", STD 79, RFC 7296, October 2014,
           <http://www.rfc-editor.org/info/rfc7296>.

[TS29.228] 3rd Generation Partnership Project, "Technical
           Specification Group Core Network and Terminals; IP
           Multimedia (IM) Subsystem Cx and Dx Interfaces; Signalling
           flows and message contents", 3GPP TS 29.228, September
           2014, <http://www.3gpp.org/ftp/Specs/html-info/29228.htm>.

[TS29.229] 3rd Generation Partnership Project, "Technical
           Specification Group Core Network and Terminals; Cx and Dx
           interfaces based on the Diameter protocol; Protocol
           details", 3GPP TS 29.229, September 2014,
           <http://www.3gpp.org/ftp/Specs/html-info/29229.htm>.

[TS29.328] 3rd Generation Partnership Project, "Technical
           Specification Group Core Network and Terminals; IP
           Multimedia (IM) Subsystem Sh interface; Signalling flows
           and message contents", 3GPP TS 29.328, September 2014,
           <http://www.3gpp.org/ftp/Specs/html-info/29328.htm>.

[TS29.329] 3rd Generation Partnership Project, "Technical
           Specification Group Core Network and Terminals; Sh
           Interface based on the Diameter protocol; Protocol
           details", 3GPP TS 29.329, September 2014,
           <http://www.3gpp.org/ftp/Specs/html-info/29329.htm>.

Contributors 🧡

The content of this document was influenced by a design team created to revisit the Diameter extensibility rules. The team was formed in February 2008 and finished its work in June 2008. Besides the people listed in the Authors' Addresses section, the design team members were:

  • Avi Lior
  • Glen Zorn
  • Jari Arkko
  • Jouni Korhonen
  • Mark Jones
  • Tolga Asveren
  • Glenn McGregor
  • Dave Frascone

We'd like to thank Tolga Asveren, Glenn McGregor, and John Loughney for their work as coauthors on earlier versions of this document 🥰

Acknowledgments 🌟

We really appreciate the insight from Diameter implementors who highlighted the issues and concerns this document addresses 💜 The authors would also like to thank Jean Mahoney, Ben Campbell, Sebastien Decugis, and Benoit Claise for their invaluable, detailed reviews and comments on this document 🙈

Authors' Addresses ✨

Okay bestie, last stop! 🧚 Here's who to contact if you have questions. Lionel is the editor, so they're basically the head coach 💅

Lionel Morand (editor)
Orange Labs
38/40 rue du General Leclerc
Issy-Les-Moulineaux Cedex 9  92794
France

Phone: +33145296257
EMail: lionel.morand@orange.com

Next up is Victor, who's at Fluke Networks 🦋

Victor Fajardo
Fluke Networks

EMail: vf0213@gmail.com

And last but definitely not least, Hannes 🌸 with a website too, so you can go see what they're up to 👑

Hannes Tschofenig
Hall in Tirol  6060
Austria

EMail: Hannes.Tschofenig@gmx.net
URI:   http://www.tschofenig.priv.at
📦 where this page comes from