idnits 2.17.00 (12 Aug 2021) /tmp/idnits44523/draft-ietf-dime-app-design-guide-21.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document seems to contain a disclaimer for pre-RFC5378 work, and may have content which was first submitted before 10 November 2008. The disclaimer is necessary when there are original authors that you have been unable to contact, or if some do not wish to grant the BCP78 rights to the IETF Trust. If you are able to get all authors (current and original) to grant those rights, you can and should remove the disclaimer; otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (December 19, 2013) is 3074 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Obsolete informational reference (is this intentional?): RFC 2409 (Obsoleted by RFC 4306) -- Obsolete informational reference (is this intentional?): RFC 3588 (Obsoleted by RFC 6733) -- Obsolete informational reference (is this intentional?): RFC 4005 (Obsoleted by RFC 7155) -- Obsolete informational reference (is this intentional?): RFC 5226 (Obsoleted by RFC 8126) -- Obsolete informational reference (is this intentional?): RFC 5996 (Obsoleted by RFC 7296) Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 7 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Diameter Maintenance and Extensions (DIME) L. Morand, Ed. 3 Internet-Draft Orange Labs 4 Intended status: Informational V. Fajardo 5 Expires: June 22, 2014 6 H. Tschofenig 7 Nokia Siemens Networks 8 December 19, 2013 10 Diameter Applications Design Guidelines 11 draft-ietf-dime-app-design-guide-21 13 Abstract 15 The Diameter base protocol provides facilities for protocol 16 extensibility enabling to define new Diameter applications or modify 17 existing applications. This document is a companion document to the 18 Diameter Base protocol that further explains and clarifies the rules 19 to extend Diameter. It is meant as a guidelines document and 20 therefore as informative in nature. 22 Status of This Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at http://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on June 22, 2014. 39 Copyright Notice 41 Copyright (c) 2013 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (http://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 This document may contain material from IETF Documents or IETF 55 Contributions published or made publicly available before November 56 10, 2008. The person(s) controlling the copyright in some of this 57 material may not have granted the IETF Trust the right to allow 58 modifications of such material outside the IETF Standards Process. 59 Without obtaining an adequate license from the person(s) controlling 60 the copyright in such materials, this document may not be modified 61 outside the IETF Standards Process, and derivative works of it may 62 not be created outside the IETF Standards Process, except to format 63 it for publication as an RFC or to translate it into languages other 64 than English. 66 Table of Contents 68 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 69 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 70 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 3 71 4. Reusing Existing Diameter Applications . . . . . . . . . . . 5 72 4.1. Adding a New Command . . . . . . . . . . . . . . . . . . 5 73 4.2. Deleting an Existing Command . . . . . . . . . . . . . . 6 74 4.3. Reusing Existing Commands . . . . . . . . . . . . . . . . 6 75 4.3.1. Adding AVPs to a Command . . . . . . . . . . . . . . 7 76 4.3.2. Deleting AVPs from a Command . . . . . . . . . . . . 8 77 4.4. Reusing Existing AVPs . . . . . . . . . . . . . . . . . . 9 78 4.4.1. Setting of the AVP Flags . . . . . . . . . . . . . . 9 79 4.4.2. Reuse of AVP of Type Enumerated . . . . . . . . . . . 9 80 5. Defining New Diameter Applications . . . . . . . . . . . . . 10 81 5.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 10 82 5.2. Defining New Commands . . . . . . . . . . . . . . . . . . 10 83 5.3. Use of Application-Id in a Message . . . . . . . . . . . 11 84 5.4. Application-Specific Session State Machines . . . . . . . 11 85 5.5. Session-Id AVP and Session Management . . . . . . . . . . 12 86 5.6. Use of Enumerated Type AVPs . . . . . . . . . . . . . . . 12 87 5.7. Application-Specific Message Routing . . . . . . . . . . 14 88 5.8. Translation Agents . . . . . . . . . . . . . . . . . . . 15 89 5.9. End-to-End Application Capabilities Exchange . . . . . . 15 90 5.10. Diameter Accounting Support . . . . . . . . . . . . . . . 16 91 5.11. Diameter Security Mechanisms . . . . . . . . . . . . . . 18 92 6. Defining Generic Diameter Extensions . . . . . . . . . . . . 18 93 7. Guidelines for Registrations of Diameter Values . . . . . . . 19 94 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21 95 9. Security Considerations . . . . . . . . . . . . . . . . . . . 21 96 10. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 22 97 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 22 98 12. Informative References . . . . . . . . . . . . . . . . . . . 22 99 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 24 101 1. Introduction 103 The Diameter base protocol provides facilities to extend Diameter 104 (see Section 1.3 of [RFC6733]) to support new functionality. In the 105 context of this document, extending Diameter means one of the 106 following: 108 1. Addition of new functionality to an existing Diameter application 109 without defining a new application. 111 2. Addition of new functionality to an existing Diameter application 112 that requires the definition of a new application. 114 3. The definition of an entirely new Diameter application to offer 115 functionality not supported by existing applications. 117 4. The definition of a new generic functionality that can be reused 118 across different applications. 120 All of these choices are design decisions that can be done by any 121 combination of reusing existing or defining new commands, AVPs or AVP 122 values. However, application designers do not have complete freedom 123 when making their design. A number of rules have been defined in 124 [RFC6733] that place constraints on when an extension requires the 125 allocation of a new Diameter application identifier or a new command 126 code value. The objective of this document is the following: 128 o Clarify the Diameter extensibility rules as defined in the 129 Diameter base protocol. 131 o Discuss design choices and provide guidelines when defining new 132 applications. 134 o Present trade-off choices. 136 2. Terminology 138 This document reuses the terminology defined in [RFC6733]. 140 3. Overview 142 As designed, the Diameter base protocol [RFC6733] can be seen as a 143 two-layer protocol. The lower layer is mainly responsible for 144 managing connections between neighboring peers and for message 145 routing. The upper layer is where the Diameter applications reside. 146 This model is in line with a Diameter node having an application 147 layer and a peer-to-peer delivery layer. The Diameter base protocol 148 document defines the architecture and behavior of the message 149 delivery layer and then provides the framework for designing Diameter 150 applications on the application layer. This framework includes 151 definitions of application sessions and accounting support (see 152 Section 8 and Section 9 of [RFC6733]). Accordingly, a Diameter node 153 is seen in this document as a single instance of a Diameter message 154 delivery layer and one or more Diameter applications using it. 156 The Diameter base protocol is designed to be extensible and the 157 principles are described in the Section 1.3 of [RFC6733]. As a 158 summary, Diameter can be extended by: 160 1. Defining new AVP values 162 2. Creating new AVPs 164 3. Creating new commands 166 4. Creating new applications 168 As a main guiding principle, the recommendation is: "try to re-use as 169 much as possible!". It will reduce the time to finalize 170 specification writing, and it will lead to a smaller implementation 171 effort as well as reduce the need for testing. In general, it is 172 clever to avoid duplicate effort when possible. 174 However, re-use is not appropriate when the existing functionality 175 does not fit the new requirement and/or the re-use leads to 176 ambiguity. 178 The impact on extending existing applications can be categorized into 179 two groups: 181 Minor Extension: Enhancing the functional scope of an existing 182 application by the addition of optional features to support. Such 183 enhancement has no backward compatibility issue with the existing 184 application. 186 A typical example would be the definition of a new optional AVP 187 for use in an existing command. Diameter implementations 188 supporting the existing application but not the new AVP will 189 simply ignore it, without consequences for the Diameter message 190 handling. The standardization effort will be fairly small. 192 Major Extension: Enhancing an application that requires the 193 definition of a new Diameter application. 195 Typical examples would be the creation of a new command for 196 providing functionality not supported by existing applications or 197 the definition of a new AVP with the M-bit set to be carried in an 198 existing command. For such extension, a significant specification 199 effort is required and a careful approach is recommended. 201 We would also like to remind that the definition of a new Diameter 202 application and the definition of a new command should be something 203 to avoid as much as possible. In the past, there has been some 204 reluctance to define new commands and new applications. With the 205 modified extensibility rules provided by [RFC6733], registering new 206 commands and new applications does not lead to additional overhead 207 for the specification author in terms of standardization process. 208 Registering new functionality (new commands, new AVPs, new 209 applications, etc.) with IANA remains important to avoid namespace 210 collisions, which will likely lead to deployment problems. 212 4. Reusing Existing Diameter Applications 214 An existing application may need to be enhanced to fulfill new 215 requirements and these modifications can be at the command level and/ 216 or at the AVP level. The following sections describe the possible 217 modifications that can be performed on existing applications and 218 their related impact. 220 4.1. Adding a New Command 222 Adding a new command is considered as a major extension and requires 223 a new Diameter application to be defined. Adding a new command to an 224 application means either defining a completely new command or 225 importing the command's Command Code Format (CCF) syntax from another 226 application whereby the new application inherits some or all of the 227 functionality of the application where the command came from. In the 228 former case, the decision to create a new application is 229 straightforward since this is typically a result of adding a new 230 functionality that does not exist yet. For the latter, the decision 231 to create a new application will depend on whether importing the 232 command in a new application is more suitable than simply using the 233 existing application as it is in conjunction with any other 234 application. Therefore, a case by case study of each application 235 requirement should be applied. 237 An example considers the Diameter EAP application [RFC4072] and the 238 Diameter NASREQ application [RFC4005]. When network access 239 authentication using EAP is required, the Diameter EAP commands 240 (Diameter-EAP-Request/Diameter-EAP-Answer) are used; otherwise the 241 NASREQ application will be used. When the Diameter EAP application 242 is used, the accounting exchanges defined in Diameter NASREQ may be 243 used. 245 However, in general, it is difficult to come to a hard guideline, and 246 so a case-by-case study of each application requirement should be 247 applied. Before adding or importing a command, application designers 248 should consider the following: 250 o Can the new functionality be fulfilled by creating a new command 251 independent from any existing command? In this case, the 252 resulting new application and the existing application can work 253 independent of, but cooperating with each other. 255 o Can the existing command be reused without major extensions and 256 therefore without the need for the definition of a new 257 application, e.g., new functionality introduced by the creation of 258 new optional AVPs. 260 Note: Importing commands too liberally could result in a monolithic 261 and hard to manage application supporting too many different 262 features. 264 4.2. Deleting an Existing Command 266 Although this process is not typical, removing a command from an 267 application requires a new Diameter application to be defined. This 268 is due to the fact that the reception of the deleted command would 269 systematically result in a protocol error (i.e., 270 DIAMETER_COMMAND_UNSUPPORTED). 272 It is unusual to delete an existing command from an application for 273 the sake of deleting it or the functionality it represents. This 274 normally indicates of a flawed design. An exception might be if the 275 intent of the deletion is to create a newer version of the same 276 application that is somehow simpler than the previous version. 278 4.3. Reusing Existing Commands 280 This section discusses rules in adding and/or deleting AVPs from an 281 existing command of an existing application. The cases described in 282 this section may not necessarily result in the creation of new 283 applications. 285 From a historical point of view, it is worth to note that there was a 286 strong recommendation to re-use existing commands in the [RFC3588] to 287 prevent rapid depletion of code values available for vendor-specific 288 commands. However, [RFC6733] has relaxed the allocation policy and 289 enlarged the range of available code values for vendor-specific 290 applications. Although reuse of existing commands is still 291 recommended, protocol designers can consider defining a new command 292 when it provides a solution more suitable than the twisting of an 293 existing command's use and applications. 295 4.3.1. Adding AVPs to a Command 297 Based on the rules in [RFC6733], AVPs that are added to an existing 298 command can be categorized into: 300 o Mandatory (to understand) AVPs. As defined in [RFC6733], these 301 are AVPs with the M-bit flag set in this command, which means that 302 a Diameter node receiving them is required to understand not only 303 their values but also their semantics. Failure to do so will 304 cause an message handling error. This is regardless of whether 305 these AVPs are required or optional as specified by the command's 306 Command Code Format (CCF) syntax . 308 o Optional (to understand) AVPs. As defined in [RFC6733], these are 309 AVPs with the M-bit flag cleared in this command. A Diameter node 310 receiving these AVPs can simply ignore them if it does not support 311 them. 313 NOTE: As stated in RFC6733, the M-bit setting for a given AVP is 314 relevant to an application and each command within that 315 application that includes the AVP. 317 The rules are strict in the case where the AVPs to be added in an 318 exiting command are mandatory to understand, i.e., they have the 319 M-bit set. A mandatory AVP cannot be added to an existing command 320 without defining a new Diameter application, as stated in [RFC6733]. 321 This falls into the "Major Extensions" category. Despite the clarity 322 of the rule, ambiguity still arises when evaluating whether a new AVP 323 being added should be mandatory to begin with. Application designers 324 should consider the following questions when deciding about the M-bit 325 for a new AVP: 327 o Would it be required for the receiving side to be able to process 328 and understand the AVP and its content? 330 o Would the new AVPs change the state machine of the application? 332 o Would the presence of the new AVP lead to a different number of 333 round-trips, effectively changing the state machine of the 334 application? 336 o Would the new AVP be used to differentiate between old and new 337 versions of the same application whereby the two versions are not 338 backward compatible? 340 o Would the new AVP have duality in meaning, i.e., be used to carry 341 application-related information as well as to indicate that the 342 message is for a new application? 344 If the answer to at least one of the questions is "yes" then the 345 M-bit has to be set for the new AVP. This list of questions is non- 346 exhaustive and other criteria can be taken into account in the 347 decision process. 349 If application designers are instead contemplating the use of 350 optional AVPs, i.e., with the M-bit cleared, then the following are 351 some of the pitfalls that should be avoided: 353 o Use of optional AVPs with intersecting meaning. One AVP has 354 partially the same usage and meaning as another AVP. The presence 355 of both can lead to confusion. 357 o An optional AVPs with dual purpose, i.e., to carry application 358 data as well as to indicate support for one or more features. 359 This has a tendency to introduce interpretation issues. 361 o Adding one or more optional AVPs and indicating (usually within 362 descriptive text for the command) that at least one of them has to 363 be present in the command. This essentially circumventing the 364 ABNF and is equivalent to adding a mandatory AVP to the command. 366 These practices generally result in interoperability issues and 367 should be avoided as much as possible. 369 4.3.2. Deleting AVPs from a Command 371 Application designers may want to reuse an existing command but some 372 of the AVP present in the command's CCF syntax specification may be 373 irrelevant for the functionality foreseen to be supported by this 374 command. It may be then tempting to delete those AVPs from the 375 command. 377 The impacts of deleting an AVP from a command depends on its command 378 code format specification and M-bit setting: 380 o Deleting an AVP that is indicated as { AVP } in the command's CCF 381 syntax specification (regardless of the M-bit setting). 383 In this case, a new command code and subsequently a new Diameter 384 application have to be specified. 386 o Deleting an AVP, which has the M-bit set, and is indicated as [ 387 AVP ] in the command's CCF syntax specification. 389 No new command code has to be specified but the definition of a 390 new Diameter application is required. 392 o Deleting an AVP, which has the M-bit cleared, and is indicated as 393 [ AVP ] in the command's CCF syntax specification. 395 In this case, the AVP can be deleted without consequences. 397 If possible, application designers should attempt the reuse the 398 command's CCF syntax specification without modification and simply 399 ignore (but not delete) any optional AVP that will not be used. This 400 is to maintain compatibility with existing applications that will not 401 know about the new functionality as well as maintain the integrity of 402 existing dictionaries. 404 4.4. Reusing Existing AVPs 406 This section discusses rules in reusing existing AVP when reusing an 407 existing command or defining a new command in a new application. 409 4.4.1. Setting of the AVP Flags 411 When reusing AVPs in a new application, the AVP flag setting, such as 412 the mandatory flag ('M'-bit), has to be re-evaluated for a new 413 Diameter application and, if necessary, even for every command within 414 the application. In general, for AVPs defined outside of the 415 Diameter base protocol, the characteristics of an AVP are tied to its 416 role within an application and the commands. 418 All other AVP flags shall remain unchanged. 420 4.4.2. Reuse of AVP of Type Enumerated 421 When reusing an AVP of type Enumerated in a command for a new 422 application, it is recommended to avoid modifying the set of valid 423 values defined for this AVP. Modifying the set of Enumerated values 424 includes adding a value or deprecating the use of a value defined 425 initially for the AVP. Modifying the set of values will impact the 426 application defining this AVP and all the applications using this AVP 427 with potential interoperability issues. When the full range of 428 values defined for this Enumerated AVP is not suitable for the new 429 application, it is recommended to define a new AVP to avoid backwards 430 compatibility issues with existing implementations. 432 5. Defining New Diameter Applications 434 5.1. Introduction 436 This section discusses the case where new applications have 437 requirements that cannot be fulfilled by existing applications and 438 would require definition of completely new commands, AVPs and/or AVP 439 values. Typically, there is little ambiguity about the decision to 440 create these types of applications. Some examples are the interfaces 441 defined for the IP Multimedia Subsystem of 3GPP, e.g., Cx/Dx 442 ([TS29.228] and [TS29.229]), Sh ([TS29.328] and [TS29.329]) etc. 444 Application designers should try to import existing AVPs and AVP 445 values for any newly defined commands. In certain cases where 446 accounting will be used, the models described in Section 5.10 should 447 also be considered. 449 Additional considerations are described in the following sections. 451 5.2. Defining New Commands 453 As a general recommendation, commands should not be defined from 454 scratch. It is instead recommend to re-use an existing command 455 offering similar functionality and use it as a starting point. 457 Moreover, the new command's CCF syntax specification should be 458 carefully defined when considering applicability and extensibility of 459 the application. If most of the AVPs contained in the command are 460 indicated as fixed or required, it might be difficult to reuse the 461 same command and therefore the same application in a slightly changed 462 environment. Defining a command with most of the AVPs indicated as 463 optional must not be seen as a sub-optimal design introducing too 464 much flexibility in the protocol. The protocol designers are only 465 advised to clearly state the condition of presence of these AVPs and 466 properly define the corresponding behaviour of the Diameter nodes 467 when these AVPs are absent from the command. 469 Note: As a hint for protocol designers, it is not sufficient to just 470 look at the command's CCF syntax specification. It is also necessary 471 to carefully read through the accompanying text in the specification. 473 In the same way, the CCF syntax specification should be defined such 474 that it will be possible to add any arbitrary optional AVPs with the 475 M-bit cleared (including vendor-specific AVPs) without modifying the 476 application. For this purpose, it is strongly recommended to add "* 477 [AVP]" in the command's CCF, which allows the addition of any 478 arbitrary AVP as described in [RFC6733]. 480 5.3. Use of Application-Id in a Message 482 When designing new applications, designers should specify that the 483 Application Id carried in all session-level messages must be the 484 Application Id of the application using those messages. This 485 includes the session-level messages defined in Diameter base 486 protocol, i.e., RAR/RAA, STR/STA, ASR/ASA and possibly ACR/ACA in the 487 coupled accounting model, see Section 5.10. Some existing 488 specifications do not adhere to this rule for historical reasons. 489 However, this guidance should be followed to avoid routing problems. 491 In general, when a new application has been allocated with a new 492 Application Id and it also reuses existing commands with or without 493 modifications, it must use the newly allocated Application Id in the 494 header and in all relevant Application Id AVPs (Auth-Application-Id 495 or Acct-Application-Id) present in the commands message body. 497 Additionally, application designs using Vendor-Specific-Application- 498 Id AVP should not use the Vendor-Id AVP to further dissect or 499 differentiate the vendor-specification Application Id. Diameter 500 routing is not based on the Vendor-Id. As such, the Vendor-Id should 501 not be used as an additional input for routing or delivery of 502 messages. The Vendor-Id AVP is an informational AVP only and kept 503 for backward compatibility reasons. 505 5.4. Application-Specific Session State Machines 507 Section 8 of [RFC6733] provides session state machines for 508 authentication, authorization and accounting (AAA) services and these 509 session state machines are not intended to cover behavior outside of 510 AAA. If a new application cannot clearly be categorized into any of 511 these AAA services, it is recommended that the application defines 512 its own session state machine. Support for server-initiated request 513 is a clear example where an application-specific session state 514 machine would be needed, for example, the Rw interface for ITU-T push 515 model (cf.[Q.3303.3]). 517 5.5. Session-Id AVP and Session Management 519 Diameter applications are usually designed with the aim of managing 520 user sessions (e.g., Diameter network access session (NASREQ) 521 application [RFC4005]) or specific service access session (e.g., 522 Diameter SIP application [RFC4740]). In the Diameter base protocol, 523 session state is referenced using the Session-Id AVP. All Diameter 524 messages that use the same Session-Id will be bound to the same 525 session. Diameter-based session management also implies that both 526 Diameter client and server (and potentially proxy agents along the 527 path) maintain session state information. 529 However, some applications may not need to rely on the Session-Id to 530 identify and manage sessions because other information can be used 531 instead to correlate Diameter messages. Indeed, the User-Name AVP or 532 any other specific AVP can be present in every Diameter message and 533 used therefore for message correlation. Some applications might not 534 require the notion of Diameter session concept at all. For such 535 applications, the Auth-Session-State AVP is usually set to 536 NO_STATE_MAINTAINED in all Diameter messages and these applications 537 are therefore designed as a set of stand-alone transactions. Even if 538 an explicit access session termination is required, application- 539 specific commands are defined and used instead of the Session- 540 Termination-Request/Answer (STR/STA) or Abort-Session-Request/Answer 541 (ASR/ASA) defined in the Diameter base protocol. In such a case, the 542 Session-Id is not significant. 544 Based on these considerations, protocol designers should carefully 545 appraise whether the application currently defined relies on it's own 546 session management concept or whether the Session-Id defined in the 547 Diameter base protocol would be used for correlation of messages 548 related to the same session. If not, the protocol designers could 549 decide to define application commands without the Session-Id AVP. If 550 any session management concept is supported by the application, the 551 application documentation must clearly specify how the session is 552 handled between client and server (as possibly Diameter agents in the 553 path). 555 5.6. Use of Enumerated Type AVPs 557 The type Enumerated was initially defined to provide a list of valid 558 values for an AVP with their respective interpretation described in 559 the specification. For instance, AVPs of type Enumerated can be used 560 to provide further information on the reason for the termination of a 561 session or a specific action to perform upon the reception of the 562 request. 564 As described in the section 4.4.2 above, defining an AVP of type 565 Enumerated presents some limitations in term of extensibility and 566 reusability. Indeed, the finite set of valid values defined at the 567 definition of the AVP of type Enumerated cannot be modified in 568 practice without causing backward compatibility issues with existing 569 implementations. As a consequence, AVPs of Type Enumerated cannot be 570 extended by adding new values to support new capabilities. Diameter 571 protocol designers are then strongly advised to carefully consider 572 before defining an Enumerated AVP whether the set of values will 573 remain unchanged or new values may be required in a near future. If 574 such extension is foreseen or cannot be avoided, it is recommended to 575 rather define AVPs of type Unsigned32 or Unsigned64 in which the data 576 field would contain an address space representing "values" that would 577 have the same use of Enumerated values. 579 For instance, an AVP describing possible access networks would be 580 defined as follow: 582 Access-Network-Type AVP (XXX) is of type Unsigned32 and contains an 583 32-bit address space representing types of access networks. This 584 application defines the following classes of access networks, all 585 identified by the thousands digit in the decimal notation: 587 o 1xxx (Mobile Access Networks) 589 o 2xxx (Fixed Access Network) 591 o 3xxx (Wireless Access Networks) 593 Values that fall within the Mobile Access Networks category are used 594 to inform a peer that a request has been sent for a user attached to 595 a mobile access networks. The following values are defined in this 596 application: 598 1001: 3GPP-GERAN 600 TBD. 602 1002: 3GPP-UTRAN-FDD 604 TBD. 606 Unlike Enumerated AVP, any new value can be added in the address 607 space defined by this Unsigned32 AVP without modifying the definition 608 of the AVP. There is therefore no risk of backward compatibility 609 issue, especially when intermediate nodes may be present between 610 Diameter endpoints. 612 In the same line, AVPs of type Enumerated are too often used as a 613 simple Boolean flag, indicating for instance a specific permission or 614 capability, and therefore only two values are defined, e.g., TRUE/ 615 FALSE, AUTORIZED/UNAUTHORIZED or SUPPORTED/UNSUPPORTED. This is a 616 sub-optimal design since it limits the extensibility of the 617 application: any new capability/permission would have to be supported 618 by a new AVP or new Enumerated value of the already defined AVP, with 619 the backward compatibility issues described above. Instead of using 620 an Enumerated AVP for a Boolean flag, protocol designers are again 621 encouraged to use AVPs of type Unsigned32 or Unsigned64 AVP in which 622 the data field would be defined as bit mask whose bit settings are 623 described in the relevant Diameter application specification. Such 624 AVPs can be reused and extended without major impact on the Diameter 625 application. The bit mask should leave room for future additions. 626 Examples of AVPs that use bit masks are the Session-Binding AVP 627 defined in [RFC6733] and the MIP6-Feature-Vector AVP defined in 628 [RFC5447]. 630 5.7. Application-Specific Message Routing 632 As described in [RFC6733], a Diameter request that needs to be sent 633 to a home server serving a specific realm, but not to a specific 634 server (such as the first request of a series of round trips), will 635 contain a Destination-Realm AVP and no Destination-Host AVP. 637 For such a request, the message routing usually relies only on the 638 Destination- Realm AVP and the Application Id present in the request 639 message header. However, some applications may need to rely on the 640 User-Name AVP or any other application-specific AVP present in the 641 request to determine the final destination of a request, e.g., to 642 find the target AAA server hosting the authorization information for 643 a given user when multiple AAA servers are addressable in the realm. 645 In such a context, basic routing mechanisms described in [RFC6733] 646 are not fully suitable, and additional application-level routing 647 mechanisms have to be described in the application documentation to 648 provide such specific AVP-based routing. Such functionality will be 649 basically hosted by an application-specific proxy agent that will be 650 responsible for routing decisions based on the received specific 651 AVPs. 653 Examples of such application-specific routing functions can be found 654 in the Cx/Dx applications ([TS29.228] and [TS29.229]) of the 3GPP IP 655 Multimedia Subsystem, in which the proxy agent (Subscriber Location 656 Function aka SLF) uses specific application-level identities found in 657 the request to determine the final destination of the message. 659 Whatever the criteria used to establish the routing path of the 660 request, the routing of the answer has to follow the reverse path of 661 the request, as described in [RFC6733], with the answer being sent to 662 the source of the received request, using transaction states and hop- 663 by-hop identifier matching. In particular, this ensures that the 664 Diameter Relay or Proxy agents in the request routing path will be 665 able to release the transaction state upon receipt of the 666 corresponding answer, avoiding unnecessary failover. Application 667 designers are strongly dissuaded from modifying the answer-routing 668 principles described in [RFC6733] when defining a new application. 670 5.8. Translation Agents 672 As defined in [RFC6733], a translation agent is a device that 673 provides interworking between Diameter and another protocol (e.g., 674 RADIUS). 676 In the case of RADIUS, it was initially thought that defining the 677 translation function would be straightforward by adopting few basic 678 principles, e.g., by the use of a shared range of code values for 679 RADIUS attributes and Diameter AVPs. Guidelines for implementing a 680 RADIUS-Diameter translation agent were put into RFC 4005 ([RFC4005]). 682 However, it was acknowledged that such translation mechanism was not 683 so obvious and deeper protocol analysis was required to ensure 684 efficient interworking between RADIUS and Diameter. Moreover, the 685 interworking requirements depend on the functionalities provided by 686 the Diameter application under specification, and a case-by-case 687 analysis will be required. 689 Therefore, protocol designers cannot assume the availability of a 690 "standard" Diameter-to-RADIUS gateways agent when planning to 691 interoperate with the RADIUS infrastructure. They should specify the 692 required translation mechanism along with the Diameter application, 693 if needed. This recommendation applies for any kind of translation. 695 5.9. End-to-End Application Capabilities Exchange 697 New Diameter applications can rely on optional AVPs to exchange 698 application-specific capabilities and features. These AVPs can be 699 exchanged on an end-to-end basis at the application layer. Examples 700 of this can be found with the MIP6-Feature-Vector AVP in [RFC5447] 701 and the QoS-Capability AVP in [RFC5777]. 703 The end-to-end capabilities AVPs formalize the addition of new 704 optional functionality to existing applications by announcing support 705 for it. Applications that do not understand these AVPs can discard 706 them upon receipt. Receivers of these AVPs can discover the 707 additional functionality supported by the end-point originating the 708 request and behave accordingly when processing the request. Senders 709 of these AVPs can safely assume the receiving end-point does not 710 support any functionality carried by the AVP if it is not present in 711 corresponding response. This is useful in cases where deployment 712 choices are offered, and the generic design can be made available for 713 a number of applications. 715 When used in a new application, protocol designers should clearly 716 specify this end-to-end capabilities exchange and the corresponding 717 behaviour of the Diameter nodes supporting the application. 719 It is also important to note that this end-to-end capabilities 720 exchange relies on the use of optional AVPs is not meant as a generic 721 mechanism to support extensibility of Diameter applications with 722 arbitrary functionality. When the added features drastically change 723 the Diameter application or when Diameter agents have to be upgraded 724 to support the new features, a new application should be defined. 726 5.10. Diameter Accounting Support 728 Accounting can be treated as an auxiliary application that is used in 729 support of other applications. In most cases, accounting support is 730 required when defining new applications. This document provides two 731 possible models for using accounting: 733 Split Accounting Model: 735 In this model, the accounting messages will use the Diameter base 736 accounting Application Id (value of 3). The design implication 737 for this is that the accounting is treated as an independent 738 application, especially for Diameter routing. This means that 739 accounting commands emanating from an application may be routed 740 separately from the rest of the other application messages. This 741 may also imply that the messages end up in a central accounting 742 server. A split accounting model is a good design choice when: 744 * The application itself does not define its own accounting 745 commands. 747 * The overall system architecture permits the use of centralized 748 accounting for one or more Diameter applications. 750 Centralizing accounting may have advantages but there are also 751 drawbacks. The model assumes that the accounting server can 752 differentiate received accounting messages. Since the received 753 accounting messages can be for any application and/or service, the 754 accounting server has to have a method to match accounting 755 messages with applications and/or services being accounted for. 756 This may mean defining new AVPs, checking the presence, absence or 757 contents of existing AVPs, or checking the contents of the 758 accounting record itself. One of these means could be to insert 759 into the request sent to the accounting server an Auth- 760 Application-Id AVP containing the identifier of the application 761 for which the accounting request is sent. But in general, there 762 is no clean and generic scheme for sorting these messages. 763 Therefore, the use of this model is recommended only when all 764 received accounting messages can be clearly identified and sorted. 765 For most cases, the use of Coupled Accounting Model is 766 recommended. 768 Coupled Accounting Model: 770 In this model, the accounting messages will use the Application Id 771 of the application using the accounting service. The design 772 implication for this is that the accounting messages are tightly 773 coupled with the application itself; meaning that accounting 774 messages will be routed like the other application messages. It 775 would then be the responsibility of the application server 776 (application entity receiving the ACR message) to send the 777 accounting records carried by the accounting messages to the 778 proper accounting server. The application server is also 779 responsible for formulating a proper response (ACA). A coupled 780 accounting model is a good design choice when: 782 * The system architecture or deployment does not provide an 783 accounting server that supports Diameter. Consequently, the 784 application server has to be provisioned to use a different 785 protocol to access the accounting server, e.g., via LDAP, SOAP 786 etc. This case includes the support of older accounting 787 systems that are not Diameter aware. 789 * The system architecture or deployment requires that the 790 accounting service for the specific application should be 791 handled by the application itself. 793 In all cases above, there will generally be no direct Diameter 794 access to the accounting server. 796 These models provide a basis for using accounting messages. 797 Application designers may obviously deviate from these models 798 provided that the factors being addressed here have also been taken 799 into account. Although it is not recommended, an application may 800 define a new set of commands to carry application-specific accounting 801 records. 803 5.11. Diameter Security Mechanisms 805 As specified in [RFC6733], the Diameter message exchange should be 806 secured between neighboring Diameter peers using TLS/TCP or DTLS/ 807 SCTP. However, IPsec can also be deployed to secure communication 808 between Diameter peers. When IPsec is used instead of TLS or DTLS, 809 the following recommendations apply. 811 IPsec ESP [RFC4301] in transport mode with non-null encryption and 812 authentication algorithms is used to provide per-packet 813 authentication, integrity protection and confidentiality, and support 814 the replay protection mechanisms of IPsec. IKEv2 [RFC5996] is 815 recommended for performing mutual authentication and for establishing 816 and maintaining security associations (SAs). 818 IKEv1 [RFC2409] was used with RFC 3588 [RFC3588] and for easier 819 migration from IKEv1 based implementations both RSA digital 820 signatures and pre-shared keys should be supported in IKEv2. 821 However, if IKEv1 is used, implementers should follow the guidelines 822 given in Section 13.1 of RFC 3588 [RFC3588]. 824 6. Defining Generic Diameter Extensions 826 Generic Diameter extensions are AVPs, commands or applications that 827 are designed to support other Diameter applications. They are 828 auxiliary applications meant to improve or enhance the Diameter 829 protocol itself or Diameter applications/functionality. Some 830 examples include the extensions to support auditing and redundancy 831 (see [I-D.calhoun-diameter-res-mgmt]), improvements in duplicate 832 detection scheme (see [I-D.asveren-dime-dupcons]), and the support 833 for QoS AVPs (see [RFC5777]). 835 Since generic extensions may cover many aspects of Diameter and 836 Diameter applications, it is not possible to enumerate all scenarios. 837 However, some of the most common considerations are as follows: 839 Backward Compatibility: 841 With the design of generic extensions an protocol designer has to 842 consider with potential concerns about how existing applications 843 deal with the new extension they do not understand. Designers 844 also have to make sure that new extensions do not break expected 845 message delivery layer behavior. 847 Forward Compatibility: 849 Protocol designers need to make sure that their design will not 850 introduce undue restrictions for future applications. 852 Trade-off in Signaling: 854 Designers may have to choose between the use of optional AVPs 855 piggybacked onto existing commands versus defining new commands 856 and applications. Optional AVPs are simpler to implement and may 857 not need changes to existing applications. However, this ties the 858 sending of extension data to the application's transmission of a 859 message. This has consequences if the application and the 860 extensions have different timing requirements. The use of 861 commands and applications solves this issue, but the trade-off is 862 the additional complexity of defining and deploying a new 863 application. It is left up to the designer to find a good balance 864 among these trade-offs based on the requirements of the extension. 866 In practice, generic extensions often use optional AVPs because they 867 are simple and non-intrusive to the application that would carry 868 them. Peers that do not support the generic extensions need not 869 understand nor recognize these optional AVPs. However, it is 870 recommended that the authors of the extension specify the context or 871 usage of the optional AVPs. As an example, in the case that the AVP 872 can be used only by a specific set of applications then the 873 specification must enumerate these applications and the scenarios 874 when the optional AVPs will be used. In the case where the optional 875 AVPs can be carried by any application, it is should be sufficient to 876 specify such a use case and perhaps provide specific examples of 877 applications using them. 879 In most cases, these optional AVPs piggybacked by applications would 880 be defined as a Grouped AVP and it would encapsulate all the 881 functionality of the generic extension. In practice, it is not 882 uncommon that the Grouped AVP will encapsulate an existing AVP that 883 has previously been defined as mandatory ('M'-bit set) e.g., 3GPP IMS 884 Cx/Dx interfaces ([TS29.228] and [TS29.229]). 886 7. Guidelines for Registrations of Diameter Values 888 As summarized in the Section 3 of this document and further described 889 in the Section 1.3 of [RFC6733], there are four main ways to extend 890 Diameter. The process for defining new functionality slightly varies 891 based on the different extensions. This section provides protocol 892 designers with some guidance regarding the definition of values for 893 possible Diameter extensions and the necessary interaction with IANA 894 to register the new functionality. 896 a. Defining new AVP values 897 The specifications defining AVPs and AVP values provide guidance 898 for defining new values and the corresponding policy for adding 899 these values. For example, the RFC 5777 [RFC5777] defines the 900 Treatment-Action AVP which contains a list of valid values 901 corresponding to pre-defined actions (drop, shape, mark, permit). 902 This set of values can be extended following the Specification 903 Required policy defined in [RFC5226]. As a second example, the 904 Diameter base specification [RFC6733] defines the Result-Code AVP 905 that contains a 32-bit address space used to identity possible 906 errors. According to the Section 11.3.2 of [RFC6733], new values 907 can be assigned by IANA via an IETF Review process [RFC5226]. 909 b. Creating new AVPs 911 Two different types of AVP Codes namespaces can be used to create 912 a new AVPs: 914 * IETF AVP Codes namespace; 916 * Vendor-specific AVP Codes namespace. 918 In the latter case, a vendor needs to be first assigned by IANA 919 with a private enterprise number, which can be used within the 920 Vendor-Id field of the vendor-specific AVP. This enterprise 921 number delimits a private namespace in which the vendor is 922 responsible for vendor-specific AVP code value assignment. The 923 absence of a Vendor-Id or a Vendor-Id value of zero (0) in the AVP 924 header identifies standard AVPs from the IETF AVP Codes namespace 925 managed by IANA. The allocation of code values from the IANA- 926 managed namespace is conditioned by an Expert Review of the 927 specification defining the AVPs or an IETF review if a block of 928 AVPs needs to be assigned. Moreover, the remaining bits of the 929 AVP Flags field of the AVP header can be also assigned via 930 Standard Action if the creation of new AVP Flags is desired. 932 c. Creating new commands 934 Unlike the AVP Code namespace, the Command Code namespace is flat 935 but the range of values is subdivided into three chunks with 936 distinct IANA registration policies: 938 * A range of standard Command Code values that can be allocated 939 via IETF review; 941 * A range of vendor-specific Command Code values that can be 942 allocated on a First-Come/First-Served basis; 944 * A range of values reserved only for experimental and testing 945 purposes. 947 As for AVP Flags, the remaining bits of the Command Flags field of 948 the Diameter header can also be assigned via a Standards Action to 949 create new Command Flags if required. 951 d. Creating new applications 953 Similarly to the Command Code namespace, the Application-Id 954 namespace is flat but divided into two distinct ranges: 956 * A range of values reserved for standard Application-Ids 957 allocated after Expert Review of the specification defining the 958 standard application; 960 * A range for values for vendor specific applications, allocated 961 by IANA on a First-Come/First-Serve basis. 963 The IANA AAA parameters page can be found at http://www.iana.org/ 964 assignments/aaa-parameters/aaa-parameters.xml and the enterprise 965 number IANA page is available at http://www.iana.org/assignments/ 966 enterprise-numbers. More details on the policies followed by IANA 967 for namespace management (e.g. First-Come/First-Served, Expert 968 Review, IETF Review, etc.) can be found in [RFC5226]. 970 NOTE: 971 When the same functionality/extension is used by more than one 972 vendor, it is recommended to define a standard extension. 973 Moreover, the registration of vendor-specific extension is 974 encouraged to avoid interoperability issues in the same network. 975 With this aim, the registration policy of vendor-specific 976 extension has been simplified with the publication of [RFC6733] 977 and the namespace reserved for vendor-specific extensions is large 978 enough to avoid exhaustion. 980 8. IANA Considerations 982 This document does not require actions by IANA. 984 9. Security Considerations 986 This document provides guidelines and considerations for extending 987 Diameter and Diameter applications. Although such an extension may 988 related to a security functionality, the document does not explicitly 989 give guidance on enhancing Diameter with respect to security. 991 10. Contributors 993 The content of this document was influenced by a design team created 994 to revisit the Diameter extensibility rules. The team consisting of 995 the members listed below was formed in February 2008 and finished its 996 work in June 2008. 998 o Avi Lior 1000 o Glen Zorn 1002 o Jari Arkko 1004 o Lionel Morand 1006 o Mark Jones 1008 o Victor Fajardo 1010 o Tolga Asveren 1012 o Jouni Korhonen 1014 o Glenn McGregor 1016 o Hannes Tschofenig 1018 o Dave Frascone 1020 We would like to thank Tolga Asveren, Glenn McGregor, and John 1021 Loughney for their contributions as co-authors to earlier versions of 1022 this document. 1024 11. Acknowledgments 1026 We greatly appreciate the insight provided by Diameter implementers 1027 who have highlighted the issues and concerns being addressed by this 1028 document. The authors would also like to thank Jean Mahoney, Ben 1029 Campbell and Sebastien Decugis for their invaluable detailed reviews 1030 and comments on this document. 1032 12. Informative References 1034 [I-D.asveren-dime-dupcons] 1035 Asveren, T., "Diameter Duplicate Detection Cons.", draft- 1036 asveren-dime-dupcons-00 (work in progress), August 2006. 1038 [I-D.calhoun-diameter-res-mgmt] 1039 Calhoun, P., "Diameter Resource Management Extensions", 1040 draft-calhoun-diameter-res-mgmt-08.txt (work in progress), 1041 March 2001. 1043 [Q.3303.3] 1044 3rd Generation Partnership Project, "ITU-T Recommendation 1045 Q.3303.3, "Resource control protocol no. 3 (rcp3): 1046 Protocol at the Rw interface between the Policy Decision 1047 Physical Entity (PD-PE) and the Policy Enforcement 1048 Physical Entity (PE-PE): Diameter"", 2008. 1050 [RFC2409] Harkins, D. and D. Carrel, "The Internet Key Exchange 1051 (IKE)", RFC 2409, November 1998. 1053 [RFC3588] Calhoun, P., Loughney, J., Guttman, E., Zorn, G., and J. 1054 Arkko, "Diameter Base Protocol", RFC 3588, September 2003. 1056 [RFC4005] Calhoun, P., Zorn, G., Spence, D., and D. Mitton, 1057 "Diameter Network Access Server Application", RFC 4005, 1058 August 2005. 1060 [RFC4072] Eronen, P., Hiller, T., and G. Zorn, "Diameter Extensible 1061 Authentication Protocol (EAP) Application", RFC 4072, 1062 August 2005. 1064 [RFC4301] Kent, S. and K. Seo, "Security Architecture for the 1065 Internet Protocol", RFC 4301, December 2005. 1067 [RFC4740] Garcia-Martin, M., Belinchon, M., Pallares-Lopez, M., 1068 Canales-Valenzuela, C., and K. Tammi, "Diameter Session 1069 Initiation Protocol (SIP) Application", RFC 4740, November 1070 2006. 1072 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1073 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1074 May 2008. 1076 [RFC5447] Korhonen, J., Bournelle, J., Tschofenig, H., Perkins, C., 1077 and K. Chowdhury, "Diameter Mobile IPv6: Support for 1078 Network Access Server to Diameter Server Interaction", RFC 1079 5447, February 2009. 1081 [RFC5777] Korhonen, J., Tschofenig, H., Arumaithurai, M., Jones, M., 1082 and A. Lior, "Traffic Classification and Quality of 1083 Service (QoS) Attributes for Diameter", RFC 5777, February 1084 2010. 1086 [RFC5996] Kaufman, C., Hoffman, P., Nir, Y., and P. Eronen, 1087 "Internet Key Exchange Protocol Version 2 (IKEv2)", RFC 1088 5996, September 2010. 1090 [RFC6733] Fajardo, V., Arkko, J., Loughney, J., and G. Zorn, 1091 "Diameter Base Protocol", RFC 6733, October 2012. 1093 [TS29.228] 1094 3rd Generation Partnership Project, "3GPP TS 29.228; 1095 Technical Specification Group Core Network and Terminals; 1096 IP Multimedia (IM) Subsystem Cx and Dx Interfaces; 1097 Signalling flows and message contents", 1098 . 1100 [TS29.229] 1101 3rd Generation Partnership Project, "3GPP TS 29.229; 1102 Technical Specification Group Core Network and Terminals; 1103 Cx and Dx interfaces based on the Diameter protocol; 1104 Protocol details", 1105 . 1107 [TS29.328] 1108 3rd Generation Partnership Project, "3GPP TS 29.328; 1109 Technical Specification Group Core Network and Terminals; 1110 IP Multimedia (IM) Subsystem Sh interface; signalling 1111 flows and message content", 1112 . 1114 [TS29.329] 1115 3rd Generation Partnership Project, "3GPP TS 29.329; 1116 Technical Specification Group Core Network and Terminals; 1117 Sh Interface based on the Diameter protocol; Protocol 1118 details", 1119 . 1121 Authors' Addresses 1123 Lionel Morand (editor) 1124 Orange Labs 1125 38/40 rue du General Leclerc 1126 Issy-Les-Moulineaux Cedex 9 92794 1127 France 1129 Phone: +33145296257 1130 Email: lionel.morand@orange.com 1131 Victor Fajardo 1133 Email: vf0213@gmail.com 1135 Hannes Tschofenig 1136 Nokia Siemens Networks 1137 Linnoitustie 6 1138 Espoo 02600 1139 Finland 1141 Phone: +358 (50) 4871445 1142 Email: Hannes.Tschofenig@gmx.net 1143 URI: http://www.tschofenig.priv.at