< draft-ietf-dime-app-design-guide-22.txt		draft-ietf-dime-app-design-guide-23.txt >
	Diameter Maintenance and Extensions (DIME) L. Morand, Ed.		Diameter Maintenance and Extensions (DIME) L. Morand, Ed.
	Internet-Draft Orange Labs		Internet-Draft Orange Labs
	Intended status: Best Current Practice V. Fajardo		Intended status: Best Current Practice V. Fajardo
	Expires: October 17, 2014 Independent		Expires: November 13, 2014 Independent
	H. Tschofenig		H. Tschofenig
	Nokia Siemens Networks		Nokia Siemens Networks
	April 15, 2014		May 12, 2014
	Diameter Applications Design Guidelines		Diameter Applications Design Guidelines
	draft-ietf-dime-app-design-guide-22		draft-ietf-dime-app-design-guide-23
	Abstract		Abstract
	The Diameter base protocol provides facilities for protocol		The Diameter base protocol provides facilities for protocol
	extensibility enabling to define new Diameter applications or modify		extensibility enabling to define new Diameter applications or modify
	existing applications. This document is a companion document to the		existing applications. This document is a companion document to the
	Diameter Base protocol that further explains and clarifies the rules		Diameter Base protocol that further explains and clarifies the rules
	to extend Diameter. It is meant as a guidelines document and		to extend Diameter. Futhermore, this document provides guidelines to
	therefore as informative in nature.		Diameter application designers reusing/defining Diameter applications
			or creating generic Diameter extensions.
	Status of This Memo		Status of This Memo
	This Internet-Draft is submitted in full conformance with the		This Internet-Draft is submitted in full conformance with the
	provisions of BCP 78 and BCP 79.		provisions of BCP 78 and BCP 79.
	Internet-Drafts are working documents of the Internet Engineering		Internet-Drafts are working documents of the Internet Engineering
	Task Force (IETF). Note that other groups may also distribute		Task Force (IETF). Note that other groups may also distribute
	working documents as Internet-Drafts. The list of current Internet-		working documents as Internet-Drafts. The list of current Internet-
	Drafts is at http://datatracker.ietf.org/drafts/current/.		Drafts is at http://datatracker.ietf.org/drafts/current/.
	Internet-Drafts are draft documents valid for a maximum of six months		Internet-Drafts are draft documents valid for a maximum of six months
	and may be updated, replaced, or obsoleted by other documents at any		and may be updated, replaced, or obsoleted by other documents at any
	time. It is inappropriate to use Internet-Drafts as reference		time. It is inappropriate to use Internet-Drafts as reference
	material or to cite them other than as "work in progress."		material or to cite them other than as "work in progress."
	This Internet-Draft will expire on October 17, 2014.		This Internet-Draft will expire on November 13, 2014.
	Copyright Notice		Copyright Notice
	Copyright (c) 2014 IETF Trust and the persons identified as the		Copyright (c) 2014 IETF Trust and the persons identified as the
	document authors. All rights reserved.		document authors. All rights reserved.
	This document is subject to BCP 78 and the IETF Trust's Legal		This document is subject to BCP 78 and the IETF Trust's Legal
	Provisions Relating to IETF Documents		Provisions Relating to IETF Documents
	(http://trustee.ietf.org/license-info) in effect on the date of		(http://trustee.ietf.org/license-info) in effect on the date of
	publication of this document. Please review these documents		publication of this document. Please review these documents
	skipping to change at page 2, line 37 ¶		skipping to change at page 2, line 38 ¶
	4.1. Adding a New Command . . . . . . . . . . . . . . . . . . 5		4.1. Adding a New Command . . . . . . . . . . . . . . . . . . 5
	4.2. Deleting an Existing Command . . . . . . . . . . . . . . 6		4.2. Deleting an Existing Command . . . . . . . . . . . . . . 6
	4.3. Reusing Existing Commands . . . . . . . . . . . . . . . . 7		4.3. Reusing Existing Commands . . . . . . . . . . . . . . . . 7
	4.3.1. Adding AVPs to a Command . . . . . . . . . . . . . . 7		4.3.1. Adding AVPs to a Command . . . . . . . . . . . . . . 7
	4.3.2. Deleting AVPs from a Command . . . . . . . . . . . . 9		4.3.2. Deleting AVPs from a Command . . . . . . . . . . . . 9
	4.4. Reusing Existing AVPs . . . . . . . . . . . . . . . . . . 9		4.4. Reusing Existing AVPs . . . . . . . . . . . . . . . . . . 9
	4.4.1. Setting of the AVP Flags . . . . . . . . . . . . . . 10		4.4.1. Setting of the AVP Flags . . . . . . . . . . . . . . 10
	4.4.2. Reuse of AVP of Type Enumerated . . . . . . . . . . . 10		4.4.2. Reuse of AVP of Type Enumerated . . . . . . . . . . . 10
	5. Defining New Diameter Applications . . . . . . . . . . . . . 10		5. Defining New Diameter Applications . . . . . . . . . . . . . 10
	5.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 10		5.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 10
	5.2. Defining New Commands . . . . . . . . . . . . . . . . . . 10		5.2. Defining New Commands . . . . . . . . . . . . . . . . . . 11
	5.3. Use of Application-Id in a Message . . . . . . . . . . . 11		5.3. Use of Application-Id in a Message . . . . . . . . . . . 11
	5.4. Application-Specific Session State Machines . . . . . . . 12		5.4. Application-Specific Session State Machines . . . . . . . 12
	5.5. Session-Id AVP and Session Management . . . . . . . . . . 12		5.5. Session-Id AVP and Session Management . . . . . . . . . . 12
	5.6. Use of Enumerated Type AVPs . . . . . . . . . . . . . . . 13		5.6. Use of Enumerated Type AVPs . . . . . . . . . . . . . . . 13
	5.7. Application-Specific Message Routing . . . . . . . . . . 15		5.7. Application-Specific Message Routing . . . . . . . . . . 15
	5.8. Translation Agents . . . . . . . . . . . . . . . . . . . 15		5.8. Translation Agents . . . . . . . . . . . . . . . . . . . 15
	5.9. End-to-End Application Capabilities Exchange . . . . . . 16		5.9. End-to-End Application Capabilities Exchange . . . . . . 16
	5.10. Diameter Accounting Support . . . . . . . . . . . . . . . 17		5.10. Diameter Accounting Support . . . . . . . . . . . . . . . 17
	5.11. Diameter Security Mechanisms . . . . . . . . . . . . . . 18		5.11. Diameter Security Mechanisms . . . . . . . . . . . . . . 18
	6. Defining Generic Diameter Extensions . . . . . . . . . . . . 19		6. Defining Generic Diameter Extensions . . . . . . . . . . . . 19
	skipping to change at page 5, line 49 ¶		skipping to change at page 5, line 49 ¶
	An existing application may need to be enhanced to fulfill new		An existing application may need to be enhanced to fulfill new
	requirements and these modifications can be at the command level and/		requirements and these modifications can be at the command level and/
	or at the AVP level. The following sections describe the possible		or at the AVP level. The following sections describe the possible
	modifications that can be performed on existing applications and		modifications that can be performed on existing applications and
	their related impact.		their related impact.
	4.1. Adding a New Command		4.1. Adding a New Command
	Adding a new command to an existing application is considered as a		Adding a new command to an existing application is considered as a
	major extension and requires a new Diameter application to be		major extension and requires a new Diameter application to be
	defined. Adding a new command means either defining a completely new		defined, as stated in the Section 1.3.4 of [RFC6733]. Adding a new
	command or importing the command's Command Code Format (CCF) syntax		command means either defining a completely new command or importing
	from another application whereby the new application inherits some or		the command's Command Code Format (CCF) syntax from another
	all of the functionality of the application where the command came		application whereby the new application inherits some or all of the
	from. In the former case, the decision to create a new application		functionality of the application where the command came from. In the
	is straightforward since this is typically a result of adding a new		former case, the decision to create a new application is
			straightforward since this is typically a result of adding a new
	functionality that does not exist yet. For the latter, the decision		functionality that does not exist yet. For the latter, the decision
	to create a new application will depend on whether importing the		to create a new application will depend on whether importing the
	command in a new application is more suitable than simply using the		command in a new application is more suitable than simply using the
	existing application as it is in conjunction with any other		existing application as it is in conjunction with any other
	application. Therefore, a case by case study of each application		application. Therefore, a case by case study of each application
	requirement SHOULD be applied.		requirement SHOULD be applied.
	An example considers the Diameter EAP application [RFC4072] and the		An example considers the Diameter EAP application [RFC4072] and the
	Diameter Network Access Server application [RFC7155]. When network		Diameter Network Access Server application [RFC7155]. When network
	access authentication using EAP is required, the Diameter EAP		access authentication using EAP is required, the Diameter EAP
	skipping to change at page 7, line 46 ¶		skipping to change at page 7, line 49 ¶
	o Optional (to understand) AVPs. As defined in [RFC6733], these are		o Optional (to understand) AVPs. As defined in [RFC6733], these are
	AVPs with the M-bit flag cleared in this command. A Diameter node		AVPs with the M-bit flag cleared in this command. A Diameter node
	receiving these AVPs can simply ignore them if it does not support		receiving these AVPs can simply ignore them if it does not support
	them.		them.
	It is important to note that the definition given above are		It is important to note that the definition given above are
	independent of whether these AVPs are required or optional in the		independent of whether these AVPs are required or optional in the
	command as specified by the command's Command Code Format (CCF)		command as specified by the command's Command Code Format (CCF)
	syntax [RFC6733].		syntax [RFC6733].
	NOTE: As stated in RFC6733, the M-bit setting for a given AVP is		NOTE: As stated in [RFC6733], the M-bit setting for a given AVP is
	relevant to an application and each command within that		relevant to an application and each command within that
	application that includes the AVP.		application that includes the AVP.
	The rules are strict in the case where the AVPs to be added in an		The rules are strict in the case where the AVPs to be added in an
	exiting command are mandatory to understand, i.e., they have the		exiting command are mandatory to understand, i.e., they have the
	M-bit set. A mandatory AVP MUST NOT be added to an existing command		M-bit set. A mandatory AVP MUST NOT be added to an existing command
	without defining a new Diameter application, as stated in [RFC6733].		without defining a new Diameter application, as stated in [RFC6733].
	This falls into the "Major Extensions" category. Despite the clarity		This falls into the "Major Extensions" category. Despite the clarity
	of the rule, ambiguity still arises when evaluating whether a new AVP		of the rule, ambiguity still arises when evaluating whether a new AVP
	being added should be mandatory to begin with. Application designers		being added should be mandatory to begin with. Application designers
	skipping to change at page 10, line 7 ¶		skipping to change at page 10, line 7 ¶
	new functionality as well as maintain the integrity of existing		new functionality as well as maintain the integrity of existing
	dictionaries.		dictionaries.
	4.4. Reusing Existing AVPs		4.4. Reusing Existing AVPs
	This section discusses rules in reusing existing AVP when reusing an		This section discusses rules in reusing existing AVP when reusing an
	existing command or defining a new command in a new application.		existing command or defining a new command in a new application.
	4.4.1. Setting of the AVP Flags		4.4.1. Setting of the AVP Flags
	When reusing AVPs in a new application, the AVP flag setting, such as		When reusing AVPs in a new application, the M-bit flag setting MUST
	the mandatory flag ('M'-bit), has to be re-evaluated for a new		be re-evaluated for a new Diameter application and, if necessary,
	Diameter application and, if necessary, even for every command within		even for every command within the application. In general, for AVPs
	the application. In general, for AVPs defined outside of the		defined outside of the Diameter base protocol, the characteristics of
	Diameter base protocol, the characteristics of an AVP are tied to its		an AVP are tied to its role within a given application and the
	role within an application and the commands.		commands used in this application.
	All other AVP flags MUST remain unchanged.		All other AVP flags (V-bit, P-bit, reserved bits) MUST remain
			unchanged.
	4.4.2. Reuse of AVP of Type Enumerated		4.4.2. Reuse of AVP of Type Enumerated
	When reusing an AVP of type Enumerated in a command for a new		When reusing an AVP of type Enumerated in a command for a new
	application, it is RECOMMENDED to avoid modifying the set of valid		application, it is RECOMMENDED to avoid modifying the set of valid
	values defined for this AVP. Modifying the set of Enumerated values		values defined for this AVP. Modifying the set of Enumerated values
	includes adding a value or deprecating the use of a value defined		includes adding a value or deprecating the use of a value defined
	initially for the AVP. Modifying the set of values will impact the		initially for the AVP. Modifying the set of values will impact the
	application defining this AVP and all the applications using this AVP		application defining this AVP and all the applications using this
	with potential interoperability issues. When the full range of		AVP, causing potential interoperability issues. When the full range
	values defined for this Enumerated AVP is not suitable for the new		of values defined for this Enumerated AVP is not suitable for the new
	application, it is RECOMMENDED to define a new AVP to avoid backwards		application, it is RECOMMENDED to define a new AVP to avoid backwards
	compatibility issues with existing implementations.		compatibility issues with existing implementations.
	5. Defining New Diameter Applications		5. Defining New Diameter Applications
	5.1. Introduction		5.1. Introduction
	This section discusses the case where new applications have		This section discusses the case where new applications have
	requirements that cannot be fulfilled by existing applications and		requirements that cannot be fulfilled by existing applications and
	would require definition of completely new commands, AVPs and/or AVP		would require definition of completely new commands, AVPs and/or AVP
	skipping to change at page 11, line 28 ¶		skipping to change at page 11, line 34 ¶
	NOTE: As a hint for protocol designers, it is not sufficient to just		NOTE: As a hint for protocol designers, it is not sufficient to just
	look at the command's CCF syntax specification. It is also		look at the command's CCF syntax specification. It is also
	necessary to carefully read through the accompanying text in the		necessary to carefully read through the accompanying text in the
	specification.		specification.
	In the same way, the CCF syntax specification SHOULD be defined such		In the same way, the CCF syntax specification SHOULD be defined such
	that it will be possible to add any arbitrary optional AVPs with the		that it will be possible to add any arbitrary optional AVPs with the
	M-bit cleared (including vendor-specific AVPs) without modifying the		M-bit cleared (including vendor-specific AVPs) without modifying the
	application. For this purpose, "* [AVP]" SHOULD be added in the		application. For this purpose, "* [AVP]" SHOULD be added in the
	command's CCF, which allows the addition of any arbitrary AVP as		command's CCF, which allows the addition of any arbitrary number of
	described in [RFC6733].		optional AVPs as described in [RFC6733].
	5.3. Use of Application-Id in a Message		5.3. Use of Application-Id in a Message
	When designing new applications, application designers SHOULD specify		When designing new applications, application designers SHOULD specify
	that the Application Id carried in all session-level messages is the		that the Application Id carried in all session-level messages is the
	Application Id of the application using those messages. This		Application Id of the application using those messages. This
	includes the session-level messages defined in Diameter base		includes the session-level messages defined in Diameter base
	protocol, i.e., RAR/RAA, STR/STA, ASR/ASA and possibly ACR/ACA in the		protocol, i.e., RAR/RAA, STR/STA, ASR/ASA and possibly ACR/ACA in the
	coupled accounting model, see Section 5.10. Some existing		coupled accounting model, see Section 5.10. Some existing
	specifications do not adhere to this rule for historical reasons.		specifications do not adhere to this rule for historical reasons.
	skipping to change at page 16, line 27 ¶		skipping to change at page 16, line 27 ¶
	[RFC7155]) which deprecates the RFC4005 ([RFC4005]).		[RFC7155]) which deprecates the RFC4005 ([RFC4005]).
	Therefore, protocol designers SHOULD NOT assume the availability of a		Therefore, protocol designers SHOULD NOT assume the availability of a
	"standard" Diameter-to-RADIUS gateways agent when planning to		"standard" Diameter-to-RADIUS gateways agent when planning to
	interoperate with the RADIUS infrastructure. They SHOULD specify the		interoperate with the RADIUS infrastructure. They SHOULD specify the
	required translation mechanism along with the Diameter application,		required translation mechanism along with the Diameter application,
	if needed. This recommendation applies for any kind of translation.		if needed. This recommendation applies for any kind of translation.
	5.9. End-to-End Application Capabilities Exchange		5.9. End-to-End Application Capabilities Exchange
	New Diameter applications can rely on optional AVPs to exchange		Diameter applications can rely on optional AVPs to exchange
	application-specific capabilities and features. These AVPs can be		application-specific capabilities and features. These AVPs can be
	exchanged on an end-to-end basis at the application layer. Examples		exchanged on an end-to-end basis at the application layer. Examples
	of this can be found with the MIP6-Feature-Vector AVP in [RFC5447]		of this can be found with the MIP6-Feature-Vector AVP in [RFC5447]
	and the QoS-Capability AVP in [RFC5777].		and the QoS-Capability AVP in [RFC5777].
	The end-to-end capabilities AVPs formalize the addition of new		End-to-end capabilities AVPs can be added as optional AVPs with the
	optional functionality to existing applications by announcing support		M-bit cleared to existing applications to announce support of new
	for it. Applications that do not understand these AVPs can discard		functionality. Receivers that do not understand these AVPs or the
	them upon receipt. Receivers of these AVPs can discover the		AVP values can simply ignore them, as stated in [RFC6733]. When
	additional functionality supported by the end-point originating the		supported, receivers of these AVPs can discover the additional
			functionality supported by the Diameter end-point originating the
	request and behave accordingly when processing the request. Senders		request and behave accordingly when processing the request. Senders
	of these AVPs can safely assume the receiving end-point does not		of these AVPs can safely assume the receiving end-point does not
	support any functionality carried by the AVP if it is not present in		support any functionality carried by the AVP if it is not present in
	corresponding response. This is useful in cases where deployment		corresponding response. This is useful in cases where deployment
	choices are offered, and the generic design can be made available for		choices are offered, and the generic design can be made available for
	a number of applications.		a number of applications.
	When used in a new application, protocol designers SHOULD clearly		When used in a new application, these end-to-end capabilities AVPs
	specify this end-to-end capabilities exchange and the corresponding		SHOULD be added as optional AVP into the CCF of the commands used by
	behaviour of the Diameter nodes supporting the application.		the new application. Protocol designers SHOULD clearly specify this
			end-to-end capabilities exchange and the corresponding behaviour of
			the Diameter nodes supporting the application.
	It is also important to note that this end-to-end capabilities		It is also important to note that this end-to-end capabilities
	exchange relying on the use of optional AVPs is not meant as a		exchange relying on the use of optional AVPs is not meant as a
	generic mechanism to support extensibility of Diameter applications		generic mechanism to support extensibility of Diameter applications
	with arbitrary functionality. When the added features drastically		with arbitrary functionality. When the added features drastically
	change the Diameter application or when Diameter agents must be		change the Diameter application or when Diameter agents must be
	upgraded to support the new features, a new application SHOULD be		upgraded to support the new features, a new application SHOULD be
	defined.		defined, as recommended in [RFC6733].
	5.10. Diameter Accounting Support		5.10. Diameter Accounting Support
	Accounting can be treated as an auxiliary application that is used in		Accounting can be treated as an auxiliary application that is used in
	support of other applications. In most cases, accounting support is		support of other applications. In most cases, accounting support is
	required when defining new applications. This document provides two		required when defining new applications. This document provides two
	possible models for using accounting:		possible models for using accounting:
	Split Accounting Model:		Split Accounting Model:
End of changes. 16 change blocks.
	36 lines changed or deleted		42 lines changed or added
This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/