< draft-ietf-dime-app-design-guide-24.txt		draft-ietf-dime-app-design-guide-25.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: December 6, 2014 Independent		Expires: January 20, 2015 Independent
	H. Tschofenig		H. Tschofenig
	Nokia Siemens Networks		Nokia Siemens Networks
	June 4, 2014		July 19, 2014
	Diameter Applications Design Guidelines		Diameter Applications Design Guidelines
	draft-ietf-dime-app-design-guide-24		draft-ietf-dime-app-design-guide-25
	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. Futhermore, this document provides guidelines to		to extend Diameter. Furthermore, this document provides guidelines
	Diameter application designers reusing/defining Diameter applications		to Diameter application designers reusing/defining Diameter
	or creating generic Diameter extensions.		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 December 6, 2014.		This Internet-Draft will expire on January 20, 2015.
	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 29 ¶		skipping to change at page 2, line 29 ¶
	it for publication as an RFC or to translate it into languages other		it for publication as an RFC or to translate it into languages other
	than English.		than English.
	Table of Contents		Table of Contents
	1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3		1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
	2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3		2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3
	3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 4		3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 4
	4. Reusing Existing Diameter Applications . . . . . . . . . . . 5		4. Reusing Existing Diameter Applications . . . . . . . . . . . 5
	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 . . . . . . . . . . . . . . 7
	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 . . . . . . . . . . . . . . . . . . 10
	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 . . . . . . . . . . . . . . . . . . 11		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
	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, as stated in the Section 1.3.4 of [RFC6733]. Adding a new		defined, as stated in the Section 1.3.4 of [RFC6733]. The need for a
	command means either defining a completely new command or importing		new application is due to the fact that a Diameter node not upgraded
	the command's Command Code Format (CCF) syntax from another		to support the new application and therefore the new command will
	application whereby the new application inherits some or all of the		reject any unknown command with the protocol error
	functionality of the application where the command came from. In the		DIAMETER_COMMAND_UNSUPPORTED and the transaction will fail.
	former case, the decision to create a new application is
			Adding a new command means either defining a completely new command
			or importing the command's Command Code Format (CCF) syntax from
			another application whereby the new application inherits some or all
			of the functionality of the application where the command came from.
			In the former case, the decision to create a new application is
	straightforward since this is typically a result of adding a new		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
	skipping to change at page 6, line 38 ¶		skipping to change at page 6, line 43 ¶
	o Can the new functionality be fulfilled by creating a new command		o Can the new functionality be fulfilled by creating a new command
	independent from any existing command? In this case, the		independent from any existing command? In this case, the
	resulting new application and the existing application can work		resulting new application and the existing application can work
	independent of, but cooperating with each other.		independent of, but cooperating with each other.
	o Can the existing command be reused without major extensions and		o Can the existing command be reused without major extensions and
	therefore without the need for the definition of a new		therefore without the need for the definition of a new
	application, e.g. new functionality introduced by the creation of		application, e.g. new functionality introduced by the creation of
	new optional AVPs.		new optional AVPs.
	Note: Importing commands too liberally could result in a monolithic		It is important to note that importing commands too liberally could
	and hard to manage application supporting too many different		result in a monolithic and hard to manage application supporting too
	features.		many different features.
	4.2. Deleting an Existing Command		4.2. Deleting an Existing Command
	Although this process is not typical, removing a command from an		Although this process is not typical, removing a command from an
	application requires a new Diameter application to be defined and		application requires a new Diameter application to be defined and
	then it is considered as a major extension. This is due to the fact		then it is considered as a major extension. This is due to the fact
	that the reception of the deleted command would systematically result		that the reception of the deleted command would systematically result
	in a protocol error (i.e., DIAMETER_COMMAND_UNSUPPORTED).		in a protocol error (i.e., DIAMETER_COMMAND_UNSUPPORTED).
	It is unusual to delete an existing command from an application for		It is unusual to delete an existing command from an application for
	skipping to change at page 7, line 38 ¶		skipping to change at page 7, line 46 ¶
	4.3.1. Adding AVPs to a Command		4.3.1. Adding AVPs to a Command
	Based on the rules in [RFC6733], AVPs that are added to an existing		Based on the rules in [RFC6733], AVPs that are added to an existing
	command can be categorized into:		command can be categorized into:
	o Mandatory (to understand) AVPs. As defined in [RFC6733], these		o Mandatory (to understand) AVPs. As defined in [RFC6733], these
	are AVPs with the M-bit flag set in this command, which means that		are AVPs with the M-bit flag set in this command, which means that
	a Diameter node receiving them is required to understand not only		a Diameter node receiving them is required to understand not only
	their values but also their semantics. Failure to do so will		their values but also their semantics. Failure to do so will
	cause an message handling error.		cause an message handling error: either a error message with the
			result-code set to DIAMETER_AVP_UNSUPPORTED if the AVP not
			understood in a request or a application specific error handling
			if the given AVP is in an answer.
	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].
	skipping to change at page 9, line 19 ¶		skipping to change at page 9, line 32 ¶
	Application designers may want to reuse an existing command but some		Application designers may want to reuse an existing command but some
	of the AVP present in the command's CCF syntax specification may be		of the AVP present in the command's CCF syntax specification may be
	irrelevant for the functionality foreseen to be supported by this		irrelevant for the functionality foreseen to be supported by this
	command. It may be then tempting to delete those AVPs from the		command. It may be then tempting to delete those AVPs from the
	command.		command.
	The impacts of deleting an AVP from a command depends on its command		The impacts of deleting an AVP from a command depends on its command
	code format specification and M-bit setting:		code format specification and M-bit setting:
	o Deleting an AVP that is indicated as a required AVP (noted as		o Case 1: Deleting an AVP that is indicated as a required AVP (noted
	{AVP}) in the command's CCF syntax specification (regardless of		as {AVP}) in the command's CCF syntax specification (regardless of
	the M-bit setting).		the M-bit setting).
	In this case, a new command code and subsequently a new Diameter		In this case, a new command code and subsequently a new Diameter
	application MUST be specified.		application MUST be specified.
	o Deleting an AVP, which has the M-bit set, and is indicated as		o Case 2: Deleting an AVP, which has the M-bit set, and is indicated
	optional AVP (noted as [AVP]) in the command CCF) in the command's		as optional AVP (noted as [AVP]) in the command CCF) in the
	CCF syntax specification.		command's CCF syntax specification.
	No new command code has to be specified but the definition of a		In this case, no new command code has to be specified but the
	new Diameter application is REQUIRED.		definition of a new Diameter application is REQUIRED.
	o Deleting an AVP, which has the M-bit cleared, and is indicated as		o Case 3: Deleting an AVP, which has the M-bit cleared, and is
	[ AVP ] in the command's CCF syntax specification.		indicated as [AVP] in the command's CCF syntax specification.
	In this case, the AVP can be deleted without consequences.		In this case, the AVP can be deleted without consequences.
	Application designers SHOULD attempt the reuse the command's CCF		Application designers SHOULD attempt the reuse the command's CCF
	syntax specification without modification and simply ignore (but not		syntax specification without modification and simply ignore (but not
	delete) any optional AVP that will not be used. This is to maintain		delete) any optional AVP that will not be used. This is to maintain
	compatibility with existing applications that will not know about the		compatibility with existing applications that will not know about the
	new functionality as well as maintain the integrity of existing		new functionality as well as maintain the integrity of existing
	dictionaries.		dictionaries.
	skipping to change at page 22, line 14 ¶		skipping to change at page 22, line 14 ¶
	Similarly to the Command Code namespace, the Application-Id		Similarly to the Command Code namespace, the Application-Id
	namespace is flat but divided into two distinct ranges:		namespace is flat but divided into two distinct ranges:
	* A range of values reserved for standard Application-Ids		* A range of values reserved for standard Application-Ids
	allocated after Expert Review of the specification defining the		allocated after Expert Review of the specification defining the
	standard application;		standard application;
	* A range for values for vendor specific applications, allocated		* A range for values for vendor specific applications, allocated
	by IANA on a First-Come/First-Serve basis.		by IANA on a First-Come/First-Serve basis.
	The IANA AAA parameters page can be found at http://www.iana.org/		The IANA AAA parameters page can be found at
	assignments/aaa-parameters/aaa-parameters.xml and the enterprise		http://www.iana.org/assignments/aaa-parameters/aaa-parameters.xml and
	number IANA page is available at http://www.iana.org/assignments/		the enterprise number IANA page is available at
	enterprise-numbers. More details on the policies followed by IANA		http://www.iana.org/assignments/enterprise-numbers. More details on
	for namespace management (e.g. First-Come/First-Served, Expert		the policies followed by IANA for namespace management (e.g. First-
	Review, IETF Review, etc.) can be found in [RFC5226].		Come/First-Served, Expert Review, IETF Review, etc.) can be found in
			[RFC5226].
	NOTE:		NOTE:
	When the same functionality/extension is used by more than one		When the same functionality/extension is used by more than one
	vendor, it is RECOMMENDED to define a standard extension.		vendor, it is RECOMMENDED to define a standard extension.
	Moreover, a vendor-specific extension SHOULD be registered to		Moreover, a vendor-specific extension SHOULD be registered to
	avoid interoperability issues in the same network. With this aim,		avoid interoperability issues in the same network. With this aim,
	the registration policy of vendor-specific extension has been		the registration policy of vendor-specific extension has been
	simplified with the publication of [RFC6733] and the namespace		simplified with the publication of [RFC6733] and the namespace
	reserved for vendor-specific extensions is large enough to avoid		reserved for vendor-specific extensions is large enough to avoid
	exhaustion.		exhaustion.
End of changes. 15 change blocks.
	34 lines changed or deleted		43 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/