RFC 3588
Diameter Base Protocol
Part 1 of 32 🎀✨
Diameter Base Protocol 💖
okay bestie, this is RFC 3588, and it's giving serious standards-track main character energy 👑. It was published in September 2003 as a Standards Track document, which means it's a real Internet protocol spec and not just an idea 💅. The authors are P. Calhoun (Airespace, Inc.), J. Loughney (Nokia), E. Guttman (Sun Microsystems, Inc.), G. Zorn (Cisco Systems, Inc.), and J. Arkko (Ericsson). It doesn't obsolete or update any earlier RFCs, because none are listed in its header 🧚.
Status of this Memo 🌸
So this document is an Internet standards track protocol for the Internet community, and it's basically asking everyone for discussion and suggestions for improvements 🫶. If you want to know where it sits officially, check the current edition of the "Internet Official Protocol Standards" (STD 1) for the standardization state and status. And the distribution of this memo is unlimited, so share it with everyone 🦋.
Copyright Notice 💜
Copyright (C) The Internet Society (2003). All Rights Reserved. 🔒
Abstract ✨
Okay so the Diameter base protocol is an Authentication, Authorization and Accounting (AAA) framework for applications like network access or IP mobility 🌈. It's designed to work for both local Authentication, Authorization & Accounting and roaming situations, which is honestly so iconic 😭. This document spells out the message format, transport, error reporting, accounting and security services that every Diameter application uses 💅. And the Diameter base application has to be supported by all Diameter implementations, no exceptions 🔥.
Conventions Used In This Document 🎀
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 BCP 14, RFC 2119 [KEYWORD]. Translation: those capitalised words are the strict ones, so read them carefully 🙈.
Table of Contents 🍓
1. Introduction................................................. 6
1.1. Diameter Protocol..................................... 9
1.1.1. Description of the Document Set.............. 10
1.2. Approach to Extensibility............................. 11
1.2.1. Defining New AVP Values...................... 11
1.2.2. Creating New AVPs............................ 11
1.2.3. Creating New Authentication Applications..... 11
1.2.4. Creating New Accounting Applications......... 12
1.2.5. Application Authentication Procedures........ 14
1.3. Terminology........................................... 14
2. Protocol Overview............................................ 18
2.1. Transport............................................. 20
2.1.1. SCTP Guidelines.............................. 21
2.2. Securing Diameter Messages............................ 21
2.3. Diameter Application Compliance....................... 21
2.4. Application Identifiers............................... 22
2.5. Connections vs. Sessions.............................. 22
2.6. Peer Table............................................ 23
2.7. Realm-Based Routing Table............................. 24
2.8. Role of Diameter Agents............................... 25
2.8.1. Relay Agents................................. 26
2.8.2. Proxy Agents................................. 27
2.8.3. Redirect Agents.............................. 28
2.8.4. Translation Agents........................... 29
2.9. End-to-End Security Framework......................... 30
2.10. Diameter Path Authorization........................... 30
3. Diameter Header.............................................. 32
3.1. Command Codes......................................... 35
3.2. Command Code ABNF specification....................... 36
3.3. Diameter Command Naming Conventions................... 38
4. Diameter AVPs................................................ 38
4.1. AVP Header............................................ 39
4.1.1. Optional Header Elements..................... 41
4.2. Basic AVP Data Formats................................ 41
4.3. Derived AVP Data Formats.............................. 42
4.4. Grouped AVP Values.................................... 49
4.4.1. Example AVP with a Grouped Data Type......... 50
4.5. Diameter Base Protocol AVPs........................... 53
5. Diameter Peers............................................... 56
5.1. Peer Connections...................................... 56
5.2. Diameter Peer Discovery............................... 56
5.3. Capabilities Exchange................................. 59
5.3.1. Capabilities-Exchange-Request................ 60
5.3.2. Capabilities-Exchange-Answer................. 60
5.3.3. Vendor-Id AVP................................ 61
5.3.4. Firmware-Revision AVP........................ 61
5.3.5. Host-IP-Address AVP.......................... 62
5.3.6. Supported-Vendor-Id AVP...................... 62
5.3.7. Product-Name AVP............................. 62
5.4. Disconnecting Peer Connections........................ 62
5.4.1. Disconnect-Peer-Request...................... 63
5.4.2. Disconnect-Peer-Answer....................... 63
5.4.3. Disconnect-Cause AVP......................... 63
5.5. Transport Failure Detection........................... 64
5.5.1. Device-Watchdog-Request...................... 64
5.5.2. Device-Watchdog-Answer....................... 64
5.5.3. Transport Failure Algorithm.................. 65
5.5.4. Failover and Failback Procedures............. 65
5.6. Peer State Machine.................................... 66
5.6.1. Incoming connections......................... 68
5.6.2. Events....................................... 69
5.6.3. Actions...................................... 70
5.6.4. The Election Process......................... 71
6. Diameter Message Processing.................................. 71
6.1. Diameter Request Routing Overview..................... 71
6.1.1. Originating a Request........................ 73
6.1.2. Sending a Request............................ 73
6.1.3. Receiving Requests........................... 73
6.1.4. Processing Local Requests.................... 73
6.1.5. Request Forwarding........................... 74
6.1.6. Request Routing.............................. 74
6.1.7. Redirecting Requests......................... 74
6.1.8. Relaying and Proxying Requests............... 75
6.2. Diameter Answer Processing............................ 76
6.2.1. Processing Received Answers.................. 77
6.2.2. Relaying and Proxying Answers................ 77
6.3. Origin-Host AVP....................................... 77
6.4. Origin-Realm AVP...................................... 78
6.5. Destination-Host AVP.................................. 78
6.6. Destination-Realm AVP................................. 78
6.7. Routing AVPs.......................................... 78
6.7.1. Route-Record AVP............................. 79
6.7.2. Proxy-Info AVP............................... 79
6.7.3. Proxy-Host AVP............................... 79
6.7.4. Proxy-State AVP.............................. 79
6.8. Auth-Application-Id AVP............................... 79
6.9. Acct-Application-Id AVP............................... 79
6.10. Inband-Security-Id AVP................................ 79
6.11. Vendor-Specific-Application-Id AVP.................... 80
6.12. Redirect-Host AVP..................................... 80
6.13. Redirect-Host-Usage AVP............................... 80
6.14. Redirect-Max-Cache-Time AVP........................... 81
6.15. E2E-Sequence AVP...................................... 82Okay bestie, here's the rest of the map 🗺️✨ Sections 7 through the Full Copyright Statement, every page number included 💅
7. Error Handling............................................... 82
7.1. Result-Code AVP....................................... 84
7.1.1. Informational................................ 84
7.1.2. Success...................................... 84
7.1.3. Protocol Errors.............................. 85
7.1.4. Transient Failures........................... 86
7.1.5. Permanent Failures........................... 86
7.2. Error Bit............................................. 88
7.3. Error-Message AVP..................................... 89
7.4. Error-Reporting-Host AVP.............................. 89
7.5. Failed-AVP AVP........................................ 89
7.6. Experimental-Result AVP............................... 90
7.7. Experimental-Result-Code AVP.......................... 90
8. Diameter User Sessions....................................... 90
8.1. Authorization Session State Machine................... 92
8.2. Accounting Session State Machine...................... 96
8.3. Server-Initiated Re-Auth.............................. 101
8.3.1. Re-Auth-Request.............................. 102
8.3.2. Re-Auth-Answer............................... 102
8.4. Session Termination................................... 103
8.4.1. Session-Termination-Request.................. 104
8.4.2. Session-Termination-Answer................... 105
8.5. Aborting a Session.................................... 105
8.5.1. Abort-Session-Request........................ 106
8.5.2. Abort-Session-Answer......................... 106
8.6. Inferring Session Termination from Origin-State-Id.... 107
8.7. Auth-Request-Type AVP................................. 108
8.8. Session-Id AVP........................................ 108
8.9. Authorization-Lifetime AVP............................ 109
8.10. Auth-Grace-Period AVP................................. 110
8.11. Auth-Session-State AVP................................ 110
8.12. Re-Auth-Request-Type AVP.............................. 110
8.13. Session-Timeout AVP................................... 111
8.14. User-Name AVP......................................... 111
8.15. Termination-Cause AVP................................. 111
8.16. Origin-State-Id AVP................................... 112
8.17. Session-Binding AVP................................... 113
8.18. Session-Server-Failover AVP........................... 113
8.19. Multi-Round-Time-Out AVP.............................. 114
8.20. Class AVP............................................. 114
8.21. Event-Timestamp AVP................................... 115
9. Accounting................................................... 115
9.1. Server Directed Model................................. 115
9.2. Protocol Messages..................................... 116
9.3. Application Document Requirements..................... 116
9.4. Fault Resilience...................................... 116
9.5. Accounting Records.................................... 117
9.6. Correlation of Accounting Records..................... 118
9.7. Accounting Command-Codes.............................. 119
9.7.1. Accounting-Request........................... 119
9.7.2. Accounting-Answer............................ 120
9.8. Accounting AVPs....................................... 121
9.8.1. Accounting-Record-Type AVP................... 121
9.8.2. Acct-Interim-Interval AVP.................... 122
9.8.3. Accounting-Record-Number AVP................. 123
9.8.4. Acct-Session-Id AVP.......................... 123
9.8.5. Acct-Multi-Session-Id AVP.................... 123
9.8.6. Accounting-Sub-Session-Id AVP................ 123
9.8.7. Accounting-Realtime-Required AVP............. 123
10. AVP Occurrence Table......................................... 124
10.1. Base Protocol Command AVP Table....................... 124
10.2. Accounting AVP Table.................................. 126
11. IANA Considerations.......................................... 127
11.1. AVP Header............................................ 127
11.1.1. AVP Code..................................... 127
11.1.2. AVP Flags.................................... 128
11.2. Diameter Header....................................... 128
11.2.1. Command Codes................................ 128
11.2.2. Command Flags................................ 129
11.3. Application Identifiers............................... 129
11.4. AVP Values............................................ 129
11.4.1. Result-Code AVP Values....................... 129
11.4.2. Accounting-Record-Type AVP Values............ 130
11.4.3. Termination-Cause AVP Values................. 130
11.4.4. Redirect-Host-Usage AVP Values............... 130
11.4.5. Session-Server-Failover AVP Values........... 130
11.4.6. Session-Binding AVP Values................... 130
11.4.7. Disconnect-Cause AVP Values.................. 130
11.4.8. Auth-Request-Type AVP Values................. 130
11.4.9. Auth-Session-State AVP Values................ 130
11.4.10. Re-Auth-Request-Type AVP Values.............. 131
11.4.11. Accounting-Realtime-Required AVP Values...... 131
11.5. Diameter TCP/SCTP Port Numbers........................ 131
11.6. NAPTR Service Fields.................................. 131
12. Diameter Protocol Related Configurable Parameters............ 131
13. Security Considerations...................................... 132
13.1. IPsec Usage........................................... 133
13.2. TLS Usage............................................. 134
13.3. Peer-to-Peer Considerations........................... 134
14. References................................................... 136
14.1. Normative References.................................. 136
14.2. Informative References................................ 138
15. Acknowledgements............................................. 140
Appendix A. Diameter Service Template........................... 141
Appendix B. NAPTR Example....................................... 142
Appendix C. Duplicate Detection................................. 143
Appendix D. Intellectual Property Statement..................... 145
Authors' Addresses............................................... 146
Full Copyright Statement......................................... 1471. Introduction ✨
okay bestie, so AAA protocols (Authentication, Authorization and Accounting) like TACACS [TACACS] and RADIUS [RADIUS] were originally built for dial-up PPP [PPP] and terminal server access 📞🌸. Then the internet grew up, new access tech showed up (wireless, DSL, Mobile IP, Ethernet 🦋), and routers and network access servers (NAS) got way more complex and dense. so AAA protocols suddenly had a LOT more expectations to live up to 💅. the network access requirements are summed up in [AAAREQ], and here's the tea:
Failover [RADIUS] doesn't define failover mechanisms, so failover behavior is different from one implementation to the next 😭. Diameter fixes this by supporting application-layer acknowledgements and defining failover algorithms plus the associated state machine. the details are in Section 5.5 and [AAATRANS] 🎀.
Transmission-level security [RADIUS] defines an application-layer authentication and integrity scheme that is required only for use with Response packets. [RADEXT] adds another authentication and integrity mechanism, but its use is only required during Extensible Authentication Protocol (EAP) sessions. attribute-hiding is supported, but [RADIUS] doesn't give you per-packet confidentiality 🙈. and in accounting, [RADACCT] assumes replay protection is handled by the backend billing server, not the protocol itself, which is kinda sus 💀.
[RFC3162] defines using IPsec with RADIUS, but IPsec support isn't required. ngl this is a problem for roaming: within [IKE], authentication only happens in Phase 1, before the IPsec SAs get set up in Phase 2, so it's typically not possible to define separate trust or authorization schemes for each application. that limits IPsec for inter-domain AAA (like roaming), where you might want a distinct certificate hierarchy for an AAA deployment 🧚. so to get universal transmission-level security and let both intra- and inter-domain AAA deployments work, IPsec support is MANDATORY in Diameter and TLS support is OPTIONAL. security is discussed in Section 13 🔥.
Reliable transport RADIUS runs over UDP and doesn't define retransmission behavior, so reliability varies between implementations. [ACCMGMT] calls this a major issue in accounting, because packet loss can translate directly into revenue loss 💸. Diameter runs over reliable transport mechanisms (TCP, SCTP) as defined in [AAATRANS] 🫶.
Agent support [RADIUS] doesn't explicitly support agents, including Proxies, Redirects and Relays. since the expected behavior isn't defined, it varies between implementations 🙃. Diameter defines agent behavior explicitly, and that's in Section 2.8 ✨.
Server-initiated messages RADIUS server-initiated messages are defined in [DYNAUTH], but support is OPTIONAL. this makes features like unsolicited disconnect or reauthentication/reauthorization on demand really hard to build across a mixed deployment 😩. support for server-initiated messages is MANDATORY in Diameter and is described in Section 8 🌈.
Auditability RADIUS doesn't define data-object security mechanisms, so untrusted proxies may modify attributes or even packet headers without anyone noticing 😱. combined with no capabilities negotiation, it's super hard to figure out what happened when there's a dispute 🕵️♀️. implementing data object security isn't mandatory in Diameter, but these capabilities are supported and described in [AAACMS] 💜.
Transition support Diameter doesn't share a common protocol data unit (PDU) with RADIUS, but a lot of effort went into backward compatibility so the two can be deployed on the same network 🍓. at first, Diameter is expected to show up in new network devices and in gateways that let legacy RADIUS devices talk to Diameter agents. that's described in [NASREQ], and it lets you add Diameter support to legacy networks just by adding a gateway or server that speaks both RADIUS and Diameter 🦋.
in addition to all that, Diameter also gives you:
Capability negotiation RADIUS doesn't support error messages, capability negotiation, or a mandatory/non-mandatory flag for attributes. since RADIUS clients and servers don't know each other's capabilities, they might not agree on a service they both accept, or even know what service was implemented 🤷♀️. Diameter includes error handling (Section 7), capability negotiation (Section 5.3), and mandatory/non-mandatory attribute-value pairs (AVPs) (Section 4.1) 👑.
Peer discovery and configuration RADIUS implementations usually need the name or address of servers or clients manually configured, along with the matching shared secrets. that's a huge admin burden, and it tempts people to reuse the RADIUS shared secret, which can cause major security vulnerabilities if the Request Authenticator isn't globally and temporally unique as required in [RADIUS] 😬. through DNS, Diameter enables dynamic discovery of peers 🧚. dynamic session keys can be derived via transmission-level security 🔐.
Roaming support the ROAMOPS WG gave us a survey of roaming implementations [ROAMREV], detailed roaming requirements [ROAMCRIT], defined the Network Access Identifier (NAI) [NAI], and documented existing implementations (and imitations 💀) of RADIUS-based roaming [PROXYCHAIN]. [PROXYCHAIN] introduced proxy chaining through an intermediate server to improve scalability and make roaming between providers easier 🌸. however, RADIUS doesn't explicitly support proxies and lacks auditability and transmission-level security features, so RADIUS-based roaming is vulnerable to attack from external parties and open to fraud by the roaming partners themselves 😭. as a result, it's not suitable for wide-scale deployment on the Internet [PROXYCHAIN]. Diameter fixes all of that with explicit support for inter-domain roaming and message routing (Sections 2.7 and 6), auditability [AAACMS], and transmission-layer security (Section 13), so roaming can be secure and scalable 💖.
in the decade since AAA protocols first showed up, NAS devices got a LOT more capable 🚀. so even though Diameter is way more sophisticated than RADIUS, it's still feasible to implement in embedded devices, thanks to faster processors and the widespread availability of embedded IPsec and TLS implementations ⭐.
1.1. Diameter Protocol ✨
the Diameter base protocol gives you these facilities:
- Delivery of AVPs (attribute value pairs) 🎀
- Capabilities negotiation 🤝
- Error notification 🚨
- Extensibility, through addition of new commands and AVPs (required in [AAAREQ]). 🧩
- Basic services necessary for applications, such as handling of user sessions or accounting 💅
all data delivered by the protocol is in the form of an AVP. some of these AVP values are used by Diameter itself, and others deliver data for particular applications that use Diameter 🦋. AVPs can be added to Diameter messages arbitrarily, as long as the required AVPs are included and the AVPs that are explicitly excluded are NOT included. the base protocol uses AVPs for these required features:
- Transporting user authentication information, so the Diameter server can authenticate the user 🔑.
- Transporting service specific authorization information between client and servers, so the peers can decide whether a user's access request should be granted ✅.
- Exchanging resource usage information, which MAY be used for accounting purposes, capacity planning, etc. 📊
- Relaying, proxying and redirecting Diameter messages through a server hierarchy 🌐.
the Diameter base protocol provides the minimum requirements a AAA protocol needs, as required by [AAAREQ] 💖. the base protocol can be used by itself for accounting only, or with a Diameter application like Mobile IPv4 [DIAMMIP] or network access [NASREQ]. the base protocol can also be extended for new applications by adding new commands or AVPs 🧚. right now, Diameter's focus is network access and accounting applications. a truly generic AAA protocol used by lots of applications might offer functionality Diameter doesn't, so it's IMPERATIVE that designers of new applications understand their requirements before using Diameter 👑.
see Section 2.4 for more on Diameter applications 🎀.
any node can initiate a request. in that sense, Diameter is a peer-to-peer protocol 🫶. in this document, a Diameter Client is a device at the edge of the network that performs access control, like a Network Access Server (NAS) or a Foreign Agent (FA) 🛜. a Diameter client generates Diameter messages to request authentication, authorization, and accounting services for the user. a Diameter agent is a node that does NOT authenticate and/or authorize messages locally; agents include proxies, redirects and relay agents 🍓. a Diameter server performs authentication and/or authorization of the user 🔐. a Diameter node MAY act as an agent for certain requests while acting as a server for others 🌈.
the Diameter protocol also supports server-initiated messages, like a request to abort service to a particular user 🙈.
1.1.1. Description of the Document Set 📚
right now, the Diameter specification is made up of a base specification (this document), the Transport Profile [AAATRANS], and applications: Mobile IPv4 [DIAMMIP] and NASREQ [NASREQ] ✨.
the Transport Profile document [AAATRANS] covers transport layer issues that come up with AAA protocols, plus recommendations for getting around them 🚛. this document also defines the Diameter failover algorithm and state machine 💜.
the Mobile IPv4 [DIAMMIP] application defines a Diameter application that lets a Diameter server do AAA functions for Mobile IPv4 services to a mobile node 📱.
the NASREQ [NASREQ] application defines a Diameter Application that lets a Diameter server be used in a PPP/SLIP Dial-Up and Terminal Server Access environment. it also considered servers that need to convert protocols between Diameter and RADIUS 🔄.
in summary, this document defines the base protocol specification for AAA, which includes accounting support. the Mobile IPv4 and NASREQ documents describe applications that use this base specification for Authentication, Authorization and Accounting 🎉.
1.2. Approach to Extensibility ✨
okay so Diameter is built to be extensible 💅 and it can grow in a few different ways:
- Defining new AVP values
- Creating new AVPs
- Creating new authentication/authorization applications
- Creating new accounting applications
- Application authentication procedures
bestie, reusing existing AVP values, AVPs and Diameter applications is strongly recommended 🫶 reuse makes standardization and implementation way easier and helps dodge potential interoperability issues. command codes are expected to be reused too 🔁 new command codes can only be created by IETF Consensus (see Section 11.2.1) 🔒
1.2.1. Defining New AVP Values 🌸
new applications should try to reuse AVPs from existing applications when possible, instead of making new AVPs 🧚 for AVPs of type Enumerated, an application might need a new value to carry some service-specific info.
so to allocate a new AVP value, a request MUST be sent to IANA [IANA], along with an explanation of the new AVP value 📝 IANA considerations for Diameter are covered in Section 11.
1.2.2. Creating New AVPs 🎀
when no existing AVP can work, a new AVP should be created 💖 the new AVP MUST use one of the data types listed in Section 4.2.
if you need a logical grouping of AVPs, and there could be multiple "groups" in a single command, it's recommended to use a Grouped AVP (see Section 4.4) 🍓
and to create a new AVP, a request MUST be sent to IANA with a specification for the AVP. the request MUST include the commands that would use the AVP 🦋
1.2.3. Creating New Authentication Applications 👑
every Diameter application specification MUST have an IANA assigned Application Identifier (see Section 2.4) or a vendor specific Application Identifier 🪪
if a new Diameter usage scenario can't fit into an existing application without major changes to the spec, it may be worth creating a new Diameter application 🌈 major changes to an application include:
- Adding new AVPs to the command, which have the "M" bit set.
- Requiring a command that has a different number of round trips to satisfy a request (e.g., application foo has a command that requires one round trip, but new application bar has a command that requires two round trips to complete).
- Adding support for an authentication method requiring definition of new AVPs for use with the application. Since a new EAP authentication method can be supported within Diameter without requiring new AVPs, addition of EAP methods does not require the creation of a new authentication application.
making a new application should be a last resort 🙈 an implementation MAY add arbitrary non-mandatory AVPs to any command defined in an application, including vendor-specific AVPs, without needing a new application at all. check Section 11.1.1 for the details 👀
to justify a new application identifier, Diameter applications MUST define one Command Code, or add new mandatory AVPs to the ABNF 🧾
the expected AVPs MUST be defined in an ABNF [ABNF] grammar (see Section 3.2) 📐 if the Diameter application has accounting requirements, it MUST also specify the AVPs that should be present in the Diameter Accounting messages (see Section 9.3). but just because a new authentication application id is needed doesn't mean a new accounting application id is needed too 🙃
when possible, a new Diameter application SHOULD reuse existing Diameter AVPs, so you don't end up defining multiple AVPs that carry similar info 🫧
1.2.4. Creating New Accounting Applications 💸
some services only need Diameter accounting 💅 those services need to define the AVPs carried in the Accounting-Request (ACR)/ Accounting-Answer (ACA) messages, but they don't need new command codes. an implementation MAY add arbitrary non-mandatory AVPs (AVPs with the "M" bit not set) to any command defined in an application, including vendor-specific AVPs, without needing a new accounting application. check Section 11.1.1 for details 🌷
application Identifiers are still required for Diameter capability exchange 🤝 every Diameter accounting application specification MUST have an IANA assigned Application Identifier (see Section 2.4) or a vendor specific Application Identifier.
every Diameter implementation MUST support accounting 💜 basic accounting support is enough for any application that uses the ACR/ACA commands defined in this document, as long as no new mandatory AVPs are added. a mandatory AVP is one with the "M" bit set when sent within an accounting command, whether or not it's required or optional in the ABNF for the accounting application 🧐
creating a new accounting application should be a last resort too 😭 it MUST NOT be used unless a new command or additional mechanisms (e.g., application defined state machine) are defined within the application, or new mandatory AVPs are added to the ABNF.
inside an accounting command, setting the "M" bit means a backend server (e.g., billing server) or the accounting server itself MUST understand the AVP in order to compute a correct bill 🧾💰 if the AVP isn't relevant to billing, then when it's included in an accounting command it MUST NOT have the "M" bit set, even if the "M" bit is set when the same AVP is used in other Diameter commands (i.e., authentication/authorization commands). not me being picky, but this one matters 🚨
a DIAMETER base accounting implementation MUST be configurable to advertise supported accounting applications, so the accounting server doesn't accept accounting requests for unbillable services 🙅♀️ the combination of the home domain and the accounting application Id can be used to route the request to the right accounting server 🗺️
when possible, a new Diameter accounting application SHOULD try to reuse existing AVPs, so you don't define multiple AVPs that carry similar info 🫶
if base accounting is used without any mandatory AVPs, new commands or additional mechanisms (e.g., application defined state machine), then the base protocol defined standard accounting application Id (Section 2.4) MUST be used in ACR/ACA commands 🎯
1.2.5. Application Authentication Procedures 🔐
when possible, applications SHOULD be designed so that new authentication methods MAY be added without requiring changes to the application 🦄 this MAY require new AVP values to be assigned to represent the new authentication transform, or any other scheme that produces similar results. when possible, authentication frameworks such as Extensible Authentication Protocol [EAP] SHOULD be used 🌟
1.3. Terminology 📖✨
Okay bestie, this is the glossary moment 🧚 Every term here is a building block, so let's go one by one.
AAA 🎀 Authentication, Authorization and Accounting. Iconic trio.
Accounting 💅 Collecting info on resource usage for capacity planning, auditing, billing or cost allocation. Basically keeping receipts.
Accounting Record 📝 A summary of a user's resource consumption over the entire session. The accounting servers building it might process interim accounting events, or accounting events from several devices serving the same user. Lowkey a group project.
Authentication 🔐 Verifying the identity of an entity (subject). "Are you who you say you are?"
Authorization 🗝️ Figuring out whether a requesting entity (subject) is allowed access to a resource (object). Authentication checks the ID, authorization checks the permission slip.
AVP 🦋 A Diameter protocol message is a header followed by one or more Attribute-Value-Pairs (AVPs). Each AVP has its own header, and it carries protocol-specific data (like routing information) plus authentication, authorization or accounting info. AVPs are the little boxes that hold everything. 📦
Broker 🌸 A business term used a lot in AAA infrastructures. A broker is a relay, proxy or redirect agent, and it MAY be operated by roaming consortiums. Depending on the business model, a broker may choose to deploy relay agents or proxy agents.
Diameter Agent 🧚 A Diameter node that provides relay, proxy, redirect or translation services.
Diameter Client 🚪 A device at the edge of the network that does access control. Examples are a Network Access Server (NAS) or a Foreign Agent (FA).
Diameter Node 💜 A host process that implements the Diameter protocol and acts as a Client, Agent or Server. It's the umbrella term for all of them.
Diameter Peer 🫶 A Diameter Node that a given Diameter Node has a direct transport connection to. Direct line, no middleman.
Diameter Security Exchange 🔒 The process where two Diameter nodes set up end-to-end security between themselves.
Diameter Server 👑 A server that handles authentication, authorization and accounting requests for a particular realm. By its very nature, a Diameter Server MUST support Diameter applications in addition to the base protocol. Not optional, babe.
Downstream ⬇️ The direction of a Diameter message going from the home server toward the access device.
End-to-End Security 🌈 TLS and IPsec give you hop-by-hop security, meaning security across a transport connection. But once relays or proxies show up, that hop-by-hop protection doesn't cover the whole Diameter user session 😭. End-to-end security is between two Diameter nodes, possibly talking through Diameter Agents, and it protects the entire path from the originating node to the terminating node. Full coverage, no gaps.
Home Realm 🏠 The administrative domain where the user has an account relationship. Home sweet home.
Home Server 🔁 See Diameter Server. Same thing, different nickname.
Interim accounting 📸 An interim accounting message is a snapshot of usage during a user's session. It's usually used for partial accounting in case a device reboot or some other network problem stops the session summary message or session record from arriving. Think of it as saving your progress 💾.
Local Realm 🏡 The administrative domain that provides services to a user. An administrative domain MAY act as a local realm for some users while being a home realm for others. Multitasking queen 👑.
Multi-session 🧵 A logical link between several sessions, tracked by Acct-Multi-Session-Id. A Multi-link PPP bundle is the classic example: each leg of the bundle is a session, and the whole bundle is the multi-session.
Network Access Identifier 🪪 The Network Access Identifier, or NAI [NAI], is what Diameter uses to pull out a user's identity and realm. The identity identifies the user during authentication and/or authorization, while the realm is used for message routing.
Proxy Agent or Proxy 🎭 Proxies forward requests and responses, and they also make policy decisions about resource usage and provisioning. This usually happens by tracking the state of NAS devices. Proxies typically don't respond to client Requests until they get a Response from the server, but they may send Reject messages when policies are violated. Because of that, proxies need to understand the semantics of the messages passing through them, and they may not support all Diameter applications. Gatekeeper energy 🚧.
Realm 🗺️ The string in the NAI that comes right after the '@' character. NAI realm names are required to be unique, and they're piggybacked on the administration of the DNS namespace. Diameter uses the realm (also loosely called a domain) to figure out whether a message can be handled locally or has to be routed or redirected. In RADIUS, realm names aren't necessarily piggybacked on DNS and can be independent of it. 🙈
Real-time Accounting ⏱️ Processing info on resource usage within a defined time window. Time limits are usually set to cap financial risk. Tick tock.
Relay Agent or Relay 🏃♀️ Relays forward requests and responses based on routing-related AVPs and realm routing table entries. Since relays don't make policy decisions, they don't examine or alter non-routing AVPs. So relays never originate messages, don't need to understand the semantics of messages or non-routing AVPs, and can handle any Diameter application or message type. They decide based on routing AVPs and realm forwarding tables, and they don't keep state on NAS resource usage or sessions in progress. Low drama, high efficiency 💖.
Redirect Agent ↪️ Instead of forwarding requests and responses between clients and servers, redirect agents tell clients which server to talk to and let them connect directly. Since they aren't in the forwarding path, they don't alter any AVPs passing between client and server. Redirect agents don't originate messages and can handle any message type, although they may be configured to only redirect certain types while acting as relay or proxy agents for others. Like proxy agents, they don't keep state about sessions or NAS resources. 🦩
Roaming Relationships ✈️ These include relationships between companies and ISPs, relationships among peer ISPs within a roaming consortium, and relationships between an ISP and a roaming consortium. It's all about who's allowed to hang out with whom 🌍.
Security Association 🤝 An association between two endpoints in a Diameter session that lets them communicate with integrity and confidentiality, even when relays and/or proxies are in the middle. Secret handshake energy 🫢.
Session 🎬 A related progression of events devoted to one particular activity. Each application SHOULD provide guidelines on when a session begins and ends. All Diameter packets with the same Session-Identifier are part of the same session.
Session state 📋 A stateful agent is one that keeps session state information by tracking all authorized active sessions. Each authorized session is bound to a particular service, and its state stays active until it's notified otherwise or it expires. It remembers everything 🧠.
Sub-session 🎶 A distinct service (for example, QoS or data characteristics) provided to a given session. These services can happen at the same time (like simultaneous voice and data transfer during the same session) or one after another. These changes within a session are tracked with Accounting-Sub-Session-Id. Multiple vibes, one session 🎧.
Transaction state 🔁 The Diameter protocol requires agents to maintain transaction state, which is used for failover. When an agent forwards a request, it saves the Hop-by-Hop identifier, then replaces that field with a locally unique identifier. When the matching answer comes back, the original value gets restored. The request's state is released once the answer is received. A stateless agent is one that only maintains transaction state. Sneaky but necessary 🫣.
Translation Agent 🌐 A stateful Diameter node that translates between Diameter and another AAA protocol, such as RADIUS. Translator, but make it iconic 🗣️.
Transport Connection 🔗 A TCP or SCTP connection that exists directly between two Diameter peers. Also known as a Peer-to-Peer Connection. Straight shot, no detours ✨.
Upstream ⬆️ The direction of a Diameter message going from the access device toward the home server.
User 🙋♀️ The entity requesting or using some resource, in support of which a Diameter client has generated a request. The main character of the whole story 👑🌸.
2. Protocol Overview 🦋
okay so the base Diameter protocol can totally be used by itself for accounting apps 💅 but for authentication and authorization it's always extended for a specific application 🎀 two Diameter applications get defined in companion docs: NASREQ [NASREQ] and Mobile IPv4 [DIAMMIP] 🌸 this doc introduces them but the actual specs live elsewhere. more Diameter applications MAY be defined in the future (see Section 11.3) ✨
Diameter Clients MUST support the base protocol, which includes accounting 💖 on top of that they MUST fully support each Diameter application needed to run the client's service, like NASREQ and/or Mobile IPv4. a Diameter Client that doesn't support both NASREQ and Mobile IPv4 MUST be called "Diameter X Client" (where X is the application it supports) and not just a "Diameter Client" 🫶
Diameter Servers MUST support the base protocol, which includes accounting 🔥 plus they MUST fully support each Diameter application needed for the intended service, like NASREQ and/or Mobile IPv4. a Diameter Server that doesn't support both NASREQ and Mobile IPv4 MUST be called "Diameter X Server" (where X is the application it supports) and not just a "Diameter Server" 👑
Diameter Relays and redirect agents are, by definition, protocol transparent 🧚 they MUST transparently support the Diameter base protocol (which includes accounting) and ALL Diameter applications. (okay so "ALL" here is just me hyping it, the actual rule is that they support all of them, babe 💅)
Hold on, let me be precise, because this part matters: the rule is that relays and redirect agents MUST transparently support the Diameter base protocol, which includes accounting, and all Diameter applications. no extra caps needed 💜
Diameter proxies MUST support the base protocol, which includes accounting 🌈 in addition, they MUST fully support each Diameter application needed to implement proxied services, like NASREQ and/or Mobile IPv4. a Diameter proxy that doesn't support both NASREQ and Mobile IPv4 MUST be called "Diameter X Proxy" (where X is the application it supports) and not a "Diameter Proxy" 🍓
The base Diameter protocol is all about capabilities negotiation, how messages get sent, and how peers may eventually be abandoned 🦋 it also defines certain rules that apply to ALL exchanges of messages between Diameter nodes (ok I'm getting carried away, these are just the rules for every exchange, periodt) 💀
Communication between Diameter peers starts with one peer sending a message to another Diameter peer ✨ the set of AVPs in that message is determined by a particular Diameter application. one AVP that's included to reference a user's session is the Session-Id 🌸
The initial request for authentication and/or authorization of a user includes the Session-Id 💖 that Session-Id then gets used in all subsequent messages to identify the user's session (see Section 8 for more info) 🎀 the receiving party can accept the request, or reject it by returning an answer message with the Result-Code AVP set to indicate an error occurred 🙈 how the Diameter server or client behaves when it gets a request totally depends on the Diameter application being used 💅
Session state (tied to a Session-Id) MUST be freed upon receipt of the Session-Termination-Request, the Session-Termination-Answer, expiration of the authorized service time in the Session-Timeout AVP, and according to rules set in a particular Diameter application 😭 this is one of those "don't leave things hanging" moments, bestie 🫶
2.1. Transport 🚀
Transport profile is defined in [AAATRANS] ✨
The base Diameter protocol runs on port 3868 of both TCP [TCP] and SCTP [SCTP] 🌈
Diameter clients MUST support either TCP or SCTP, while agents and servers MUST support both 💅 future versions of this spec MAY mandate that clients support SCTP 🔮
A Diameter node MAY initiate connections from a source port other than the one it declares it accepts incoming connections on 🦋 but it MUST be prepared to receive connections on port 3868 🫶 a given Diameter instance of the peer state machine MUST NOT use more than one transport connection to communicate with a given peer 🙅♀️ the exception is when multiple instances exist on the peer, then a separate connection per process is allowed 🧚
When no transport connection exists with a peer, an attempt to connect SHOULD be made periodically 🍓 this is handled by the Tc timer, whose recommended value is 30 seconds ⏰ there are certain exceptions, like when a peer has terminated the transport connection saying it doesn't wish to communicate 🙈
When connecting to a peer and either zero or more transports are specified, SCTP SHOULD be tried first, followed by TCP 💖 see Section 5.2 for more on peer discovery 💅
Diameter implementations SHOULD be able to interpret ICMP protocol port unreachable messages as explicit indications that the server is not reachable, subject to security policy on trusting such messages 🛡️ they SHOULD also be able to interpret a reset from the transport and timed-out connection attempts 👀
If Diameter receives data up from TCP that can't be parsed or identified as a Diameter error made by the peer, the stream is compromised and can't be recovered 😭 so the transport connection MUST be closed using a RESET call (send a TCP RST bit) or an SCTP ABORT message (graceful closure is compromised) 💀
2.1.1. SCTP Guidelines 🧜♀️
the following are guidelines for Diameter implementations that support SCTP ✨
- For interoperability: All Diameter nodes MUST be prepared to receive Diameter messages on any SCTP stream in the association 🫶
- To prevent blocking: All Diameter nodes SHOULD utilize all SCTP streams available to the association to prevent head-of-the-line blocking 🌊
2.2. Securing Diameter Messages 🔐
Diameter clients, like Network Access Servers (NASes) and Mobility Agents, MUST support IP Security [SECARCH] and MAY support TLS [TLS] 🎀 Diameter servers MUST support TLS and IPsec 💪 the Diameter protocol MUST NOT be used without any security mechanism (TLS or IPsec) 🚨 no cap, this one's serious 😤
it's suggested that IPsec can be used primarily at the edges and in intra-domain traffic, like using pre-shared keys between a NAS and a local AAA proxy 🌸 this also eases the requirements on the NAS to support certificates 💖 it's also suggested that inter-domain traffic would primarily use TLS 🦋 see Sections 13.1 and 13.2 for more details on IPsec and TLS usage 📚
2.3. Diameter Application Compliance 💅
Application Identifiers are advertised during the capabilities exchange phase (see Section 5.3) ✨ for a given application, advertising support for it implies that the sender supports all command codes and the AVPs specified in the associated ABNFs described in the specification 🫶
An implementation MAY add arbitrary non-mandatory AVPs to any command defined in an application, including vendor-specific AVPs 🧚 please refer to Section 11.1.1 for details 🙏
2.4. Application Identifiers 🆔
Each Diameter application MUST have an IANA assigned Application Identifier (see Section 11.3) 🏷️ the base protocol doesn't require an Application Identifier since its support is mandatory 💅 during the capabilities exchange, Diameter nodes tell their peers which applications they support locally 📣 and all Diameter messages contain an Application Identifier, which is used in the message forwarding process 🔁
the Application Identifier values defined are:
Diameter Common Messages 0
NASREQ 1 [NASREQ]
Mobile-IP 2 [DIAMMIP]
Diameter Base Accounting 3
Relay 0xffffffffRelay and redirect agents MUST advertise the Relay Application Identifier, while all other Diameter nodes MUST advertise locally supported applications 💖 the receiver of a Capabilities Exchange message advertising Relay service MUST assume that the sender supports all current and future applications 🤯
Diameter relay and proxy agents are responsible for finding an upstream server that supports the application of a particular message 🕵️♀️ if none can be found, an error message is returned with the Result-Code AVP set to DIAMETER_UNABLE_TO_DELIVER 😭 rip
2.5. Connections vs. Sessions 🧠
this section is here to help you understand the difference between a connection and a session, which get used a LOT throughout this doc 💅
a connection is a transport level connection between two peers, used to send and receive Diameter messages 🔌 a session is a logical concept at the application layer 🧠 it's shared between an access device and a server and is identified via the Session-Id AVP ✨
+--------+ +-------+ +--------+
| Client | | Relay | | Server |
+--------+ +-------+ +--------+
<----------> <---------->
peer connection A peer connection B
<----------------------------->
User session x
Figure 1: Diameter connections and sessionsin the example in Figure 1, peer connection A is established between the Client and its local Relay 🌈 peer connection B is established between the Relay and the Server 🌊 user session X spans from the Client via the Relay to the Server 🎀 each "user" of a service causes an auth request to be sent, with a unique session identifier 🆔 once it's accepted by the server, both the client and the server are aware of the session 🫶
it's important to note that there is NO relationship between a connection and a session 🙈 (sorry, "no" here is lowercase, I'm just being extra) and Diameter messages for multiple sessions are all multiplexed through a single connection 🧚 so one pipe, lots of sessions, iconic 👑
2.6. Peer Table 📋
The Diameter Peer Table is used in message forwarding and is referenced by the Realm Routing Table 🗺️ a Peer Table entry contains the following fields:
- Host identity: Follows the conventions described for the DiameterIdentity derived AVP data format in Section 4.4 🆔 this field contains the contents of the Origin-Host (Section 6.3) AVP found in the CER or CEA message 💖
StatusT: This is the state of the peer entry, and MUST match one of the values listed in Section 5.6 🚦- Static or Dynamic: Specifies whether a peer entry was statically configured or dynamically discovered 🧭
- Expiration time: Specifies the time at which dynamically discovered peer table entries are to be either refreshed or expired ⏳
- TLS Enabled: Specifies whether TLS is to be used when communicating with the peer 🔐
- Additional security information: when needed (e.g., keys, certificates) 🗝️
2.7. Realm-Based Routing Table 🗺️
Okay so every realm-based routing lookup happens against what everyone calls the Realm Routing Table (see Section 12) 💅 Each Realm Routing Table Entry has these fields:
- Realm Name 🎀 This is the one that usually works as the primary key in lookups. Some implementations do longest-match-from-the-right on the realm instead of demanding an exact match, which is lowkey so clever 🌸
- Application Identifier 🦋 An application is identified by a vendor id AND an application id. For all IETF standards track Diameter applications, the vendor id is
0. A route entry can point somewhere different depending on the application identification AVP of the message. This field MUST be used as a secondary key field in routing table lookups. - Local Action 🧚 This field tells you how a message should be treated. There are four supported actions:
- LOCAL: Diameter messages that resolve to a route entry with the Local Action set to Local can be satisfied locally, so they don't need to be routed to another server ✨
- RELAY: All Diameter messages in this category MUST be routed to a next hop server, without modifying any non-routing AVPs. See Section 6.1.8 for relaying guidelines 🫶
- PROXY: All Diameter messages in this category MUST be routed to a next hop server. The local server MAY apply its local policies to the message by including new AVPs to the message prior to routing. See Section 6.1.8 for proxying guidelines 🔥
- REDIRECT: Diameter messages in this category MUST have the identity of the home Diameter server(s) appended, and returned to the sender of the message. See Section 6.1.7 for redirect guidelines 🙈
- Server Identifier 👑 One or more servers the message is to be routed to. These servers MUST also be present in the Peer table. When the Local Action is set to RELAY or PROXY, this field contains the identity of the server(s) the message must be routed to. When the Local Action field is set to REDIRECT, this field contains the identity of one or more servers the message should be redirected to.
- Static or Dynamic 🌈 Specifies whether a route entry was statically configured, or dynamically discovered.
- Expiration time ⏳ Specifies the time at which a dynamically discovered route table entry expires.
It is important to note that Diameter agents MUST support at least one of the LOCAL, RELAY, PROXY or REDIRECT modes of operation. Agents do not need to support all modes of operation in order to conform with the protocol specification, but MUST follow the protocol compliance guidelines in Section 2. Relay agents MUST NOT reorder AVPs, and proxies MUST NOT reorder AVPs. 💀
The routing table MAY include a default entry that MUST be used for any requests not matching any of the other entries. The routing table MAY consist of only such an entry. 🍓
When a request is routed, the target server MUST have advertised the Application Identifier (see Section 2.4) for the given message, or have advertised itself as a relay or proxy agent. Otherwise, an error is returned with the Result-Code AVP set to DIAMETER_UNABLE_TO_DELIVER. 😭
2.8. Role of Diameter Agents 🦋
Besides clients and servers, the Diameter protocol brings in relay, proxy, redirect, and translation agents, each of which is defined in Section 1.3. These Diameter agents are useful for a bunch of reasons:
- They can distribute administration of systems to a configurable grouping, including maintaining security associations 🔐
- They can concentrate requests from a number of co-located or distributed NAS equipment sets to a set of like user groups 🌸
- They can do value-added processing on requests or responses 💅
- They can be used for load balancing ⚖️
- A complex network will have multiple authentication sources, so they can sort requests and forward them toward the correct target 🧭
The Diameter protocol requires that agents maintain transaction state, which is used for failover purposes. Transaction state means that when a request gets forwarded, its Hop-by-Hop identifier is saved, and the field is replaced with a locally unique identifier. That original value gets restored when the matching answer comes back. The request's state is released once the answer is received. A stateless agent is one that only maintains transaction state 🫧
The Proxy-Info AVP lets stateless agents attach local state to a Diameter request, with the guarantee that the same state will show up in the answer. However, the protocol's failover procedures require that agents keep a copy of pending requests 🥹
A stateful agent is one that maintains session state information, keeping track of all authorized active sessions. Each authorized session is bound to a particular service, and its state is considered active either until it's notified otherwise, or until it expires. Each authorized session has an expiration, which Diameter servers communicate via the Session-Timeout AVP ⏰
Maintaining session state MAY be useful in certain applications, such as:
- Protocol translation (e.g.,
RADIUS <-> Diameter) 🔄 - Limiting resources authorized to a particular user 🚦
- Per user or transaction auditing 🔍
A Diameter agent MAY act in a stateful manner for some requests and be stateless for others. A Diameter implementation MAY act as one type of agent for some requests, and as another type of agent for others. 🦄
2.8.1. Relay Agents 🏃♀️
Relay Agents are Diameter agents that accept requests and route messages to other Diameter nodes based on information found in the messages (e.g., Destination-Realm). This routing decision is made using a list of supported realms and known peers. This is known as the Realm Routing Table, as defined further in Section 2.7 📋
Relays MAY be used to aggregate requests from multiple Network Access Servers (NASes) within a common geographical area (POP). Using Relays is a big win because it means NASes don't need to be configured with the security information they'd otherwise need to talk to Diameter servers in other realms. It also cuts down on the configuration load on Diameter servers that would otherwise come with adding, changing, or deleting NASes 🙌
Relays modify Diameter messages by inserting and removing routing information, but they don't modify any other portion of a message. Relays SHOULD NOT maintain session state but MUST maintain transaction state. 🧠
+------+ ---------> +------+ ---------> +------+
| | 1. Request | | 2. Request | |
| NAS | | DRL | | HMS |
| | 4. Answer | | 3. Answer | |
+------+ <--------- +------+ <--------- +------+
example.net example.net example.com
Figure 2: Relaying of Diameter messagesThe example in Figure 2 shows a request sent from NAS, which is an access device, for the user bob@example.com. Before issuing the request, NAS does a Diameter route lookup using "example.com" as the key, and figures out the message is to be relayed to DRL, which is a Diameter Relay. DRL does the same route lookup as NAS, then relays the message to HMS, which is example.com's Home Diameter Server. HMS sees that the request can be handled locally (via the realm), processes the authentication and/or authorization request, and replies with an answer. That answer gets routed back to NAS using the saved transaction state 🎬
Since Relays don't do any application level processing, they provide relaying services for all Diameter applications, and therefore MUST advertise the Relay Application Identifier. 💖
2.8.2. Proxy Agents 🌷
Proxy agents are similar to relays in that they route Diameter messages using the Diameter Routing Table. They're different, though, because they modify messages to implement policy enforcement. That means proxies have to keep track of the state of their downstream peers (e.g., access devices) so they can enforce resource usage, provide admission control, and do provisioning 📊
It's important to note that even though proxies MAY provide a value-add function for NASes, they don't let access devices use end-to-end security, since modifying messages breaks authentication 🚫
Proxies MAY be used in call control centers or access ISPs that provide outsourced connections. They can monitor the number and types of ports in use, and make allocation and admission decisions according to their configuration 🎧
Proxies that want to limit resources MUST maintain session state. All proxies MUST maintain transaction state. 🛡️
Since enforcing policies requires understanding the service being provided, Proxies MUST only advertise the Diameter applications they support. 💅✨
2.8.3. Redirect Agents ✨
okay so redirect agents are giving centralized routing realness 🎀. picture a consortium where one redirect agent helps every member, but it doesn't want to be stuck relaying every single message between realms 💅. the best part: when a member changes its infrastructure, the consortium doesn't have to send routing updates to everyone. iconic, no cap 🫶
since redirect agents don't relay messages and only send back an answer with the info agents need to talk directly, they don't modify messages 🦋. they also never see answer messages, so they can't keep session state 🙈. and because they never relay requests, they're not required to keep transaction state either 💜.
figure 3 is the whole vibe 🧚: NAS sends a request for bob@example.com to its relay, DRL. DRL has no routing entry for example.com in its Diameter Routing Table, so it falls back to its default route, DRD. DRD is the redirect agent, and it sends back a redirect notification with HMS' contact info. DRL then sets up a transport connection with HMS (if one doesn't already exist) and forwards the request there 🚀
+------+
| |
| DRD |
| |
+------+
^ |
2. Request | | 3. Redirection
| | Notification
| v
+------+ ---------> +------+ ---------> +------+
| | 1. Request | | 4. Request | |
| NAS | | DRL | | HMS |
| | 6. Answer | | 5. Answer | |
+------+ <--------- +------+ <--------- +------+
example.net example.net example.comFigure 3: Redirecting a Diameter Message
since redirect agents don't do any application level processing, they provide relaying services for all Diameter applications, so they MUST advertise the Relay Application Identifier. the main character of the consortium, honestly 👑
2.8.4. Translation Agents 🌈
a translation agent is a device that translates between two protocols (like RADIUS<->Diameter or TACACS+<->Diameter) 🔄. these are likely to act as aggregation servers that talk to the Diameter infrastructure, which lets the embedded systems migrate at a slower pace. so chill, the old gear doesn't have to rush 🌸
because Diameter brings long-lived authorized sessions, translation agents MUST be session stateful and MUST maintain transaction state. no skipping that part 💀
translation can only happen if the agent recognizes the application of a particular request, so translation agents MUST only advertise their locally supported applications. know your lane 🎀
+------+ ---------> +------+ ---------> +------+
| | RADIUS Request | | Diameter Request | |
| NAS | | TLA | | HMS |
| | RADIUS Answer | | Diameter Answer | |
+------+ <--------- +------+ <--------- +------+
example.net example.net example.comFigure 4: Translation of RADIUS to Diameter
2.9. End-to-End Security Framework 🔐
okay the security glow-up 💖. end-to-end security is giving confidentiality and message origin authentication 🔒. it's provided by supporting AVP integrity and confidentiality between two peers, even though the messages pass through agents along the way ✨
end-to-end security comes through the End-to-End security extension, described in [AAACMS]. which situations need it is decided by policy on each of the peers. security policies aren't standardized, and they can be applied by next hop Diameter peer or by destination realm. for example, if TLS or IPsec transmission-level security is already sufficient, there might be no need for end-to-end security 🙃
end-to-end security policies can look like this:
- never use end-to-end security 🙅♀️
- use end-to-end security on messages containing sensitive AVPs. service provider policy decides which AVPs count as sensitive. AVPs containing keys and passwords should be considered sensitive, accounting AVPs may be considered sensitive, and any AVP where the P bit may be set or which may be encrypted may be considered sensitive too 🤫
- always use end-to-end security 🛡️
it is strongly RECOMMENDED that all Diameter implementations support end-to-end security. literally the move 💅🌈
2.10. Diameter Path Authorization 🛡️
as we said in Section 2.2, Diameter requires transmission level security to be used on each connection (TLS or IPsec). so each connection is authenticated, replay and integrity protected, and confidential on a per-packet basis 🔐. the protection is giving full protection, bestie 💜
but wait, there's more 👀. in addition to authenticating each connection, each connection as well as the entire session MUST also be authorized. before initiating a connection, a Diameter Peer MUST check that its peers are authorized to act in their roles. being authentic doesn't mean being authorized. a Diameter peer could be totally legit and still NOT be allowed to act as a Diameter Server advertising a set of Diameter applications 🙈
prior to bringing up a connection, authorization checks are performed at each connection along the path. Diameter capabilities negotiation (CER/CEA) also MUST be carried out, so everyone knows which Diameter applications each peer supports 🎀. Diameter sessions MUST be routed only through authorized nodes that have advertised support for the Diameter application required by the session. no random detours, periodt 💅
as noted in Section 6.1.8, a relay or proxy agent MUST append a Route-Record AVP to all requests forwarded. that AVP holds the identity of the peer the request was received from 📝
the home Diameter server, before authorizing a session, MUST check the Route-Record AVPs to make sure the route the request took is acceptable 🕵️♀️. for example, admins in the home realm might not want to honor requests that went through an untrusted realm. by authorizing a request, the home Diameter server is basically saying it's willing to take part in the business deal set out in its contract with the previous hop 🤝. if the route is unacceptable, a DIAMETER_AUTHORIZATION_REJECTED error message is sent (see Section 7.1.5) 🚫
a home realm may also want to check that each accounting request corresponds to a Diameter response that authorized the session. accounting requests without matching authorization responses SHOULD be subjected to further scrutiny, and so should accounting requests showing a difference between the requested and provided service 🧐
the local Diameter agent, when it receives a Diameter response authorizing a session, MUST check the Route-Record AVPs too, to make sure the route that response took is acceptable 🔁. at every step, forwarding an authorization response counts as showing a willingness to take on financial risk for the session 💸. a local realm can limit that exposure, like by setting credit limits for intermediate realms and refusing responses that would break those limits 🧮. when a local realm issues an accounting request matching the authorization response, it's implicitly agreeing to provide the service in that response 🤝
if the local realm can't provide the service, a DIAMETER_UNABLE_TO_COMPLY error message MUST be sent within the accounting request. and a Diameter client that gets an authorization response for a service it can't perform MUST NOT swap in an alternate service and then send accounting requests for that alternate service instead. that's a hard no, bestie 🙅♀️💀
3. Diameter Header ✨
okay so here's the Diameter header format bestie 🎀 It's a quick summary, and every field is sent in network byte order (big-endian) 💅
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Version | Message Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| command flags | Command-Code |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Application-ID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Hop-by-Hop Identifier |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| End-to-End Identifier |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| AVPs ...
+-+-+-+-+-+-+-+-+-+-+-+-+-Version 🦋 This Version field MUST be set to 1 to indicate Diameter Version 1.
Message Length 🌸 The Message Length field is three octets and tells you the length of the whole Diameter message, header fields included.
Command Flags 💖 The Command Flags field is eight bits, and these bits are assigned:
0 1 2 3 4 5 6 7
+-+-+-+-+-+-+-+-+
|R P E T r r r r|
+-+-+-+-+-+-+-+-+- R(equest): if this is set, the message is a request. If it's cleared, the message is an answer.
- P(roxiable): if this is set, the message MAY be proxied, relayed or redirected. If it's cleared, the message MUST be locally processed.
- E(rror): if this is set, the message contains a protocol error, and it won't conform to the ABNF described for this command. Messages with the 'E' bit set are commonly called error messages. This bit MUST NOT be set in request messages. See Section 7.2.
- T(Potentially re-transmitted message): this flag gets set after a link failover procedure, to help remove duplicate requests. It's set when resending requests that haven't been acknowledged yet, as a hint that it might be a duplicate caused by a link failure. This bit MUST be cleared when sending a request for the first time; otherwise the sender MUST set this flag. Diameter agents only need to care about how many requests they send based on a single received request. Retransmissions by other entities don't need to be tracked. Diameter agents that receive a request with the T flag set MUST keep the T flag set in the forwarded request. This flag MUST NOT be set if an error answer message (e.g., a protocol error) has been received for the earlier message. It can only be set in cases where no answer has come back from the server for a request and the request is sent again. This flag MUST NOT be set in answer messages.
- r(eserved): these flag bits are reserved for future use. They MUST be set to zero, and the receiver MUST ignore them.
Command-Code 🧚 The Command-Code field is three octets, and it's used to communicate the command associated with the message. The 24-bit address space is managed by IANA (see Section 11.2.1).
Command-Code values 16,777,214 and 16,777,215 (hexadecimal values FFFFFE-FFFFFF) are reserved for experimental use (see Section 11.3).
Application-ID 👑 Application-ID is four octets and is used to identify which application the message applies to. The application can be an authentication application, an accounting application or a vendor specific application. See Section 11.3 for the possible values that the Application-ID may use.
The application-id in the header MUST be the same as what is contained in any relevant AVPs contained in the message.
Hop-by-Hop Identifier 🍓 The Hop-by-Hop Identifier is an unsigned 32-bit integer field (in network byte order), and it helps match requests with replies. The sender MUST ensure that the Hop-by-Hop Identifier in a request is unique on a given connection at any given time, and MAY attempt to ensure that the number is unique across reboots. The sender of an Answer message MUST ensure that the Hop-by-Hop Identifier field contains the same value that was found in the corresponding request. The Hop-by-Hop Identifier is normally a monotonically increasing number, whose start value was randomly generated. An answer message that is received with an unknown Hop-by-Hop Identifier MUST be discarded.
End-to-End Identifier 🔥 The End-to-End Identifier is an unsigned 32-bit integer field (in network byte order), and it's used to detect duplicate messages. Upon reboot, implementations MAY set the high order 12 bits to contain the low order 12 bits of current time, and the low order 20 bits to a random value. Senders of request messages MUST insert a unique identifier on each message. The identifier MUST remain locally unique for a period of at least 4 minutes, even across reboots. The originator of an Answer message MUST ensure that the End-to-End Identifier field contains the same value that was found in the corresponding request. The End-to-End Identifier MUST NOT be modified by Diameter agents of any kind. The combination of the Origin-Host (see Section 6.3) and this field is used to detect duplicates. Duplicate requests SHOULD cause the same answer to be transmitted (modulo the hop-by-hop Identifier field and any routing AVPs that may be present), and MUST NOT affect any state that was set when the original request was processed. Duplicate answer messages that are to be locally consumed (see Section 6.2) SHOULD be silently discarded.
AVPs 💜 AVPs are a way of encapsulating information relevant to the Diameter message. See Section 4 for more information on AVPs.
3.1. Command Codes 🌈
Each command Request/Answer pair gets a command code, and the sub-type (request or answer) is identified by the 'R' bit in the Command Flags field of the Diameter header.
Every Diameter message MUST contain a command code in its header's Command-Code field, which is used to determine the action that is to be taken for a particular message. The following Command Codes are defined in the Diameter base protocol:
Command-Name Abbrev. Code Reference
--------------------------------------------------------
Abort-Session-Request ASR 274 8.5.1
Abort-Session-Answer ASA 274 8.5.2
Accounting-Request ACR 271 9.7.1
Accounting-Answer ACA 271 9.7.2
Capabilities-Exchange- CER 257 5.3.1
Request
Capabilities-Exchange- CEA 257 5.3.2
Answer
Device-Watchdog-Request DWR 280 5.5.1
Device-Watchdog-Answer DWA 280 5.5.2
Disconnect-Peer-Request DPR 282 5.4.1
Disconnect-Peer-Answer DPA 282 5.4.2
Re-Auth-Request RAR 258 8.3.1
Re-Auth-Answer RAA 258 8.3.2
Session-Termination- STR 275 8.4.1
Request
Session-Termination- STA 275 8.4.2
Answer3.2. Command Code ABNF specification ✨
Okay bestie, every Command Code that gets defined MUST come with its own ABNF specification 🎀. That's the bit that spells out which AVPs MUST be present and which ones MAY be present. Here's the format:
command-def = command-name "::=" diameter-message
command-name = diameter-name
diameter-name = ALPHA *(ALPHA / DIGIT / "-")
diameter-message = header [ *fixed] [ *required] [ *optional]
[ *fixed]
header = "<" Diameter-Header:" command-id
[r-bit] [p-bit] [e-bit] [application-id]">"
application-id = 1*DIGIT
command-id = 1*DIGIT
; The Command Code assigned to the command
r-bit = ", REQ"
; If present, the 'R' bit in the Command
; Flags is set, indicating that the message
; is a request, as opposed to an answer.
p-bit = ", PXY"
; If present, the 'P' bit in the Command
; Flags is set, indicating that the message
; is proxiable.
e-bit = ", ERR"
; If present, the 'E' bit in the Command
; Flags is set, indicating that the answer
; message contains a Result-Code AVP in
; the "protocol error" class.
fixed = [qual] "<" avp-spec ">"
; Defines the fixed position of an AVP
required = [qual] "{" avp-spec "}"
; The AVP MUST be present and can appear
; anywhere in the message.
optional = [qual] "[" avp-name "]"
; The avp-name in the 'optional' rule cannot
; evaluate to any AVP Name which is included
; in a fixed or required rule. The AVP can
; appear anywhere in the message.
qual = [min] "*" [max]
; See ABNF conventions, RFC 2234 Section 6.6.
; The absence of any qualifiers depends on whether
; it precedes a fixed, required, or optional
; rule. If a fixed or required rule has no
; qualifier, then exactly one such AVP MUST
; be present. If an optional rule has no
; qualifier, then 0 or 1 such AVP may be
; present.
;
; NOTE: "[" and "]" have a different meaning
; than in ABNF (see the optional rule, above).
; These braces cannot be used to express
; optional fixed rules (such as an optional
; ICV at the end). To do this, the convention
; is '0*1fixed'.
min = 1*DIGIT
; The minimum number of times the element may
; be present. The default value is zero.
max = 1*DIGIT
; The maximum number of times the element may
; be present. The default value is infinity. A
; value of zero implies the AVP MUST NOT be
; present.
avp-spec = diameter-name
; The avp-spec has to be an AVP Name, defined
; in the base or extended Diameter
; specifications.
avp-name = avp-spec / "AVP"
; The string "AVP" stands for *any* arbitrary
; AVP Name, which does not conflict with the
; required or fixed position AVPs defined in
; the command code definition.Now the grammar is out of the way 💅 Here's a totally made-up command code, because examples are literally the best 🧚:
Example-Request ::= < "Diameter-Header: 9999999, REQ, PXY >
{ User-Name }
* { Origin-Host }
* [ AVP3.3. Diameter Command Naming Conventions 💖
Okay so Diameter command names usually have one or more English words, then the verb Request or Answer at the end. Every English word gets a hyphen between it and the next one 🫶. There's also a three-letter acronym for both the request and the answer, and that's normally provided too.
An example is a message set used to terminate a session 🌸. The command name is Session-Terminate-Request and Session-Terminate-Answer, and the acronyms are STR and STA, respectively.
Both the request and the answer for a given command share the same command code, which is giving consistency ✨. The request is identified by the R(equest) bit in the Diameter header set to one (1), asking that a particular action be performed, like authorizing a user or terminating a session. Once the receiver has finished the request, it sends back the matching answer, which includes a result code that says one of the following:
- The request was successful
- The request failed
- An additional request must be sent to provide information the peer requires prior to returning a successful or failed answer.
- The receiver could not process the request, but provides information about a Diameter peer that is able to satisfy the request, known as redirect.
Additional information, encoded within AVPs, MAY also be included in answer messages 🦋.
4. Diameter AVPs 🎀
Diameter AVPs are the little containers that carry the good stuff 🧁: authentication, accounting, authorization, routing and security information, plus configuration details for both the request and the reply.
Some AVPs MAY be listed more than once. What that does is specific to each AVP, and the AVP description spells it out 💅.
Each AVP of type OctetString MUST be padded to align on a 32-bit boundary, while other AVP types align naturally. Zero-valued bytes get added to the end of the AVP Data field until a word boundary is reached. The padding length is not reflected in the AVP Length field 🙈.
4.1. AVP Header
The fields in the AVP header MUST be sent in network byte order. Here's the layout 👑:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| AVP Code |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|V M P r r r r r| AVP Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Vendor-ID (opt) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Data ...
+-+-+-+-+-+-+-+-+AVP Code : The AVP Code, combined with the Vendor-Id field, identifies the attribute uniquely. AVP numbers 1 through 255 are reserved for backward compatibility with RADIUS, without setting the Vendor-Id field. AVP numbers 256 and above are used for Diameter, and they're allocated by IANA (see Section 11.1) 🌈.
AVP Flags : The AVP Flags field tells the receiver how each attribute must be handled. The 'r' (reserved) bits are unused and SHOULD be set to 0. Subsequent Diameter applications MAY define additional bits within the AVP Header, and an unrecognized bit SHOULD be considered an error. The 'P' bit indicates the need for encryption for end-to-end security 🔐.
The 'M' Bit, known as the Mandatory bit, indicates whether support of the AVP is required. If an AVP with the 'M' bit set is received by a Diameter client, server, proxy, or translation agent and either the AVP or its value is unrecognized, the message MUST be rejected. Diameter Relay and redirect agents MUST NOT reject messages with unrecognized AVPs. Main character agent energy 💅.
The 'M' bit MUST be set according to the rules defined for the AVP containing it. To keep interoperability intact, a Diameter implementation MUST be able to exclude from a Diameter message any Mandatory AVP which is neither defined in the base Diameter protocol nor in any of the Diameter Application specifications governing the message in which it appears. It MAY do this in one of the following ways:
- If a message is rejected because it contains a Mandatory AVP which is neither defined in the base Diameter standard nor in any of the Diameter Application specifications governing the message in which it appears, the implementation may resend the message without the AVP, possibly inserting additional standard AVPs instead.
- A configuration option may be provided on a system wide, per peer, or per realm basis that would allow/prevent particular Mandatory AVPs to be sent. Thus an administrator could change the configuration to avoid interoperability problems 🛠️.
Diameter implementations are required to support all Mandatory AVPs which are allowed by the message's formal syntax and defined either in the base Diameter standard or in one of the Diameter Application specifications governing the message.
AVPs with the 'M' bit cleared are informational only, and a receiver that gets a message with such an AVP that is not supported, or whose value is not supported, MAY simply ignore the AVP 🫠.
The 'V' bit, known as the Vendor-Specific bit, indicates whether the optional Vendor-ID field is present in the AVP header. When set, the AVP Code belongs to the specific vendor code address space 🧩.
Unless otherwise noted, AVPs will have the following default AVP Flags field settings:
- The 'M' bit MUST be set. The 'V' bit MUST NOT be set.
AVP Length : The AVP Length field is three octets, and it indicates the number of octets in this AVP, including the AVP Code, AVP Length, AVP Flags, Vendor-ID field (if present) and the AVP data. If a message is received with an invalid attribute length, the message SHOULD be rejected 🚫.
4.1.1. Optional Header Elements
The AVP Header contains one optional field. That field is only present if the respective bit-flag is enabled ✨.
Vendor-ID : The Vendor-ID field is present if the 'V' bit is set in the AVP Flags field. The optional four-octet Vendor-ID field contains the IANA assigned "SMI Network Management Private Enterprise Codes" [ASSIGNNO] value, encoded in network byte order. Any vendor wishing to implement a vendor-specific Diameter AVP MUST use their own Vendor-ID along with their privately managed AVP address space, which guarantees they won't collide with any other vendor's vendor-specific AVP(s), nor with future IETF applications 💜.
A vendor ID value of zero (0) corresponds to the IETF adopted AVP values, as managed by the IANA. Since the absence of the vendor ID field implies that the AVP in question is not vendor specific, implementations MUST NOT use the zero (0) vendor ID 🙅♀️.
4.2. Basic AVP Data Formats ✨
okay so the Data field is zero or more octets 🧸 and it holds whatever info the Attribute needs. Its format and length come from the AVP Code and AVP Length fields. The Data field's format MUST be one of the base data types below, or a type built from them 💅. If a brand-new Basic AVP Data Format is ever needed, a new version of this RFC MUST be created, so no sneaky new types 🙅♀️
OctetString 🫧 is the chill one: arbitrary data of variable length. Unless noted otherwise, the AVP Length field MUST be set to at least 8 (12 if the 'V' bit is enabled). If an OctetString value isn't a multiple of four octets, padding gets added so the next AVP (if there is one) starts on a 32-bit boundary 🎀
Integer32 is a 32-bit signed value in network byte order 🔢. The AVP Length field MUST be set to 12 (16 if the 'V' bit is enabled).
Integer64 is a 64-bit signed value in network byte order 🌸. The AVP Length field MUST be set to 16 (20 if the 'V' bit is enabled).
Unsigned32 is a 32-bit unsigned value in network byte order 💜. The AVP Length field MUST be set to 12 (16 if the 'V' bit is enabled).
Unsigned64 is a 64-bit unsigned value in network byte order ✨. The AVP Length field MUST be set to 16 (20 if the 'V' bit is enabled).
Float32 is single-precision floating point, as described by [FLOATPOINT] 🦋. The 32-bit value goes over the wire in network byte order, and the AVP Length field MUST be set to 12 (16 if the 'V' bit is enabled).
Float64 is double-precision floating point, as described by [FLOATPOINT] 🌈. The 64-bit value goes over the wire in network byte order, and the AVP Length field MUST be set to 16 (20 if the 'V' bit is enabled).
Grouped is the bundle queen 👑. Its Data field is a sequence of AVPs, each one following the previous one in the order they're specified, headers and padding included. The AVP Length field is 8 (12 if the 'V' bit is enabled) plus the total length of everything inside, headers and padding included. So a Grouped AVP's length is always a multiple of 4 🍓
4.3. Derived AVP Data Formats
okay so apart from the Basic ones, applications are allowed to make their own formats derived from the Basic AVP Data Formats 🧚. Any application that defines a new AVP Derived Data Format MUST include it in a section called "AVP Derived Data Formats", written the same way as the definitions here. Each new definition has to either be defined in full or listed with a reference to the RFC that defines it 📚
These are the AVP Derived Data Formats that applications use a lot 💖
Address is derived from OctetString and it's a discriminated union 🗺️. It can hold, for example, a 32-bit ([IPV4]) or 128-bit ([IPV6]) address, most significant octet first. The first two octets are the AddressType, which holds an Address Family defined in [IANAADFAM]. That AddressType is what tells you how to read the rest of the octets 🔍
Time is also derived from OctetString 🕰️. The string MUST contain four octets, in the same format as the first four bytes of the NTP timestamp format. That NTP Timestamp format is defined in chapter 3 of [SNTP]. The value is the number of seconds since 0h on 1 January 1900, in Coordinated Universal Time (UTC) ⏰
⚠️ bestie, the Time value overflows on 6h 28m 16s UTC, 7 February 2036! 😭 [SNTP] has a procedure to extend it to 2104, and that procedure MUST be supported by all DIAMETER nodes. no excuses 🫶
UTF8String is also derived from OctetString 🌷. It's a human-readable string using the ISO/IEC IS 10646-1 character set, encoded as an OctetString with the UTF-8 [UFT8] transformation format described in RFC 2279 🌍. Since 10646 keeps getting amendments that add new code points, implementations MUST be ready to meet any code point from 0x00000001 to 0x7fffffff. Byte sequences that aren't valid UTF-8 encodings of a code point, or that fall outside that range, are prohibited 🚫
Using control codes SHOULD be avoided. If you need to show a new line, the control code sequence CR LF SHOULD be used 🍃. Leading or trailing white space SHOULD be avoided too ✂️. For code points that the user interface hardware or software can't show directly, an alternative means of entry and display, such as hexadecimal, MAY be provided 🔡
Fun fact 🤓: for information encoded in 7-bit US-ASCII, UTF-8 is identical to US-ASCII. UTF-8 can take several bytes for one character or code point, so the length in octets of a UTF8String can be different from the number of characters in it. And the AVP Length field of a UTF8String is measured in octets, not characters, so keep that straight 🧠
DiameterIdentity is derived from OctetString too 🪪. Its definition is:
DiameterIdentity = FQDNA DiameterIdentity uniquely identifies a Diameter node, and it's used for duplicate connection and routing loop detection 🔁. The contents of the string MUST be the FQDN of the Diameter node. If several Diameter nodes run on the same host, each one MUST be assigned its own unique DiameterIdentity 🏠. If a node can be identified by several FQDNs, a single FQDN should be picked at startup and used as the only DiameterIdentity for that node, no matter which connection it's sent on 💅
DiameterURI is how you write a Diameter host identity 🔗. A DiameterURI MUST follow the URI syntax [URI] rules below:
"aaa://" FQDN [ port ] [ transport ] [ protocol ]
; No transport security
"aaas://" FQDN [ port ] [ transport ] [ protocol ]
; Transport security used
FQDN = Fully Qualified Host Name
port = ":" 1*DIGIT
; One of the ports used to listen for
; incoming connections.
; If absent,
; the default Diameter port (3868) is
; assumed.
transport = ";transport=" transport-protocol
; One of the transports used to listen
; for incoming connections. If absent,
; the default SCTP [SCTP] protocol is
; assumed. UDP MUST NOT be used when
; the aaa-protocol field is set to
; diameter.
transport-protocol = ( "tcp" / "sctp" / "udp" )
protocol = ";protocol=" aaa-protocol
; If absent, the default AAA protocol
; is diameter.
aaa-protocol = ( "diameter" / "radius" / "tacacs+" )Quick heads-up on that one 👀: aaa:// means no transport security, while aaas:// means transport security is in use. And UDP MUST NOT be used when the aaa-protocol field is set to diameter 🙅♀️
Here are some valid Diameter host identities to vibe check 🎀:
aaa://host.example.com;transport=tcp
aaa://host.example.com:6666;transport=tcp
aaa://host.example.com;protocol=diameter
aaa://host.example.com:6666;protocol=diameter
aaa://host.example.com:6666;transport=tcp;protocol=diameter
aaa://host.example.com:1813;transport=udp;protocol=radiusEnumerated is derived from the Integer32 AVP Base Format 🔢. It has a list of valid values and what each one means, and that list lives in the Diameter application that introduces the AVP 🌟
IPFilterRule is derived from OctetString and uses the ASCII charset 🛡️. Packets can get filtered based on this info attached to them:
- Direction (in or out)
- Source and destination IP address (possibly masked)
- Protocol
- Source and destination port (lists or ranges)
- TCP flags
- IP fragment flag
- IP options
- ICMP types
Rules for the right direction get evaluated in order, and the first rule that matches ends the evaluation 🏁. Each packet is only evaluated once. If no rule matches, the packet gets dropped if the last rule evaluated was a permit, and passed if the last rule was a deny 🙃
IPFilterRule filters MUST follow this format:
action dir proto from src to dst [options]Here's what each piece means 🧩:
action:permitlets packets that match the rule through,denydrops them.dir:"in"is from the terminal,"out"is to the terminal.proto: an IP protocol given by number. The"ip"keyword means any protocol will match.srcanddst:<address/mask> [ports]
For the <address/mask> part, there are a few ways to write it 🗝️:
ipno: an IPv4 or IPv6 number in dotted-quad or canonical IPv6 form. Only this exact IP number matches the rule.ipno/bits: an IP number like the above with a mask width, such as1.2.3.4/24. In that case, all IP numbers from1.2.3.0to1.2.3.255match. The bit width MUST be valid for the IP version, and the IP number MUST NOT have bits set beyond the mask. For a match to happen, the packet has to carry the same IP version as the one used to describe the IP address. To test for a particular IP version, the bits part can be set to zero. The keywordanymeans0.0.0.0/0or its IPv6 equivalent. The keywordassignedmeans the address or set of addresses assigned to the terminal. For IPv4, a typical first rule is oftendeny in ip! assigned🌷
You can invert the sense of a match by putting the not modifier (!) in front of an address, which makes all other addresses match instead. This doesn't change how port numbers get selected 🔄
With the TCP, UDP and SCTP protocols, you can also specify ports like this:
{port/port-port}[,ports[,...]]The - notation covers a range of ports, boundaries included 📏
Fragmented packets with a non-zero offset (so, not the first fragment) will never match a rule that has one or more port specifications 🧩. Check the frag option for details on matching fragmented packets 🫶
options are where the fun is, bestie 💅
frag🧩 Match if the packet is a fragment and this is not the first fragment of the datagram.fragmay not be used in conjunction with eithertcpflagsor TCP/UDP port specifications.ipoptions spec🛣️ Match if the IP header contains the comma separated list of options specified in spec. The supported IP options aressrr(strict source route),lsrr(loose source route),rr(record packet route) andts(timestamp). The absence of a particular option may be denoted with a!.tcpoptions spec🎀 Match if the TCP header contains the comma separated list of options specified in spec. The supported TCP options aremss(maximum segment size),window(tcp window advertisement),sack(selective ack),ts(rfc1323 timestamp) andcc(rfc1644 t/tcp connection count). The absence of a particular option may be denoted with a!.established🤝 TCP packets only. Match packets that have the RST or ACK bits set.setup🌱 TCP packets only. Match packets that have the SYN bit set but no ACK bit.tcpflags spec🚩 TCP packets only. Match if the TCP header contains the comma separated list of flags specified in spec. The supported TCP flags arefin,syn,rst,psh,ackandurg. The absence of a particular flag may be denoted with a!. A rule that contains atcpflagsspecification can never match a fragmented packet that has a non-zero offset. See thefragoption for details on matching fragmented packets.icmptypes types🏓 ICMP packets only. Match if the ICMP type is in the list types. The list may be specified as any combination of ranges or individual types separated by commas. Both the numeric values and the symbolic values listed below can be used. The supported ICMP types are: echo reply (0), destination unreachable (3), source quench (4), redirect (5), echo request (8), router advertisement (9), router solicitation (10), time-to-live exceeded (11), IP header bad (12), timestamp request (13), timestamp reply (14), information request (15), information reply (16), address mask request (17) and address mask reply (18).
Okay now the most important bit 🚨 There is one kind of packet that the access device MUST always discard, and that is an IP fragment with a fragment offset of one. It's a valid packet, but it only has one use, which is trying to circumvent firewalls. Not it, not on my watch 😤
An access device that is unable to interpret or apply a deny rule MUST terminate the session. An access device that is unable to interpret or apply a permit rule MAY apply a more restrictive rule. An access device MAY apply deny rules of its own before the supplied rules, for example to protect the access device owner's infrastructure.
The rule syntax is a modified subset of ipfw(8) from FreeBSD, and the ipfw.c code may provide a useful base for implementations. Pure main character energy from FreeBSD 🦋
QoSFilterRule 💖
The QosFilterRule format is derived from the OctetString AVP Base Format. It uses the ASCII charset. Packets may be marked or metered based on the following information that is associated with it:
- Direction (in or out)
- Source and destination IP address (possibly masked)
- Protocol
- Source and destination port (lists or ranges)
- DSCP values (no mask or range)
Rules for the appropriate direction are evaluated in order, with the first matched rule terminating the evaluation. Each packet is evaluated once. If no rule matches, the packet is treated as best effort. An access device that is unable to interpret or apply a QoS rule SHOULD NOT terminate the session. Gentle vibes only 🌸
QoSFilterRule filters MUST follow the format:
action dir proto from src to dst [options]tag🏷️ Mark packet with a specific DSCP [DIFFSERV]. The DSCP option MUST be included.meter📏 Meter traffic. The metering options MUST be included.dirThe format is as described under IPFilterRule.protoThe format is as described under IPFilterRule.srcanddstThe format is as described under IPFilterRule.
4.4. Grouped AVP Values 🧺
The Diameter protocol allows AVP values of type 'Grouped.' This implies that the Data field is actually a sequence of AVPs. It is possible to include an AVP with a Grouped type within a Grouped type, that is, to nest them. AVPs within an AVP of type Grouped have the same padding requirements as non-Grouped AVPs, as defined in Section 4. Matryoshka vibes 🪆
The AVP Code numbering space of all AVPs included in a Grouped AVP is the same as for non-grouped AVPs. Further, if any of the AVPs encapsulated within a Grouped AVP has the 'M' (mandatory) bit set, the Grouped AVP itself MUST also include the 'M' bit set. Don't let the mandatory bit slip through the cracks 🙈
Every Grouped AVP defined MUST include a corresponding grammar, using ABNF [ABNF] (with modifications), as defined below. The grammar is written like this:
grouped-avp-def = name "::=" avp
name-fmt = ALPHA *(ALPHA / DIGIT / "-")
name = name-fmt
; The name has to be the name of an AVP,
; defined in the base or extended Diameter
; specifications.
avp = header [ *fixed] [ *required] [ *optional]
[ *fixed]
header = "<" "AVP-Header:" avpcode [vendor] ">"
avpcode = 1*DIGIT
; The AVP Code assigned to the Grouped AVP
vendor = 1*DIGIT
; The Vendor-ID assigned to the Grouped AVP.
; If absent, the default value of zero is
; used.4.4.1. Example AVP with a Grouped Data type 🧚
The Example-AVP (AVP Code 999999) is of type Grouped and is used to clarify how Grouped AVP values work. The Grouped Data field has the following ABNF grammar:
Example-AVP ::= < AVP Header: 999999 >
{ Origin-Host }
1*{ Session-Id }
*[ AVP ]An Example-AVP with Grouped Data follows. ✨
The Origin-Host AVP is required (Section 6.3). In this case:
Origin-Host = "example.com".One or more Session-Ids must follow. Here there are two:
Session-Id =
"grump.example.com:33041;23432;893;0AF3B81"
Session-Id =
"grump.example.com:33054;23561;2358;0AF3B82"optional AVPs included are
Recovery-Policy = <binary>
2163bc1d0ad82371f6bc09484133c3f09ad74a0dd5346d54195a7cf0b35
2cabc881839a4fdcfbc1769e2677a4c1fb499284c5f70b48f58503a45c5
c2d6943f82d5930f2b7c1da640f476f0e9c9572a50db8ea6e51e1c2c7bd
f8bb43dc995144b8dbe297ac739493946803e1cee3e15d9b765008a1b2a
cf4ac777c80041d72c01e691cf751dbf86e85f509f3988e5875dc905119
26841f00f0e29a6d1ddc1a842289d440268681e052b30fb638045f7779c
1d873c784f054f688f5001559ecff64865ef975f3e60d2fd7966b8c7f92
Futuristic-Acct-Record = <binary>
fe19da5802acd98b07a5b86cb4d5d03f0314ab9ef1ad0b67111ff3b90a0
57fe29620bf3585fd2dd9fcc38ce62f6cc208c6163c008f4258d1bc88b8
17694a74ccad3ec69269461b14b2e7a4c111fb239e33714da207983f58c
41d018d56fe938f3cbf089aac12a912a2f0d1923a9390e5f789cb2e5067
d3427475e49968f841The data for the optional AVPs is represented in hex since the format of these AVPs is neither known at the time of definition of the Example-AVP group, nor (likely) at the time when the example instance of this AVP is interpreted, except by Diameter implementations which support the same set of AVPs. The encoding example illustrates how padding is used and how length fields are calculated. Also note that AVPs may be present in the Grouped AVP value which the receiver cannot interpret (here, the Recover-Policy and Futuristic-Acct-Record AVPs). Sneaky unknown AVPs, we see you 👀
This AVP would be encoded as follows:
0 1 2 3 4 5 6 7
+-------+-------+-------+-------+-------+-------+-------+-------+
0 | Example AVP Header (AVP Code = 999999), Length = 468 |
+-------+-------+-------+-------+-------+-------+-------+-------+
8 | Origin-Host AVP Header (AVP Code = 264), Length = 19 |
+-------+-------+-------+-------+-------+-------+-------+-------+
16 | 'e' | 'x' | 'a' | 'm' | 'p' | 'l' | 'e' | '.' |
+-------+-------+-------+-------+-------+-------+-------+-------+
24 | 'c' | 'o' | 'm' |Padding| Session-Id AVP Header |
+-------+-------+-------+-------+-------+-------+-------+-------+
32 | (AVP Code = 263), Length = 50 | 'g' | 'r' | 'u' | 'm' |
+-------+-------+-------+-------+-------+-------+-------+-------+
. . .
+-------+-------+-------+-------+-------+-------+-------+-------+
64 | 'A' | 'F' | '3' | 'B' | '8' | '1' |Padding|Padding|
+-------+-------+-------+-------+-------+-------+-------+-------+
72 | Session-Id AVP Header (AVP Code = 263), Length = 51 |
+-------+-------+-------+-------+-------+-------+-------+-------+
80 | 'g' | 'r' | 'u' | 'm' | 'p' | '.' | 'e' | 'x' |
+-------+-------+-------+-------+-------+-------+-------+-------+
. . .
+-------+-------+-------+-------+-------+-------+-------+-------+
104 | '0' | 'A' | 'F' | '3' | 'B' | '8' | '2' |Padding|
+-------+-------+-------+-------+-------+-------+-------+-------+
112 | Recovery-Policy Header (AVP Code = 8341), Length = 223 |
+-------+-------+-------+-------+-------+-------+-------+-------+
120 | 0x21 | 0x63 | 0xbc | 0x1d | 0x0a | 0xd8 | 0x23 | 0x71 |
+-------+-------+-------+-------+-------+-------+-------+-------+
. . .
+-------+-------+-------+-------+-------+-------+-------+-------+
320 | 0x2f | 0xd7 | 0x96 | 0x6b | 0x8c | 0x7f | 0x92 |Padding|
+-------+-------+-------+-------+-------+-------+-------+-------+
328 | Futuristic-Acct-Record Header (AVP Code = 15930), Length = 137|
+-------+-------+-------+-------+-------+-------+-------+-------+
336 | 0xfe | 0x19 | 0xda | 0x58 | 0x02 | 0xac | 0xd9 | 0x8b |
+-------+-------+-------+-------+-------+-------+-------+-------+
. . .
+-------+-------+-------+-------+-------+-------+-------+-------+
464 | 0x41 |Padding|Padding|Padding|
+-------+-------+-------+-------+4.5. Diameter Base Protocol AVPs ✨
okay so this is the big list of every base protocol AVP you need to know, bestie 🫶 The table tells you each one's name, its AVP Code, its data type, the flag rules, and whether it MAY be encrypted 🔐
quick decoder for the "Encr" column: if a message with that AVP is going through a Diameter agent (proxy, redirect or relay), the originator MUST NOT send it unless there's end-to-end security between the originator and recipient that protects that AVP's integrity/confidentiality, OR the originator has locally trusted config saying end-to-end security isn't needed 💅
and the "P" in the "MAY" column is basically the same vibe: the message MUST NOT be sent via an agent unless there's end-to-end security between originator and recipient, or the originator has locally trusted config saying it isn't needed 🙈
also, to save space, we're using DiamIdent as the short form of DiameterIdentity 🎀
+---------------------+
| AVP Flag rules |
|----+-----+----+-----|----+
AVP Section | | |SHLD| MUST| |
Attribute Name Code Defined Data Type |MUST| MAY | NOT| NOT|Encr|
-----------------------------------------|----+-----+----+-----|----|
Acct- 85 9.8.2 Unsigned32 | M | P | | V | Y |
Interim-Interval | | | | | |
Accounting- 483 9.8.7 Enumerated | M | P | | V | Y |
Realtime-Required | | | | | |
Acct- 50 9.8.5 UTF8String | M | P | | V | Y |
Multi-Session-Id | | | | | |
Accounting- 485 9.8.3 Unsigned32 | M | P | | V | Y |
Record-Number | | | | | |
Accounting- 480 9.8.1 Enumerated | M | P | | V | Y |
Record-Type | | | | | |
Accounting- 44 9.8.4 OctetString| M | P | | V | Y |
Session-Id | | | | | |
Accounting- 287 9.8.6 Unsigned64 | M | P | | V | Y |
Sub-Session-Id | | | | | |
Acct- 259 6.9 Unsigned32 | M | P | | V | N |
Application-Id | | | | | |
Auth- 258 6.8 Unsigned32 | M | P | | V | N |
Application-Id | | | | | |
Auth-Request- 274 8.7 Enumerated | M | P | | V | N |
Type | | | | | |
Authorization- 291 8.9 Unsigned32 | M | P | | V | N |
Lifetime | | | | | |
Auth-Grace- 276 8.10 Unsigned32 | M | P | | V | N |
Period | | | | | |
Auth-Session- 277 8.11 Enumerated | M | P | | V | N |
State | | | | | |
Re-Auth-Request- 285 8.12 Enumerated | M | P | | V | N |
Type | | | | | |
Class 25 8.20 OctetString| M | P | | V | Y |
Destination-Host 293 6.5 DiamIdent | M | P | | V | N |
Destination- 283 6.6 DiamIdent | M | P | | V | N |
Realm | | | | | |
Disconnect-Cause 273 5.4.3 Enumerated | M | P | | V | N |
E2E-Sequence AVP 300 6.15 Grouped | M | P | | V | Y |
Error-Message 281 7.3 UTF8String | | P | | V,M | N |
Error-Reporting- 294 7.4 DiamIdent | | P | | V,M | N |
Host | | | | | |
Event-Timestamp 55 8.21 Time | M | P | | V | N |
Experimental- 297 7.6 Grouped | M | P | | V | N |
Result | | | | | |
-----------------------------------------|----+-----+----+-----|----|
+---------------------+
| AVP Flag rules |
|----+-----+----+-----|----+
AVP Section | | |SHLD| MUST|MAY |
Attribute Name Code Defined Data Type |MUST| MAY | NOT| NOT|Encr|
-----------------------------------------|----+-----+----+-----|----|
Experimental- 298 7.7 Unsigned32 | M | P | | V | N |
Result-Code | | | | | |
Failed-AVP 279 7.5 Grouped | M | P | | V | N |
Firmware- 267 5.3.4 Unsigned32 | | | |P,V,M| N |
Revision | | | | | |
Host-IP-Address 257 5.3.5 Address | M | P | | V | N |
Inband-Security | M | P | | V | N |
-Id 299 6.10 Unsigned32 | | | | | |
Multi-Round- 272 8.19 Unsigned32 | M | P | | V | Y |
Time-Out | | | | | |
Origin-Host 264 6.3 DiamIdent | M | P | | V | N |
Origin-Realm 296 6.4 DiamIdent | M | P | | V | N |
Origin-State-Id 278 8.16 Unsigned32 | M | P | | V | N |
Product-Name 269 5.3.7 UTF8String | | | |P,V,M| N |
Proxy-Host 280 6.7.3 DiamIdent | M | | | P,V | N |
Proxy-Info 284 6.7.2 Grouped | M | | | P,V | N |
Proxy-State 33 6.7.4 OctetString| M | | | P,V | N |
Redirect-Host 292 6.12 DiamURI | M | P | | V | N |
Redirect-Host- 261 6.13 Enumerated | M | P | | V | N |
Usage | | | | | |
Redirect-Max- 262 6.14 Unsigned32 | M | P | | V | N |
Cache-Time | | | | | |
Result-Code 268 7.1 Unsigned32 | M | P | | V | N |
Route-Record 282 6.7.1 DiamIdent | M | | | P,V | N |
Session-Id 263 8.8 UTF8String | M | P | | V | Y |
Session-Timeout 27 8.13 Unsigned32 | M | P | | V | N |
Session-Binding 270 8.17 Unsigned32 | M | P | | V | Y |
Session-Server- 271 8.18 Enumerated | M | P | | V | Y |
Failover | | | | | |
Supported- 265 5.3.6 Unsigned32 | M | P | | V | N |
Vendor-Id | | | | | |
Termination- 295 8.15 Enumerated | M | P | | V | N |
Cause | | | | | |
User-Name 1 8.14 UTF8String | M | P | | V | Y |
Vendor-Id 266 5.3.3 Unsigned32 | M | P | | V | N |
Vendor-Specific- 260 6.11 Grouped | M | P | | V | N |
Application-Id | | | | | |
-----------------------------------------|----+-----+----+-----|----|5. Diameter Peers 🌸
this section is all about how Diameter nodes set up connections and chat with their peers 💬
5.1. Peer Connections 🦋
okay so a Diameter node can know a bunch of possible peers, but it's not really economical to keep a connection open to every single one 🙃 At a minimum, a Diameter node SHOULD have an established connection with two peers per realm, called the primary and secondary peers. Of course, a node MAY have additional connections if it's deemed necessary ✨ Typically, all messages for a realm go to the primary peer, but if failover procedures get invoked, any pending requests get sent to the secondary peer. Implementations are free to load balance requests between a set of peers too, so no pressure 💖
Note that a given peer MAY act as a primary for one realm while acting as a secondary for another realm 🌈
when a peer is deemed suspect (which can happen for various reasons, including not receiving a DWA within an allotted timeframe), no new requests should be forwarded to that peer, but failover procedures get invoked 🚨 When an active peer is moved into this mode, additional connections SHOULD be established so the necessary number of active connections still exists 🫶
there are two ways a peer gets removed from the suspect peer list 👑
- the peer is no longer reachable, which shuts down the transport connection, and the peer moves to the closed state 💀
- three watchdog messages get exchanged with accepted round trip times, and the connection to the peer is considered stabilized 🧚
in the event the peer being removed is either the primary or secondary, an alternate peer SHOULD replace the deleted peer and assume the role of either primary or secondary 🍓 that's literally the main character energy of failover, bestie 😭
5.2. Diameter Peer Discovery 🧚
okay bestie, dynamic agent discovery is giving simpler and more robust Diameter deployments 💅. To keep peer discovery interoperable between implementations, these mechanisms are described, and they're all based on existing IETF standards 🎀. The first option (manual configuration) MUST be supported by all DIAMETER nodes, while the latter two options (SRVLOC and DNS) MAY be supported ✨.
There are two situations where peer discovery happens. The first is when a Diameter client needs to find a first-hop Diameter agent. The second is when a Diameter agent needs to find another agent so it can handle a Diameter operation further 🫶. In both cases, the following 'search order' is recommended:
- The Diameter implementation checks its list of static (manually) configured Diameter agent locations 📝. These get used if they exist and respond.
- The Diameter implementation uses SLPv2 [SLP] to discover Diameter services 🔍. The Diameter service template [TEMPLATE] is included in Appendix A.
It is recommended that SLPv2 security be deployed (this requires distributing keys to SLPv2 agents). This is discussed further in Appendix A. SLPv2 security SHOULD be used (requiring distribution of keys to SLPv2 agents) in order to ensure that discovered peers are authorized for their roles. SLPv2 is discussed further in Appendix A 🔐.
- The Diameter implementation performs a NAPTR query for a server in a particular realm 🌸. The Diameter implementation has to know in advance which realm to look for a Diameter agent in. This could be deduced, for example, from the 'realm' in a NAI that a Diameter implementation needed to perform a Diameter operation on.
- 3.1 The services relevant for the task of transport protocol selection are those with NAPTR service fields with values
AAA+D2x, where x is a letter that corresponds to a transport protocol supported by the domain. This specification defines D2T for TCP and D2S for SCTP. We also establish an IANA registry for NAPTR service name to transport protocol mappings 🦋.
- 3.1 The services relevant for the task of transport protocol selection are those with NAPTR service fields with values
These NAPTR records provide a mapping from a domain, to the SRV record for contacting a server with the specific transport protocol in the NAPTR services field. The resource record will contain an empty regular expression and a replacement value, which is the SRV record for that particular transport protocol. If the server supports multiple transport protocols, there will be multiple NAPTR records, each with a different service value. As per RFC 2915 [NAPTR], the client discards any records whose services fields are not applicable. For the purposes of this specification, several rules are defined.
- 3.2 A client MUST discard any service fields that identify a resolution service whose value is not "D2X", for values of X that indicate transport protocols supported by the client. The NAPTR processing as described in RFC 2915 will result in discovery of the most preferred transport protocol of the server that is supported by the client, as well as an SRV record for the server.
The domain suffixes in the NAPTR replacement field SHOULD match the domain of the original query 💜.
- If no NAPTR records are found, the requester queries for those address records for the destination address,
'_diameter._sctp'.realmor'_diameter._tcp'.realm. Address records include A RRs, AAAA RRs or other similar records, chosen according to the requestor's network protocol capabilities. If the DNS server returns no address records, the requestor gives up 😭.
If the server is using a site certificate, the domain name in the query and the domain name in the replacement field MUST both be valid based on the site certificate handed out by the server in the TLS or IKE exchange. Similarly, the domain name in the SRV query and the domain name in the target in the SRV record MUST both be valid based on the same site certificate. Otherwise, an attacker could modify the DNS records to contain replacement values in a different domain, and the client could not validate that this was the desired behavior, or the result of an attack 🚨.
Also, the Diameter Peer MUST check to make sure that the discovered peers are authorized to act in its role. Authentication via IKE or TLS, or validation of DNS RRs via DNSSEC is not sufficient to conclude this. For example, a web server may have obtained a valid TLS certificate, and secured RRs may be included in the DNS, but this does not imply that it is authorized to act as a Diameter Server. Main character energy for the wrong reasons 💀.
Authorization can be achieved for example, by configuration of a Diameter Server CA. Alternatively this can be achieved by definition of OIDs within TLS or IKE certificates so as to signify Diameter Server authorization 👑.
A dynamically discovered peer causes an entry in the Peer Table (see Section 2.6) to be created. Note that entries created via DNS MUST expire (or be refreshed) within the DNS TTL. If a peer is discovered outside of the local realm, a routing table entry (see Section 2.7) for the peer's realm is created. The routing table entry's expiration MUST match the peer's expiration value ⏰.
5.3. Capabilities Exchange 🤝
When two Diameter peers establish a transport connection, they MUST exchange the Capabilities Exchange messages, as specified in the peer state machine (see Section 5.6). This message allows the discovery of a peer's identity and its capabilities (protocol version number, supported Diameter applications, security mechanisms, etc.) 🪪.
The receiver only issues commands to its peers that have advertised support for the Diameter application that defines the command. A Diameter node MUST cache the supported applications in order to ensure that unrecognized commands and/or AVPs are not unnecessarily sent to a peer. Caching is a whole vibe 🧠.
A receiver of a Capabilities-Exchange-Req (CER) message that does not have any applications in common with the sender MUST return a Capabilities-Exchange-Answer (CEA) with the Result-Code AVP set to DIAMETER_NO_COMMON_APPLICATION, and SHOULD disconnect the transport layer connection. Note that receiving a CER or CEA from a peer advertising itself as a Relay (see Section 2.4) MUST be interpreted as having common applications with the peer 🫠.
Similarly, a receiver of a Capabilities-Exchange-Req (CER) message that does not have any security mechanisms in common with the sender MUST return a Capabilities-Exchange-Answer (CEA) with the Result-Code AVP set to DIAMETER_NO_COMMON_SECURITY, and SHOULD disconnect the transport layer connection 🔒.
CERs received from unknown peers MAY be silently discarded, or a CEA MAY be issued with the Result-Code AVP set to DIAMETER_UNKNOWN_PEER. In both cases, the transport connection is closed. If the local policy permits receiving CERs from unknown hosts, a successful CEA MAY be returned. If a CER from an unknown peer is answered with a successful CEA, the lifetime of the peer entry is equal to the lifetime of the transport connection. In case of a transport failure, all the pending transactions destined to the unknown peer can be discarded 🚪.
The CER and CEA messages MUST NOT be proxied, redirected or relayed. No middlemen allowed, periodt 🙅♀️.
Since the CER/CEA messages cannot be proxied, it is still possible that an upstream agent receives a message for which it has no available peers to handle the application that corresponds to the Command-Code. In such instances, the 'E' bit is set in the answer message (see Section 7.) with the Result-Code AVP set to DIAMETER_UNABLE_TO_DELIVER to inform the downstream to take action (e.g., re-routing request to an alternate peer) 🔁.
With the exception of the Capabilities-Exchange-Request message, a message of type Request that includes the Auth-Application-Id or Acct-Application-Id AVPs, or a message with an application-specific command code, MAY only be forwarded to a host that has explicitly advertised support for the application (or has advertised the Relay Application Identifier) 🎯.
5.3.1. Capabilities-Exchange-Request 📨
The Capabilities-Exchange-Request (CER), indicated by the Command-Code set to 257 and the Command Flags' 'R' bit set, is sent to exchange local capabilities. Upon detection of a transport failure, this message MUST NOT be sent to an alternate peer 🚫.
When Diameter is run over SCTP [SCTP], which allows for connections to span multiple interfaces and multiple IP addresses, the Capabilities-Exchange-Request message MUST contain one Host-IP-Address AVP for each potential IP address that MAY be locally used when transmitting Diameter messages 🌐.
Message Format
<CER> ::= < Diameter Header: 257, REQ >
{ Origin-Host }
{ Origin-Realm }
1* { Host-IP-Address }
{ Vendor-Id }
{ Product-Name }
[ Origin-State-Id ]
* [ Supported-Vendor-Id ]
* [ Auth-Application-Id ]
* [ Inband-Security-Id ]
* [ Acct-Application-Id ]
* [ Vendor-Specific-Application-Id ]
[ Firmware-Revision ]
* [ AVP ]5.3.2. Capabilities-Exchange-Answer 📬
The Capabilities-Exchange-Answer (CEA), indicated by the Command-Code set to 257 and the Command Flags' 'R' bit cleared, is sent in response to a CER message 💌.
When Diameter is run over SCTP [SCTP], which allows connections to span multiple interfaces, hence, multiple IP addresses, the Capabilities-Exchange-Answer message MUST contain one Host-IP-Address AVP for each potential IP address that MAY be locally used when transmitting Diameter messages 🌈.
Message Format
<CEA> ::= < Diameter Header: 257 >
{ Result-Code }
{ Origin-Host }
{ Origin-Realm }
1* { Host-IP-Address }
{ Vendor-Id }
{ Product-Name }
[ Origin-State-Id ]
[ Error-Message ]
* [ Failed-AVP ]
* [ Supported-Vendor-Id ]
* [ Auth-Application-Id ]
* [ Inband-Security-Id ]
* [ Acct-Application-Id ]
* [ Vendor-Specific-Application-Id ]
[ Firmware-Revision ]
* [ AVP ]5.3.3. Vendor-Id AVP 🏷️
The Vendor-Id AVP (AVP Code 266) is of type Unsigned32 and contains the IANA "SMI Network Management Private Enterprise Codes" [ASSIGNNO] value assigned to the vendor of the Diameter application. In combination with the Supported-Vendor-Id AVP (Section 5.3.6), this MAY be used in order to know which vendor specific attributes may be sent to the peer. It is also envisioned that the combination of the Vendor-Id, Product-Name (Section 5.3.7) and the Firmware-Revision (Section 5.3.4) AVPs MAY provide very useful debugging information. Future debugging bestie energy 🔎✨.
A Vendor-Id value of zero in the CER or CEA messages is reserved and indicates that this field is ignored 🙈.
5.3.4. Firmware-Revision AVP ✨
okay so the Firmware-Revision AVP (AVP Code 267) is an Unsigned32 🎀 and its whole job is to tell a Diameter peer which firmware revision the sending device is running 💅
and if the device doesn't have a firmware revision (like a general purpose computer running Diameter software modules, for example) then it's totally fine to report the revision of the Diameter software module instead 🧚
5.3.5. Host-IP-Address AVP 🌸
the Host-IP-Address AVP (AVP Code 257) is an Address type and it lets a peer know the sender's IP address 🫶 every source address that a Diameter node expects to use with SCTP [SCTP] MUST be advertised in the CER and CEA messages, with one Host-IP-Address AVP for each address 😭 and this AVP MUST ONLY be used in the CER and CEA messages, no exceptions bestie 🙈
5.3.6. Supported-Vendor-Id AVP 🦋
the Supported-Vendor-Id AVP (AVP Code 265) is an Unsigned32 and holds the IANA "SMI Network Management Private Enterprise Codes" [ASSIGNNO] value for a vendor that is NOT the device vendor 👑 the sender puts it in the CER and CEA messages to tell the peer that it supports (a subset of) the vendor-specific AVPs defined by that vendor 💜
5.3.7. Product-Name AVP 🍓
the Product-Name AVP (AVP Code 269) is a UTF8String that carries the vendor assigned name for the product ✨ the Product-Name AVP SHOULD stay the same across firmware revisions for the same product, because that's the whole point of a product name 💅🔥
5.4. Disconnecting Peer connections 🚪
okay this part is so relatable 😭 when a Diameter node drops one of its transport connections, the peer has no clue why, so it's probably going to assume there was a connectivity problem or that the other node rebooted 🥺 so the peer might keep trying to reconnect, like Section 2.1 says 🔁 but if the disconnect happened because the node ran low on internal resources, or because it just has no plans to forward any Diameter messages to that peer anytime soon, then constant reconnect attempts are NOT welcome at all 🙅♀️ that's where the Disconnection-Reason AVP comes in, because it holds the reason the Diameter node sent the Disconnect-Peer-Request message 🎀
the Disconnect-Peer-Request message is how a Diameter node says "hey, I'm about to disconnect the transport layer, and please don't reconnect unless you have a valid reason (like a message that needs forwarding)" 💖 when the peer gets it, it sends back the Disconnect-Peer-Answer, which SHOULD contain an error if messages were recently forwarded and are probably still in flight, because otherwise you'd get a race condition and nobody wants that chaos 😭🌪️
the receiver of the Disconnect-Peer-Answer is the one who actually starts the transport disconnect ✨
5.4.1. Disconnect-Peer-Request 🌈
the Disconnect-Peer-Request (DPR) is the message with Command-Code 282 and the 'R' bit set in the Command Flags 💜 it gets sent to a peer to let it know you're planning to shut down the transport connection 🧚 if a transport failure has been detected, this message MUST NOT be sent to an alternate peer, so don't be sneaky about it 🙅♀️
Message Format
<DPR> ::= < Diameter Header: 282, REQ >
{ Origin-Host }
{ Origin-Realm }
{ Disconnect-Cause }5.4.2. Disconnect-Peer-Answer 🎀
the Disconnect-Peer-Answer (DPA) is the message with Command-Code 282 and the 'R' bit cleared, and it's the response to a Disconnect-Peer-Request 💅 once you receive this one, the transport connection gets shut down, periodt ✨
Message Format
<DPA> ::= < Diameter Header: 282 >
{ Result-Code }
{ Origin-Host }
{ Origin-Realm }
[ Error-Message ]
* [ Failed-AVP ]5.4.3. Disconnect-Cause AVP 🌸
the Disconnect-Cause AVP (AVP Code 273) is an Enumerated type 🦋 a Diameter node MUST include this AVP in the Disconnect-Peer-Request message so the peer knows exactly why it's shutting the transport connection down 💖 these are the values that are supported:
REBOOTING 0
A scheduled reboot is imminent.
BUSY 1
The peer's internal resources are constrained, and it has
determined that the transport connection needs to be closed.
DO_NOT_WANT_TO_TALK_TO_YOU 2
The peer has determined that it does not see a need for the
transport connection to exist, since it does not expect any
messages to be exchanged in the near future.5.5. Transport Failure Detection 🔍
so since Diameter is the protocol it is, it's recommended that transport failures get detected as soon as possible 🏃♀️ catching them fast means fewer messages get sent to agents that are unavailable, which saves you from unnecessary delays and gives you way better failover performance 🔥 the Device-Watchdog-Request and Device-Watchdog-Answer messages (defined in this section) are how you proactively catch transport failures 🫶
5.5.1. Device-Watchdog-Request 🐶
the Device-Watchdog-Request (DWR) is the message with Command-Code 280 and the 'R' bit set 💅 it gets sent to a peer when no traffic has been exchanged between the two peers (see Section 5.5.3) 💜 and if a transport failure has been detected, this message MUST NOT be sent to an alternate peer 🙈
Message Format
<DWR> ::= < Diameter Header: 280, REQ >
{ Origin-Host }
{ Origin-Realm }
[ Origin-State-Id ]5.5.2. Device-Watchdog-Answer 🦋
the Device-Watchdog-Answer (DWA) is the message with Command-Code 280 and the 'R' bit cleared, and it's sent back as the response to a Device-Watchdog-Request 🧚
Message Format
<DWA> ::= < Diameter Header: 280 >
{ Result-Code }
{ Origin-Host }
{ Origin-Realm }
[ Error-Message ]
* [ Failed-AVP ]
[ Original-State-Id ]5.5.3. Transport Failure Algorithm 🧠
the transport failure algorithm is defined in [AAATRANS] 💖 every Diameter implementation MUST support the algorithm from that specification if it wants to be compliant with the Diameter base protocol, no shortcuts 👑
5.5.4. Failover and Failback Procedures 🔄
okay so when a transport failure is detected with a peer, all the pending request messages need to get forwarded to an alternate agent if that's possible 🏃♀️ this is commonly called failover 🌈
to pull off failover, a Diameter node has to keep a pending message queue for each given peer 📦 when an answer message comes in, the matching request gets removed from the queue, and the Hop-by-Hop Identifier field is what matches the answer to the queued request 🫶
when a transport failure is detected, all the messages in the queue get sent to an alternate agent with the T flag set, if that's possible 💅 when a Diameter client or agent boots up, the T flag is also set on any records still waiting to be sent in non-volatile storage ✨ there's one case where forwarding just isn't possible: when the message has a fixed destination and the unavailable peer is that message's final destination (see Destination-Host AVP) 😭 for that kind of error, the agent has to return an answer message with the 'E' bit set and the Result-Code AVP set to DIAMETER_UNABLE_TO_DELIVER 🙅♀️
it's important to note that multiple identical requests or answers MAY be received as a result of a failover 👀 to spot the duplicates, you MUST use the End-to-End Identifier field in the Diameter header along with the Origin-Host AVP 🔍
as described in Section 2.1, a connection request should be attempted with the failed peer periodically so the transport connection can be re-established 🔁 once a connection is successfully set up, messages can start flowing to that peer again, and this is commonly called failback 🎉🦋
5.6. Peer State Machine 💅✨
Okay bestie, this section is the big boss 🎀 It's a finite state machine, and every Diameter implementation MUST observe it. Each Diameter node MUST follow this state machine whenever it talks to each peer. Multiple actions are separated by commas and can wrap onto the next line when there's not enough room. The same goes for state and next state, so don't panic if a row looks like it's spilling over 🙈
This state machine is closely coupled with the one in [AAATRANS], which handles opening, closing, failing over, probing, and reopening transport connections. Heads up that [AAATRANS] requires watchdog messages to probe connections. For Diameter, we use DWR and DWA messages for that 🦋
Here's the naming trick. I- means the initiator (connecting) connection, and R- means the responder (listening) connection. If there's no prefix, the event or action is the same no matter which connection it happened on 🌸
The stable states are Closed, I-Open, and R-Open. Everything else is intermediate. I-Open and R-Open are basically twins, the only difference being whether the initiator or responder transport connection is the one doing the talking ✨
A CER message is always sent on the initiating connection right after the connection request completes successfully. If there's an election, one of the two connections shuts down. The responder connection survives if the local Diameter entity's Origin-Host is higher than the peer's. The initiator connection survives if the peer's Origin-Host is higher. After that, all messages go over the surviving connection. The results of an election on one peer are guaranteed to be the inverse of the results on the other, which is so iconic 👑
For TLS, the handshake starts once both ends are in the open state. If the handshake succeeds, everything else goes over TLS. If it fails, both ends drop to the closed state 🔥
The state machine only constrains how a Diameter implementation looks to its peers through what shows up on the wire. Any implementation that gives equivalent results counts as compliant 💖
state event action next state
-----------------------------------------------------------------
Closed Start I-Snd-Conn-Req Wait-Conn-Ack
R-Conn-CER R-Accept, R-Open
Process-CER,
R-Snd-CEA
Wait-Conn-Ack I-Rcv-Conn-Ack I-Snd-CER Wait-I-CEA
I-Rcv-Conn-Nack Cleanup Closed
R-Conn-CER R-Accept, Wait-Conn-Ack/
Process-CER Elect
Timeout Error Closed
Wait-I-CEA I-Rcv-CEA Process-CEA I-Open
R-Conn-CER R-Accept, Wait-Returns
Process-CER,
Elect
I-Peer-Disc I-Disc Closed
I-Rcv-Non-CEA Error Closed
Timeout Error Closed
Wait-Conn-Ack/ I-Rcv-Conn-Ack I-Snd-CER,Elect Wait-Returns
Elect I-Rcv-Conn-Nack R-Snd-CEA R-Open
R-Peer-Disc R-Disc Wait-Conn-Ack
R-Conn-CER R-Reject Wait-Conn-Ack/
Elect
Timeout Error Closed
Wait-Returns Win-Election I-Disc,R-Snd-CEA R-Open
I-Peer-Disc I-Disc, R-Open
R-Snd-CEA
I-Rcv-CEA R-Disc I-Open
R-Peer-Disc R-Disc Wait-I-CEA
R-Conn-CER R-Reject Wait-Returns
Timeout Error Closed
R-Open Send-Message R-Snd-Message R-Open
R-Rcv-Message Process R-Open
R-Rcv-DWR Process-DWR, R-Open
R-Snd-DWA
R-Rcv-DWA Process-DWA R-Open
R-Conn-CER R-Reject R-Open
Stop R-Snd-DPR Closing
R-Rcv-DPR R-Snd-DPA, Closed
R-Disc
R-Peer-Disc R-Disc Closed
R-Rcv-CER R-Snd-CEA R-Open
R-Rcv-CEA Process-CEA R-Open
I-Open Send-Message I-Snd-Message I-Open
I-Rcv-Message Process I-Open
I-Rcv-DWR Process-DWR, I-Open
I-Snd-DWA
I-Rcv-DWA Process-DWA I-Open
R-Conn-CER R-Reject I-Open
Stop I-Snd-DPR Closing
I-Rcv-DPR I-Snd-DPA, Closed
I-Disc
I-Peer-Disc I-Disc Closed
I-Rcv-CER I-Snd-CEA I-Open
I-Rcv-CEA Process-CEA I-Open
Closing I-Rcv-DPA I-Disc Closed
R-Rcv-DPA R-Disc Closed
Timeout Error Closed
I-Peer-Disc I-Disc Closed
R-Peer-Disc R-Disc Closed5.6.1. Incoming connections 🚪
When a connection request shows up from a Diameter peer, you usually can't know who that peer is until a CER arrives. That's because host and port identify a Diameter peer, and the source port of an incoming connection is random. Once the CER lands, the peer's identity can be pinned down from Origin-Host 🔍
So a Diameter peer needs separate logic, outside the state machine, to receive connection requests, accept them, and wait for CER. When a CER shows up on a new connection, the Origin-Host in it is used to find the state machine for that peer, and then the new connection and the CER get handed to that state machine as an R-Conn-CER event 🎀
The incoming-connection logic SHOULD close and discard the connection if any message other than CER arrives, or if an implementation-defined timeout goes off before CER shows up. Be a little strict here, babe 💅
Since handling incoming connections up to and including CER needs its own logic, separate from any individual peer's state machine, it gets described on its own here instead of in the state machine above 🌈
5.6.2. Events 🎉
Events are what set off the transitions and actions in the automaton. In this section we ignore the -I and -R prefixes, since the event would be identical no matter which of the two connections it happened on 🦋
Start: The Diameter application has signaled that a connection should be initiated with the peer.R-Conn-CER: An acknowledgement is received stating that the transport connection has been established, and the associated CER has arrived.Rcv-Conn-Ack: A positive acknowledgement is received confirming that the transport connection is established.Rcv-Conn-Nack: A negative acknowledgement was received stating that the transport connection was not established.Timeout: An application-defined timer has expired while waiting for some event.Rcv-CER: A CER message from the peer was received.Rcv-CEA: A CEA message from the peer was received.Rcv-Non-CEA: A message other than CEA from the peer was received.Peer-Disc: A disconnection indication from the peer was received.Rcv-DPR: A DPR message from the peer was received.Rcv-DPA: A DPA message from the peer was received.Win-Election: An election was held, and the local node was the winner.Send-Message: A message is to be sent.Rcv-Message: A message other than CER, CEA, DPR, DPA, DWR or DWA was received.Stop: The Diameter application has signaled that a connection should be terminated (e.g., on system shutdown).
5.6.3. Actions ⚡
Events trigger actions in the automaton, and actions usually mean sending packets and/or doing something to the connection. In this section we ignore the I- and R- prefixes, since the action would be the same on either connection 💜
Snd-Conn-Req: A transport connection is initiated with the peer.Accept: The incoming connection associated with theR-Conn-CERis accepted as the responder connection.Reject: The incoming connection associated with theR-Conn-CERis disconnected.Process-CER: The CER associated with theR-Conn-CERis processed.Snd-CER: A CER message is sent to the peer.Snd-CEA: A CEA message is sent to the peer.Cleanup: If necessary, the connection is shut down, and any local resources are freed.Error: The transport layer connection is disconnected, either politely or abortively, in response to an error condition. Local resources are freed.Process-CEA: A received CEA is processed.Snd-DPR: A DPR message is sent to the peer.Snd-DPA: A DPA message is sent to the peer.Disc: The transport layer connection is disconnected, and local resources are freed.Elect: An election occurs (see Section 5.6.4 for more information).Snd-Message: A message is sent.Snd-DWR: A DWR message is sent.Snd-DWA: A DWA message is sent.Process-DWR: The DWR message is serviced.Process-DWA: The DWA message is serviced.Process: A message is serviced.
5.6.4. The Election Process 🗳️
The election happens on the responder 👑 The responder compares the Origin-Host from the CER its peer sent with its own Origin-Host. If the local Diameter entity's Origin-Host is higher than the peer's, a Win-Election event fires locally.
Here's how the comparison works. The shorter OctetString gets padded with zeros until it's the same length as the longer one. Then the two get compared octet by octet as unsigned numbers, with the first octet being the most significant. Any leftover octets are treated as having the value 0x80 ✨
6. Diameter message processing 🧚
This section explains how Diameter requests and answers get created and processed. Let's go 🚀
6.1. Diameter Request Routing Overview
okay bestie, so a request finds its way to its final destination using a combo of the Destination-Realm and Destination-Host AVPs 💌 and there are three combos to know about ✨:
- a request that can't be proxied (like CER) MUST NOT contain either
Destination-RealmorDestination-HostAVPs. 🙅♀️ - a request that needs to reach a home server serving a specific realm, but not a specific server (like the first request of a series of round-trips), MUST contain a
Destination-RealmAVP, but MUST NOT contain aDestination-HostAVP. 🧚 - otherwise, a request that needs to reach a specific home server among those serving a given realm, MUST contain both the
Destination-RealmandDestination-HostAVPs. 👑
The Destination-Host AVP gets used like we just described when the destination is locked in 🔒, which includes:
- Authentication requests that span multiple round trips 🔁
- A Diameter message that uses a security mechanism that relies on a pre-established session key shared between the source and the final destination of the message 🔐
- Server initiated messages that MUST be received by a specific Diameter client (e.g., access device), such as the
Abort-Session-Requestmessage, which is used to request that a particular user's session be terminated 💀
Note that an agent can forward a request to a host described in the Destination-Host AVP only if that host is included in its peer table (see Section 2.7). Otherwise, the request is routed based on the Destination-Realm only (see Sections 6.1.6). 🙈
The Destination-Realm AVP MUST be present if the message is proxiable. Request messages that may be forwarded by Diameter agents (proxies, redirects or relays) MUST also contain an Acct-Application-Id AVP, an Auth-Application-Id AVP or a Vendor-Specific-Application-Id AVP. A message that MUST NOT be forwarded by Diameter agents (proxies, redirects or relays) MUST not include the Destination-Realm in its ABNF. The value of the Destination-Realm AVP MAY be extracted from the User-Name AVP, or from other application-specific methods. 📝
When a message comes in, it gets processed in this order, no skipping 🫶:
- If the message is destined for the local host, the procedures listed in Section 6.1.4 are followed.
- If the message is intended for a Diameter peer that the local host can directly communicate with, the procedures listed in Section 6.1.5 are followed. This is known as Request Forwarding.
- The procedures listed in Section 6.1.6 are followed, which is known as Request Routing.
- If none of the above is successful, an answer is returned with the Result-Code set to DIAMETER_UNABLE_TO_DELIVER, with the E-bit set. 😭
For routing of Diameter messages to work within an administrative domain, all Diameter nodes within the realm MUST be peers. 🌈
Heads up that these processing rules are general guidelines for Diameter developers, not the law of the land 🤓. Certain implementations MAY use different methods than the ones described here, and still comply with the protocol specification. See Section 7 for more detail on error handling. 💜
6.1.1. Originating a Request
When creating a request, in addition to any other procedures described in the application definition for that specific request, the following procedures MUST be followed ✨:
- the Command-Code is set to the appropriate value
- the 'R' bit is set
- the End-to-End Identifier is set to a locally unique value
- the
Origin-HostandOrigin-RealmAVPs MUST be set to the appropriate values, used to identify the source of the message - the
Destination-HostandDestination-RealmAVPs MUST be set to the appropriate values as described in Section 6.1. - an
Acct-Application-IdAVP, anAuth-Application-Idor aVendor-Specific-Application-IdAVP must be included if the request is proxiable. 🎀
6.1.2. Sending a Request
When sending a request, whether it was originated locally or came from a forwarding or routing operation, the following procedures MUST be followed 📤:
- the Hop-by-Hop Identifier should be set to a locally unique value
- The message should be saved in the list of pending requests.
Other actions to perform on the message, based on the particular role the agent is playing, are described in the following sections. 🦋
6.1.3. Receiving Requests
A relay or proxy agent MUST check for forwarding loops when receiving requests. A loop is detected if the server finds its own identity in a Route-Record AVP. When that happens, the agent MUST answer with the Result-Code AVP set to DIAMETER_LOOP_DETECTED. 🔁😭
6.1.4. Processing Local Requests
A request is known to be for local consumption when one of the following conditions occurs 🏠:
- The
Destination-HostAVP contains the local host's identity, - The
Destination-HostAVP is not present, theDestination-RealmAVP contains a realm the server is configured to process locally, and the Diameter application is locally supported, or - Both the
Destination-Hostand theDestination-Realmare not present.
When a request is locally processed, the rules in Section 6.2 should be used to generate the corresponding answer. 🌸
6.1.5. Request Forwarding
Request forwarding is done using the Diameter Peer Table. The Diameter peer table contains all of the peers that the local node is able to directly communicate with. 📇
When a request is received, and the host encoded in the Destination-Host AVP is one that is present in the peer table, the message SHOULD be forwarded to that peer. 💅
6.1.6. Request Routing
Diameter request message routing is done via realms and applications. A Diameter message that may be forwarded by Diameter agents (proxies, redirects or relays) MUST include the target realm in the Destination-Realm AVP and one of the application identification AVPs Auth-Application-Id, Acct-Application-Id or Vendor-Specific-Application-Id. The realm MAY be retrieved from the User-Name AVP, which is in the form of a Network Access Identifier (NAI). The realm portion of the NAI is inserted in the Destination-Realm AVP. 🗺️
Diameter agents MAY have a list of locally supported realms and applications, and MAY have a list of externally supported realms and applications. When a request comes in that includes a realm and/or application that is not locally supported, the message is routed to the peer configured in the Realm Routing Table (see Section 2.7). 🛣️✨
6.1.7. Redirecting requests
When a redirect agent receives a request whose routing entry is set to REDIRECT, it MUST reply with an answer message with the 'E' bit set, while maintaining the Hop-by-Hop Identifier in the header, and include the Result-Code AVP set to DIAMETER_REDIRECT_INDICATION. Each of the servers associated with the routing entry is added in a separate Redirect-Host AVP. 👉
+------------------+
| Diameter |
| Redirect Agent |
+------------------+
^ | 2. command + 'E' bit
1. Request | | Result-Code =
joe@example.com | | DIAMETER_REDIRECT_INDICATION +
| | Redirect-Host AVP(s)
| v
+-------------+ 3. Request +-------------+
| example.com |------------->| example.net |
| Relay | | Diameter |
| Agent |<-------------| Server |
+-------------+ 4. Answer +-------------+Figure 5: Diameter Redirect Agent 🎀
The receiver of the answer message with the 'E' bit set, and the Result-Code AVP set to DIAMETER_REDIRECT_INDICATION, uses the Hop-by-Hop field in the Diameter header to find the request in the pending message queue (see Section 5.3) that is to be redirected. If no transport connection exists with the new agent, one is created, and the request is sent directly to it. 🚀
Multiple Redirect-Host AVPs are allowed. The receiver of the answer message with the 'E' bit set selects exactly one of these hosts as the destination of the redirected message. 🎯
6.1.8. Relaying and Proxying Requests
A relay or proxy agent MUST append a Route-Record AVP to all requests forwarded. The AVP contains the identity of the peer the request was received from. 🖊️
The Hop-by-Hop identifier in the request is saved and replaced with a locally unique value. The source of the request is also saved, which includes the IP address, port and protocol. 💾
A relay or proxy agent MAY include the Proxy-Info AVP in requests if it requires access to any local state information when the corresponding response is received. Proxy-Info AVP has certain security implications and SHOULD contain an embedded HMAC with a node-local key. Alternatively, it MAY simply use local storage to store state information. 🔐🧠
The message is then forwarded to the next hop, as identified in the Realm Routing Table. 📬
Figure 6 is an example of message routing using the procedures listed in these sections 👀:
(Origin-Host=nas.mno.net) (Origin-Host=nas.mno.net)
(Origin-Realm=mno.net) (Origin-Realm=mno.net)
(Destination-Realm=example.com) (Destination-
Realm=example.com)
(Route-Record=nas.example.net)
+------+ ------> +------+ ------> +------+
| | (Request) | | (Request) | |
| NAS +-------------------+ DRL +-------------------+ HMS |
| | | | | |
+------+ <------ +------+ <------ +------+
example.net (Answer) example.net (Answer) example.com
(Origin-Host=hms.example.com) (Origin-Host=hms.example.com)
(Origin-Realm=example.com) (Origin-Realm=example.com)Figure 6: Routing of Diameter messages 🌷
6.2. Diameter Answer Processing
When a request is locally processed, the following procedures MUST be applied to create the associated answer, in addition to any additional procedures that MAY be discussed in the Diameter application defining the command 🧁:
- The same Hop-by-Hop identifier in the request is used in the answer.
- The local host's identity is encoded in the
Origin-HostAVP. - The
Destination-HostandDestination-RealmAVPs MUST NOT be present in the answer message. - The Result-Code AVP is added with its value indicating success or failure.
- If the
Session-Idis present in the request, it MUST be included in the answer. - Any
Proxy-InfoAVPs in the request MUST be added to the answer message, in the same order they were present in the request. - The 'P' bit is set to the same value as the one in the request.
- The same End-to-End identifier in the request is used in the answer. ✨
Note that the error messages (see Section 7.3) are also subjected to the above processing rules. 💅
6.2.1. Processing received Answers
A Diameter client or proxy MUST match the Hop-by-Hop Identifier in an answer received against the list of pending requests. The corresponding message should be removed from the list of pending requests. It SHOULD ignore answers received that do not match a known Hop-by-Hop Identifier. 🫶🔥
6.2.2. Relaying and Proxying Answers ✨
okay so if the answer is for a request that got proxied or relayed, the agent MUST restore the original value of the Diameter header's Hop-by-Hop Identifier field 🔁 it's giving "put everything back where you found it" energy
if the last Proxy-Info AVP in the message is targeted to the local Diameter server, that AVP MUST be removed before the answer gets forwarded 🧹 bestie, clean up after yourself
now the failure case 😬 if a relay or proxy agent gets an answer with a Result-Code AVP showing a failure, it MUST NOT touch the contents of that AVP. ever. any extra local errors it finds SHOULD be logged, but they do NOT get reflected in the Result-Code AVP 🙅♀️ the error stays honest
but if the agent gets an answer with a Result-Code AVP showing success, and it wants to change that to an error, it MUST modify the Result-Code AVP to hold the appropriate error in the message going toward the access device 💅 it also has to include the Error-Reporting-Host AVP, and it MUST issue an STR on behalf of the access device. main character drama, but make it procedural 😭
last step: the agent MUST then send the answer back to the host that it got the original request from 🦋 full circle, periodt
6.3. Origin-Host AVP
The Origin-Host AVP (AVP Code 264) is of type DiameterIdentity, and MUST be present in all Diameter messages 🫶 this AVP tells you which endpoint actually sent the message. relay agents MUST NOT modify it, so hands off!
the value of the Origin-Host AVP is guaranteed to be unique within a single host 🔑 one-of-a-kind, iconic
ngl this one is a little plot twist: the Origin-Host AVP might resolve to more than one address, because the Diameter peer can support more than one address 🌸
this AVP SHOULD be placed as close to the Diameter header as possible. 6.10
6.4. Origin-Realm AVP
The Origin-Realm AVP (AVP Code 296) is of type DiameterIdentity 🌈 it holds the Realm of whoever originated any Diameter message, and it MUST be present in all messages. no exceptions, no cap 🧢
this AVP SHOULD be placed as close to the Diameter header as possible.
6.5. Destination-Host AVP
The Destination-Host AVP (AVP Code 293) is of type DiameterIdentity 🎀 it MUST be present in all unsolicited agent initiated messages, MAY be present in request messages, and MUST NOT be present in Answer messages. so it's basically a "only when it's needed" kind of AVP 💜
if the Destination-Host AVP is missing, the message gets sent to any Diameter server that supports the application inside the realm named in the Destination-Realm AVP 🧚 open invite, the whole realm can answer
this AVP SHOULD be placed as close to the Diameter header as possible.
6.6. Destination-Realm AVP
The Destination-Realm AVP (AVP Code 283) is of type DiameterIdentity, and it holds the realm the message is supposed to be routed to 🗺️ the Destination-Realm AVP MUST NOT be present in Answer messages.
Diameter Clients put in the realm portion of the User-Name AVP 🙋♀️ and Diameter servers that start a request message use the value of the Origin-Realm AVP from a previous message they got from the intended target host (unless it's already known a priori, which is a fancy way of saying "already known ahead of time") 🧠 when it's there, the Destination-Realm AVP is what gets used to make message routing decisions. literally its whole job 🚦
request messages whose ABNF does not list the Destination-Realm AVP as a mandatory AVP are inherently non-routable messages 🚫 no address, no ride.
this AVP SHOULD be placed as close to the Diameter header as possible.
6.7. Routing AVPs
The AVPs in this section are the Diameter AVPs used for routing purposes 🛣️ these AVPs change as agents process Diameter messages, so they MUST NOT be protected by end-to-end security. they're basically the travel stickers on your luggage, they're supposed to get updated along the way ✈️
6.7.1. Route-Record AVP
The Route-Record AVP (AVP Code 282) is of type DiameterIdentity 🦋 the identity added in this AVP MUST be the same as the one received in the Origin-Host of the Capabilities Exchange message. consistency is everything bestie
6.7.2. Proxy-Info AVP
The Proxy-Info AVP (AVP Code 284) is of type Grouped 💖 its Grouped Data field has the following ABNF grammar:
Proxy-Info ::= < AVP Header: 284 >
{ Proxy-Host }
{ Proxy-State }
* [ AVP ]6.7.3. Proxy-Host AVP
The Proxy-Host AVP (AVP Code 280) is of type DiameterIdentity 🍓 this AVP holds the identity of the host that added the Proxy-Info AVP. the receipt of who was there!
6.7.4. Proxy-State AVP
The Proxy-State AVP (AVP Code 33) is of type OctetString 🫧 it contains state local information, and it MUST be treated as opaque data. hands off, don't peek inside 🙈
6.8. Auth-Application-Id AVP
The Auth-Application-Id AVP (AVP Code 258) is of type Unsigned32, and it's used to advertise support for the Authentication and Authorization portion of an application (see Section 2.4) 🔐 the Auth-Application-Id MUST also be present in all Authentication and/or Authorization messages that are defined in a separate Diameter specification and have an Application ID assigned. slay the paperwork, periodt 📜
6.9. Acct-Application-Id AVP
The Acct-Application-Id AVP (AVP Code 259) is of type Unsigned32 and it's used to advertise support for the Accounting portion of an application (see Section 2.4) 💰 the Acct-Application-Id MUST also be present in all Accounting messages. exactly one of the Auth-Application-Id and Acct-Application-Id AVPs MAY be present. pick one, it's giving "either or" energy ✨
6.10. Inband-Security-Id AVP
The Inband-Security-Id AVP (AVP Code 299) is of type Unsigned32, and it's used to advertise support for the Security portion of the application 🔒
right now these values are supported, but there's ample room to add new security Ids 🌈
NO_INBAND_SECURITY 0
This peer does not support TLS. This is the default value, if the
AVP is omitted.
TLS 1
This node supports TLS security, as defined by [TLS].6.11. Vendor-Specific-Application-Id AVP
The Vendor-Specific-Application-Id AVP (AVP Code 260) is of type Grouped, and it's used to advertise support for a vendor-specific Diameter Application 🧁 exactly one of the Auth-Application-Id and Acct-Application-Id AVPs MAY be present.
this AVP MUST also be present as the first AVP in all experimental commands defined in the vendor-specific application 👑 first place or nothing!
this AVP SHOULD be placed as close to the Diameter header as possible.
AVP Format
<Vendor-Specific-Application-Id> ::= < AVP Header: 260 >
1* [ Vendor-Id ]
0*1{ Auth-Application-Id }
0*1{ Acct-Application-Id }6.12. Redirect-Host AVP
one or more instances of this AVP MUST be present if the answer message's 'E' bit is set and the Result-Code AVP is set to DIAMETER_REDIRECT_INDICATION 🧭 it's the "go over there instead" moment
upon receiving the above, the receiving Diameter node SHOULD forward the request directly to one of the hosts identified in these AVPs 🏃♀️ the server in the selected Redirect-Host AVP SHOULD be used for all messages pertaining to this session. stay loyal to your redirect, lowkey 💜
6.13. Redirect-Host-Usage AVP
The Redirect-Host-Usage AVP (AVP Code 261) is of type Enumerated 🎟️ this AVP MAY be present in answer messages whose 'E' bit is set and the Result-Code AVP is set to DIAMETER_REDIRECT_INDICATION.
when it's present, this AVP dictates how the routing entry from the Redirect-Host is supposed to be used. the supported values are:
DONT_CACHE 0
The host specified in the Redirect-Host AVP should not be cached.
This is the default value.
ALL_SESSION 1
All messages within the same session, as defined by the same value
of the Session-ID AVP MAY be sent to the host specified in the
Redirect-Host AVP.
ALL_REALM 2
All messages destined for the realm requested MAY be sent to the
host specified in the Redirect-Host AVP.
REALM_AND_APPLICATION 3
All messages for the application requested to the realm specified
MAY be sent to the host specified in the Redirect-Host AVP.
ALL_APPLICATION 4
All messages for the application requested MAY be sent to the host
specified in the Redirect-Host AVP.
ALL_HOST 5
All messages that would be sent to the host that generated the
Redirect-Host MAY be sent to the host specified in the Redirect-
Host AVP.
ALL_USER 6
All messages for the user requested MAY be sent to the host
specified in the Redirect-Host AVP.6.14. Redirect-Max-Cache-Time AVP
The Redirect-Max-Cache-Time AVP (AVP Code 262) is of type Unsigned32 ⏳ this AVP MUST be present in answer messages whose 'E' bit is set, the Result-Code AVP is set to DIAMETER_REDIRECT_INDICATION, and the Redirect-Host-Usage AVP is set to a non-zero value.
this AVP holds the max number of seconds the peer and route table entries (made because of the Redirect-Host) will be cached. ngl, the expiry date matters 🕰️ note that once a host created by a redirect indication is no longer reachable, any associated peer and routing table entries MUST be deleted. no ghost entries allowed 👻🚫
6.15. E2E-Sequence AVP
The E2E-Sequence AVP (AVP Code 300) provides anti-replay protection for end to end messages, and it's of type grouped 🔁 it contains a random value (an OctetString with a nonce) and a counter (an Integer). for each end-to-end peer a node talks to (or remembers talking to), a different nonce value MUST be used, and the counter starts at zero and goes up by one each time this AVP is emitted to that peer 🔢 this AVP MUST be included in all messages which use end-to-end protection (e.g., CMS signing or encryption). it's the security glow-up we all need 🛡️✨
7. Error Handling ✨
Okay so Diameter has two kinds of errors, and they're different enough that you need to know which is which 💅. A protocol error happens at the base protocol level and MAY need attention from each hop along the way, like when a message can't be routed 🛣️. An application error comes from something going wrong with a function a Diameter application defines, like user authentication or a Missing AVP 🙈.
Result-Code AVP values used to report protocol errors MUST only show up in answer messages whose 'E' bit is set 🔥. So when a request causes a protocol error, the answer comes back with the 'E' bit set and the Result-Code AVP holding the right protocol error value. On the way back to the originator, each proxy or relay agent MAY do something with that message 🦋.
1. Request +---------+ Link Broken
+-------------------------->|Diameter |----///----+
| +---------------------| | v
+------+--+ | 2. answer + 'E' set | Relay 2 | +--------+
|Diameter |<-+ (Unable to Forward) +---------+ |Diameter|
| | | Home |
| Relay 1 |--+ +---------+ | Server |
+---------+ | 3. Request |Diameter | +--------+
+-------------------->| | ^
| Relay 3 |-----------+
+---------+Figure 7: Example of Protocol Error causing answer message
Figure 7 shows a message being sent upstream through a Diameter relay 🌸. When Relay 2 gets the request and realises it can't forward it to the home server, it sends back an answer with the 'E' bit set and the Result-Code AVP set to DIAMETER_UNABLE_TO_DELIVER. Since that's a protocol error, Relay 1 has to take special action 🧚. It reroutes the message through its alternate, Relay 3. Iconic recovery arc ✨.
+---------+ 1. Request +---------+ 2. Request +---------+
| Access |------------>|Diameter |------------>|Diameter |
| | | | | Home |
| Device |<------------| Relay |<------------| Server |
+---------+ 4. Answer +---------+ 3. Answer +---------+
(Missing AVP) (Missing AVP)Figure 8: Example of Application Error Answer message
Figure 8 shows a Diameter message that set off an application error 💀. When one of these happens, the Diameter entity reporting it clears the 'R' bit in the Command Flags and adds the Result-Code AVP with the proper value 🎀. Application errors don't need any proxy or relay agent involvement, so the answer just goes straight back to the originator of the request 💖.
Some application errors also need extra AVPs in the answer. In those cases, the Diameter node that sets the Result-Code AVP to flag the error MUST add those AVPs 🫶. A few examples:
- An unrecognized AVP shows up with the 'M' bit (Mandatory bit) set. That triggers an answer with the Result-Code AVP set to DIAMETER_AVP_UNSUPPORTED, and the Failed-AVP AVP containing the offending AVP 🙅♀️.
- An AVP arrives with an unrecognized value. The answer comes back with the Result-Code AVP set to DIAMETER_INVALID_AVP_VALUE, and the Failed-AVP AVP holding the AVP that caused the problem 🍓.
- A command arrives with an AVP that's left out, even though the command's ABNF says it's mandatory. The receiver sends an answer with the Result-Code set to DIAMETER_MISSING_AVP, and it creates an AVP with the AVP Code and other fields set the way they'd be in the missing AVP 🧩. That created AVP then gets added to the Failed-AVP AVP 🌈.
The Result-Code AVP describes whatever error the Diameter node ran into while processing 🔍. If there's more than one error, the Diameter node MUST report only the first one it encountered (which it might spot in some implementation-dependent order) 👑. The specific errors this AVP can describe are listed in the next section, so keep scrolling bestie 💜.
7.1. Result-Code AVP
Okay the Result-Code AVP is AVP Code 268, type Unsigned32, and it tells you whether a request actually finished successfully or hit an error 🎀. Every Diameter answer message defined in IETF applications MUST include exactly one Result-Code AVP 💅. A non-successful Result-Code AVP (one with a non 2xxx value other than DIAMETER_REDIRECT_INDICATION) MUST include the Error-Reporting-Host AVP if the host setting the Result-Code is different from the identity encoded in the Origin-Host AVP 🫶.
The Result-Code data field is a 32-bit address space managed by IANA for errors (see Section 11.4) 🦋. Diameter sorts errors into classes, and you can tell which class one is from the thousands digit in its decimal notation:
- 1xxx (Informational) ✨
- 2xxx (Success) 💖
- 3xxx (Protocol Errors) 🛣️
- 4xxx (Transient Failures) 🌸
- 5xxx (Permanent Failure) 💀
A class that isn't recognised (one whose first digit isn't defined in this section) MUST be handled as a permanent failure 🚫. No vibes-based guessing allowed 😭.
7.1.1. Informational
Errors in this category tell the requester that the request couldn't be satisfied, and that they need to do something else before they get access 🔑.
DIAMETER_MULTI_ROUND_AUTH 1001
This informational error comes from a Diameter server to tell the access device that the authentication mechanism in use takes multiple round trips, so a follow-up request has to be sent before access can be granted 🔁.
7.1.2. Success
Errors in the Success category are used to tell a peer that a request has been completed successfully 🥳.
DIAMETER_SUCCESS 2001
The Request was successfully completed 🎉.
DIAMETER_LIMITED_SUCCESS 2002
When this comes back, the request was successfully completed, but the application still has to do more processing before the user can actually get service 🌟.
7.1.3. Protocol Errors
Protocol errors SHOULD be treated on a per-hop basis, and Diameter proxies MAY try to fix the error if that's possible 🛠️. Note that these, and only these, errors MUST only be used in answer messages whose 'E' bit is set 🚨.
DIAMETER_COMMAND_UNSUPPORTED 3001
The Request had a Command-Code that the receiver didn't recognise or support. This MUST be used when a Diameter node gets an experimental command it doesn't understand 🤷♀️.
DIAMETER_UNABLE_TO_DELIVER 3002
This error shows up when Diameter can't deliver the message to its destination. Either no host in the realm supporting the required application was available to process the request, or a Destination-Host AVP was given without its associated Destination-Realm AVP 📭.
DIAMETER_REALM_NOT_SERVED 3003
The realm the request was meant for isn't recognised 🗺️.
DIAMETER_TOO_BUSY 3004
When this comes back, a Diameter node SHOULD try sending the message to an alternate peer. This error MUST only be used when a specific server was requested and it can't provide the service 😮💨.
DIAMETER_LOOP_DETECTED 3005
An agent spotted a loop while trying to get the message to the intended recipient. The message MAY be sent to an alternate peer if one is available, but the peer reporting the error has spotted a configuration problem 🔄.
DIAMETER_REDIRECT_INDICATION 3006
A redirect agent has decided the request can't be satisfied locally, and the initiator should send the request straight to the server whose contact info has been added to the response 📬. When this is set, the Redirect-Host AVP MUST be present 💌.
DIAMETER_APPLICATION_UNSUPPORTED 3007
A request was sent for an application that isn't supported 🙅.
DIAMETER_INVALID_HDR_BITS 3008
A request came in with the bits in its Diameter header either set to an invalid combination, or set to a value that doesn't match the command code's definition 🧐.
DIAMETER_INVALID_AVP_BITS 3009
A request came in with an AVP whose flag bits are set to an unrecognised value, or that doesn't match the AVP's definition 🚩.
DIAMETER_UNKNOWN_PEER 3010
A CER came in from a peer nobody knows 👀.
7.1.4. Transient Failures
Transient failure errors tell a peer that the request couldn't be satisfied when it arrived, but it MAY be able to satisfy the request later ⏳.
DIAMETER_AUTHENTICATION_REJECTED 4001
The authentication process for the user failed, most likely because the user typed in an invalid password 🔐. Further attempts MUST only be tried after the user has been prompted for a new password 🔑.
DIAMETER_OUT_OF_SPACE 4002
A Diameter node got the accounting request but couldn't commit it to stable storage because it temporarily ran out of space 💾.
ELECTION_LOST 4003
The peer worked out that it lost the election process, so it disconnected the transport connection 👋.
7.1.5. Permanent Failures 🚫
Permanent failures are the "don't bother retrying, bestie" crew 💀. They tell the peer that the request failed and should not be attempted again.
DIAMETER_AVP_UNSUPPORTED(5001): The peer got a message with an AVP it doesn't recognize or support, and that AVP was marked with the Mandatory bit 🙅. A message with this error MUST contain one or moreFailed-AVPAVP containing the AVPs that caused the failure.DIAMETER_UNKNOWN_SESSION_ID(5002): The request had a Session-Id that nobody recognizes 🤷.DIAMETER_AUTHORIZATION_REJECTED(5003): A request came in for a user who couldn't be authorized. This could happen if the service requested isn't permitted for that user 🚷.DIAMETER_INVALID_AVP_VALUE(5004): The request had an AVP with an invalid value in its data portion. A message indicating this error MUST include the offending AVPs within aFailed-AVPAVP.DIAMETER_MISSING_AVP(5005): The request was missing an AVP that the Command Code definition requires. If this value is sent in theResult-CodeAVP, aFailed-AVPAVP SHOULD be included in the message. TheFailed-AVPAVP MUST contain an example of the missing AVP, complete with theVendor-Idif applicable. The value field of the missing AVP should be of correct minimum length and contain zeroes 🧸.DIAMETER_RESOURCES_EXCEEDED(5006): A request came in that can't be authorized because the user has already used up their allowed resources. Example: a user restricted to one dial-up PPP port tries to set up a second PPP connection 📞.DIAMETER_CONTRADICTING_AVPS(5007): The Home Diameter server spotted AVPs in the request that contradict each other, and it won't provide service to the user. One or moreFailed-AVPAVPs MUST be present, containing the AVPs that contradicted each other 😤.DIAMETER_AVP_NOT_ALLOWED(5008): A message came in with an AVP that MUST NOT be present. TheFailed-AVPAVP MUST be included and contain a copy of the offending AVP 🛑.DIAMETER_AVP_OCCURS_TOO_MANY_TIMES(5009): A message included an AVP that showed up more often than the message definition allows. TheFailed-AVPAVP MUST be included and contain a copy of the first instance of the offending AVP that exceeded the maximum number of occurrencesDIAMETER_NO_COMMON_APPLICATION(5010): Returned when a CER message is received and there are no common applications supported between the peers 🤝.DIAMETER_UNSUPPORTED_VERSION(5011): Returned when a request arrives with a version number that isn't supported 🔢.DIAMETER_UNABLE_TO_COMPLY(5012): Returned when a request is rejected for unspecified reasons. Mysterious, very dramatic 🌫️.DIAMETER_INVALID_BIT_IN_HEADER(5013): Returned when an unrecognized bit in the Diameter header is set to one (1) ⚡.DIAMETER_INVALID_AVP_LENGTH(5014): The request had an AVP with an invalid length. A message indicating this error MUST include the offending AVPs within aFailed-AVPAVP 📏.DIAMETER_INVALID_MESSAGE_LENGTH(5015): Returned when a request is received with an invalid message length 📦.DIAMETER_INVALID_AVP_BIT_COMBO(5016): The request had an AVP that isn't allowed to have the given value in the AVP Flags field. A message indicating this error MUST include the offending AVPs within aFailed-AVPAVP 🧩.DIAMETER_NO_COMMON_SECURITY(5017): Returned when a CER message is received and there are no common security mechanisms supported between the peers. A Capabilities-Exchange-Answer (CEA) MUST be returned with theResult-CodeAVP set toDIAMETER_NO_COMMON_SECURITY🔐.
7.2. Error Bit 🚩
The E (Error Bit) in the Diameter header is set when the request caused a protocol-related error (see Section 7.1.3). A message with the E bit MUST NOT be sent as a response to an answer message. Note that a message with the E bit set is still subjected to the processing rules defined in Section 6.2. When it's set, the answer message will not conform to the ABNF specification for the command, and will instead conform to the following ABNF:
Message Format
<answer-message> ::= < Diameter Header: code, ERR [PXY] >
0*1< Session-Id >
{ Origin-Host }
{ Origin-Realm }
{ Result-Code }
[ Origin-State-Id ]
[ Error-Reporting-Host ]
[ Proxy-Info ]
* [ AVP ]The code used in the header is the same as the one in the request message, but with the R bit cleared and the E bit set. The P bit in the header is set to the same value as the one in the request message 🎀.
7.3. Error-Message AVP 💬
The Error-Message AVP (AVP Code 281) is of type UTF8String. It MAY accompany a Result-Code AVP as a human-readable error message. The Error-Message AVP isn't meant to be useful in real time, and it SHOULD NOT be expected to be parsed by network entities 🙈.
7.4. Error-Reporting-Host AVP 🕵️
The Error-Reporting-Host AVP (AVP Code 294) is of type DiameterIdentity. This AVP contains the identity of the Diameter host that sent the Result-Code AVP with a value other than 2001 (Success), but only if the host setting the Result-Code is different from the one encoded in the Origin-Host AVP. It's meant for troubleshooting, and it MUST be set when the Result-Code AVP indicates a failure 🔍.
7.5. Failed-AVP AVP 🧾
The Failed-AVP AVP (AVP Code 279) is of type Grouped, and it gives debugging info when a request is rejected or not fully processed because of wrong info in a specific AVP. The value of the Result-Code AVP tells you the reason for the Failed-AVP AVP.
The possible reasons for this AVP are: an improperly constructed AVP, an unsupported or unrecognized AVP, an invalid AVP value, the omission of a required AVP, the presence of an explicitly excluded AVP (see tables in Section 10), or the presence of two or more occurrences of an AVP that is restricted to 0, 1, or 0-1 occurrences 🔎.
A Diameter message MAY contain one Failed-AVP AVP, containing the entire AVP that couldn't be processed successfully. If the failure reason is the omission of a required AVP, an AVP with the missing AVP code, the missing vendor id, and a zero-filled payload of the minimum required length for the omitted AVP will be added 🪄.
AVP Format
<Failed-AVP> ::= < AVP Header: 279 >
1* {AVP}7.6. Experimental-Result AVP 🧪
The Experimental-Result AVP (AVP Code 297) is of type Grouped, and it tells you whether a particular vendor-specific request was completed successfully or whether an error happened. Its Data field has the following ABNF grammar:
AVP Format
Experimental-Result ::= < AVP Header: 297 >
{ Vendor-Id }
{ Experimental-Result-Code }The Vendor-Id AVP (see Section 5.3.3) in this grouped AVP identifies the vendor responsible for assigning the result code that follows. All Diameter answer messages defined in vendor-specific applications MUST include either one Result-Code AVP or one Experimental-Result AVP 🏷️.
7.7. Experimental-Result-Code AVP 🔢
The Experimental-Result-Code AVP (AVP Code 298) is of type Unsigned32 and contains a vendor-assigned value representing the result of processing the request.
It's recommended that vendor-specific result codes follow the same conventions given for the Result-Code AVP regarding the different types of result codes and the handling of errors (for non 2xxx values) 💜.
8. Diameter User Sessions 🎟️
Diameter can provide two different types of services to applications. The first involves authentication and authorization, and can optionally make use of accounting. The second only makes use of accounting.
When a service makes use of the authentication and/or authorization portion of an application, and a user requests access to the network, the Diameter client issues an auth request to its local server. The auth request is defined in a service-specific Diameter application (e.g., NASREQ). The request contains a Session-Id AVP, which is used in subsequent messages (e.g., subsequent authorization, accounting, etc.) relating to the user's session. The Session-Id AVP is how the client and servers correlate a Diameter message with a user session 🔗.
When a Diameter server authorizes a user to use network resources for a finite amount of time, and it's willing to extend the authorization via a future request, it MUST add the Authorization-Lifetime AVP to the answer message. The Authorization-Lifetime AVP defines the maximum number of seconds a user MAY make use of the resources before another authorization request is expected by the server. The Auth-Grace-Period AVP contains the number of seconds following the expiration of the Authorization-Lifetime, after which the server will release all state information related to the user's session ⏳.
Note that if payment for services is expected by the serving realm from the user's home realm, the Authorization-Lifetime AVP, combined with the Auth-Grace-Period AVP, implies the maximum length of the session the home realm is willing to be fiscally responsible for. Services provided past the expiration of the Authorization-Lifetime and Auth-Grace-Period AVPs are the responsibility of the access device. Of course, the actual cost of services rendered is clearly outside the scope of the protocol 💸.
An access device that does not expect to send a re-authorization or a session termination request to the server MAY include the Auth-Session-State AVP with the value set to NO_STATE_MAINTAINED as a hint to the server. If the server accepts the hint, it agrees that since no session termination message will be received once service to the user is terminated, it cannot maintain state for the session. If the answer message from the server contains a different value in the Auth-Session-State AVP (or the default value if the AVP is absent), the access device MUST follow the server's directives. Note that the value NO_STATE_MAINTAINED MUST NOT be set in subsequent re-authorization requests and answers 🫶.
The base protocol doesn't include any authorization request messages, since these are largely application-specific and are defined in a Diameter application document. However, the base protocol does define a set of messages used to terminate user sessions. These let servers that maintain state information free up resources 🧹.
When a service only makes use of the Accounting portion of the Diameter protocol, even in combination with an application, the Session-Id is still used to identify user sessions. However, the session termination messages aren't used, since a session is signaled as terminated by issuing an accounting stop message 🦋.
8.1. Authorization Session State Machine ✨
okay so this section is basically the life cycle of a Diameter session, and it's giving finite state machines 🫶 Every Diameter implementation that uses the authentication and/or authorization side of a Diameter application MUST follow these, no exceptions bestie. When the text says "Service-Specific," it means a message defined in a Diameter application (think Mobile IPv4 or NASREQ) 💅
There are four authorization session state machines in the base protocol, and they come in two pairs. The first two are for sessions where the server keeps session state, which is signaled by the Auth-Session-State AVP (or by it being missing). One machine is the client's view and the other is the server's view. The last two are for when the server does not keep session state, and yep, it's the same deal: one for the client, one for the server 🌸
Once a session lands in the Idle state, any resources that were allocated for it must be released. And if an event isn't listed in the state machines, it MUST be treated as an error condition, and an answer MUST be sent back to the originator of the message (if an answer even applies) 🚨
In the tables, "Failure to send X" means the Diameter agent can't send command X to the intended destination. That could happen because the peer is down, or because the peer replied with a transient failure or temporary protocol error, DIAMETER_TOO_BUSY or DIAMETER_LOOP_DETECTED, in the Result-Code AVP of the matching Answer command. And "X successfully sent" is just the opposite of "Failure to send X," so it's the same coin, flipped 🪙✨
Here's the client state machine for when state is maintained on the server 🎀
CLIENT, STATEFUL
State Event Action New State
-------------------------------------------------------------
Idle Client or Device Requests Send Pending
access service
specific
auth req
Idle ASR Received Send ASA Idle
for unknown session with
Result-Code
= UNKNOWN_
SESSION_ID
Pending Successful Service-specific Grant Open
authorization answer Access
received with default
Auth-Session-State value
Pending Successful Service-specific Sent STR Discon
authorization answer received
but service not provided
Pending Error processing successful Sent STR Discon
Service-specific authorization
answer
Pending Failed Service-specific Cleanup Idle
authorization answer received
Open User or client device Send Open
requests access to service service
specific
auth req
Open Successful Service-specific Provide Open
authorization answer received Service
Open Failed Service-specific Discon. Idle
authorization answer user/device
received.
Open Session-Timeout Expires on Send STR Discon
Access Device
Open ASR Received, Send ASA Discon
client will comply with with
request to end the session Result-Code
= SUCCESS,
Send STR.
Open ASR Received, Send ASA Open
client will not comply with with
request to end the session Result-Code
!= SUCCESS
Open Authorization-Lifetime + Send STR Discon
Auth-Grace-Period expires on
access device
Discon ASR Received Send ASA Discon
Discon STA Received Discon. Idle
user/deviceNext up is the server side of the stateful setup, for when the server is holding onto state for the session 🧚
SERVER, STATEFUL
State Event Action New State
-------------------------------------------------------------
Idle Service-specific authorization Send Open
request received, and successful
user is authorized serv.
specific answer
Idle Service-specific authorization Send Idle
request received, and failed serv.
user is not authorized specific answer
Open Service-specific authorization Send Open
request received, and user successful
is authorized serv. specific
answer
Open Service-specific authorization Send Idle
request received, and user failed serv.
is not authorized specific
answer,
Cleanup
Open Home server wants to Send ASR Discon
terminate the service
Open Authorization-Lifetime (and Cleanup Idle
Auth-Grace-Period) expires
on home server.
Open Session-Timeout expires on Cleanup Idle
home server
Discon Failure to send ASR Wait, Discon
resend ASR
Discon ASR successfully sent and Cleanup Idle
ASA Received with Result-Code
Not ASA Received None No Change.
Discon
Any STR Received Send STA, Idle
Cleanup.Now the stateless vibes 🦋 This is the client's view when the server is NOT keeping state for the session 🌈
CLIENT, STATELESS
State Event Action New State
-------------------------------------------------------------
Idle Client or Device Requests Send Pending
access service
specific
auth req
Pending Successful Service-specific Grant Open
authorization answer Access
received with Auth-Session-
State set to
NO_STATE_MAINTAINED
Pending Failed Service-specific Cleanup Idle
authorization answer
received
Open Session-Timeout Expires on Discon. Idle
Access Device user/device
Open Service to user is terminated Discon. Idle
user/deviceAnd last but definitely not least, the server's stateless machine, for when it isn't maintaining state for the session 💜
SERVER, STATELESS
State Event Action New State
-------------------------------------------------------------
Idle Service-specific authorization Send serv. Idle
request received, and specific
successfully processed answer8.2. Accounting Session State Machine ✨
Okay bestie, this is the accounting state machine era 💅 The following state machines MUST be supported for any application that has an accounting portion or that only needs accounting services 🎀. The first one is the one clients watch 👀. See Section 9.7 for Accounting Command Codes and Section 9.8 for Accounting AVPs 💖.
The server side can change depending on the application 🤔. The Diameter base protocol has a default state machine that MUST be followed by every application that hasn't specified other state machines. That's the second one, and we'll get to it below 🧚.
The default server side is super chill 🦋. It accepts accounting records in any order at any time, and it doesn't put any standards requirements on how those records get processed. Implementations MAY do checking, ordering, correlation, fraud detection, and other tasks based on these records. Both base Diameter AVPs AND application specific AVPs MAY be inspected as part of that. The tasks can happen right after a record comes in or later in a post-processing phase. But since they're usually app or policy dependent, the Diameter specs don't standardize them 🤷♀️. Applications MAY define rules for when to accept accounting records, based on the value of the Accounting-Realtime-Required AVP, credit limit checks, and so on 🌈.
However, the base protocol also defines one optional server side state machine that MAY be followed by applications that need to keep track of the session state at the accounting server 🌸. Ngl, this kind of tracking doesn't mix well with surviving long duration connectivity problems 😭. So the use of this state machine is recommended only where the value of the Accounting-Realtime-Required AVP is DELIVER_AND_GRANT. That way, accounting connectivity problems are required to cause the serviced user to get disconnected. Otherwise, the server could stop accepting records once the connection is back, and the client's records would get lost 💀. This is the third state machine in this section ⭐. It's supervised by a supervision session timer Ts, and the value should be reasonably higher than the Acct_Interim_Interval value. Ts MAY be set to two times the value of the Acct_Interim_Interval so the accounting session on the Diameter server doesn't flip to Idle during a short transient network failure 🫶.
Any event that isn't listed in the state machines MUST be considered an error condition, and a corresponding answer MUST be returned to the originator of the message, if applicable 🚨.
In the state table, the event 'Failure to send' means the Diameter client can't communicate with the desired destination 🙈. That could be because the peer is down, or because the peer sent back a transient failure or temporary protocol error notification, which is DIAMETER_OUT_OF_SPACE, DIAMETER_TOO_BUSY, or DIAMETER_LOOP_DETECTED in the Result-Code AVP of the Accounting Answer command 🍓.
The event 'Failed answer' means the Diameter client got a non-transient failure notification in the Accounting Answer command 😤.
Heads up: the action 'Disconnect user/dev' MUST have an effect on the authorization session state table too. For example, it causes the STR message to be sent, if the given application has both authentication/authorization and accounting portions 🔥.
The states PendingS, PendingI, PendingL, PendingE, and PendingB are the pending states. They wait for an answer to an accounting request related to a Start, Interim, Stop, Event, or buffered record, respectively 🦋.
CLIENT, ACCOUNTING
State Event Action New State
-------------------------------------------------------------
Idle Client or device requests Send PendingS
access accounting
start req.
Idle Client or device requests Send PendingE
a one-time service accounting
event req
Idle Records in storage Send PendingB
record
PendingS Successful accounting Open
start answer received
PendingS Failure to send and buffer Store Open
space available and realtime Start
not equal to DELIVER_AND_GRANT Record
PendingS Failure to send and no buffer Open
space available and realtime
equal to GRANT_AND_LOSE
PendingS Failure to send and no buffer Disconnect Idle
space available and realtime user/dev
not equal to
GRANT_AND_LOSE
PendingS Failed accounting start answer Open
received and realtime equal
to GRANT_AND_LOSE
PendingS Failed accounting start answer Disconnect Idle
received and realtime not user/dev
equal to GRANT_AND_LOSE
PendingS User service terminated Store PendingS
stop
record
Open Interim interval elapses Send PendingI
accounting
interim
record
Open User service terminated Send PendingL
accounting
stop req.
PendingI Successful accounting interim Open
answer received
PendingI Failure to send and (buffer Store Open
space available or old record interim
can be overwritten) and record
realtime not equal to
DELIVER_AND_GRANT
PendingI Failure to send and no buffer Open
space available and realtime
equal to GRANT_AND_LOSE
PendingI Failure to send and no buffer Disconnect Idle
space available and realtime user/dev
not equal to GRANT_AND_LOSE
PendingI Failed accounting interim Open
answer received and realtime
equal to GRANT_AND_LOSE
PendingI Failed accounting interim Disconnect Idle
answer received and realtime user/dev
not equal to GRANT_AND_LOSE
PendingI User service terminated Store PendingI
stop
record
PendingE Successful accounting Idle
event answer received
PendingE Failure to send and buffer Store Idle
space available event
record
PendingE Failure to send and no buffer Idle
space available
PendingE Failed accounting event answer Idle
received
PendingB Successful accounting answer Delete Idle
received record
PendingB Failure to send Idle
PendingB Failed accounting answer Delete Idle
received record
PendingL Successful accounting Idle
stop answer received
PendingL Failure to send and buffer Store Idle
space available stop
record
PendingL Failure to send and no buffer Idle
space available
PendingL Failed accounting stop answer Idle
receivedThat's the whole client side, and it's giving organized 🎀 Now for the server side, which has two flavours depending on whether it's stateless or stateful 🌈.
SERVER, STATELESS ACCOUNTING
State Event Action New State
-------------------------------------------------------------
Idle Accounting start request Send Idle
received, and successfully accounting
processed. start
answer
Idle Accounting event request Send Idle
received, and successfully accounting
processed. event
answer
Idle Interim record received, Send Idle
and successfully processed. accounting
interim
answer
Idle Accounting stop request Send Idle
received, and successfully accounting
processed stop answer
Idle Accounting request received, Send Idle
no space left to store accounting
records answer,
Result-Code
= OUT_OF_
SPACE SERVER, STATEFUL ACCOUNTING
State Event Action New State
-------------------------------------------------------------
Idle Accounting start request Send Open
received, and successfully accounting
processed. start
answer,
Start Ts
Idle Accounting event request Send Idle
received, and successfully accounting
processed. event
answer
Idle Accounting request received, Send Idle
no space left to store accounting
records answer,
Result-Code
= OUT_OF_
SPACE
Open Interim record received, Send Open
and successfully processed. accounting
interim
answer,
Restart Ts
Open Accounting stop request Send Idle
received, and successfully accounting
processed stop answer,
Stop Ts
Open Accounting request received, Send Idle
no space left to store accounting
records answer,
Result-Code
= OUT_OF_
SPACE,
Stop Ts
Open Session supervision timer Ts Stop Ts Idle
expired8.3. Server-Initiated Re-Auth 🔁
okay so a Diameter server is allowed to start a re-authentication and/or re-authorization for a session by sending a Re-Auth-Request (RAR). main character server energy 💅
For example, with pre-paid services, the server that first authorized the session might want a little "hey, are you still there?" check to confirm the user is still actually using the service 🙈
An access device that gets a RAR with a Session-Id matching a currently active session MUST initiate a re-auth towards the user, if the service supports this particular feature. Each Diameter application MUST state whether service-initiated re-auth is supported, since some applications don't let access devices prompt the user for re-auth. not me... 🫶
8.3.1. Re-Auth-Request
okay the RAR is Command-Code 258 with the 'R' bit set, and any server can send it to the access device that's providing session service. The goal is to ask that the user gets re-authenticated and/or re-authorized ✨
Message Format
<RAR> ::= < Diameter Header: 258, REQ, PXY >
< Session-Id >
{ Origin-Host }
{ Origin-Realm }
{ Destination-Realm }
{ Destination-Host }
{ Auth-Application-Id }
{ Re-Auth-Request-Type }
[ User-Name ]
[ Origin-State-Id ]
* [ Proxy-Info ]
* [ Route-Record ]
* [ AVP ]8.3.2. Re-Auth-Answer
The RAA is Command-Code 258 with the 'R' bit clear, and it's the reply to the RAR 🎀 The Result-Code AVP MUST be present, and it tells you what happened to the request.
A successful RAA message MUST be followed by an application-specific authentication and/or authorization message. bestie, that's the rule, no cap 🔥
Message Format
<RAA> ::= < Diameter Header: 258, PXY >
< Session-Id >
{ Result-Code }
{ Origin-Host }
{ Origin-Realm }
[ User-Name ]
[ Origin-State-Id ]
[ Error-Message ]
[ Error-Reporting-Host ]
* [ Failed-AVP ]
* [ Redirect-Host ]
[ Redirect-Host-Usage ]
[ Redirect-Host-Cache-Time ]
* [ Proxy-Info ]
* [ AVP ]8.4. Session Termination 🦋
okay so a Diameter server that authorized a session and is keeping state for it NEEDS to know when that session is over. Partly for tracking, and partly so stateful agents can free up whatever they gave the user's session 💜 For sessions whose state isn't being kept, this section doesn't apply.
When a user session that needed Diameter authorization ends, the access device that provided the service MUST issue a Session-Termination-Request (STR) to the server that authorized it, so it knows the session is no longer active. An STR MUST be issued when a session ends for any reason: user logoff, expiration of Session-Timeout, administrative action, termination upon receipt of an Abort-Session-Request (see below), orderly shutdown of the access device, etc. ✨
The access device also MUST issue an STR for a session that was authorized but never actually started. This could happen because of a sudden resource shortage in the access device, or because the access device won't provide the type of service requested in the authorization, or because it doesn't support a mandatory AVP returned in the authorization, etc. 💀
It's also possible for an authorized session to never start because of a proxy 👀 For example, a proxy might edit an authorization answer and flip a success into a failure before passing it along to the access device. If the answer did not contain an Auth-Session-State AVP with the value NO_STATE_MAINTAINED, a proxy that stops an authorized session from starting MUST issue an STR to the server that authorized it. Why? Because the access device has no way of knowing the session had been authorized in the first place 😭
A Diameter server that receives an STR MUST clean up resources (e.g., session state) tied to the Session-Id in the STR, and return a Session-Termination-Answer.
A Diameter server also MUST clean up resources when the Session-Timeout expires, or when the Authorization-Lifetime and the Auth-Grace-Period AVPs expires without a re-authorization request being received, regardless of whether an STR for that session comes in. The access device isn't expected to keep providing service past those timers, so if either one expires, the access device may have unexpectedly shut down 🌈
8.4.1. Session-Termination-Request
The STR is Command-Code 275 with the Command Flags' 'R' bit set, and the access device sends it to tell the Diameter Server that an authenticated and/or authorized session is ending 🍓
Message Format
<STR> ::= < Diameter Header: 275, REQ, PXY >
< Session-Id >
{ Origin-Host }
{ Origin-Realm }
{ Destination-Realm }
{ Auth-Application-Id }
{ Termination-Cause }
[ User-Name ]
[ Destination-Host ]
* [ Class ]
[ Origin-State-Id ]
* [ Proxy-Info ]
* [ Route-Record ]
* [ AVP ]8.4.2. Session-Termination-Answer
The STA is Command-Code 275 with the message flags' 'R' bit clear, and the Diameter Server sends it to acknowledge that the session has been terminated 🧚 The Result-Code AVP MUST be present, and it MAY contain an indication that an error occurred while servicing the STR.
Upon sending or receipt of the STA, the Diameter Server MUST release all resources for the session indicated by the Session-Id AVP. Any intermediate server in the Proxy-Chain MAY also release any resources, if necessary. the cleanup squad is out here 🧹
Message Format
<STA> ::= < Diameter Header: 275, PXY >
< Session-Id >
{ Result-Code }
{ Origin-Host }
{ Origin-Realm }
[ User-Name ]
* [ Class ]
[ Error-Message ]
[ Error-Reporting-Host ]
* [ Failed-AVP ]
[ Origin-State-Id ]
* [ Redirect-Host ]
[ Redirect-Host-Usage ]
^
[ Redirect-Max-Cache-Time ]
* [ Proxy-Info ]
* [ AVP ]8.5. Aborting a Session 🛑
okay so a Diameter server can ask the access device to stop providing service for a session by sending an Abort-Session-Request (ASR) 💅
For example, the server that originally authorized the session might need that session stopped for credit or other reasons nobody saw coming when it was authorized. On the flip side, an operator might run a management server whose whole job is sending ASRs to administratively boot users off the network 🙅♀️
An access device that receives an ASR with a Session-ID matching a currently active session MAY stop the session. Whether it actually stops depends on implementation and/or configuration. For example, an access device might only honor ASRs from certain agents. In any case, the access device MUST respond with an Abort-Session-Answer, including a Result-Code AVP to show what action it took 🫶
Note that if the access device does stop the session after getting an ASR, it sends an STR to the authorizing server (which may or may not be the agent that sent the ASR), just like it would if the session ended for any other reason ✨
8.5.1. Abort-Session-Request
The ASR is Command-Code 274 with the message flags' 'R' bit set, and any server can send it to the access device providing session service. It asks that the session identified by the Session-Id be stopped 🦋
Message Format
<ASR> ::= < Diameter Header: 274, REQ, PXY >
< Session-Id >
{ Origin-Host }
{ Origin-Realm }
{ Destination-Realm }
{ Destination-Host }
{ Auth-Application-Id }
[ User-Name ]
[ Origin-State-Id ]
* [ Proxy-Info ]
* [ Route-Record ]
* [ AVP ]8.5.2. Abort-Session-Answer
The ASA is Command-Code 274 with the message flags' 'R' bit clear, and it's sent back in response to the ASR. The Result-Code AVP MUST be present, and it tells you the disposition of the request 🌸
If the session identified by the Session-Id in the ASR was successfully terminated, Result-Code is set to DIAMETER_SUCCESS. If the session isn't currently active, Result-Code is set to DIAMETER_UNKNOWN_SESSION_ID. If the access device doesn't stop the session for any other reason, Result-Code is set to DIAMETER_UNABLE_TO_COMPLY 💀
Message Format
<ASA> ::= < Diameter Header: 274, PXY >
< Session-Id >
{ Result-Code }
{ Origin-Host }
{ Origin-Realm }
[ User-Name ]
[ Origin-State-Id ]
[ Error-Message ]
[ Error-Reporting-Host ]
* [ Failed-AVP ]
* [ Redirect-Host ]
[ Redirect-Host-Usage ]
[ Redirect-Max-Cache-Time ]
* [ Proxy-Info ]
* [ AVP ]8.6. Inferring Session Termination from Origin-State-Id 🕵️♀️
okay so Origin-State-Id helps you spot terminated sessions quickly, the ones that never got an STR because an access device shut down unexpectedly 🔍
Including Origin-State-Id in CER/CEA messages means a next-hop server can tell right away, the moment it connects, whether the device lost its sessions since the last connection. 🌈
Including it in request messages lets a server that talks to the device through a proxy make that same call too. BUT a server that isn't directly connected to the access device won't find out the device restarted until it gets a new request from it. So using this across proxies is opportunistic rather than reliable, though still useful nonetheless 🧚
When a Diameter server gets an Origin-State-Id that is greater than the Origin-State-Id it previously received from the same issuer, it may assume the issuer has lost state since the previous message, and that all sessions that were active under the lower Origin-State-Id have been terminated. The Diameter server MAY clean up all session state associated with those lost sessions, and MAY also issues STRs for all such lost sessions that were authorized on upstream servers, so session state gets cleaned up globally 🫧
8.7. Auth-Request-Type AVP ✨
Okay bestie, the Auth-Request-Type AVP (AVP Code 274) is an Enumerated one 💅. It shows up in application-specific auth requests to tell the peers whether a user is getting authenticated only, authorized only, or both 🔥. Heads up: any value other than both MAY cause RADIUS interoperability issues 💀. Here are the values:
AUTHENTICATE_ONLY(value 1) 🔐: The request is for authentication only, and it MUST contain the relevant application specific authentication AVPs that the Diameter server needs to authenticate the user.AUTHORIZE_ONLY(value 2) 🎟️: The request is for authorization only, and it MUST contain the application specific authorization AVPs needed to identify the service being requested or offered.AUTHORIZE_AUTHENTICATE(value 3) 👑: The request asks for both authentication and authorization. It MUST include both the relevant application specific authentication information and the authorization information needed to identify the service being requested or offered.
8.8. Session-Id AVP 🆔
The Session-Id AVP (AVP Code 263) is a UTF8String, and it's how we identify a specific session (see Section 8) 🫶. Every message about one session MUST include only one Session-Id AVP, and the same value MUST be used the whole time that session is alive. When it's there, the Session-Id SHOULD show up right after the Diameter Header (see Section 3) ✨.
The Session-Id MUST be globally and eternally unique, because it has to identify a user session all by itself, with no other info needed 🦋. It can also be how you line up historical authentication info with accounting info, which is so useful 🙌. The Session-Id has a mandatory part and an implementation-defined part, and there's a recommended format for that second part, outlined below 🧚.
The Session-Id MUST begin with the sender's identity, encoded as a DiameterIdentity (see Section 4.4) 🪪. The rest of it is separated by a ";" character and MAY be any sequence that the client can guarantee to be eternally unique. The recommended format looks like this (square brackets [] mark an optional element):
<DiameterIdentity>;<high 32 bits>;<low 32 bits>[;<optional value>]The <high 32 bits> and <low 32 bits> parts are decimal representations of the high and low 32 bits of a monotonically increasing 64-bit value. That 64-bit value is split into two parts to make life easier for 32-bit processors 🤓. At startup, the high 32 bits of the 64-bit value MAY be initialized to the time, and the low 32 bits MAY be initialized to zero. For practical purposes this basically kills any chance of overlapping Session-Ids after a reboot, as long as the reboot takes more than a second ⏱️. Or, an implementation MAY keep track of the increasing value in non-volatile memory 💾.
The <optional value> is implementation specific, but it may include a modem's device Id, a layer 2 address, a timestamp, etc. 📡
Here's an example with no optional value:
accesspoint7.acme.com;1876543210;523And here's one with an optional value:
accesspoint7.acme.com;1876543210;523;mobile@200.1.1.88The Session-Id gets created by the Diameter application that starts the session, which in most cases is the client 🧑💻. Also, a Session-Id MAY be used for both the authorization and accounting commands of a given application 💜.
8.9. Authorization-Lifetime AVP ⏳
The Authorization-Lifetime AVP (AVP Code 291) is Unsigned32, and it holds the max number of seconds of service the user gets before they need to be re-authenticated and/or re-authorized 🕰️. Be extra careful when you pick this value, because a low, non-zero value could create a ton of Diameter traffic, and that could congest both the network and the agents 😭.
A value of zero (0) means the access device needs to re-auth immediately 🚨. This usually happens when multiple authentication methods are in play. A successful auth response with this AVP set to zero is how the server says, "start the next authentication method right now" 🏃♀️. If the AVP isn't there, or it's all ones (every bit in the 32-bit field set to one), that means no re-auth is expected 🙅♀️.
If this AVP and the Session-Timeout AVP are both in a message, the Session-Timeout value MUST NOT be smaller than the Authorization-Lifetime AVP 📏.
An Authorization-Lifetime AVP MAY be present in re-authorization messages 🔁. It holds the number of seconds the user is authorized to get service, counted from when the access device gets the re-auth answer message 🎀.
The client MAY give this AVP as a hint for the max lifetime it's willing to accept 💭. The server MAY return a value that is equal to, or smaller than, the one the client gave 🫠.
8.10. Auth-Grace-Period AVP 🌙
The Auth-Grace-Period AVP (AVP Code 276) is Unsigned32, and it holds the number of seconds the Diameter server will wait after the Authorization-Lifetime AVP runs out before it cleans up the session's resources 🧹.
8.11. Auth-Session-State AVP 🧠
The Auth-Session-State AVP (AVP Code 277) is Enumerated, and it says whether state is kept for a particular session 📝. The client MAY include this AVP in requests as a hint for the server, but the value in the server's answer message is binding, so that's the final word 👑. These values are supported:
STATE_MAINTAINED(value 0) 📌: State is being kept, so the access device MUST issue a session termination message when service to the user ends. This is the default value 💖.NO_STATE_MAINTAINED(value 1) 🫥: No session termination messages will be sent by the access device when the Authorization-Lifetime expires.
8.12. Re-Auth-Request-Type AVP 🔄
The Re-Auth-Request-Type AVP (AVP Code 285) is Enumerated, and it goes in application-specific auth answers to tell the client what to expect when the Authorization-Lifetime expires 👀. If the answer message has an Authorization-Lifetime AVP with a positive value, the Re-Auth-Request-Type AVP MUST be present in that answer message 🫡. These values are defined:
AUTHORIZE_ONLY(value 0) 🎫: An authorization-only re-auth is expected when the Authorization-Lifetime expires. This is the default if the AVP isn't in an answer message that includes the Authorization-Lifetime 🌸.AUTHORIZE_AUTHENTICATE(value 1) 🔐👑: An authentication and authorization re-auth is expected when the Authorization-Lifetime expires.
8.13. Session-Timeout AVP ⌛
The Session-Timeout AVP (AVP Code 27) [RADIUS] is Unsigned32, and it holds the max number of seconds of service the user gets before the session is terminated 🛑. When both the Session-Timeout and the Authorization-Lifetime AVPs are in an answer message, the Session-Timeout MUST be equal to or greater than the Authorization-Lifetime value 📐.
If a session ends on an access device because the Session-Timeout ran out, an STR MUST cause an STR to be issued 📨. The only exception is when the access device and the home server had already agreed that no session termination messages would be sent (see Section 8.9) 🙅♀️.
A Session-Timeout AVP MAY be present in a re-authorization answer message. It holds the remaining number of seconds counted from the beginning of the re-auth 🔁.
A value of zero, or no AVP at all, means the session has an unlimited number of seconds before it terminates ♾️.
The client MAY give this AVP as a hint for the max timeout it's willing to accept 💭. The server MAY return a value that is equal to, or smaller than, the one the client gave 🫠.
8.14. User-Name AVP 🙋♀️
The User-Name AVP (AVP Code 1) [RADIUS] is UTF8String, and it holds the User-Name in a format that matches the NAI specification [NAI] 🪪✨.
8.15. Termination-Cause AVP 🚪
The Termination-Cause AVP (AVP Code 295) is Enumerated, and it's used to say why a session got terminated on the access device 🧾. These values are defined:
DIAMETER_LOGOUT(value 1) 👋: The user started the disconnect.DIAMETER_SERVICE_NOT_PROVIDED(value 2) 🫥: The user disconnected before the authorization answer message was received.DIAMETER_BAD_ANSWER(value 3) 💀: The authorization answer the access device got wasn't processed successfully.DIAMETER_ADMINISTRATIVE(value 4) 🏛️: The user wasn't granted access, or got disconnected, for administrative reasons, like when an Abort-Session-Request message comes in.DIAMETER_LINK_BROKEN(value 5) 💔: The communication to the user was abruptly cut off.DIAMETER_AUTH_EXPIRED(value 6) ⏰: The user's access ended because their authorized session time ran out.DIAMETER_USER_MOVED(value 7) 🚶♀️: The user is getting services from another access device now.DIAMETER_SESSION_TIMEOUT(value 8) 🕐: The user's session timed out, and service was terminated.
8.16. Origin-State-Id AVP 🕰️
The Origin-State-Id AVP (AVP Code 278) is Unsigned32, and it's a monotonically increasing value that goes up whenever a Diameter entity restarts and loses its previous state, like after a reboot 🔌. The Origin-State-Id MAY be included in any Diameter message, including CER 📬.
A Diameter entity that issues this AVP MUST create a higher value every time its state is reset 📈. It MAY set the Origin-State-Id to the time of startup, or it MAY use an incrementing counter kept in non-volatile memory across restarts 💾.
If it's there, the Origin-State-Id MUST reflect the state of the entity named in Origin-Host 🪞. If a proxy changes Origin-Host, it MUST either remove the Origin-State-Id or update it appropriately too 🧼.
Usually, the Origin-State-Id is used by an access device that always starts up with no active sessions. Any session that was active before a restart is gone 💨. By including Origin-State-Id in a message, the device lets other Diameter entities infer that sessions tied to a lower Origin-State-Id aren't active anymore 🔍. If an access device doesn't want those inferences made, it MUST either leave Origin-State-Id out of every message, or set its value to 0 🙅♀️.
8.17. Session-Binding AVP ✨
bestie, this one is a bit mask 🎀 The Session-Binding AVP (AVP Code 270) is type Unsigned32, and it MAY show up in application-specific authorization answer messages. If it's there, it MAY tell the Diameter client that every future application-specific re-auth message for this session MUST go to the same authorization server. It MAY also say that a Session-Termination-Request message for this session MUST go to that same authorizing server 💅
The bits are:
RE_AUTH 1
STR 2
ACCOUNTING 4RE_AUTH(1): when it's set, future re-auth messages for this session MUST NOT include theDestination-HostAVP. When it's cleared (the default), theDestination-HostAVP MUST be present in all re-auth messages for this session 🦋STR(2): when it's set, the STR message for this session MUST NOT include theDestination-HostAVP. When it's cleared (the default), theDestination-HostAVP MUST be in the STR message for this session 🌸ACCOUNTING(4): when it's set, all accounting messages for this session MUST NOT include theDestination-HostAVP. When it's cleared (the default), theDestination-HostAVP, if known, MUST be in all accounting messages for this session 🔥
8.18. Session-Server-Failover AVP 🧚
The Session-Server-Failover AVP (AVP Code 271) is Enumerated. It MAY show up in application-specific authorization answers that either leave out Session-Binding or include it with any bit set to zero. If it's present, it MAY tell the Diameter client that when a re-auth or STR message fails because of a delivery problem, the client SHOULD send a follow-up without the Destination-Host AVP. When it's absent, the default is REFUSE_SERVICE 💖
Here are the values:
REFUSE_SERVICE 0
TRY_AGAIN 1
ALLOW_SERVICE 2
TRY_AGAIN_ALLOW_SERVICE 3REFUSE_SERVICE(0): if the re-auth or the STR message delivery fails, end service with the user and don't try again 🙈TRY_AGAIN(1): if either the re-auth or the STR message delivery fails, resend that message without theDestination-HostAVP present ✨ALLOW_SERVICE(2): if re-auth delivery fails, assume re-authorization succeeded. If STR delivery fails, terminate the session 🌈TRY_AGAIN_ALLOW_SERVICE(3): if either the re-auth or the STR delivery fails, resend it without theDestination-HostAVP present. If the second attempt fails for re-auth, assume re-authorization succeeded. If the second attempt fails for STR, terminate the session 👑
8.19. Multi-Round-Time-Out AVP ⏰
The Multi-Round-Time-Out AVP (AVP Code 272) is type Unsigned32, and it SHOULD be present in application-specific authorization answers whose Result-Code AVP is set to DIAMETER_MULTI_ROUND_AUTH. It holds the maximum number of seconds the access device MUST give the user to answer an authentication request. Timer energy 🫶
8.20. Class AVP 🎀
The Class AVP (AVP Code 25) is type OctetString, and Diameter servers use it to hand state information back to the access device. When one or more Class AVPs show up in application-specific authorization answers, they MUST also be present in later re-authorization, session termination and accounting messages. Class AVPs in a re-authorization answer override the ones from any earlier authorization answer 🔄
Server implementations SHOULD NOT return Class AVPs that need more than 4096 bytes of storage on the Diameter client. And if a Diameter client gets Class AVPs bigger than its local storage can handle, it MUST terminate the session 🚨
8.21. Event-Timestamp AVP 🕰️
The Event-Timestamp (AVP Code 55) is type Time, and it MAY be included in Accounting-Request and Accounting-Answer messages to record when the reported event happened, counted in seconds since January 1, 1900 00:00 UTC 🌸
9. Accounting 💜
This accounting protocol is based on a server directed model, with real-time delivery of accounting info built in ✨ A bunch of fault resilience methods [ACCMGMT] are baked into the protocol to cut down on lost accounting data in different failure situations and with different assumptions about what the devices can do 🛡️
9.1. Server Directed Model 🧭
In the server directed model, the device generating the accounting data gets instructions from either the authorization server (if it was contacted) or the accounting server about how that data shall be forwarded. That info includes how timely the accounting records need to be 🍓
As [ACCMGMT] explains, real-time transfer of accounting records is a requirement, because you need things like credit limit checks and fraud detection 🚫💳 Batch accounting is NOT a requirement, so Diameter doesn't support it. Should batched accounting be required in the future, a new Diameter application will need to be created, or it could be handled with another protocol. Even though accounting requests get processed one at a time at the Diameter layer, the transport protocols under Diameter typically batch several requests into the same packet when traffic is heavy. That may be enough for lots of applications 📦
The authorization server (or chain of them) picks the right transfer strategy, based on what it knows about the user and its roaming partnerships. The server (or agents) use the Acct-Interim-Interval and Accounting-Realtime-Required AVPs to control the Diameter peer acting as a client. When the Acct-Interim-Interval AVP is present, it tells the Diameter node acting as a client to keep producing accounting records continuously, even during a session. The Accounting-Realtime-Required AVP controls how the client behaves when transferring accounting records from the Diameter client is delayed or fails 🕹️
The Diameter accounting server MAY override the interim interval or the realtime requirements by including the Acct-Interim-Interval or Accounting-Realtime-Required AVP in the Accounting-Answer message. When one of these AVPs is present, the latest value received SHOULD be used for further accounting activities for the same session 🔁
9.2. Protocol Messages 📨
A Diameter node that gets a successful authentication and/or authorization message from the Home AAA server MUST collect accounting info for the session. The Accounting-Request message carries that info to the Home AAA server, which MUST reply with an Accounting-Answer message to confirm it got it. The Accounting-Answer includes the Result-Code AVP, which MAY indicate that the accounting message had an error. A rejected Accounting-Request MAY cause the user's session to end, depending on the Accounting-Realtime-Required value received earlier for that session 🙋♀️
Each Diameter Accounting protocol message MAY be compressed to save network bandwidth. If IPsec and IKE secure the Diameter session, then IP compression [IPComp] MAY be used, and IKE [IKE] MAY be used to negotiate the compression parameters. If TLS secures the Diameter session, then TLS compression [TLS] MAY be used 🗜️
9.3. Application document requirements 📝
Each Diameter application (e.g., NASREQ, MobileIP) MUST define its Service-Specific AVPs that MUST be present in the Accounting-Request message, in a section called "Accounting AVPs". The application MUST assume that the AVPs described in this document will be present in all Accounting messages, so it only needs to define its service-specific AVPs in that section 💅
9.4. Fault Resilience 🛡️
Diameter Base protocol mechanisms handle small message loss and short-lived network faults ✨
Diameter peers acting as clients MUST implement failover to guard against server failures and certain network failures. Diameter peers acting as agents, or related off-line processing systems, MUST detect duplicate accounting records caused by the same record being sent to several servers and by messages duplicated in transit. That detection MUST be based on inspecting the Session-Id and Accounting-Record-Number AVP pairs. Appendix C discusses duplicate detection needs and implementation issues 🔍
Diameter clients MAY have non-volatile memory for safely storing accounting records across reboots or long network failures, network partitions, and server failures. If that memory is available, the client SHOULD store new accounting records there as soon as they're created, and keep them until a positive acknowledgement of their reception from the Diameter Server arrives. After a reboot, the client MUST start sending the records in non-volatile memory to the accounting server, with appropriate modifications to the termination cause, session length and other relevant information in the records 🔋
A further application of this protocol may include AVPs to control how many accounting records may at most be stored in the Diameter client without being committed to non-volatile memory or transferred to the Diameter server 🎛️
The client SHOULD NOT remove accounting data from any of its memory areas before the correct Accounting-Answer has been received. The client MAY remove the oldest, undelivered or not-yet-acknowledged accounting data if it runs out of resources such as memory. Whether the client accepts new sessions under this condition is an implementation-dependent matter 🫶
9.5. Accounting Records ✨
okay bestie, every accounting record needs the Session-Id AVP, and it MUST be there 💖 The User-Name AVP MUST show up too, but only if the Diameter client actually has it 🎀 If you need strong auth across agents, end-to-end security can be used for authentication 🔐
Different kinds of accounting records get sent depending on what service is being accounted and whether the authorization server wants interim accounting 👀 If the service is a one-time event, where the start and stop happen at the same moment, then the Accounting-Record-Type AVP MUST be present and set to EVENT_RECORD. Literally one record, no drama 💅
If the service has a measurable length, the AVP MUST use START_RECORD, STOP_RECORD, and possibly INTERIM_RECORD 🦋 If the authorization server has NOT turned on interim accounting for the session, two accounting records MUST be generated for each session-type service. The first Accounting-Request for a session MUST have the Accounting-Record-Type AVP set to START_RECORD, and the last one MUST be STOP_RECORD 🌸
Now if the authorization server HAS turned on interim accounting, the Diameter client MUST produce extra records between START_RECORD and STOP_RECORD, marked INTERIM_RECORD ⏱️ How often those show up is controlled by Acct-Interim-Interval, plus any re-authentication or re-authorization of the session. Also, the Diameter client MUST overwrite any older interim records it's storing locally for delivery whenever a new one gets made for the same session 🧹 That way only one pending interim record can exist on an access device for any given session. Clean girl energy ✨
One more rule: a particular Accounting-Sub-Session-Id value MUST appear in only one sequence of accounting records from a DIAMETER client, except when retransmitting 🔁 That one sequence MUST be either a single record with EVENT_RECORD, or several records starting with START_RECORD, then zero or more INTERIM_RECORD, then one STOP_RECORD. And a particular Diameter application specification MUST define which sequence types have to be used 📋
9.6. Correlation of Accounting Records 🔗
The Session-Id AVP is globally unique (see Section 8.8), and it's what the protocol uses during the authorization phase to identify a particular session 🫶 Services that don't need any authorization still use the Session-Id AVP to identify their sessions, so it's giving consistency 💜
Accounting messages MAY use a different Session-Id from the one sent in authorization messages. Specific applications MAY require a different Session-ID for their accounting messages too 🌈
Some applications need multiple accounting sub-sessions 🧩 Those send messages with a constant Session-Id AVP but a different Accounting-Sub-Session-Id AVP, and correlation happens using the Session-Id. Important tea ☕: if sub-sessions were used in the START_RECORD messages, then receiving a STOP_RECORD with no Accounting-Sub-Session-Id AVP means ALL the sub-sessions are terminated 🛑
Then there's the case where a user gets service from different access devices, like Mobile IPv4, and each one has its own unique Session-Id 🛰️ For those, the Acct-Multi-Session-Id AVP handles correlation. During authorization, a server that figures out a request is for an existing session SHOULD include the Acct-Multi-Session-Id AVP, and the access device MUST include it in all subsequent accounting messages 📡
The Acct-Multi-Session-Id AVP MAY include the value of the original Session-Id. Its contents are implementation specific, but it MUST be globally unique across other Acct-Multi-Session-Id values, and it MUST NOT change during the life of a session 🔒
A Diameter application document MUST define the exact concept of a session being accounted for, and it MAY define the concept of a multi-session 🎀 For example, the NASREQ DIAMETER application treats a single PPP connection to a Network Access Server as one session, and a set of Multilink PPP sessions as one multi-session 🧁
9.7. Accounting Command-Codes 📟
This section defines Command-Code values that MUST be supported by all Diameter implementations that provide Accounting services. No skipping these, bestie 💅
9.7.1. Accounting-Request 📤
The Accounting-Request (ACR) command is indicated by the Command-Code field set to 271 with the Command Flags' 'R' bit set. A Diameter node acting as a client sends it to exchange accounting information with a peer 💌
One of the Acct-Application-Id and Vendor-Specific-Application-Id AVPs MUST be present 🫧 If the Vendor-Specific-Application-Id grouped AVP shows up, it's gotta have an Acct-Application-Id inside it 🧸
The AVP listed below SHOULD include service specific accounting AVPs, as described in Section 9.3 ✨
Message Format 🧾
<ACR> ::= < Diameter Header: 271, REQ, PXY >
< Session-Id >
{ Origin-Host }
{ Origin-Realm }
{ Destination-Realm }
{ Accounting-Record-Type }
{ Accounting-Record-Number }
[ Acct-Application-Id ]
[ Vendor-Specific-Application-Id ]
[ User-Name ]
[ Accounting-Sub-Session-Id ]
[ Acct-Session-Id ]
[ Acct-Multi-Session-Id ]
[ Acct-Interim-Interval ]
[ Accounting-Realtime-Required ]
[ Origin-State-Id ]
[ Event-Timestamp ]
* [ Proxy-Info ]
* [ Route-Record ]
* [ AVP ]9.7.2. Accounting-Answer 💬
The Accounting-Answer (ACA) command is indicated by the Command-Code field set to 271 with the Command Flags' 'R' bit cleared. It's the acknowledgement for an Accounting-Request 🫶 The Accounting-Answer carries the same Session-Id, and it only includes the usage AVPs if CMS is in use when sending it 📊 Heads up: putting usage AVPs in there when CMS isn't being used makes answer messages unnecessarily big, AND it can't be used as a server's proof of receipt of those AVPs in an end-to-end fashion 🙈 If the Accounting-Request was protected by end-to-end security, then the matching ACA message MUST be protected by end-to-end security too 🔐
Only the target Diameter Server, known as the home Diameter Server, SHOULD respond with the Accounting-Answer command 🏠
One of the Acct-Application-Id and Vendor-Specific-Application-Id AVPs MUST be present. If the Vendor-Specific-Application-Id grouped AVP shows up, it has to have an Acct-Application-Id inside 🧸
The AVP listed below SHOULD include service specific accounting AVPs, as described in Section 9.3 🌷
Message Format 🧾
<ACA> ::= < Diameter Header: 271, PXY >
< Session-Id >
{ Result-Code }
{ Origin-Host }
{ Origin-Realm }
{ Accounting-Record-Type }
{ Accounting-Record-Number }
[ Acct-Application-Id ]
[ Vendor-Specific-Application-Id ]
[ User-Name ]
[ Accounting-Sub-Session-Id ]
[ Acct-Session-Id ]
[ Acct-Multi-Session-Id ]
[ Error-Reporting-Host ]
[ Acct-Interim-Interval ]
[ Accounting-Realtime-Required ]
[ Origin-State-Id ]
[ Event-Timestamp ]
* [ Proxy-Info ]
* [ AVP ]9.8. Accounting AVPs 💎
This section has the AVPs that describe accounting usage information for a specific session 📈
9.8.1. Accounting-Record-Type AVP 🏷️
The Accounting-Record-Type AVP (AVP Code 480) is of type Enumerated and tells you what kind of accounting record is being sent. These are the values defined so far:
EVENT_RECORD(value 1): an Accounting Event Record says a one-time event happened, with the start and end at the same moment 🎟️ It holds all the info relevant to the service and is the only record of that service. Solo main character moment 👑START_RECORD(value 2): Accounting Start, Interim, and Stop Records say a service of measurable length was given 🚀 The Accounting Start Record kicks off an accounting session and holds info relevant to starting it 🌅INTERIM_RECORD(value 3): an Interim Accounting Record holds cumulative accounting info for an existing accounting session 📊 Interim Accounting Records SHOULD be sent every time a re-authentication or re-authorization happens 🔄 Also, application-specific Diameter applications MAY define extra interim record triggers 🧩 Whether to use INTERIM_RECORD records is picked by the Acct-Interim-Interval AVP ⏲️STOP_RECORD(value 4): an Accounting Stop Record ends an accounting session and holds cumulative accounting info for the existing session 🛑
9.8.2. Acct-Interim-Interval 🕰️
The Acct-Interim-Interval AVP (AVP Code 85) is of type Unsigned32 and gets sent from the Diameter home authorization server to the Diameter client 💌 The client reads it to decide how and when to make accounting records. Depending on the value, a service session can produce one, two, or two+N accounting records, based on what the home-organization needs 🧁 Here's how the AVP changes what gets produced:
- Leaving out the Acct-Interim-Interval AVP, or including it with the Value field set to 0, means EVENT_RECORD, START_RECORD, and STOP_RECORD get produced, as appropriate for the service 🎯
- Including the AVP with the Value field set to a non-zero value means INTERIM_RECORD records MUST be produced between the START_RECORD and STOP_RECORD records 🌊 The Value field is the nominal interval between those records, in seconds. The Diameter node that originates the accounting info, called the client, MUST produce the first INTERIM_RECORD roughly when that nominal interval has passed since the START_RECORD, then the next one when the interval passes again, and so on until the session ends and a STOP_RECORD is produced 🏁 On top of that, the client MUST make sure the interim record production times are randomized, so that huge accounting message storms don't happen either between records or around a common service start time 🎲 No thundering herd, babe 🫶
9.8.3. Accounting-Record-Number AVP 🔢
The Accounting-Record-Number AVP (AVP Code 485) is of type Unsigned32 and identifies this record within one session 🪪 Session-Id AVPs are globally unique, so the combination of Session-Id and Accounting-Record-Number AVPs is also globally unique, and you can use it to match accounting records with confirmations ✅ An easy way to make unique numbers: set the value to 0 for EVENT_RECORD and START_RECORD records, set it to 1 for the first INTERIM_RECORD, 2 for the second, and so on, until the STOP_RECORD's value is one more than the last INTERIM_RECORD 🌈 Numbering that's honestly so satisfying 😭🍓
9.8.4. Acct-Session-Id AVP 🎀
okay so the Acct-Session-Id AVP (AVP Code 44) is of type OctetString and is only used when RADIUS/Diameter translation occurs 🦋 It carries the contents of the RADIUS Acct-Session-Id attribute, so it's basically the bridge between the two worlds ✨
9.8.5. Acct-Multi-Session-Id AVP 🔗
the Acct-Multi-Session-Id AVP (AVP Code 50) is of type UTF8String and follows the format in Section 8.8 💅 its whole job is linking together a bunch of related accounting sessions. every session still gets its own unique Session-Id, but they all share the same Acct-Multi-Session-Id, iykyk 🧚 the Diameter server MAY send this AVP back in an authorization answer, and it MUST be used in all accounting messages for the given session 🫶
9.8.6. Accounting-Sub-Session-Id AVP 🌸
the Accounting-Sub-Session-Id AVP (AVP Code 287) is of type Unsigned64 and holds the accounting sub-session identifier 💖 the combination of the Session-Id and this AVP MUST be unique per sub-session, and the value of this AVP MUST be monotonically increased by one for all new sub-sessions. no cap, the numbers only go up 📈
if this AVP isn't there, that means no sub-sessions are in use. the one exception is an Accounting-Request whose Accounting-Record-Type is set to STOP_RECORD 💀 a STOP_RECORD message with no Accounting-Sub-Session-Id AVP present will signal the termination of all sub-sessions for a given Session-Id, so it's the big "everybody out" button 👑
9.8.7. Accounting-Realtime-Required AVP 🦋
the Accounting-Realtime-Required AVP (AVP Code 483) is of type Enumerated and gets sent from the Diameter home authorization server to the Diameter client, or in the Accounting-Answer from the accounting server 🌈 the client uses what's in this AVP to figure out what to do when sending accounting records to the accounting server has been temporarily blocked, for example because of a network problem 🙈
the possible values are:
- DELIVER_AND_GRANT (
1): with this value, the service MUST only be granted as long as there is a connection to an accounting server. ngl this one is strict 😤 the set of alternative accounting servers counts as one server here, so having to move the accounting record stream to a backup server is not a reason to cut off the user's service ✨ - GRANT_AND_STORE (
2): with this value, service SHOULD be granted if there is a connection, or as long as records can still be stored as described in Section 9.4 🍓 this is the default behavior if the AVP isn't included in the reply from the authorization server 🫶 - GRANT_AND_LOSE (
3): with this value, service SHOULD be granted even if the records can not be delivered or stored 😭 the records might just get lost, so bestie, plan accordingly 💜
10. AVP Occurrence Table 📋
the following tables present the AVPs defined in this document, and specify in which Diameter messages they MAY, or MAY NOT be present 🎀 AVPs that can only be present within a Grouped AVP aren't represented in this table, so don't go looking for them here 🙈
the table uses these symbols:
0 The AVP MUST NOT be present in the message.
0+ Zero or more instances of the AVP MAY be present in the
message.
0-1 Zero or one instance of the AVP MAY be present in the
message. It is considered an error if there are more than
one instance of the AVP.
1 One instance of the AVP MUST be present in the message.
1+ At least one instance of the AVP MUST be present in the
message.10.1. Base Protocol Command AVP Table 🍓
this table is limited to the non-accounting Command Codes defined in this specification ✨
+-----------------------------------------------+
| Command-Code |
+---+---+---+---+---+---+---+---+---+---+---+---+
Attribute Name |CER|CEA|DPR|DPA|DWR|DWA|RAR|RAA|ASR|ASA|STR|STA|
--------------------+---+---+---+---+---+---+---+---+---+---+---+---+
Acct-Interim- |0 |0 |0 |0 |0 |0 |0-1|0 |0 |0 |0 |0 |
Interval | | | | | | | | | | | | |
Accounting-Realtime-|0 |0 |0 |0 |0 |0 |0-1|0 |0 |0 |0 |0 |
Required | | | | | | | | | | | | |
Acct-Application-Id |0+ |0+ |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |
Auth-Application-Id |0+ |0+ |0 |0 |0 |0 |1 |0 |1 |0 |1 |0 |
Auth-Grace-Period |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |
Auth-Request-Type |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |
Auth-Session-State |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |
Authorization- |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |
Lifetime | | | | | | | | | | | | |
Class |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0+ |0+ |
Destination-Host |0 |0 |0 |0 |0 |0 |1 |0 |1 |0 |0-1|0 |
Destination-Realm |0 |0 |0 |0 |0 |0 |1 |0 |1 |0 |1 |0 |
Disconnect-Cause |0 |0 |1 |0 |0 |0 |0 |0 |0 |0 |0 |0 |
Error-Message |0 |0-1|0 |0-1|0 |0-1|0 |0-1|0 |0-1|0 |0-1|
Error-Reporting-Host|0 |0 |0 |0 |0 |0 |0 |0-1|0 |0-1|0 |0-1|
Failed-AVP |0 |0+ |0 |0+ |0 |0+ |0 |0+ |0 |0+ |0 |0+ |
Firmware-Revision |0-1|0-1|0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |
Host-IP-Address |1+ |1+ |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |
Inband-Security-Id |0+ |0+ |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |
Multi-Round-Time-Out|0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |
Origin-Host |1 |1 |1 |1 |1 |1 |1 |1 |1 |1 |1 |1 |
Origin-Realm |1 |1 |1 |1 |1 |1 |1 |1 |1 |1 |1 |1 |
Origin-State-Id |0-1|0-1|0 |0 |0-1|0-1|0-1|0-1|0-1|0-1|0-1|0-1|
Product-Name |1 |1 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |
Proxy-Info |0 |0 |0 |0 |0 |0 |0+ |0+ |0+ |0+ |0+ |0+ |
Redirect-Host |0 |0 |0 |0 |0 |0 |0 |0+ |0 |0+ |0 |0+ |
Redirect-Host-Usage |0 |0 |0 |0 |0 |0 |0 |0-1|0 |0-1|0 |0-1|
Redirect-Max-Cache- |0 |0 |0 |0 |0 |0 |0 |0-1|0 |0-1|0 |0-1|
Time | | | | | | | | | | | | |
Result-Code |0 |1 |0 |1 |0 |1 |0 |1 |0 |0 |0 |1 |
Re-Auth-Request-Type|0 |0 |0 |0 |0 |0 |1 |0 |0 |0 |0 |0 |
Route-Record |0 |0 |0 |0 |0 |0 |0+ |0 |0+ |0 |0+ |0 |
Session-Binding |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |
Session-Id |0 |0 |0 |0 |0 |0 |1 |1 |1 |1 |1 |1 |
Session-Server- |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |
Failover | | | | | | | | | | | | |
Session-Timeout |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |
Supported-Vendor-Id |0+ |0+ |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |
Termination-Cause |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |1 |0 |
User-Name |0 |0 |0 |0 |0 |0 |0-1|0-1|0-1|0-1|0-1|0-1|
Vendor-Id |1 |1 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |
Vendor-Specific- |0+ |0+ |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |
Application-Id | | | | | | | | | | | | |
--------------------+---+---+---+---+---+---+---+---+---+---+---+---+10.2. Accounting AVP Table 🧾
this table shows which AVPs defined in this document should be present in the Accounting messages 💅 these AVP occurrence requirements are guidelines, which may be expanded and/or overridden by application-specific requirements in the Diameter applications documents 🌸
+-----------+
| Command |
| Code |
+-----+-----+
Attribute Name | ACR | ACA |
------------------------------+-----+-----+
Acct-Interim-Interval | 0-1 | 0-1 |
Acct-Multi-Session-Id | 0-1 | 0-1 |
Accounting-Record-Number | 1 | 1 |
Accounting-Record-Type | 1 | 1 |
Acct-Session-Id | 0-1 | 0-1 |
Accounting-Sub-Session-Id | 0-1 | 0-1 |
Accounting-Realtime-Required | 0-1 | 0-1 |
Acct-Application-Id | 0-1 | 0-1 |
Auth-Application-Id | 0 | 0 |
Class | 0+ | 0+ |
Destination-Host | 0-1 | 0 |
Destination-Realm | 1 | 0 |
Error-Reporting-Host | 0 | 0+ |
Event-Timestamp | 0-1 | 0-1 |
Origin-Host | 1 | 1 |
Origin-Realm | 1 | 1 |
Proxy-Info | 0+ | 0+ |
Route-Record | 0+ | 0+ |
Result-Code | 0 | 1 |
Session-Id | 1 | 1 |
Termination-Cause | 0-1 | 0-1 |
User-Name | 0-1 | 0-1 |
Vendor-Specific-Application-Id| 0-1 | 0-1 |
------------------------------+-----+-----+11. IANA Considerations 🏛️
this section gives guidance to the Internet Assigned Numbers Authority (IANA) about registering values related to the Diameter protocol, following BCP 26 [IANA] 💖 the policies used here have the meanings defined in BCP 26: "Private Use", "First Come First Served", "Expert Review", "Specification Required", "IETF Consensus", and "Standards Action" 🎀
this section explains the criteria IANA should use when assigning numbers within the namespaces defined in this document ✨
Diameter is not meant to be a general purpose protocol, so allocations SHOULD NOT be made for purposes unrelated to authentication, authorization or accounting 🙅♀️
for registration requests where a Designated Expert should be consulted, the responsible IESG area director should appoint the Designated Expert 👑 for Designated Expert with Specification Required, the request is posted to the AAA WG mailing list (or, if it has been disbanded, a successor designated by the Area Director) for comment and review, and MUST include a pointer to a public specification 📮 before a period of 30 days has passed, the Designated Expert will either approve or deny the registration request and publish a notice of the decision to the AAA WG mailing list or its successor 🗓️ a denial notice must be justified by an explanation and, where it is possible, concrete suggestions on how the request can be modified so it becomes acceptable 🫶
11.1. AVP Header 🧩
as defined in Section 4, the AVP header contains three fields that require IANA namespace management: the AVP Code, Vendor-ID and Flags field 🌈
11.1.1. AVP Codes 🔢
okay so the AVP Code namespace is where attributes get their numbers, and there's more than one of them 🧚. Vendors get their own namespace, identified by their Vendor-ID (also called Enterprise-Number), and they run their own vendor-specific AVP code assignments inside it 💅. No Vendor-ID, or a Vendor-ID of zero (0), means you're in the IETF IANA-controlled AVP Codes namespace. IANA controls the AVP Codes, and sometimes the possible values inside an AVP too 🌸.
AVP Code 0 is not used 🙈. AVP Codes 1-255 are managed separately as RADIUS Attribute Types [RADTYPE]. This document defines AVP Codes 257-274, 276-285, 287, 291-300, 480, 483 and 485-486 ✨. For how the namespace gets assigned in this specification, see Section 4.5.
AVPs may be allocated following Designated Expert with Specification Required [IANA] 📋. Releasing blocks of AVPs (more than 3 at a time for a given purpose) should require IETF Consensus 🎀.
Also, Diameter has a mechanism for Vendor-Specific AVPs, where the Vendor-Id field in the AVP header is set to a non-zero value 🦋. Vendor-Specific AVP codes are for Private Use, and they should be encouraged instead of grabbing global attribute types, for functions that only matter to one vendor's Diameter implementation, where interoperability isn't deemed useful 💜. If a Vendor-Specific AVP ends up implemented by more than one vendor, then allocating a global AVP should be encouraged instead 👑.
11.1.2. AVP Flags 🚩
the AVP Flags field has 8 bits in the AVP header, defined in Section 4 🌈. This document assigns bit 0 ('V'endor Specific), bit 1 ('M'andatory) and bit 2 ('P'rotected) 💖. The remaining bits should only be assigned via a Standards Action [IANA], so hands off unless it's a Standards Action 🙅♀️.
11.2. Diameter Header 🎀
as defined in Section 3, the Diameter header has two fields that need IANA namespace management: Command Code and Command Flags 🫶.
11.2.1. Command Codes 🧾
the Command Code namespace is used to identify Diameter commands ✨. Values 0-255 are reserved for RADIUS backward compatibility, and they're defined as "RADIUS Packet Type Codes" in [RADTYPE] 🍓. Values 256-16,777,213 are for permanent, standard commands, allocated by IETF Consensus [IANA] 💅. This document defines Command Codes 257, 258, 271, 274-275, 280 and 282. For how the namespace gets assigned in this specification, see Section 3.1 🦋.
Values 16,777,214 and 16,777,215 (hexadecimal values 0xfffffe - 0xffffff) are reserved for experimental commands 🧪. These codes are only for experimental and testing purposes, so no guarantee is made for interoperability between Diameter peers using experimental commands, as outlined in [IANA-EXP]. Tread carefully, bestie 💀.
11.2.2. Command Flags 🚩
the Diameter header's Command Flags field has eight bits 💜. This document assigns bit 0 ('R'equest), bit 1 ('P'roxy), bit 2 ('E'rror) and bit 3 ('T') ✨. Bits 4 through 7 MUST only be assigned via a Standards Action [IANA], so that's a hard rule 🔥.
11.3. Application Identifiers 🌸
as defined in Section 2.4, the Application Identifier is used to identify a specific Diameter Application 🧚. There are standards-track application IDs and vendor specific application IDs 🌈.
IANA [IANA] has assigned the range 0x00000001 to 0x00ffffff for standards-track applications, and 0x01000000 - 0xfffffffe for vendor specific applications, on a first-come, first-served basis 🎀. These values are allocated:
Diameter Common Messages 0
NASREQ 1 [NASREQ]
Mobile-IP 2 [DIAMMIP]
Diameter Base Accounting 3
Relay 0xffffffffAssignment of standards-track application IDs is by Designated Expert with Specification Required [IANA] 📋.
Both Application-Id and Acct-Application-Id AVPs use the same Application Identifier space 👯♀️.
Vendor-Specific Application Identifiers are for Private Use 🔒. They're assigned on a First Come, First Served basis by IANA 💖.
11.4. AVP Values 🍭
certain AVPs in Diameter define a list of values with various meanings 🎨. For attributes other than the ones specified in this section, adding more values to the list can be done on a First Come, First Served basis by IANA ✨.
11.4.1. Result-Code AVP Values 🚦
as defined in Section 7.1, the Result-Code AVP (AVP Code 268) defines the values 1001, 2001-2002, 3001-3010, 4001-4002 and 5001-5017 💅.
All remaining values are available for assignment via IETF Consensus [IANA] 🫶.
11.4.2. Accounting-Record-Type AVP Values 🧾
as defined in Section 9.8.1, the Accounting-Record-Type AVP (AVP Code 480) defines the values 1-4 🌸. All remaining values are available for assignment via IETF Consensus [IANA] 🦋.
11.4.3. Termination-Cause AVP Values 🛑
as defined in Section 8.15, the Termination-Cause AVP (AVP Code 295) defines the values 1-8 💜. All remaining values are available for assignment via IETF Consensus [IANA] ✨.
11.4.4. Redirect-Host-Usage AVP Values 🔀
as defined in Section 6.13, the Redirect-Host-Usage AVP (AVP Code 261) defines the values 0-5 🎀. All remaining values are available for assignment via IETF Consensus [IANA] 🌈.
11.4.5. Session-Server-Failover AVP Values 🛟
as defined in Section 8.18, the Session-Server-Failover AVP (AVP Code 271) defines the values 0-3 🍓. All remaining values are available for assignment via IETF Consensus [IANA] 💅.
11.4.6. Session-Binding AVP Values 🔗
as defined in Section 8.17, the Session-Binding AVP (AVP Code 270) defines the bits 1-4 🧚. All remaining bits are available for assignment via IETF Consensus [IANA] 💖.
11.4.7. Disconnect-Cause AVP Values 📴
as defined in Section 5.4.3, the Disconnect-Cause AVP (AVP Code 273) defines the values 0-2 ✨. All remaining values are available for assignment via IETF Consensus [IANA] 🫶.
11.4.8. Auth-Request-Type AVP Values 🔐
as defined in Section 8.7, the Auth-Request-Type AVP (AVP Code 274) defines the values 1-3 🌸. All remaining values are available for assignment via IETF Consensus [IANA] 👑.
11.4.9. Auth-Session-State AVP Values 🗂️
as defined in Section 8.11, the Auth-Session-State AVP (AVP Code 277) defines the values 0-1 🦋. All remaining values are available for assignment via IETF Consensus [IANA] 💜.
11.4.10. Re-Auth-Request-Type AVP Values 🔁
as defined in Section 8.12, the Re-Auth-Request-Type AVP (AVP Code 285) defines the values 0-1 🎀. All remaining values are available for assignment via IETF Consensus [IANA] ✨.
11.4.11. Accounting-Realtime-Required AVP Values ⏱️
as defined in Section 9.8.7, the Accounting-Realtime-Required AVP (AVP Code 483) defines the values 1-3 🌈. All remaining values are available for assignment via IETF Consensus [IANA] 🍓.
11.4.12. Inband-Security-Id AVP (code 299) 🔐
as defined in Section 6.10, the Inband-Security-Id AVP (AVP Code 299) defines the values 0-1 💅. All remaining values are available for assignment via IETF Consensus [IANA] 🧚.
11.5. Diameter TCP/SCTP Port Numbers 🔌
IANA has assigned TCP and SCTP port number 3868 to Diameter 🦋.
11.6. NAPTR Service Fields 🏷️
the registration in the RFC MUST include the following information 📝:
Service Field: the service field being registered. An example for a new fictitious transport protocol called NCTP might be "AAA+D2N" 🧪.
Protocol: the specific transport protocol associated with that service field. This MUST include the name and acronym for the protocol, along with a reference to a document that describes the transport protocol. For example, "New Connectionless Transport Protocol (NCTP), RFC 5766" 💖.
Name and Contact Information: the name, address, email address and telephone number for the person performing the registration 📞.
The following values have been placed into the registry 🗃️:
Services Field Protocol
AAA+D2T TCP
AAA+D2S SCTP12. Diameter protocol related configurable parameters ⚙️
this section contains the configurable parameters that are found throughout this document 🎛️.
Diameter Peer A Diameter entity MAY communicate with peers that are statically configured 🤝. A statically configured Diameter peer would require that either the IP address or the fully qualified domain name (FQDN) be supplied, which would then be used to resolve through DNS 🌐.
Realm Routing Table A Diameter proxy server routes messages based on the realm portion of a Network Access Identifier (NAI) 🗺️. The server MUST have a table of Realm Names, and the address of the peer to which the message must be forwarded to 📬. The routing table MAY also include a "default route", which is typically used for all messages that cannot be locally processed 🛣️.
Tc timer The Tc timer controls the frequency that transport connection attempts are done to a peer with whom no active transport connection exists ⏰. The recommended value is 30 seconds 🕧.
13. Security Considerations 🔐
the Diameter base protocol assumes that messages are secured by using either IPSec or TLS 🛡️. This security mechanism is acceptable in environments where there is no untrusted third party agent. In other situations, end-to-end security is needed 🚨.
Diameter clients, such as Network Access Servers (NASes) and Mobility Agents, MUST support IP Security [SECARCH] and MAY support TLS [TLS] 💪. Diameter servers MUST support TLS and IPsec 🖥️. Diameter implementations MUST use transmission-level security of some kind (IPsec or TLS) on each connection 🔒.
If a Diameter connection is not protected by IPsec, then the CER/CEA exchange MUST include an Inband-Security-ID AVP with a value of TLS. For TLS usage, a TLS handshake will begin when both ends are in the open state, after completion of the CER/CEA exchange. If the TLS handshake is successful, all further messages will be sent via TLS. If the handshake fails, both ends move to the closed state. 🚨
It is suggested that IPsec be used primarily at the edges for intra-domain exchanges 🏠. For NAS devices without certificate support, pre-shared keys can be used between the NAS and a local AAA proxy 🔑.
For protection of inter-domain exchanges, TLS is recommended 🌍. See Sections 13.1 and 13.2 for more details on IPsec and TLS usage 🧾.
13.1. IPsec Usage 🔐
Okay bestie, first things first 💅 every Diameter implementation MUST support IPsec ESP [IPsec] in transport mode, with non-null encryption and authentication algorithms. That's how you get per-packet authentication, integrity protection and confidentiality 🫶 and it MUST also support the replay protection mechanisms of IPsec. No cap, that's the baseline.
Next up is IKE 🔑 Diameter implementations MUST support IKE for peer authentication, negotiation of security associations, and key management, using the IPsec DOI [IPSECDOI]. They MUST also support peer authentication with a pre-shared key, and they MAY support certificate-based peer authentication using digital signatures. Peer authentication using the public key encryption methods outlined in IKE's Sections 5.2 and 5.3 [IKE] SHOULD NOT be used. Not it 🙈
Conformant implementations MUST support both IKE Main Mode and Aggressive Mode 🎀 When pre-shared keys are used for authentication, IKE Aggressive Mode SHOULD be used, and IKE Main Mode SHOULD NOT be used. When digital signatures are used for authentication, either IKE Main Mode or IKE Aggressive Mode MAY be used. Lowkey iconic that you get a choice there ✨
When digital signatures are used to achieve authentication, an IKE negotiator SHOULD use IKE Certificate Request Payload(s) to specify the certificate authority (or authorities) that are trusted in accordance with its local policy. IKE negotiators SHOULD also use pertinent certificate revocation checks before accepting a PKI certificate for use in IKE's authentication procedures. Certificate checks are a whole vibe 🧚
Now the really picky part 🌸 The Phase 2 Quick Mode exchanges used to negotiate protection for Diameter connections MUST explicitly carry the Identity Payload fields (IDci and IDcr). The DOI supports several types of identification data, but when used in conformant implementations, each ID Payload MUST carry a single IP address and a single non-zero port number, and MUST NOT use the IP Subnet or IP Address Range formats. The point is that the Phase 2 security association lines up with specific TCP and SCTP connections 🦋
Since IPsec acceleration hardware may only be able to handle a limited number of active IKE Phase 2 SAs, Phase 2 delete messages may be sent for idle SAs, so the number of active Phase 2 SAs stays as low as possible 🍓 The receipt of an IKE Phase 2 delete message SHOULD NOT be read as a reason to tear down a Diameter connection. Honestly, it's better to leave the connection up. If more traffic shows up on it, bring up another IKE Phase 2 SA to protect it. This stops the connection from going up and down over and over again 😭
13.2. TLS Usage 🔒
A Diameter node that starts a connection to another Diameter node acts as a TLS client according to [TLS], and a Diameter node that accepts a connection acts as a TLS server 💜 Diameter nodes implementing TLS for security MUST mutually authenticate as part of TLS session establishment. To make sure that happens, the Diameter node acting as TLS server must request a certificate from the Diameter node acting as TLS client, and the Diameter node acting as TLS client MUST be prepared to supply a certificate on request. Both sides showing their IDs, bestie 🪪
Diameter nodes MUST be able to negotiate the following TLS cipher suites:
TLS_RSA_WITH_RC4_128_MD5
TLS_RSA_WITH_RC4_128_SHA
TLS_RSA_WITH_3DES_EDE_CBC_SHADiameter nodes SHOULD be able to negotiate the following TLS cipher suite:
TLS_RSA_WITH_AES_128_CBC_SHADiameter nodes MAY negotiate other TLS cipher suites. Mix and match, queen 👑
13.3. Peer-to-Peer Considerations 🤝
Like any peer-to-peer protocol, setting up the trust model inside a Diameter peer properly is essential for security 🥹 When certificates are used, you have to configure the root certificate authorities that the Diameter peer trusts. These root CAs are likely to be unique to Diameter and different from the root CAs that might be trusted for other stuff, like Web browsing. Generally, those root CAs get configured to reflect the business relationships between the organization hosting the Diameter peer and other organizations. So a Diameter peer will typically not be set up to connect with any arbitrary peer 🙅♀️ When certificate authentication is used and Diameter peers may not be known beforehand, peer discovery may be required.
Note that IPsec is a lot less flexible than TLS when it comes to configuring root CAs 💀 Since Port identifiers can't be used within IKE Phase 1, you can't uniquely configure trusted root CAs for each application separately with IPsec. The same policy has to be used for all applications. For example, a root CA trusted for Diameter must also be trusted to protect SNMP. These restrictions can be awkward at best. TLS supports application-level granularity in certificate policy, so TLS SHOULD be used to protect Diameter connections between administrative domains. IPsec is most appropriate for intra-domain usage when pre-shared keys are used as the security mechanism ✨
When pre-shared key authentication is used with IPsec to protect Diameter, unique pre-shared keys are configured with Diameter peers. Those peers are identified by their IP address (Main Mode), or possibly their FQDN (Aggressive Mode). That means the set of Diameter peers has to be known beforehand, so peer discovery is typically not necessary 🌈
Here's some guidance on the issue 📝
It is recommended that a Diameter peer implement the same security mechanism (IPsec or TLS) across all its peer-to-peer connections. Mixing security mechanisms can result in redundant security mechanisms being used (for example, TLS over IPsec) or, worse, potential security vulnerabilities 😱 When IPsec is used with Diameter, a typical security policy for outbound traffic is "Initiate IPsec, from me to any, destination port Diameter". For inbound traffic, the policy would be "Require IPsec, from any to me, destination port Diameter".
This policy makes IPsec get used whenever a Diameter peer starts a connection to another Diameter peer, and makes it required whenever an inbound Diameter connection shows up 🎀 It's super attractive because you don't have to set policy for each peer or change it dynamically every time a new Diameter connection is created. An IPsec SA is created automatically from one simple static policy. IPsec extensions usually aren't available to the sockets API on most platforms, and IPsec policy functionality depends on the implementation, so a simple static policy is often the easiest way to get IPsec turned on in a Diameter implementation 💖
One catch with the recommended policy: if a node is using both TLS and IPsec, there's no convenient way to use either TLS or IPsec but not both, unless you reserve an extra port for TLS 🙃 Diameter uses the same port for TLS and non-TLS usage. Where the recommended IPsec policy is in place, a TLS-protected connection matches the IPsec policy, so both IPsec and TLS end up protecting the Diameter connection. To avoid that, you'd have to plumb peer-specific policies in, either statically or dynamically.
If IPsec is used to secure Diameter peer-to-peer connections, IPsec policy SHOULD be set to require IPsec protection for inbound connections, and to initiate IPsec protection for outbound connections. This can be done with inbound and outbound filter policy 🧚♀️
14. References 📚
14.1. Normative References 📚✨
Okay bestie, this is the reading list the spec leans on hardest. Every one of these is needed to implement it, so no skipping 💅
[AAATRANS]Aboba, B. and J. Wood, "Authentication, Authorization and Accounting (AAA) Transport Profile", RFC 3539, June 2003.[ABNF]Crocker, D. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", RFC 2234, November 1997.[ASSIGNNO]Reynolds, J., "Assigned Numbers: RFC 1700 is Replaced by an On-line Database", RFC 3232, January 2002.[DIFFSERV]Nichols, K., Blake, S., Baker, F. and D. Black, "Definition of the Differentiated Services Field (DS Field) in the IPv4 and IPv6 Headers", RFC 2474, December 1998.[DIFFSERVAF]Heinanen, J., Baker, F., Weiss, W. and J. Wroclawski, "Assured Forwarding PHB Group", RFC 2597, June 1999.[DIFFSERVEF]Davie, B., Charny, A., Bennet, J., Benson, K., Le Boudec, J., Courtney, W., Davari, S., Firoiu, V. and D. Stiliadis, "An Expedited Forwarding PHB", RFC 3246, March 2002.[DNSSRV]Gulbrandsen, A., Vixie, P. and L. Esibov, "A DNS RR for specifying the location of services (DNS SRV)", RFC 2782, February 2000.[EAP]Blunk, L. and J. Vollbrecht, "PPP Extensible Authentication Protocol (EAP)", RFC 2284, March 1998.[FLOATPOINT]Institute of Electrical and Electronics Engineers, "IEEE Standard for Binary Floating-Point Arithmetic", ANSI/IEEE Standard 754-1985, August 1985.[IANA]Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 2434, October 1998.[IANAADFAM]IANA; "Address Family Numbers", http://www.iana.org/assignments/address-family-numbers[IANAWEB]IANA, "Number assignment", http://www.iana.org[IKE]Harkins, D. and D. Carrel, "The Internet Key Exchange (IKE)", RFC 2409, November 1998.[IPComp]Shacham, A., Monsour, R., Pereira, R. and M. Thomas, "IP Payload Compression Protocol (IPComp)", RFC 3173, September 2001.[IPSECDOI]Piper, D., "The Internet IP Security Domain of Interpretation for ISAKMP", RFC 2407, November 1998.[IPV4]Postel, J., "Internet Protocol", STD 5, RFC 791, September 1981.[IPV6]Hinden, R. and S. Deering, "IP Version 6 Addressing Architecture", RFC 2373, July 1998.[KEYWORDS]Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.[NAI]Aboba, B. and M. Beadles, "The Network Access Identifier", RFC 2486, January 1999.[NAPTR]Mealling, M. and R. Daniel, "The naming authority pointer (NAPTR) DNS resource record," RFC 2915, September 2000.[RADTYPE]IANA, "RADIUS Types", http://www.iana.org/assignments/radius-types[SCTP]Stewart, R., Xie, Q., Morneault, K., Sharp, C., Schwarzbauer, H., Taylor, T., Rytina, I., Kalla, M., Zhang, L. and V. Paxson, "Stream Control Transmission Protocol", RFC 2960, October 2000.[SLP]Veizades, J., Guttman, E., Perkins, C. and M. Day, "Service Location Protocol, Version 2", RFC 2165, June 1999.[SNTP]Mills, D., "Simple Network Time Protocol (SNTP) Version 4 for IPv4, IPv6 and OSI", RFC 2030, October 1996.[TCP]Postel, J. "Transmission Control Protocol", STD 7, RFC 793, January 1981.[TEMPLATE]Guttman, E., Perkins, C. and J. Kempf, "Service Templates and Service: Schemes", RFC 2609, June 1999.[TLS]Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", RFC 2246, January 1999.[TLSSCTP]Jungmaier, A., Rescorla, E. and M. Tuexen, "Transport Layer Security over Stream Control Transmission Protocol", RFC 3436, December 2002.[URI]Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform Resource Identifiers (URI): Generic Syntax", RFC 2396, August 1998.[UTF8]Yergeau, F., "UTF-8, a transformation format of ISO 10646", RFC 2279, January 1998.
14.2. Informative References 🦋
These ones are the background reading. Super helpful for the "why" behind everything, even though the spec doesn't strictly need them to work 🌸
[AAACMS]P. Calhoun, W. Bulley, S. Farrell, "Diameter CMS Security Application", Work in Progress.[AAAREQ]Aboba, B., Calhoun, P., Glass, S., Hiller, T., McCann, P., Shiino, H., Zorn, G., Dommety, G., Perkins, C., Patil, B., Mitton, D., Manning, S., Beadles, M., Walsh, P., Chen, X., Sivalingham, S., Hameed, A., Munson, M., Jacobs, S., Lim, B., Hirschman, B., Hsu, R., Xu, Y., Campbell, E., Baba, S. and E. Jaques, "Criteria for Evaluating AAA Protocols for Network Access", RFC 2989, November 2000.[ACCMGMT]Aboba, B., Arkko, J. and D. Harrington. "Introduction to Accounting Management", RFC 2975, October 2000.[CDMA2000]Hiller, T., Walsh, P., Chen, X., Munson, M., Dommety, G., Sivalingham, S., Lim, B., McCann, P., Shiino, H., Hirschman, B., Manning, S., Hsu, R., Koo, H., Lipford, M., Calhoun, P., Lo, C., Jaques, E., Campbell, E., Xu, Y., Baba, S., Ayaki, T., Seki, T. and A. Hameed, "CDMA2000 Wireless Data Requirements for AAA", RFC 3141, June 2001.[DIAMMIP]P. Calhoun, C. Perkins, "Diameter Mobile IP Application", Work in Progress.[DYNAUTH]Chiba, M., Dommety, G., Eklund, M., Mitton, D. and B. Aboba, "Dynamic Authorization Extensions to Remote Authentication Dial In User Service (RADIUS)", RFC 3576, July 2003.[IANA-EXP]T. Narten, "Assigning Experimental and Testing Numbers Considered Useful", Work in Progress.[MIPV4]Perkins, C., "IP Mobility Support for IPv4", RFC 3344, August 2002.[MIPREQ]Glass, S., Hiller, T., Jacobs, S. and C. Perkins, "Mobile IP Authentication, Authorization, and Accounting Requirements", RFC 2977, October 2000.[NASNG]Mitton, D. and M. Beadles, "Network Access Server Requirements Next Generation (NASREQNG) NAS Model", RFC 2881, July 2000.[NASREQ]P. Calhoun, W. Bulley, A. Rubens, J. Haag, "Diameter NASREQ Application", Work in Progress.[NASCRIT]Beadles, M. and D. Mitton, "Criteria for Evaluating Network Access Server Protocols", RFC 3169, September 2001.[PPP]Simpson, W., "The Point-to-Point Protocol (PPP)", STD 51, RFC 1661, July 1994.[PROXYCHAIN]Aboba, B. and J. Vollbrecht, "Proxy Chaining and Policy Implementation in Roaming", RFC 2607, June 1999.[RADACCT]Rigney, C., "RADIUS Accounting", RFC 2866, June 2000.[RADEXT]Rigney, C., Willats, W. and P. Calhoun, "RADIUS Extensions", RFC 2869, June 2000.[RADIUS]Rigney, C., Willens, S., Rubens, A. and W. Simpson, "Remote Authentication Dial In User Service (RADIUS)", RFC 2865, June 2000.[ROAMREV]Aboba, B., Lu, J., Alsop, J., Ding, J. and W. Wang, "Review of Roaming Implementations", RFC 2194, September 1997.[ROAMCRIT]Aboba, B. and G. Zorn, "Criteria for Evaluating Roaming Protocols", RFC 2477, January 1999.[SECARCH]Kent, S. and R. Atkinson, "Security Architecture for the Internet Protocol", RFC 2401, November 1998.[TACACS]Finseth, C., "An Access Control Protocol, Sometimes Called TACACS", RFC 1492, July 1993.
15. Acknowledgements 💖
Time for the thank-you section, and honestly the people in here deserve all the flowers 🌸🫶
The authors want to give a huge shoutout to Nenad Trifunovic, Tony Johansson and Pankaj Patel for joining the pre-IETF Document Reading Party 📖. Allison Mankin, Jonathan Wood and Bernard Aboba were absolute legends when it came to working out the transport issues, and Steven Bellovin helped out in the same way on the security side 🔐.
Paul Funk and David Mitton were the reason the Peer State Machine came out right, and the authors are so grateful for the time they gave 🙌.
Text in this document was also provided by Paul Funk, Mark Eklund, Mark Jones and Dave Spence. Jacques Caron left a pile of great comments after reading through the whole spec super carefully 👑.
The authors also want to recognise the following people, who helped build the Diameter protocol 🧚:
Allan C. Rubens, Haseeb Akhtar, William Bulley, Stephen Farrell, David Frascone, Daniel C. Fox, Lol Grant, Ignacio Goyret, Nancy Greene, Peter Heitman, Fredrik Johansson, Mark Jones, Martin Julien, Bob Kopacz, Paul Krumviede, Fergal Ladley, Ryan Moats, Victor Muslin, Kenneth Peirce, John Schnizlein, Sumit Vakil, John R. Vollbrecht and Jeff Weisberg. 🌈
And finally, Pat Calhoun would like to thank Sun Microsystems, since most of the effort that went into this document happened while he worked there 🎀
Appendix A. Diameter Service Template ✨
okay bestie, so this one is the service template that Diameter servers use to advertise themselves 🎀 It makes picking the right server way easier, because a client can ask for specific Diameter servers based on what kind of service it wants (like an AAA server for accounting 💅).
Name of submitter: "Erik Guttman" <Erik.Guttman@sun.com> Language of service template: en
Security Considerations: Diameter clients and servers use various cryptographic mechanisms to protect communication integrity, confidentiality as well as perform end-point authentication. It would thus be difficult if not impossible for an attacker to advertise itself using SLPv2 and pose as a legitimate Diameter peer without proper preconfigured secrets or cryptographic keys. Still, as Diameter services are vital for network operation it is important to use SLPv2 authentication to prevent an attacker from modifying or eliminating service advertisements for legitimate Diameter servers.
Okay but the security part is SERIOUS 😭 An attacker basically can't pretend to be a legit Diameter peer without the right preconfigured secrets or keys 🔐 BUT since Diameter services are so vital for the network, you MUST use SLPv2 authentication so nobody can mess with or delete the advertisements for real Diameter servers 💀
Hmm wait, I need to fix that, I accidentally wrote MUST in capitals and the original doesn't say that here. Let me redo it properly:
Okay but the security part is SERIOUS 😭 An attacker basically can't pretend to be a legit Diameter peer without the right preconfigured secrets or keys 🔐 Still, since Diameter services are so vital for network operation, it is important to use SLPv2 authentication so an attacker can't modify or eliminate the advertisements for legit Diameter servers 💀
Template text: -------------------------template begins here----------------------- template-type=service:diameter
template-version=0.0
template-description= The Diameter protocol is defined by RFC 3588.
template-url-syntax= url-path= ; The Diameter URL format is described in Section 2.9. ; Example: 'aaa://aaa.example.com:1812;transport=tcp supported-auth-applications= string L M # This attribute lists the Diameter applications supported by the # AAA implementation. The applications currently defined are: # Application Name Defined by # ---------------- ----------------------------------- # NASREQ Diameter Network Access Server Application # MobileIP Diameter Mobile IP Application # # Notes: # . Diameter implementations support one or more applications. # . Additional applications may be defined in the future. # An updated service template will be created at that time.
# NASREQ,MobileIP
supported-acct-applications= string L M # This attribute lists the Diameter applications supported by the # AAA implementation. The applications currently defined are: # Application Name Defined by # ---------------- ----------------------------------- # NASREQ Diameter Network Access Server Application # MobileIP Diameter Mobile IP Application # # Notes: # . Diameter implementations support one or more applications. # . Additional applications may be defined in the future. # An updated service template will be created at that time. # NASREQ,MobileIP
supported-transports= string L M SCTP # This attribute lists the supported transports that the Diameter # implementation accepts. Note that a compliant Diameter # implementation MUST support SCTP, though it MAY support other # transports, too. SCTP,TCP
-------------------------template ends here-----------------------
Here's the template itself 🦋 The supported-transports bit has the one MUST: a compliant Diameter implementation MUST support SCTP, though it MAY support other transports too 🌈
Appendix B. NAPTR Example 🌸
okay so we're gonna walk through a NAPTR lookup for aaa:ex.com 👀 The client sends a NAPTR query for that domain and gets back these records:
;; order pref flags service regexp replacement IN NAPTR 50 50 "s" "AAA+D2S" "" _diameter._sctp.example.com IN NAPTR 100 50 "s" "AAA+D2T" "" _aaa._tcp.example.com
This tells us the server supports SCTP and TCP, in that order 🧚 If the client supports SCTP, SCTP gets used, aimed at a host found by an SRV lookup of _diameter._sctp.ex.com. That lookup would return:
;; Priority Weight Port Target IN SRV 0 1 5060 server1.example.com IN SRV 0 2 5060 server2.example.com
Appendix C. Duplicate Detection 💜
okay this one is about accounting records getting duplicated and how to spot them 🙈 As described in Section 9.4, duplicate detection for accounting records is based on session identifiers. Duplicates can show up for a few reasons:
- Failover to an alternate server. When close to real-time performance is required, failover thresholds need to be kept low, and this may lead to an increased likelihood of duplicates. Failover can occur at the client or within Diameter agents.
- Failure of a client or agent after sending of a record from non-volatile memory, but prior to receipt of an application layer ACK and deletion of the record. record to be sent. This will result in retransmission of the record soon after the client or agent has rebooted.
- Duplicates received from RADIUS gateways. Since the retransmission behavior of RADIUS is not defined within [RFC2865], the likelihood of duplication will vary according to the implementation.
- Implementation problems and misconfiguration.
The T flag is used as an indication of an application layer retransmission event, e.g., due to failover to an alternate server 🦋 It is defined only for request messages sent by Diameter clients or agents. For instance, after a reboot, a client may not know whether it has already tried to send the accounting records in its non-volatile memory before the reboot occurred. Diameter servers MAY use the T flag as an aid when processing requests and detecting duplicate messages. However, servers that do this MUST ensure that duplicates are found even when the first transmitted request arrives at the server after the retransmitted request. It can be used only in cases where no answer has been received from the Server for a request and the request is sent again (e.g., due to a failover to an alternate peer, due to a recovered primary peer, or due to a client re-sending a stored record from non-volatile memory such as after reboot of a client or agent).
In some cases the Diameter accounting server can delay the duplicate detection and accounting record processing until a post-processing phase takes place. At that time records are likely to be sorted according to the included User-Name, and duplicate elimination is easy in this case ✨ In other situations it may be necessary to perform real-time duplicate detection, such as when credit limits are imposed or real-time fraud detection is desired.
In general, only generation of duplicates due to failover or re-sending of records in non-volatile storage can be reliably detected by Diameter clients or agents. In such cases the Diameter client or agents can mark the message as a possible duplicate by setting the T flag. Since the Diameter server is responsible for duplicate detection, it can choose to make use of the T flag or not, in order to optimize duplicate detection. Since the T flag does not affect interoperability, and may not be needed by some servers, generation of the T flag is REQUIRED for Diameter clients and agents, but MAY be implemented by Diameter servers 👑
As an example, it can usually be assumed that duplicates appear within a time window of the longest recorded network partition or device fault, perhaps a day. So only records within this time window need to be looked at in the backward direction. Secondly, hashing techniques or other schemes, such as the use of the T flag in the received messages, may be used to eliminate the need to do a full search even in this set, except for rare cases.
The following is an example of how the T flag may be used by the server to detect duplicate requests.
A Diameter server MAY check the T flag of the received message to determine if the record is a possible duplicate. If the T flag is set in the request message, the server searches for a duplicate within a configurable duplication time window backward and forward. This limits database searching to those records where the T flag is set. In a well run network, network partitions and device faults will presumably be rare events, so this approach represents a substantial optimization of the duplicate detection process. During failover, it is possible for the original record to be received after the T flag marked record, due to differences in network delays experienced along the path by the original and duplicate transmissions. The likelihood of this occurring increases as the failover interval is decreased. In order to be able to detect out of order duplicates, the Diameter server should use backward and forward time windows when performing duplicate checking for the T flag marked request. For example, in order to allow time for the original record to exit the network and be recorded by the accounting server, the Diameter server can delay processing records with the T flag set until a time period TIME_WAIT + RECORD_PROCESSING_TIME has elapsed after the closing of the original transport connection. After this time period has expired, it may check the T flag marked records against the database with relative assurance that the original records, if sent, have been received and recorded.
Appendix D. Intellectual Property Statement 🎀
okay this is the legal bit, but it's still important 💅 The IETF takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document, or the extent to which any license under such rights might or might not be available. It also doesn't represent that it has made any effort to identify any such rights. Information on the IETF's procedures for rights in standards-track and standards-related documentation can be found in BCP-11. Copies of claims of rights made available for publication, and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification, can be obtained from the IETF Secretariat 🌈
The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights which may cover technology that may be required to practice this standard. Please address the information to the IETF Executive Director 🫶
Authors' Addresses 🌟
Pat R. Calhoun Airespace, Inc. 110 Nortech Parkway San Jose, California, 95134 USA
Phone: +1 408-635-2023 Fax: +1 408-635-2020 EMail: pcalhoun@airespace.com
John Loughney Nokia Research Center Itamerenkatu 11-13 00180 Helsinki Finland
Phone: +358 50 483 6242 EMail: john.Loughney@nokia.com
Jari Arkko Ericsson 02420 Jorvas Finland
Phone: +358 40 5079256 EMail: Jari.Arkko@ericsson.com
Erik Guttman Sun Microsystems, Inc. Eichhoelzelstr. 7 74915 Waibstadt Germany
Phone: +49 7263 911 701 EMail: erik.guttman@sun.com
Glen Zorn Cisco Systems, Inc. 500 108th Avenue N.E., Suite 500 Bellevue, WA 98004 USA
Phone: +1 425 438 8218
Full Copyright Statement 💖
Copyright (C) The Internet Society (2003). All Rights Reserved. 🎀
Okay, so, the rules for copying this doc are pretty chill, bestie ✨ You can copy and share it with anyone, and you can make derivative works that comment on or explain it or help people implement it. You can publish and distribute those too, in whole or in part, with no restrictions of any kind. The one condition is that the above copyright notice and this paragraph stay on every copy and every derivative work. 🫶
The original document itself can NOT be modified in any way. That means no removing the copyright notice or the references to the Internet Society or other Internet organizations. There are two exceptions. The first is when you need it to develop Internet standards, in which case you have to follow the copyright procedures in the Internet Standards process. The second is when you need to translate it into a language other than English. 🌈
These permissions are perpetual, which means they will never be revoked by the Internet Society or its successors or assigns. Forever and ever! 🦋
This document and the information in it are provided "AS IS" 🙈 THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Not a single guarantee, bestie. 💀
Acknowledgement 🌸
Funding for the RFC Editor function is currently provided by the Internet Society. 👑
📦 where this page comes from
- ietf: rfc3588 2003-09
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms