idnits 2.17.00 (12 Aug 2021) /tmp/idnits45763/draft-ietf-dime-app-design-guide-20.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 lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (October 04, 2013) is 3150 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Unused Reference: 'RFC2407' is defined on line 986, but no explicit reference was found in the text -- Obsolete informational reference (is this intentional?): RFC 2407 (Obsoleted by RFC 4306) -- 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 (~~), 2 warnings (==), 8 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: April 07, 2014 6 H. Tschofenig 7 Nokia Siemens Networks 8 October 04, 2013 10 Diameter Applications Design Guidelines 11 draft-ietf-dime-app-design-guide-20 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 April 07, 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 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 57 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 58 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 3 59 4. Reusing Existing Diameter Applications . . . . . . . . . . . 5 60 4.1. Adding a New Command . . . . . . . . . . . . . . . . . . 5 61 4.2. Deleting an Existing Command . . . . . . . . . . . . . . 6 62 4.3. Reusing Existing Commands . . . . . . . . . . . . . . . . 6 63 4.3.1. Adding AVPs to a Command . . . . . . . . . . . . . . 6 64 4.3.2. Deleting AVPs from a Command . . . . . . . . . . . . 8 65 4.4. Reusing Existing AVPs . . . . . . . . . . . . . . . . . . 9 66 4.4.1. Setting of the AVP Flags . . . . . . . . . . . . . . 9 67 4.4.2. Reuse of AVP of Type Enumerated . . . . . . . . . . . 9 68 5. Defining New Diameter Applications . . . . . . . . . . . . . 9 69 5.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 10 70 5.2. Defining New Commands . . . . . . . . . . . . . . . . . . 10 71 5.3. Use of Application-Id in a Message . . . . . . . . . . . 10 72 5.4. Application-Specific Session State Machines . . . . . . . 11 73 5.5. Session-Id AVP and Session Management . . . . . . . . . . 11 74 5.6. Use of Enumerated Type AVPs . . . . . . . . . . . . . . . 12 75 5.7. Application-Specific Message Routing . . . . . . . . . . 13 76 5.8. Translation Agents . . . . . . . . . . . . . . . . . . . 13 77 5.9. End-to-End Application Capabilities Exchange . . . . . . 14 78 5.10. Diameter Accounting Support . . . . . . . . . . . . . . . 15 79 5.11. Diameter Security Mechanisms . . . . . . . . . . . . . . 16 80 6. Defining Generic Diameter Extensions . . . . . . . . . . . . 17 81 7. Guidelines for Registrations of Diameter Values . . . . . . . 18 82 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20 83 9. Security Considerations . . . . . . . . . . . . . . . . . . . 20 84 10. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 20 85 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 21 86 12. Informative References . . . . . . . . . . . . . . . . . . . 21 87 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 23 89 1. Introduction 91 The Diameter base protocol provides facilities to extend Diameter 92 (see Section 1.3 of [RFC6733]) to support new functionality. In the 93 context of this document, extending Diameter means one of the 94 following: 96 1. Addition of new functionality to an existing Diameter application 97 without defining a new application. 99 2. Addition of new functionality to an existing Diameter application 100 that requires the definition of a new application. 102 3. The definition of an entirely new Diameter application to offer 103 functionality not supported by existing applications. 105 4. The definition of a new generic functionality that can be reused 106 across different applications. 108 All of these choices are design decisions that can be done by any 109 combination of reusing existing or defining new commands, AVPs or AVP 110 values. However, application designers do not have complete freedom 111 when making their design. A number of rules have been defined in 112 [RFC6733] that place constraints on when an extension requires the 113 allocation of a new Diameter application identifier or a new command 114 code value. The objective of this document is the following: 116 o Clarify the Diameter extensibility rules as defined in the 117 Diameter base protocol. 119 o Discuss design choices and provide guidelines when defining new 120 applications. 122 o Present trade-off choices. 124 2. Terminology 126 This document reuses the terminology defined in [RFC6733]. 128 3. Overview 130 As designed, the Diameter base protocol [RFC6733] can be seen as a 131 two-layer protocol. The lower layer is mainly responsible for 132 managing connections between neighboring peers and for message 133 routing. The upper layer is where the Diameter applications reside. 134 This model is in line with a Diameter node having an application 135 layer and a peer-to-peer delivery layer. The Diameter base protocol 136 document defines the architecture and behavior of the message 137 delivery layer and then provides the framework for designing Diameter 138 applications on the application layer. This framework includes 139 definitions of application sessions and accounting support (see 140 Section 8 and Section 9 of [RFC6733]). Accordingly, a Diameter node 141 is seen in this document as a single instance of a Diameter message 142 delivery layer and one or more Diameter applications using it. 144 The Diameter base protocol is designed to be extensible and the 145 principles are described in the Section 1.3 of [RFC6733]. As a 146 summary, Diameter can be extended by: 148 1. Defining new AVP values 150 2. Creating new AVPs 152 3. Creating new commands 154 4. Creating new applications 156 As a main guiding principle, the recommendation is: "try to re-use as 157 much as possible!". It will reduce the time to finalize 158 specification writing, and it will lead to a smaller implementation 159 effort as well as reduce the need for testing. In general, it is 160 clever to avoid duplicate effort when possible. 162 However, re-use is not appropriate when the existing functionality 163 does not fit the new requirement and/or the re-use leads to 164 ambiguity. 166 The impact on extending existing applications can be categorized into 167 two groups: 169 Minor Extension: Enhancing the functional scope of an existing 170 application by the addition of optional features to support. Such 171 enhancement has no backward compatibility issue with the existing 172 application. 174 A typical example would be the definition of a new optional AVP 175 for use in an existing command. Diameter implementations 176 supporting the existing application but not the new AVP will 177 simply ignore it, without consequences for the Diameter message 178 handling. The standardization effort will be fairly small. 180 Major Extension: Enhancing an application that requires the 181 definition of a new Diameter application. 183 Typical examples would be the creation of a new command for 184 providing functionality not supported by existing applications or 185 the definition of a new AVP with the M-bit set to be carried in an 186 existing command. For such extension, a significant specification 187 effort is required and a careful approach is recommended. 189 We would also like to remind that the definition of a new Diameter 190 application and the definition of a new command should be something 191 to avoid as much as possible. In the past, there has been some 192 reluctance to define new commands and new applications. With the 193 modified extensibility rules provided by [RFC6733], registering new 194 commands and new applications does not lead to additional overhead 195 for the specification author in terms of standardization process. 196 Registering new functionality (new commands, new AVPs, new 197 applications, etc.) with IANA remains important to avoid namespace 198 collisions, which will likely lead to deployment problems. 200 4. Reusing Existing Diameter Applications 202 An existing application may need to be enhanced to fulfill new 203 requirements and these modifications can be at the command level and/ 204 or at the AVP level. The following sections describe the possible 205 modifications that can be performed on existing applications and 206 their related impact. 208 4.1. Adding a New Command 210 Adding a new command is considered as a major extension and requires 211 a new Diameter application to be defined. Adding a new command to an 212 application means either defining a completely new command or 213 importing the command's Command Code Format (CCF) syntax from another 214 application whereby the new application inherits some or all of the 215 functionality of the application where the command came from. In the 216 former case, the decision to create a new application is 217 straightforward since this is typically a result of adding a new 218 functionality that does not exist yet. For the latter, the decision 219 to create a new application will depend on whether importing the 220 command in a new application is more suitable than simply using the 221 existing application as it is in conjunction with any other 222 application. Therefore, a case by case study of each application 223 requirement should be applied. 225 An example considers the Diameter EAP application [RFC4072] and the 226 Diameter NASREQ application [RFC4005]. When network access 227 authentication using EAP is required, the Diameter EAP commands 228 (Diameter-EAP-Request/Diameter-EAP-Answer) are used; otherwise the 229 NASREQ application will be used. When the Diameter EAP application 230 is used, the accounting exchanges defined in Diameter NASREQ may be 231 used. 233 However, in general, it is difficult to come to a hard guideline, and 234 so a case-by-case study of each application requirement should be 235 applied. Before adding or importing a command, application designers 236 should consider the following: 238 o Can the new functionality be fulfilled by creating a new command 239 independent from any existing command? In this case, the 240 resulting new application and the existing application can work 241 independent of, but cooperating with each other. 243 o Can the existing command be reused without major extensions and 244 therefore without the need for the definition of a new 245 application, e.g., new functionality introduced by the creation of 246 new optional AVPs. 248 Note: Importing commands too liberally could result in a monolithic 249 and hard to manage application supporting too many different 250 features. 252 4.2. Deleting an Existing Command 254 Although this process is not typical, removing a command from an 255 application requires a new Diameter application to be defined. This 256 is due to the fact that the reception of the deleted command would 257 systematically result in a protocol error (i.e., 258 DIAMETER_COMMAND_UNSUPPORTED). 260 It is unusual to delete an existing command from an application for 261 the sake of deleting it or the functionality it represents. This 262 normally indicates of a flawed design. An exception might be if the 263 intent of the deletion is to create a newer version of the same 264 application that is somehow simpler than the previous version. 266 4.3. Reusing Existing Commands 268 This section discusses rules in adding and/or deleting AVPs from an 269 existing command of an existing application. The cases described in 270 this section may not necessarily result in the creation of new 271 applications. 273 From a historical point of view, it is worth to note that there was a 274 strong recommendation to re-use existing commands in the [RFC3588] to 275 prevent rapid depletion of code values available for vendor-specific 276 commands. However, [RFC6733] has relaxed the allocation policy and 277 enlarged the range of available code values for vendor-specific 278 applications. Although reuse of existing commands is still 279 recommended, protocol designers can consider defining a new command 280 when it provides a solution more suitable than the twisting of an 281 existing command's use and applications. 283 4.3.1. Adding AVPs to a Command 284 Based on the rules in [RFC6733], AVPs that are added to an existing 285 command can be categorized into: 287 o Mandatory (to understand) AVPs. As defined in [RFC6733], these 288 are AVPs with the M-bit flag set in this command, which means that 289 a Diameter node receiving them is required to understand not only 290 their values but also their semantics. Failure to do so will 291 cause an message handling error. This is regardless of whether 292 these AVPs are required or optional as specified by the command's 293 Command Code Format (CCF) syntax . 295 o Optional (to understand) AVPs. As defined in [RFC6733], these are 296 AVPs with the M-bit flag cleared in this command. A Diameter node 297 receiving these AVPs can simply ignore them if it does not support 298 them. 300 NOTE: As stated in RFC6733, the M-bit setting for a given AVP is 301 relevant to an application and each command within that 302 application that includes the AVP. 304 The rules are strict in the case where the AVPs to be added in an 305 exiting command are mandatory to understand, i.e., they have the 306 M-bit set. A mandatory AVP cannot be added to an existing command 307 without defining a new Diameter application, as stated in [RFC6733]. 308 This falls into the "Major Extensions" category. Despite the clarity 309 of the rule, ambiguity still arises when evaluating whether a new AVP 310 being added should be mandatory to begin with. Application designers 311 should consider the following questions when deciding about the M-bit 312 for a new AVP: 314 o Would it be required for the receiving side to be able to process 315 and understand the AVP and its content? 317 o Would the new AVPs change the state machine of the application? 319 o Would the presence of the new AVP lead to a different number of 320 round-trips, effectively changing the state machine of the 321 application? 323 o Would the new AVP be used to differentiate between old and new 324 versions of the same application whereby the two versions are not 325 backward compatible? 327 o Would the new AVP have duality in meaning, i.e., be used to carry 328 application-related information as well as to indicate that the 329 message is for a new application? 331 If the answer to at least one of the questions is "yes" then the 332 M-bit has to be set for the new AVP. This list of questions is non- 333 exhaustive and other criteria can be taken into account in the 334 decision process. 336 If application designers are instead contemplating the use of 337 optional AVPs, i.e., with the M-bit cleared, then the following are 338 some of the pitfalls that should be avoided: 340 o Use of optional AVPs with intersecting meaning. One AVP has 341 partially the same usage and meaning as another AVP. The presence 342 of both can lead to confusion. 344 o An optional AVPs with dual purpose, i.e., to carry application 345 data as well as to indicate support for one or more features. 346 This has a tendency to introduce interpretation issues. 348 o Adding one or more optional AVPs and indicating (usually within 349 descriptive text for the command) that at least one of them has to 350 be present in the command. This essentially circumventing the 351 ABNF and is equivalent to adding a mandatory AVP to the command. 353 These practices generally result in interoperability issues and 354 should be avoided as much as possible. 356 4.3.2. Deleting AVPs from a Command 358 Application designers may want to reuse an existing command but some 359 of the AVP present in the command's CCF syntax specification may be 360 irrelevant for the functionality foreseen to be supported by this 361 command. It may be then tempting to delete those AVPs from the 362 command. 364 The impacts of deleting an AVP from a command depends on its command 365 code format specification and M-bit setting: 367 o Deleting an AVP that is indicated as { AVP } in the command's CCF 368 syntax specification (regardless of the M-bit setting). 370 In this case, a new command code and subsequently a new Diameter 371 application have to be specified. 373 o Deleting an AVP, which has the M-bit set, and is indicated as [ 374 AVP ] in the command's CCF syntax specification. 376 No new command code has to be specified but the definition of a 377 new Diameter application is required. 379 o Deleting an AVP, which has the M-bit cleared, and is indicated as 380 [ AVP ] in the command's CCF syntax specification. 382 In this case, the AVP can be deleted without consequences. 384 If possible, application designers should attempt the reuse the 385 command's CCF syntax specification without modification and simply 386 ignore (but not delete) any optional AVP that will not be used. This 387 is to maintain compatibility with existing applications that will not 388 know about the new functionality as well as maintain the integrity of 389 existing dictionaries. 391 4.4. Reusing Existing AVPs 393 This section discusses rules in reusing existing AVP when reusing an 394 existing command or defining a new command in a new application. 396 4.4.1. Setting of the AVP Flags 398 When reusing AVPs in a new application, the AVP flag setting, such as 399 the mandatory flag ('M'-bit), has to be re-evaluated for a new 400 Diameter application and, if necessary, even for every command within 401 the application. In general, for AVPs defined outside of the 402 Diameter base protocol, the characteristics of an AVP are tied to its 403 role within an application and the commands. 405 All other AVP flags shall remain unchanged. 407 4.4.2. Reuse of AVP of Type Enumerated 409 When reusing an AVP of type Enumerated in a command for a new 410 application, it is recommended to avoid modifying the set of valid 411 values defined for this AVP. Modifying the set of Enumerated values 412 includes adding a value or deprecating the use of a value defined 413 initially for the AVP. Modifying the set of values will impact the 414 application defining this AVP and all the applications using this AVP 415 with potential interoperability issues. When the full range of 416 values defined for this Enumerated AVP is not suitable for the new 417 application, it is recommended to define a new AVP to avoid backwards 418 compatibility issues with existing implementations. 420 5. Defining New Diameter Applications 421 5.1. Introduction 423 This section discusses the case where new applications have 424 requirements that cannot be fulfilled by existing applications and 425 would require definition of completely new commands, AVPs and/or AVP 426 values. Typically, there is little ambiguity about the decision to 427 create these types of applications. Some examples are the interfaces 428 defined for the IP Multimedia Subsystem of 3GPP, e.g., Cx/Dx 429 ([TS29.228] and [TS29.229]), Sh ([TS29.328] and [TS29.329]) etc. 431 Application designers should try to import existing AVPs and AVP 432 values for any newly defined commands. In certain cases where 433 accounting will be used, the models described in Section 5.10 should 434 also be considered. 436 Additional considerations are described in the following sections. 438 5.2. Defining New Commands 440 As a general recommendation, commands should not be defined from 441 scratch. It is instead recommend to re-use an existing command 442 offering similar functionality and use it as a starting point. 444 Moreover, the new command's CCF syntax specification should be 445 carefully defined when considering applicability and extensibility of 446 the application. If most of the AVPs contained in the command are 447 indicated as fixed or required, it might be difficult to reuse the 448 same command and therefore the same application in a slighly changed 449 environment. Defining a command with most of the AVPs indicated as 450 optional must not be seen as a sub-optimal design introducing too 451 much flexibility in the protocol. The protocol designers are only 452 advised to clearly state the condition of presence of these AVPs and 453 properly define the corresponding behaviour of the Diameter nodes 454 when these AVPs are absent from the command. 456 Note: As a hint for protocol designers, it is not sufficient to just 457 look at the command's CCF syntax specification. It is also necessary 458 to carefully read through the accompanying text in the specification. 460 In the same way, the CCF syntax specification should be defined such 461 that it will be possible to add any arbitrary optional AVPs with the 462 M-bit cleared (including vendor-specific AVPs) without modifying the 463 application. For this purpose, it is strongly recommended to add "* 464 [AVP]" in the command's CCF, which allows the addition of any 465 arbitrary AVP as described in [RFC6733]. 467 5.3. Use of Application-Id in a Message 468 When designing new applications, designers should specify that the 469 Application Id carried in all session-level messages must be the 470 Application Id of the application using those messages. This 471 includes the session-level messages defined in Diameter base 472 protocol, i.e., RAR/RAA, STR/STA, ASR/ASA and possibly ACR/ACA in the 473 coupled accounting model, see Section 5.10. Some existing 474 specifications do not adhere to this rule for historical reasons. 475 However, this guidance should be followed to avoid routing problems. 477 In general, when a new application has been allocated with a new 478 Application Id and it also reuses existing commands with or without 479 modifications, it must use the newly allocated Application Id in the 480 header and in all relevant Application Id AVPs (Auth-Application-Id 481 or Acct-Application-Id) present in the commands message body. 483 Additionally, application designs using Vendor-Specific-Application- 484 Id AVP should not use the Vendor-Id AVP to further dissect or 485 differentiate the vendor-specification Application Id. Diameter 486 routing is not based on the Vendor-Id. As such, the Vendor-Id should 487 not be used as an additional input for routing or delivery of 488 messages. The Vendor-Id AVP is an informational AVP only and kept 489 for backward compatibility reasons. 491 5.4. Application-Specific Session State Machines 493 Section 8 of [RFC6733] provides session state machines for 494 authentication, authorization and accounting (AAA) services and these 495 session state machines are not intended to cover behavior outside of 496 AAA. If a new application cannot clearly be categorized into any of 497 these AAA services, it is recommended that the application defines 498 its own session state machine. Support for server-initiated request 499 is a clear example where an application-specific session state 500 machine would be needed, for example, the Rw interface for ITU-T push 501 model (cf.[Q.3303.3]). 503 5.5. Session-Id AVP and Session Management 505 Diameter applications are usually designed with the aim of managing 506 user sessions (e.g., Diameter network access session (NASREQ) 507 application [RFC4005]) or specific service access session (e.g., 508 Diameter SIP application [RFC4740]). In the Diameter base protocol, 509 session state is referenced using the Session-Id AVP. All Diameter 510 messages that use the same Session-Id will be bound to the same 511 session. Diameter-based session management also implies that both 512 Diameter client and server (and potentially proxy agents along the 513 path) maintain session state information. 515 However, some applications may not need to rely on the Session-Id to 516 identify and manage sessions because other information can be used 517 instead to correlate Diameter messages. Indeed, the User-Name AVP or 518 any other specific AVP can be present in every Diameter message and 519 used therefore for message correlation. Some applications might not 520 require the notion of Diameter session concept at all. For such 521 applications, the Auth-Session-State AVP is usually set to 522 NO_STATE_MAINTAINED in all Diameter messages and these applications 523 are therefore designed as a set of stand-alone transactions. Even if 524 an explicit access session termination is required, application- 525 specific commands are defined and used instead of the Session- 526 Termination-Request/Answer (STR/STA) or Abort-Session-Request/Answer 527 (ASR/ASA) defined in the Diameter base protocol. In such a case, the 528 Session-Id is not significant. 530 Based on these considerations, protocol designers should carefully 531 appraise whether the application currently defined relies on it's own 532 session management concept or whether the Session-Id defined in the 533 Diameter base protocol would be used for correlation of messages 534 related to the same session. If not, the protocol designers could 535 decide to define application commands without the Session-Id AVP. If 536 any session management concept is supported by the application, the 537 application documentation must clearly specify how the session is 538 handled between client and server (as possibly Diameter agents in the 539 path). 541 5.6. Use of Enumerated Type AVPs 543 The type Enumerated was initially defined to provide a list of valid 544 values for an AVP with their respective interpretation described in 545 the specification. For instance, AVPs of type Enumerated can be used 546 to provide further information on the reason for the termination of a 547 session or a specific action to perform upon the reception of the 548 request. 550 However, AVPs of type Enumerated are too often used as a simple 551 Boolean flag, indicating for instance a specific permission or 552 capability, and therefore only two values are defined, e.g., TRUE/ 553 FALSE, AUTORIZED/UNAUTHORIZED or SUPPORTED/UNSUPPORTED. This is a 554 sub-optimal design since it limits the extensibility of the 555 application: any new capability/permission would have to be supported 556 by a new AVP or new Enumerated value of the already defined AVP, 557 causing backwards compatibility issues with existing implementations. 559 Instead of using an Enumerated AVP for a Boolean flag, protocol 560 designers are encouraged to use Unsigned32 or Unsigned64 AVP type as 561 bit mask whose bit settings are described in the relevant Diameter 562 application specification. Such AVPs can be reused and extended 563 without major impact on the Diameter application. The bit mask 564 should leave room for future additions. Examples of AVPs that use 565 bit masks are the Session-Binding AVP defined in [RFC6733] and the 566 MIP6-Feature-Vector AVP defined in [RFC5447]. 568 5.7. Application-Specific Message Routing 570 As described in [RFC6733], a Diameter request that needs to be sent 571 to a home server serving a specific realm, but not to a specific 572 server (such as the first request of a series of round trips), will 573 contain a Destination-Realm AVP and no Destination-Host AVP. 575 For such a request, the message routing usually relies only on the 576 Destination- Realm AVP and the Application Id present in the request 577 message header. However, some applications may need to rely on the 578 User-Name AVP or any other application-specific AVP present in the 579 request to determine the final destination of a request, e.g., to 580 find the target AAA server hosting the authorization information for 581 a given user when multiple AAA servers are addressable in the realm. 583 In such a context, basic routing mechanisms described in [RFC6733] 584 are not fully suitable, and additional application-level routing 585 mechanisms have to be described in the application documentation to 586 provide such specific AVP-based routing. Such functionality will be 587 basically hosted by an application-specific proxy agent that will be 588 responsible for routing decisions based on the received specific 589 AVPs. 591 Examples of such application-specific routing functions can be found 592 in the Cx/Dx applications ([TS29.228] and [TS29.229]) of the 3GPP IP 593 Multimedia Subsystem, in which the proxy agent (Subscriber Location 594 Function aka SLF) uses specific application-level identities found in 595 the request to determine the final destination of the message. 597 Whatever the criteria used to establish the routing path of the 598 request, the routing of the answer has to follow the reverse path of 599 the request, as described in [RFC6733], with the answer being sent to 600 the source of the received request, using transaction states and hop- 601 by-hop identifier matching. In particular, this ensures that the 602 Diameter Relay or Proxy agents in the request routing path will be 603 able to release the transaction state upon receipt of the 604 corresponding answer, avoiding unnecessary failover. Application 605 designers are strongly dissuaded from modifying the answer-routing 606 principles described in [RFC6733] when defining a new application. 608 5.8. Translation Agents 609 As defined in [RFC6733], a translation agent is a device that 610 provides interworking between Diameter and another protocol (e.g., 611 RADIUS). 613 In the case of RADIUS, it was initially thought that defining the 614 translation function would be straightforward by adopting few basic 615 principles, e.g., by the use of a shared range of code values for 616 RADIUS attributes and Diameter AVPs. Guidelines for implementing a 617 RADIUS-Diameter translation agent were put into RFC 4005 ([RFC4005]). 619 However, it was acknowledged that such translation mechanism was not 620 so obvious and deeper protocol analysis was required to ensure 621 efficient interworking between RADIUS and Diameter. Moreover, the 622 interworking requirements depend on the functionalities provided by 623 the Diameter application under specification, and a case-by-case 624 analysis will be required. 626 Therefore, protocol designers cannot assume the availability of a 627 "standard" Diameter-to-RADIUS gateways agent when planning to 628 interoperate with the RADIUS infrastructure. They should specify the 629 required translation mechanism along with the Diameter application, 630 if needed. This recommendation applies for any kind of translation. 632 5.9. End-to-End Application Capabilities Exchange 634 New Diameter applications can rely on optional AVPs to exchange 635 application-specific capabilities and features. These AVPs can be 636 exchanged on an end-to-end basis at the application layer. Examples 637 of this can be found with the MIP6-Feature-Vector AVP in [RFC5447] 638 and the QoS-Capability AVP in [RFC5777]. 640 The end-to-end capabilities AVPs formalize the addition of new 641 optional functionality to existing applications by announcing support 642 for it. Applications that do not understand these AVPs can discard 643 them upon receipt. Receivers of these AVPs can discover the 644 additional functionality supported by the end-point originating the 645 request and behave accordingly when processing the request. Senders 646 of these AVPs can safely assume the receiving end-point does not 647 support any functionality carried by the AVP if it is not present in 648 corresponding response. This is useful in cases where deployment 649 choices are offered, and the generic design can be made available for 650 a number of applications. 652 When used in a new application, protocol designers should clearly 653 specify this end-to-end capabilities exchange and the corresponding 654 behaviour of the Diameter nodes supporting the application. 656 It is also important to note that this end-to-end capabilities 657 exchange relies on the use of optional AVPs is not meant as a generic 658 mechanism to support extensibility of Diameter applications with 659 arbitrary functionality. When the added features drastically change 660 the Diameter application or when Diameter agents have to be upgraded 661 to support the new features, a new application should be defined. 663 5.10. Diameter Accounting Support 665 Accounting can be treated as an auxiliary application that is used in 666 support of other applications. In most cases, accounting support is 667 required when defining new applications. This document provides two 668 possible models for using accounting: 670 Split Accounting Model: 672 In this model, the accounting messages will use the Diameter base 673 accounting Application Id (value of 3). The design implication 674 for this is that the accounting is treated as an independent 675 application, especially for Diameter routing. This means that 676 accounting commands emanating from an application may be routed 677 separately from the rest of the other application messages. This 678 may also imply that the messages end up in a central accounting 679 server. A split accounting model is a good design choice when: 681 * The application itself does not define its own accounting 682 commands. 684 * The overall system architecture permits the use of centralized 685 accounting for one or more Diameter applications. 687 Centralizing accounting may have advantages but there are also 688 drawbacks. The model assumes that the accounting server can 689 differentiate received accounting messages. Since the received 690 accounting messages can be for any application and/or service, the 691 accounting server has to have a method to match accounting 692 messages with applications and/or services being accounted for. 693 This may mean defining new AVPs, checking the presence, absence or 694 contents of existing AVPs, or checking the contents of the 695 accounting record itself. One of these means could be to insert 696 into the request sent to the accounting server an Auth- 697 Application-Id AVP containing the identifier of the application 698 for which the accounting request is sent. But in general, there 699 is no clean and generic scheme for sorting these messages. 700 Therefore, the use of this model is recommended only when all 701 received accounting messages can be clearly identified and sorted. 702 For most cases, the use of Coupled Accounting Model is 703 recommended. 705 Coupled Accounting Model: 707 In this model, the accounting messages will use the Application Id 708 of the application using the accounting service. The design 709 implication for this is that the accounting messages are tightly 710 coupled with the application itself; meaning that accounting 711 messages will be routed like the other application messages. It 712 would then be the responsibility of the application server 713 (application entity receiving the ACR message) to send the 714 accounting records carried by the accounting messages to the 715 proper accounting server. The application server is also 716 responsible for formulating a proper response (ACA). A coupled 717 accounting model is a good design choice when: 719 * The system architecture or deployment does not provide an 720 accounting server that supports Diameter. Consequently, the 721 application server has to be provisioned to use a different 722 protocol to access the accounting server, e.g., via LDAP, SOAP 723 etc. This case includes the support of older accounting 724 systems that are not Diameter aware. 726 * The system architecture or deployment requires that the 727 accounting service for the specific application should be 728 handled by the application itself. 730 In all cases above, there will generally be no direct Diameter 731 access to the accounting server. 733 These models provide a basis for using accounting messages. 734 Application designers may obviously deviate from these models 735 provided that the factors being addressed here have also been taken 736 into account. Although it is not recommended, an application may 737 define a new set of commands to carry application-specific accounting 738 records. 740 5.11. Diameter Security Mechanisms 742 As specified in [RFC6733], the Diameter message exchange should be 743 secured between neighboring Diameter peers using TLS/TCP or DTLS/ 744 SCTP. However, IPsec can also be deployed to secure communication 745 between Diameter peers. When IPsec is used instead of TLS or DTLS, 746 the following recommendations apply. 748 IPsec ESP [RFC4301] in transport mode with non-null encryption and 749 authentication algorithms is used to provide per-packet 750 authentication, integrity protection and confidentiality, and support 751 the replay protection mechanisms of IPsec. IKEv2 [RFC5996] is 752 recommended for performing mutual authentication and for establishing 753 and maintaining security associations (SAs). 755 IKEv1 [RFC2409] was used with RFC 3588 [RFC3588] and for easier 756 migration from IKEv1 based implementations both RSA digital 757 signatures and pre-shared keys should be supported in IKEv2. 758 However, if IKEv1 is used, implementers should follow the guidelines 759 given in Section 13.1 of RFC 3588 [RFC3588]. 761 6. Defining Generic Diameter Extensions 763 Generic Diameter extensions are AVPs, commands or applications that 764 are designed to support other Diameter applications. They are 765 auxiliary applications meant to improve or enhance the Diameter 766 protocol itself or Diameter applications/functionality. Some 767 examples include the extensions to support auditing and redundancy 768 (see [I-D.calhoun-diameter-res-mgmt]), improvements in duplicate 769 detection scheme (see [I-D.asveren-dime-dupcons]), and the support 770 for QoS AVPs (see [RFC5777]). 772 Since generic extensions may cover many aspects of Diameter and 773 Diameter applications, it is not possible to enumerate all scenarios. 774 However, some of the most common considerations are as follows: 776 Backward Compatibility: 778 With the design of generic extensions an protocol designer has to 779 consider with potential concerns about how existing applications 780 deal with the new extension they do not understand. Designers 781 also have to make sure that new extensions do not break expected 782 message delivery layer behavior. 784 Forward Compatibility: 786 Protocol designers need to make sure that their design will not 787 introduce undue restrictions for future applications. 789 Trade-off in Signaling: 791 Designers may have to choose between the use of optional AVPs 792 piggybacked onto existing commands versus defining new commands 793 and applications. Optional AVPs are simpler to implement and may 794 not need changes to existing applications. However, this ties the 795 sending of extension data to the application's transmission of a 796 message. This has consequences if the application and the 797 extensions have different timing requirements. The use of 798 commands and applications solves this issue, but the trade-off is 799 the additional complexity of defining and deploying a new 800 application. It is left up to the designer to find a good balance 801 among these trade-offs based on the requirements of the extension. 803 In practice, generic extensions often use optional AVPs because they 804 are simple and non-intrusive to the application that would carry 805 them. Peers that do not support the generic extensions need not 806 understand nor recognize these optional AVPs. However, it is 807 recommended that the authors of the extension specify the context or 808 usage of the optional AVPs. As an example, in the case that the AVP 809 can be used only by a specific set of applications then the 810 specification must enumerate these applications and the scenarios 811 when the optional AVPs will be used. In the case where the optional 812 AVPs can be carried by any application, it is should be sufficient to 813 specify such a use case and perhaps provide specific examples of 814 applications using them. 816 In most cases, these optional AVPs piggybacked by applications would 817 be defined as a Grouped AVP and it would encapsulate all the 818 functionality of the generic extension. In practice, it is not 819 uncommon that the Grouped AVP will encapsulate an existing AVP that 820 has previously been defined as mandatory ('M'-bit set) e.g., 3GPP IMS 821 Cx/Dx interfaces ([TS29.228] and [TS29.229]). 823 7. Guidelines for Registrations of Diameter Values 825 As summarized in the Section 3 of this document and further described 826 in the Section 1.3 of [RFC6733], there are four main ways to extend 827 Diameter. The process for defining new functionality slightly varies 828 based on the different extensions. This section provides protocol 829 designers with some guidance regarding the definition of values for 830 possible Diameter extensions and the necessary interaction with IANA 831 to register the new functionality. 833 a. Defining new AVP values 835 The specifications defining AVPs and AVP values provide guidance 836 for defining new values and the corresponding policy for adding 837 these values. For example, the RFC 5777 [RFC5777] defines the 838 Treatment-Action AVP which contains a list of valid values 839 corresponding to pre-defined actions (drop, shape, mark, permit). 840 This set of values can be extended following the Specification 841 Required policy defined in [RFC5226]. As a second example, the 842 Diameter base specification [RFC6733] defines the Result-Code AVP 843 that contains a 32-bit address space used to identity possible 844 errors. According to the Section 11.3.2 of [RFC6733], new values 845 can be assigned by IANA via an IETF Review process [RFC5226]. 847 b. Creating new AVPs 849 Two different types of AVP Codes namespaces can be used to create 850 a new AVPs: 852 * IETF AVP Codes namespace; 854 * Vendor-specific AVP Codes namespace. 856 In the latter case, a vendor needs to be first assigned by IANA 857 with a private enterprise number, which can be used within the 858 Vendor-Id field of the vendor-specific AVP. This enterprise 859 number delimits a private namespace in which the vendor is 860 responsible for vendor-specific AVP code value assignment. The 861 absence of a Vendor-Id or a Vendor-Id value of zero (0) in the AVP 862 header identifies standard AVPs from the IETF AVP Codes namespace 863 managed by IANA. The allocation of code values from the IANA- 864 managed namespace is conditioned by an Expert Review of the 865 specification defining the AVPs or an IETF review if a block of 866 AVPs needs to be assigned. Moreover, the remaining bits of the 867 AVP Flags field of the AVP header can be also assigned via 868 Standard Action if the creation of new AVP Flags is desired. 870 c. Creating new commands 872 Unlike the AVP Code namespace, the Command Code namespace is flat 873 but the range of values is subdivided into three chunks with 874 distinct IANA registration policies: 876 * A range of standard Command Code values that can be allocated 877 via IETF review; 879 * A range of vendor-specific Command Code values that can be 880 allocated on a First-Come/First-Served basis; 882 * A range of values reserved only for experimental and testing 883 purposes. 885 As for AVP Flags, the remaining bits of the Command Flags field of 886 the Diameter header can also be assigned via a Standards Action to 887 create new Command Flags if required. 889 d. Creating new applications 890 Similarly to the Command Code namespace, the Application-Id 891 namespace is flat but divided into two distinct ranges: 893 * A range of values reserved for standard Application-Ids 894 allocated after Expert Review of the specification defining the 895 standard application; 897 * A range for values for vendor specific applications, allocated 898 by IANA on a First-Come/First-Serve basis. 900 The IANA AAA parameters page can be found at http://www.iana.org/ 901 assignments/aaa-parameters/aaa-parameters.xml and the enterprise 902 number IANA page is available at http://www.iana.org/assignments/ 903 enterprise-numbers. More details on the policies followed by IANA 904 for namespace management (e.g. First-Come/First-Served, Expert 905 Review, IETF Review, etc.) can be found in [RFC5226]. 907 NOTE: 908 When the same functionality/extension is used by more than one 909 vendor, it is recommended to define a standard extension. 910 Moreover, the registration of vendor-specific extension is 911 encouraged to avoid interoperability issues in the same network. 912 With this aim, the registration policy of vendor-specific 913 extension has been simplified with the publication of [RFC6733] 914 and the namespace reserved for vendor-specific extensions is large 915 enough to avoid exhaustion. 917 8. IANA Considerations 919 This document does not require actions by IANA. 921 9. Security Considerations 923 This document provides guidelines and considerations for extending 924 Diameter and Diameter applications. Although such an extension may 925 related to a security functionality, the document does not explicitly 926 give guidance on enhancing Diameter with respect to security. 928 10. Contributors 930 The content of this document was influenced by a design team created 931 to revisit the Diameter extensibility rules. The team consisting of 932 the members listed below was formed in February 2008 and finished its 933 work in June 2008. 935 o Avi Lior 937 o Glen Zorn 938 o Jari Arkko 940 o Lionel Morand 942 o Mark Jones 944 o Victor Fajardo 946 o Tolga Asveren 948 o Jouni Korhonen 950 o Glenn McGregor 952 o Hannes Tschofenig 954 o Dave Frascone 956 We would like to thank Tolga Asveren, Glenn McGregor, and John 957 Loughney for their contributions as co-authors to earlier versions of 958 this document. 960 11. Acknowledgments 962 We greatly appreciate the insight provided by Diameter implementers 963 who have highlighted the issues and concerns being addressed by this 964 document. The authors would also like to thank Jean Mahoney, Ben 965 Campbell and Sebastien Decugis for their invaluable detailed reviews 966 and comments on this document. 968 12. Informative References 970 [I-D.asveren-dime-dupcons] 971 Asveren, T., "Diameter Duplicate Detection Cons.", draft- 972 asveren-dime-dupcons-00 (work in progress), August 2006. 974 [I-D.calhoun-diameter-res-mgmt] 975 Calhoun, P., "Diameter Resource Management Extensions", 976 draft-calhoun-diameter-res-mgmt-08.txt (work in progress), 977 March 2001. 979 [Q.3303.3] 980 3rd Generation Partnership Project, "ITU-T Recommendation 981 Q.3303.3, "Resource control protocol no. 3 (rcp3): 982 Protocol at the Rw interface between the Policy Decision 983 Physical Entity (PD-PE) and the Policy Enforcement 984 Physical Entity (PE-PE): Diameter"", 2008. 986 [RFC2407] Piper, D., "The Internet IP Security Domain of 987 Interpretation for ISAKMP", RFC 2407, November 1998. 989 [RFC2409] Harkins, D. and D. Carrel, "The Internet Key Exchange 990 (IKE)", RFC 2409, November 1998. 992 [RFC3588] Calhoun, P., Loughney, J., Guttman, E., Zorn, G., and J. 993 Arkko, "Diameter Base Protocol", RFC 3588, September 2003. 995 [RFC4005] Calhoun, P., Zorn, G., Spence, D., and D. Mitton, 996 "Diameter Network Access Server Application", RFC 4005, 997 August 2005. 999 [RFC4072] Eronen, P., Hiller, T., and G. Zorn, "Diameter Extensible 1000 Authentication Protocol (EAP) Application", RFC 4072, 1001 August 2005. 1003 [RFC4301] Kent, S. and K. Seo, "Security Architecture for the 1004 Internet Protocol", RFC 4301, December 2005. 1006 [RFC4740] Garcia-Martin, M., Belinchon, M., Pallares-Lopez, M., 1007 Canales-Valenzuela, C., and K. Tammi, "Diameter Session 1008 Initiation Protocol (SIP) Application", RFC 4740, November 1009 2006. 1011 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1012 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1013 May 2008. 1015 [RFC5447] Korhonen, J., Bournelle, J., Tschofenig, H., Perkins, C., 1016 and K. Chowdhury, "Diameter Mobile IPv6: Support for 1017 Network Access Server to Diameter Server Interaction", RFC 1018 5447, February 2009. 1020 [RFC5777] Korhonen, J., Tschofenig, H., Arumaithurai, M., Jones, M., 1021 and A. Lior, "Traffic Classification and Quality of 1022 Service (QoS) Attributes for Diameter", RFC 5777, February 1023 2010. 1025 [RFC5996] Kaufman, C., Hoffman, P., Nir, Y., and P. Eronen, 1026 "Internet Key Exchange Protocol Version 2 (IKEv2)", RFC 1027 5996, September 2010. 1029 [RFC6733] Fajardo, V., Arkko, J., Loughney, J., and G. Zorn, 1030 "Diameter Base Protocol", RFC 6733, October 2012. 1032 [TS29.228] 1033 3rd Generation Partnership Project, "3GPP TS 29.228; 1034 Technical Specification Group Core Network and Terminals; 1035 IP Multimedia (IM) Subsystem Cx and Dx Interfaces; 1036 Signalling flows and message contents", , 1037 . 1039 [TS29.229] 1040 3rd Generation Partnership Project, "3GPP TS 29.229; 1041 Technical Specification Group Core Network and Terminals; 1042 Cx and Dx interfaces based on the Diameter protocol; 1043 Protocol details", , 1044 . 1046 [TS29.328] 1047 3rd Generation Partnership Project, "3GPP TS 29.328; 1048 Technical Specification Group Core Network and Terminals; 1049 IP Multimedia (IM) Subsystem Sh interface; signalling 1050 flows and message content", , 1051 . 1053 [TS29.329] 1054 3rd Generation Partnership Project, "3GPP TS 29.329; 1055 Technical Specification Group Core Network and Terminals; 1056 Sh Interface based on the Diameter protocol; Protocol 1057 details", , 1058 . 1060 Authors' Addresses 1062 Lionel Morand (editor) 1063 Orange Labs 1064 38/40 rue du General Leclerc 1065 Issy-Les-Moulineaux Cedex 9 92794 1066 France 1068 Phone: +33145296257 1069 Email: lionel.morand@orange.com 1071 Victor Fajardo 1073 Email: vf0213@gmail.com 1074 Hannes Tschofenig 1075 Nokia Siemens Networks 1076 Linnoitustie 6 1077 Espoo 02600 1078 Finland 1080 Phone: +358 (50) 4871445 1081 Email: Hannes.Tschofenig@gmx.net 1082 URI: http://www.tschofenig.priv.at