<?xml version="1.0" encoding="US-ASCII"?>
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
<rfc category="info" docName="draft-ietf-dime-app-design-guide-19"
     ipr="trust200902">
  <?rfc toc="yes" ?>

  <?rfc symrefs="yes" ?>

  <?rfc sortrefs="yes"?>

  <?rfc compact="no" ?>

  <?rfc iprnotified="no" ?>

  <?rfc strict="no" ?>

  <front>
    <title>Diameter Applications Design Guidelines</title>

    <author fullname="Lionel Morand" initials="L." role="editor"
            surname="Morand">
      <organization>Orange Labs</organization>

      <address>
        <postal>
          <street>38/40 rue du G&eacute;n&eacute;ral Leclerc</street>

          <city>Issy-Les-Moulineaux Cedex 9</city>

          <code>92794</code>

          <country>France</country>
        </postal>

        <phone>+33145296257</phone>

        <email>lionel.morand@orange.com</email>
      </address>
    </author>

    <author fullname="Victor Fajardo" initials="V." surname="Fajardo">
      <address>
        <email>vf0213@gmail.com</email>
      </address>
    </author>

    <author fullname="Hannes Tschofenig" initials="H." surname="Tschofenig">
      <organization>Nokia Siemens Networks</organization>

      <address>
        <postal>
          <street>Linnoitustie 6</street>

          <city>Espoo</city>

          <code>02600</code>

          <country>Finland</country>
        </postal>

        <phone>+358 (50) 4871445</phone>

        <email>Hannes.Tschofenig@gmx.net</email>

        <uri>http://www.tschofenig.priv.at</uri>
      </address>
    </author>

    <date year="2013"/>

    <area>Operations and Management Area</area>

    <workgroup>Diameter Maintenance and Extensions (DIME)</workgroup>

    <keyword>Internet-Draft</keyword>

    <abstract>
      <t>The Diameter base protocol provides facilities for protocol
      extensibility enabling to define new Diameter applications or modify
      existing applications. This document is a companion document to the
      Diameter Base protocol that further explains and clarifies the rules to
      extend Diameter. It is meant as a guidelines document and therefore as
      informative in nature.</t>
    </abstract>
  </front>

  <middle>
    <section title="Introduction">
      <t>The Diameter base protocol provides facilities to extend Diameter
      (see Section 1.3 of <xref target="RFC6733"/>) to support new
      functionality. In the context of this document, extending Diameter means
      one of the following:<vspace blankLines="1"/> <list style="numbers">
          <t>Addition of new functionality to an existing Diameter application
          without defining a new application.<vspace blankLines="0"/></t>

          <t>Addition of new functionality to an existing Diameter application
          that requires the definition of a new application. <vspace
          blankLines="0"/></t>

          <t>The definition of an entirely new Diameter application to offer
          functionality not supported by existing applications. <vspace
          blankLines="0"/></t>

          <t>The definition of a new generic functionality that can be reused
          across different applications.<vspace blankLines="0"/></t>
        </list></t>

      <t>All of these choices are design decisions that can be done by any
      combination of reusing existing or defining new commands, AVPs or AVP
      values. However, application designers do not have complete freedom when
      making their design. A number of rules have been defined in <xref
      target="RFC6733"/> that place constraints on when an extension requires
      the allocation of a new Diameter application identifier or a new command
      code value. The objective of this document is the following:<vspace
      blankLines="0"/> <list style="symbols">
          <t>Clarify the Diameter extensibility rules as defined in the
          Diameter base protocol. <vspace blankLines="0"/></t>

          <!-- 
          <t>Clarify usage of certain Diameter functionality that is
          explicitly described in the Diameter Base specification.<vspace
          blankLines="0"/></t>
-->

          <t>Discuss design choices and provide guidelines when defining new
          applications. <vspace blankLines="0"/></t>

          <t>Present trade-off choices.</t>
        </list></t>
    </section>

    <!-- *************************************************************** -->

    <section title="Terminology">
      <t>This document reuses the terminology defined in <xref
      target="RFC6733"/>.</t>

      <!-- 
      <t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
      "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
      document are to be interpreted as described in <xref
      target="RFC2119"/>.</t>
-->
    </section>

    <!-- *************************************************************** -->

    <section title="Overview">
      <t>As designed, the Diameter base protocol <xref target="RFC6733"/> can
      be seen as a two-layer protocol. The lower layer is mainly responsible
      for managing connections between neighboring peers and for message
      routing. The upper layer is where the Diameter applications reside. This
      model is in line with a Diameter node having an application layer and a
      peer-to-peer delivery layer. The Diameter base protocol document defines
      the architecture and behavior of the message delivery layer and then
      provides the framework for designing Diameter applications on the
      application layer. This framework includes definitions of application
      sessions and accounting support (see Section 8 and Section 9 of <xref
      target="RFC6733"/>). Accordingly, a Diameter node is seen in this
      document as a single instance of a Diameter message delivery layer and
      one or more Diameter applications using it.</t>

      <t>The Diameter base protocol is designed to be extensible and the
      principles are described in the Section 1.3 of <xref target="RFC6733"/>.
      As a summary, Diameter can be extended by: <list style="numbers">
          <t>Defining new AVP values</t>

          <t>Creating new AVPs</t>

          <t>Creating new commands</t>

          <t>Creating new applications</t>
        </list></t>

      <t>As a main guiding principle, the recommendation is: "try to re-use as
      much as possible!". It will reduce the time to finalize specification
      writing, and it will lead to a smaller implementation effort as well as
      reduce the need for testing. In general, it is clever to avoid duplicate
      effort when possible.</t>

      <t>However, re-use is not appropriate when the existing functionality
      does not fit the new requirement and/or the re-use leads to
      ambiguity.</t>

      <t>The impact on extending existing applications can be categorized into
      two groups: <list style="hanging">
          <t hangText="Minor Extension:">Enhancing the functional scope of an
          existing application by the addition of optional features to
          support. Such enhancement has no backward compatibility issue with
          the existing application. <vspace blankLines="1"/> A typical example
          would be the definition of a new optional AVP for use in an existing
          command. Diameter implementations supporting the existing
          application but not the new AVP will simply ignore it, without
          consequences for the Diameter message handling. The standardization
          effort will be fairly small. <vspace blankLines="1"/></t>

          <t hangText="Major Extension:">Enhancing an application that
          requires the definition of a new Diameter application. <vspace
          blankLines="1"/> Typical examples would be the creation of a new
          command for providing functionality not supported by existing
          applications or the definition of a new AVP with the M-bit set to be
          carried in an existing command. For such extension, a significant
          specification effort is required and a careful approach is
          recommended.</t>
        </list></t>

      <!-- 
      <t>The rules outlined in the Section 1.3 of <xref
      target="RFC6733"/> indicate when an extension requires
      a new command code to be registered and when new Diameter applications
      have to be defined. The subsequent sections further explain and clarify
      the rules to extend the Diameter base protocol. It is meant as a
      guidelines document and therefore it does not add, remove or change
      existing rules.</t>
-->

      <t>We would also like to remind that the definition of a new Diameter
      application and the definition of a new command should be something to
      avoid as much as possible. In the past, there has been some reluctance
      to define new commands and new applications. With the modified
      extensibility rules provided by <xref target="RFC6733"/>, registering
      new commands and new applications does not lead to additional overhead
      for the specification author in terms of standardization process.
      Registering new functionality (new commands, new AVPs, new applications,
      etc.) with IANA remains important to avoid namespace collisions, which
      will likely lead to deployment problems.</t>
    </section>

    <!-- *************************************************************** -->

    <section title="Reusing Existing Diameter Applications">
      <t>An existing application may need to be enhanced to fulfill new
      requirements and these modifications can be at the command level and/or
      at the AVP level. The following sections describe the possible
      modifications that can be performed on existing applications and their
      related impact.</t>

      <section title="Adding a New Command">
        <t>Adding a new command is considered as a major extension and
        requires a new Diameter application to be defined. Adding a new
        command to an application 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
        functionality that does not exist yet. For the latter, the decision to
        create a new application will depend on whether importing the command
        in a new application is more suitable than simply using the existing
        application as it is in conjunction with any other application.
        Therefore, a case by case study of each application requirement should
        be applied.</t>

        <t>An example considers the Diameter EAP application <xref
        target="RFC4072"/> and the Diameter NASREQ application <xref
        target="RFC4005"/>. When network access authentication using EAP is
        required, the Diameter EAP commands
        (Diameter-EAP-Request/Diameter-EAP-Answer) are used; otherwise the
        NASREQ application will be used. When the Diameter EAP application is
        used, the accounting exchanges defined in Diameter NASREQ may be
        used.</t>

        <t>However, in general, it is difficult to come to a hard guideline,
        and so a case-by-case study of each application requirement should be
        applied. Before adding or importing a command, application designers
        should consider the following:<vspace blankLines="1"/> <list
            style="symbols">
            <t>Can the new functionality be fulfilled by creating a new
            command independent from any existing command? In this case, the
            resulting new application and the existing application can work
            independent of, but cooperating with each other.<vspace
            blankLines="0"/></t>

            <t>Can the existing command be reused without major extensions and
            therefore without the need for the definition of a new
            application, e.g., new functionality introduced by the creation of
            new optional AVPs.</t>
          </list></t>

        <t>Note: Importing commands too liberally could result in a monolithic
        and hard to manage application supporting too many different
        features.</t>
      </section>

      <section title="Deleting an Existing Command">
        <t>Although this process is not typical, removing a command from an
        application requires a new Diameter application to be defined. This is
        due to the fact that the reception of the deleted command would
        systematically result in a protocol error (i.e.,
        DIAMETER_COMMAND_UNSUPPORTED).</t>

        <t>It is unusual to delete an existing command from an application for
        the sake of deleting it or the functionality it represents. This
        normally indicates of a flawed design. An exception might be if the
        intent of the deletion is to create a newer version of the same
        application that is somehow simpler than the previous version.</t>
      </section>

      <section title="Reusing Existing Commands">
        <t>This section discusses rules in adding and/or deleting AVPs from an
        existing command of an existing application. The cases described in
        this section may not necessarily result in the creation of new
        applications.</t>

        <t>From a historical point of view, it is worth to note that there was
        a strong recommendation to re-use existing commands in the <xref
        target="RFC3588"/> to prevent rapid depletion of code values available
        for vendor-specific commands. However, <xref target="RFC6733"/> has
        relaxed the allocation policy and enlarged the range of available code
        values for vendor-specific applications. Although reuse of existing
        commands is still recommended, protocol designers can consider
        defining a new command when it provides a solution more suitable than
        the twisting of an existing command's use and applications.</t>

        <section title="Adding AVPs to a Command">
          <t>Based on the rules in <xref target="RFC6733"/>, AVPs that are
          added to an existing command can be categorized into:<vspace
          blankLines="0"/> <list style="symbols">
              <t>Mandatory (to understand) AVPs. As defined in <xref
              target="RFC6733"/>, these are AVPs with the M-bit flag set,
              which means that a Diameter node receiving them is required to
              understand not only their values but also their semantics.
              Failure to do so will cause an message handling error. This is
              regardless of whether these AVPs are required or optional as
              specified by the command's Command Code Format (CCF) syntax
              .<vspace blankLines="0"/></t>

              <t>Optional (to understand) AVPs. As defined in <xref
              target="RFC6733"/>, these are AVPs with the M-bit flag cleared.
              A Diameter node receiving these AVPs can simply ignore them if
              it does not support them.</t>
            </list></t>

          <t>The rules are strict in the case where the AVPs to be added are
          mandatory to understand, i.e., they have the M-bit set. A mandatory
          AVP cannot be added to an existing command without defining a new
          Diameter application, as stated in <xref target="RFC6733"/>. This
          falls into the "Major Extensions" category. Despite the clarity of
          the rule, ambiguity still arises when evaluating whether a new AVP
          being added should be mandatory to begin with. Application designers
          should consider the following questions when deciding about the
          M-bit for a new AVP:</t>

          <t><list style="symbols">
              <t>Would it be required for the receiving side to be able to
              process and understand the AVP and its content?<vspace
              blankLines="0"/></t>

              <t>Would the new AVPs change the state machine of the
              application?<vspace blankLines="0"/></t>

              <t>Would the presence of the new AVP lead to a different number
              of round-trips, effectively changing the state machine of the
              application?<vspace blankLines="0"/></t>

              <t>Would the new AVP be used to differentiate between old and
              new versions of the same application whereby the two versions
              are not backward compatible?<vspace blankLines="0"/></t>

              <t>Would the new AVP have duality in meaning, i.e., be used to
              carry application-related information as well as to indicate
              that the message is for a new application?</t>
            </list></t>

          <t>If the answer to at least one of the questions is "yes" then the
          M-bit has to be set for the new AVP. This list of questions is
          non-exhaustive and other criteria can be taken into account in the
          decision process.</t>

          <!--  <t>Note that the setting of the M-bit is not determined solely at the level of the AVP 
		  itself but it has to be seen in context of the command and the application.
		  For example, for some applications and commands a certain AVP may need to have the M-bit 
		  set while in other applications and comands this may not be necessary. In 
		  the past specifications defining AVPshave been published that provided AVP Flag rules 
that indicated preferences regarding the M-bit setting althrough the specification did not define a Diameter application or a Diameter command. In such cases it is better to be silent about the AVP flag rules (and the M-bit setting) and defer it to specifications that utilize thse AVPs in their commands.</t> 
		  -->

          <t>If application designers are instead contemplating the use of
          optional AVPs, i.e., with the M-bit cleared, then the following are
          some of the pitfalls that should be avoided:</t>

          <t><list style="symbols">
              <t>Use of optional AVPs with intersecting meaning. One AVP has
              partially the same usage and meaning as another AVP. The
              presence of both can lead to confusion. <vspace
              blankLines="0"/></t>

              <t>An optional AVPs with dual purpose, i.e., to carry
              application data as well as to indicate support for one or more
              features. This has a tendency to introduce interpretation
              issues.<vspace blankLines="0"/></t>

              <t>Adding one or more optional AVPs and indicating (usually
              within descriptive text for the command) that at least one of
              them has to be present in the command. This essentially
              circumventing the ABNF and is equivalent to adding a mandatory
              AVP to the command.</t>
            </list></t>

          <t>These practices generally result in interoperability issues and
          should be avoided as much as possible.</t>
        </section>

        <section title="Deleting AVPs from a Command">
          <t>The impacts of deleting an AVP from a command depends on its
          command code format specification and M-bit setting:</t>

          <t><list style="symbols">
              <t>Deleting an AVP that is indicated as { AVP } in the command's
              CCF syntax specification (regardless of the M-bit setting).
              <vspace blankLines="1"/> In this case, a new command code and
              subsequently a new Diameter application have to be
              specified.<vspace blankLines="0"/></t>

              <t>Deleting an AVP, which has the M-bit set, and is indicated as
              [ AVP ] in the command's CCF syntax specification. <vspace
              blankLines="1"/>No new command code has to be specified but the
              definition of a new Diameter application is required.<vspace
              blankLines="0"/></t>

              <t>Deleting an AVP, which has the M-bit cleared, and is
              indicated as [ AVP ] in the command's CCF syntax specification.
              <vspace blankLines="1"/>In this case, the AVP can be deleted
              without consequences.</t>
            </list></t>

          <t>If possible, application designers should attempt the reuse the
          command's CCF syntax specification without modification and simply
          ignore (but not delete) any optional AVP that will not be used. This
          is to maintain compatibility with existing applications that will
          not know about the new functionality as well as maintain the
          integrity of existing dictionaries.</t>
        </section>
      </section>

      <section title="Reusing Existing AVPs">
        <t>This section discusses rules in reusing existing AVP when reusing
        an existing command or defining a new command in a new
        application.</t>

        <section title="Setting of the AVP Flags">
          <t>When reusing AVPs in a new application, the AVP flag setting,
          such as the mandatory flag ('M'-bit), has to be re-evaluated for a
          new Diameter application and, if necessary, even for every command
          within the application. In general, for AVPs defined outside of the
          Diameter base protocol, the characteristics of an AVP are tied to
          its role within an application and the commands.</t>

          <t>All other AVP flags shall remain unchanged.</t>
        </section>

        <section title="Reuse of AVP of Type Enumerated">
          <t>When modifying the set of values supported by an AVP of type
          Enumerated, this means defining a new AVP. Modifying the set of
          Enumerated values includes adding a value or deprecating the use of
          a value defined initially for the AVP. Defining a new AVP will avoid
          interoperability issues.</t>
        </section>
      </section>
    </section>

    <!-- *************************************************************** -->

    <section title="Defining New Diameter Applications">
      <!--     <t>The general recommendation for Diameter extensibility is to reuse
        commands, AVPs and AVP values as much as possible. However, some of
        the extensibility rules described in the previous sections also apply
        to scenarios where a designer is trying to define a completely new
        Diameter application.</t>
-->

      <section title="Introduction">
        <t>This section discusses the case where new applications have
        requirements that cannot be fulfilled by existing applications and
        would require definition of completely new commands, AVPs and/or AVP
        values. Typically, there is little ambiguity about the decision to
        create these types of applications. Some examples are the interfaces
        defined for the IP Multimedia Subsystem of 3GPP, e.g., Cx/Dx (<xref
        target="TS29.228"/> and <xref target="TS29.229"/>), Sh (<xref
        target="TS29.328"/> and <xref target="TS29.329"/>) etc.</t>

        <t>Application designers should try to import existing AVPs and AVP
        values for any newly defined commands. In certain cases where
        accounting will be used, the models described in <xref
        target="other-accounting"/> should also be considered.</t>

        <t>Additional considerations are described in the following
        sections.</t>
      </section>

      <section title="Defining New Commands">
        <t>As a general recommendation, commands should not be defined from
        scratch. It is instead recommend to re-use an existing command
        offering similar functionality and use it as a starting point.</t>

        <t>Moreover, the new command's CCF syntax specification should be
        carefully defined when considering applicability and extensibility of
        the application. If most of the AVPs contained in the command are
        indicated as fixed or required, it might be difficult to reuse the
        same command and therefore the same application in a slighly changed
        environment. Defining a command with most of the AVPs indicated as
        optional must not be seen as a sub-optimal design introducing too much
        flexibility in the protocol. The protocol designers are only advised
        to clearly state the condition of presence of these AVPs and properly
        define the corresponding behaviour of the Diameter nodes when these
        AVPs are absent from the command.</t>

        <t>Note: As a hint for protocol designers, it is not sufficient to
        just look at the command's CCF syntax specification. It is also
        necessary to carefully read through the accompanying text in the
        specification.</t>

        <t>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 M-bit cleared (including vendor-specific AVPs) without modifying
        the application. For this purpose, it is strongly recommended to add
        "* [AVP]" in the command's CCF, which allows the addition of any
        arbitrary AVP as described in <xref target="RFC6733"/>.</t>
      </section>

      <section title="Use of Application-Id in a Message">
        <t>When designing new applications, designers should specify that the
        Application Id carried in all session-level messages must be the
        Application Id of the application using those messages. This includes
        the session-level messages defined in Diameter base protocol, i.e.,
        RAR/RAA, STR/STA, ASR/ASA and possibly ACR/ACA in the coupled
        accounting model, see <xref target="other-accounting"/>. Some existing
        specifications do not adhere to this rule for historical reasons.
        However, this guidance should be followed to avoid routing
        problems.</t>

        <t>In general, when a new application has been allocated with a new
        Application Id and it also reuses existing commands with or without
        modifications, it must use the newly allocated Application Id in the
        header and in all relevant Application Id AVPs (Auth-Application-Id or
        Acct-Application-Id) present in the commands message body.</t>

        <t>Additionally, application designs using
        Vendor-Specific-Application-Id AVP should not use the Vendor-Id AVP to
        further dissect or differentiate the vendor-specification Application
        Id. Diameter routing is not based on the Vendor-Id. As such, the
        Vendor-Id should not be used as an additional input for routing or
        delivery of messages. The Vendor-Id AVP is an informational AVP only
        and kept for backward compatibility reasons.</t>
      </section>

      <section title="Application-Specific Session State Machines">
        <t>Section 8 of <xref target="RFC6733"/> provides session state
        machines for authentication, authorization and accounting (AAA)
        services and these session state machines are not intended to cover
        behavior outside of AAA. If a new application cannot clearly be
        categorized into any of these AAA services, it is recommended that the
        application defines its own session state machine. Support for
        server-initiated request is a clear example where an
        application-specific session state machine would be needed, for
        example, the Rw interface for ITU-T push model (cf.<xref
        target="Q.3303.3"/>).</t>
      </section>

      <section title="Session-Id AVP and Session Management">
        <t>Diameter applications are usually designed with the aim of managing
        user sessions (e.g., Diameter network access session (NASREQ)
        application <xref target="RFC4005"/>) or specific service access
        session (e.g., Diameter SIP application <xref target="RFC4740"/>). In
        the Diameter base protocol, session state is referenced using the
        Session-Id AVP. All Diameter messages that use the same Session-Id
        will be bound to the same session. Diameter-based session management
        also implies that both Diameter client and server (and potentially
        proxy agents along the path) maintain session state information.</t>

        <t>However, some applications may not need to rely on the Session-Id
        to identify and manage sessions because other information can be used
        instead to correlate Diameter messages. Indeed, the User-Name AVP or
        any other specific AVP can be present in every Diameter message and
        used therefore for message correlation. Some applications might not
        require the notion of Diameter session concept at all. For such
        applications, the Auth-Session-State AVP is usually set to
        NO_STATE_MAINTAINED in all Diameter messages and these applications
        are therefore designed as a set of stand-alone transactions. Even if
        an explicit access session termination is required,
        application-specific commands are defined and used instead of the
        Session-Termination-Request/Answer (STR/STA) or
        Abort-Session-Request/Answer (ASR/ASA) defined in the Diameter base
        protocol. In such a case, the Session-Id is not significant.</t>

        <t>Based on these considerations, protocol designers should carefully
        appraise whether the application currently defined relies on it's own
        session management concept or whether the Session-Id defined in the
        Diameter base protocol would be used for correlation of messages
        related to the same session. If not, the protocol designers could
        decide to define application commands without the Session-Id AVP. If
        any session management concept is supported by the application, the
        application documentation must clearly specify how the session is
        handled between client and server (as possibly Diameter agents in the
        path).</t>
      </section>

      <section title="Use of Enumerated Type AVPs">
        <t>The type Enumerated was initially defined to provide a list of
        valid values for an AVP with their respective interpretation described
        in the specification. For instance, AVPs of type Enumerated can be
        used to provide further information on the reason for the termination
        of a session or a specific action to perform upon the reception of the
        request.</t>

        <t>However, AVPs of type Enumerated are too often used as a simple
        Boolean flag, indicating for instance a specific permission or
        capability, and therefore only two values are defined, e.g.,
        TRUE/FALSE, AUTORIZED/UNAUTHORIZED or SUPPORTED/UNSUPPORTED. This is a
        sub-optimal design since it limits the extensibility of the
        application: any new capability/permission would have to be supported
        by a new AVP or new Enumerated value of the already defined AVP,
        causing backwards compatibility issues with existing
        implementations.</t>

        <t>Instead of using an Enumerated AVP for a Boolean flag, protocol
        designers are encouraged to use Unsigned32 or Unsigned64 AVP type as
        bit mask whose bit settings are described in the relevant Diameter
        application specification. Such AVPs can be reused and extended
        without major impact on the Diameter application. The bit mask should
        leave room for future additions. Examples of AVPs that use bit masks
        are the Session-Binding AVP defined in <xref target="RFC6733"/> and
        the MIP6-Feature-Vector AVP defined in <xref target="RFC5447"/>.</t>
      </section>

      <section title="Application-Specific Message Routing">
        <t>Diameter request message routing usually relies on the
        Destination-Realm AVP and the Application Id present in the request
        message header. However, some applications may need to rely on the
        User-Name AVP or any other application-specific AVP present in the
        request to determine the final destination of a request, e.g., to find
        the target AAA server hosting the authorization information for a
        given user when multiple AAA servers are addressable in the realm.</t>

        <t>In such a context, basic routing mechanisms described in <xref
        target="RFC6733"/> are not fully suitable, and additional
        application-level routing mechanisms have to be described in the
        application documentation to provide such specific AVP-based routing.
        Such functionality will be basically hosted by an application-specific
        proxy agent that will be responsible for routing decisions based on
        the received specific AVPs.</t>

        <t>Examples of such application-specific routing functions can be
        found in the Cx/Dx applications (<xref target="TS29.228"/> and <xref
        target="TS29.229"/>) of the 3GPP IP Multimedia Subsystem, in which the
        proxy agent (Subscriber Location Function aka SLF) uses specific
        application-level identities found in the request to determine the
        final destination of the message.</t>

        <t>Whatever the criteria used to establish the routing path of the
        request, the routing of the answer has to follow the reverse path of
        the request, as described in <xref target="RFC6733"/>, with the answer
        being sent to the source of the received request, using transaction
        states and hop-by-hop identifier matching. In particular, this ensures
        that the Diameter Relay or Proxy agents in the request routing path
        will be able to release the transaction state upon receipt of the
        corresponding answer, avoiding unnecessary failover. Application
        designers are strongly dissuaded from modifying the answer-routing
        principles described in <xref target="RFC6733"/> when defining a new
        application.</t>
      </section>

      <section title="Translation Agents">
        <t>As defined in <xref target="RFC6733"/>, a translation agent is a
        device that provides interworking between Diameter and another
        protocol (e.g., RADIUS).</t>

        <t>In the case of RADIUS, it was initially thought that defining the
        translation function would be straightforward by adopting few basic
        principles, e.g., by the use of a shared range of code values for
        RADIUS attributes and Diameter AVPs. Guidelines for implementing a
        RADIUS-Diameter translation agent were put into RFC 4005 (<xref
        target="RFC4005"/>).</t>

        <t>However, it was acknowledged that such translation mechanism was
        not so obvious and deeper protocol analysis was required to ensure
        efficient interworking between RADIUS and Diameter. Moreover, the
        interworking requirements depend on the functionalities provided by
        the Diameter application under specification, and a case-by-case
        analysis will be required.</t>

        <t>Therefore, protocol designers cannot assume the availability of a
        "standard" Diameter-to-RADIUS gateways agent when planning to
        interoperate with the RADIUS infrastructure. They should specify the
        required translation mechanism along with the Diameter application, if
        needed. This recommendation applies for any kind of translation.</t>
      </section>

      <section title="End-to-End Application Capabilities Exchange">
        <t>New Diameter applications can rely on optional AVPs to exchange
        application-specific capabilities and features. These AVPs can be
        exchanged on an end-to-end basis at the application layer. Examples of
        this can be found with the MIP6-Feature-Vector AVP in <xref
        target="RFC5447"/> and the QoS-Capability AVP in <xref
        target="RFC5777"/>.</t>

        <t>The end-to-end capabilities AVPs formalize the addition of new
        optional functionality to existing applications by announcing support
        for it. Applications that do not understand these AVPs can discard
        them upon receipt. Receivers of these AVPs can discover the additional
        functionality supported by the end-point originating the request and
        behave accordingly when processing the request. Senders 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 corresponding
        response. This is useful in cases where deployment choices are
        offered, and the generic design can be made available for a number of
        applications.</t>

        <t>When used in a new application, protocol designers should clearly
        specify this end-to-end capabilities exchange and the corresponding
        behaviour of the Diameter nodes supporting the application.</t>

        <t>It is also important to note that this end-to-end capabilities
        exchange relies on the use of optional AVPs is not meant as a generic
        mechanism to support extensibility of Diameter applications with
        arbitrary functionality. When the added features drastically change
        the Diameter application or when Diameter agents have to be upgraded
        to support the new features, a new application should be defined.</t>
      </section>

      <section anchor="other-accounting" title="Diameter Accounting Support">
        <t>Accounting can be treated as an auxiliary application that is used
        in support of other applications. In most cases, accounting support is
        required when defining new applications. This document provides two
        possible models for using accounting:</t>

        <t><list style="hanging">
            <t hangText="Split Accounting Model:"><vspace blankLines="1"/>In
            this model, the accounting messages will use the Diameter base
            accounting Application Id (value of 3). The design implication for
            this is that the accounting is treated as an independent
            application, especially for Diameter routing. This means that
            accounting commands emanating from an application may be routed
            separately from the rest of the other application messages. This
            may also imply that the messages end up in a central accounting
            server. A split accounting model is a good design choice when:
            <vspace blankLines="0"/> <list style="symbols">
                <t>The application itself does not define its own accounting
                commands.<vspace blankLines="0"/></t>

                <t>The overall system architecture permits the use of
                centralized accounting for one or more Diameter
                applications.</t>
              </list> <vspace blankLines="1"/>Centralizing accounting may have
            advantages but there are also drawbacks. The model assumes that
            the accounting server can differentiate received accounting
            messages. Since the received accounting messages can be for any
            application and/or service, the accounting server has to have a
            method to match accounting messages with applications and/or
            services being accounted for. This may mean defining new AVPs,
            checking the presence, absence or contents of existing AVPs, or
            checking the contents of the accounting record itself. But in
            general, there is no clean and generic scheme for sorting these
            messages. Therefore, the use of this model is recommended only
            when all received accounting messages can be clearly identified
            and sorted. For most cases, the use of Coupled Accounting Model is
            recommended. <vspace blankLines="1"/></t>

            <t hangText="Coupled Accounting Model:"><vspace blankLines="1"/>
            In this model, the accounting messages will use the Application Id
            of the application using the accounting service. The design
            implication for this is that the accounting messages are tightly
            coupled with the application itself; meaning that accounting
            messages will be routed like the other application messages. It
            would then be the responsibility of the application server
            (application entity receiving the ACR message) to send the
            accounting records carried by the accounting messages to the
            proper accounting server. The application server is also
            responsible for formulating a proper response (ACA). A coupled
            accounting model is a good design choice when:<vspace
            blankLines="0"/> <list style="symbols">
                <t>The system architecture or deployment does not provide an
                accounting server that supports Diameter. Consequently, the
                application server has to be provisioned to use a different
                protocol to access the accounting server, e.g., via LDAP, SOAP
                etc. This case includes the support of older accounting
                systems that are not Diameter aware.<vspace
                blankLines="0"/></t>

                <t>The system architecture or deployment requires that the
                accounting service for the specific application should be
                handled by the application itself.</t>
              </list> In all cases above, there will generally be no direct
            Diameter access to the accounting server.<vspace
            blankLines="0"/></t>
          </list>These models provide a basis for using accounting messages.
        Application designers may obviously deviate from these models provided
        that the factors being addressed here have also been taken into
        account. Although it is not recommended, an application may define a
        new set of commands to carry application-specific accounting
        records.</t>
      </section>

      <section title="Diameter Security Mechanisms">
        <t>As specified in <xref target="RFC6733"/>, the Diameter message
        exchange should be secured between neighboring Diameter peers using
        TLS/TCP or DTLS/SCTP. However, IPsec can also be deployed to secure
        communication between Diameter peers. When IPsec is used instead of
        TLS or DTLS, the following recommendations apply.</t>

        <t>IPsec ESP <xref target="RFC4301"/> in transport mode with non-null
        encryption and authentication algorithms is used to provide per-packet
        authentication, integrity protection and confidentiality, and support
        the replay protection mechanisms of IPsec. IKEv2 <xref
        target="RFC5996"/> is recommended for performing mutual authentication
        and for establishing and maintaining security associations (SAs).</t>

        <t>IKEv1 <xref target="RFC2409"/> was used with RFC 3588 <xref
        target="RFC3588"/> and for easier migration from IKEv1 based
        implementations both RSA digital signatures and pre-shared keys should
        be supported in IKEv2. However, if IKEv1 is used, implementers should
        follow the guidelines given in Section 13.1 of RFC 3588 <xref
        target="RFC3588"/>.</t>
      </section>
    </section>

    <!-- *************************************************************** -->

    <section anchor="other-generic"
             title="Defining Generic Diameter Extensions">
      <t>Generic Diameter extensions are AVPs, commands or applications that
      are designed to support other Diameter applications. They are auxiliary
      applications meant to improve or enhance the Diameter protocol itself or
      Diameter applications/functionality. Some examples include the
      extensions to support auditing and redundancy (see <xref
      target="I-D.calhoun-diameter-res-mgmt"/>), improvements in duplicate
      detection scheme (see <xref target="I-D.asveren-dime-dupcons"/>), and
      the support for QoS AVPs (see <xref target="RFC5777"/>).</t>

      <t>Since generic extensions may cover many aspects of Diameter and
      Diameter applications, it is not possible to enumerate all scenarios.
      However, some of the most common considerations are as follows:<vspace
      blankLines="0"/> <list style="hanging">
          <t hangText="Backward Compatibility:"><vspace blankLines="1"/>With
          the design of generic extensions an protocol designer has to
          consider with potential concerns about how existing applications
          deal with the new extension they do not understand. Designers also
          have to make sure that new extensions do not break expected message
          delivery layer behavior.<vspace blankLines="0"/></t>

          <t hangText="Forward Compatibility:"><vspace blankLines="1"/>
          Protocol designers need to make sure that their design will not
          introduce undue restrictions for future applications.<vspace
          blankLines="0"/></t>

          <t hangText="Trade-off in Signaling:"><vspace blankLines="1"/>
          Designers may have to choose between the use of optional AVPs
          piggybacked onto existing commands versus defining new commands and
          applications. Optional AVPs are simpler to implement and may not
          need changes to existing applications. However, this ties the
          sending of extension data to the application's transmission of a
          message. This has consequences if the application and the extensions
          have different timing requirements. The use of commands and
          applications solves this issue, but the trade-off is the additional
          complexity of defining and deploying a new application. It is left
          up to the designer to find a good balance among these trade-offs
          based on the requirements of the extension.<vspace
          blankLines="0"/></t>
        </list></t>

      <t>In practice, generic extensions often use optional AVPs because they
      are simple and non-intrusive to the application that would carry them.
      Peers that do not support the generic extensions need not understand nor
      recognize these optional AVPs. However, it is recommended that the
      authors of the extension specify the context or usage of the optional
      AVPs. As an example, in the case that the AVP can be used only by a
      specific set of applications then the specification must enumerate these
      applications and the scenarios when the optional AVPs will be used. In
      the case where the optional AVPs can be carried by any application, it
      is should be sufficient to specify such a use case and perhaps provide
      specific examples of applications using them.</t>

      <t>In most cases, these optional AVPs piggybacked by applications would
      be defined as a Grouped AVP and it would encapsulate all the
      functionality of the generic extension. In practice, it is not uncommon
      that the Grouped AVP will encapsulate an existing AVP that has
      previously been defined as mandatory ('M'-bit set) e.g., 3GPP IMS Cx/Dx
      interfaces (<xref target="TS29.228"/> and <xref
      target="TS29.229"/>).</t>
    </section>

    <section title="Guidelines for Registrations of Diameter Values">
      <t>As summarized in the Section 3 of this document and further described
      in the Section 1.3 of <xref target="RFC6733"/>, there are four main ways
      to extend Diameter. The process for defining new functionality slightly
      varies based on the different extensions. This section provides protocol
      designers with some guidance regarding the definition of values for
      possible Diameter extensions and the necessary interaction with IANA to
      register the new functionality.</t>

      <t><list style="hanging">
          <t hangText="a. Defining new AVP values"><vspace blankLines="1"/>The
          specifications defining AVPs and AVP values provide guidance for
          defining new values and the corresponding policy for adding these
          values. For example, the RFC 5777 <xref target="RFC5777"/> defines
          the Treatment-Action AVP which contains a list of valid values
          corresponding to pre-defined actions (drop, shape, mark, permit).
          This set of values can be extended following the Specification
          Required policy defined in <xref target="RFC5226"/>. As a second
          example, the Diameter base specification <xref target="RFC6733"/>
          defines the Result-Code AVP that contains a 32-bit address space
          used to identity possible errors. According to the Section 11.3.2 of
          <xref target="RFC6733"/>, new values can be assigned by IANA via an
          IETF Review process <xref target="RFC5226"/>.<vspace
          blankLines="0"/></t>

          <t hangText="b. Creating new AVPs"><vspace blankLines="1"/>Two
          different types of AVP Codes namespaces can be used to create a new
          AVPs: <list style="symbols">
              <t>IETF AVP Codes namespace;</t>

              <t>Vendor-specific AVP Codes namespace.</t>
            </list>In the latter case, a vendor needs to be first assigned by
          IANA with a private enterprise number, which can be used within the
          Vendor-Id field of the vendor-specific AVP. This enterprise number
          delimits a private namespace in which the vendor is responsible for
          vendor-specific AVP code value assignment. The absence of a
          Vendor-Id or a Vendor-Id value of zero (0) in the AVP header
          identifies standard AVPs from the IETF AVP Codes namespace managed
          by IANA. The allocation of code values from the IANA-managed
          namespace is conditioned by an Expert Review of the specification
          defining the AVPs or an IETF review if a block of AVPs needs to be
          assigned. Moreover, the remaining bits of the AVP Flags field of the
          AVP header can be also assigned via Standard Action if the creation
          of new AVP Flags is desired.<vspace blankLines="0"/></t>

          <t hangText="c. Creating new commands"><vspace
          blankLines="1"/>Unlike the AVP Code namespace, the Command Code
          namespace is flat but the range of values is subdivided into three
          chunks with distinct IANA registration policies: <list
              style="symbols">
              <t>A range of standard Command Code values that can be allocated
              via IETF review;</t>

              <t>A range of vendor-specific Command Code values that can be
              allocated on a First-Come/First-Served basis;</t>

              <t>A range of values reserved only for experimental and testing
              purposes.</t>
            </list>As for AVP Flags, the remaining bits of the Command Flags
          field of the Diameter header can also be assigned via a Standards
          Action to create new Command Flags if required.<vspace
          blankLines="0"/></t>

          <t hangText="d. Creating new applications"><vspace
          blankLines="1"/>Similarly to the Command Code namespace, the
          Application-Id namespace is flat but divided into two distinct
          ranges:<list style="symbols">
              <t>A range of values reserved for standard Application-Ids
              allocated after Expert Review of the specification defining the
              standard application;</t>

              <t>A range for values for vendor specific applications,
              allocated by IANA on a First-Come/First-Serve basis.</t>
            </list></t>
        </list>The IANA AAA parameters page can be found at
      http://www.iana.org/assignments/aaa-parameters/aaa-parameters.xml and
      the enterprise number IANA page is available at
      http://www.iana.org/assignments/enterprise-numbers. More details on the
      policies followed by IANA for namespace management (e.g.
      First-Come/First-Served, Expert Review, IETF Review, etc.) can be found
      in <xref target="RFC5226"/>.</t>

      <t><list style="hanging">
          <t hangText="NOTE:"><vspace blankLines="0"/>When the same
          functionality/extension is used by more than one vendor, it is
          recommended to define a standard extension. Moreover, the
          registration of vendor-specific extension is encouraged to avoid
          interoperability issues in the same network. With this aim, the
          registration policy of vendor-specific extension has been simplified
          with the publication of <xref target="RFC6733"/> and the namespace
          reserved for vendor-specific extensions is large enough to avoid
          exhaustion.</t>
        </list></t>
    </section>

    <!-- *************************************************************** -->

    <section title="IANA Considerations">
      <t>This document does not require actions by IANA.</t>
    </section>

    <!-- *************************************************************** -->

    <section title="Security Considerations">
      <t>This document provides guidelines and considerations for extending
      Diameter and Diameter applications. Although such an extension may
      related to a security functionality, the document does not explicitly
      give guidance on enhancing Diameter with respect to security.</t>
    </section>

    <!-- *************************************************************** -->

    <section title="Contributors">
      <t>The content of this document was influenced by a design team created
      to revisit the Diameter extensibility rules. The team consisting of the
      members listed below was formed in February 2008 and finished its work
      in June 2008. <vspace blankLines="0"/> <list style="symbols">
          <t>Avi Lior</t>

          <t>Glen Zorn</t>

          <t>Jari Arkko</t>

          <t>Lionel Morand</t>

          <t>Mark Jones</t>

          <t>Victor Fajardo</t>

          <t>Tolga Asveren</t>

          <t>Jouni Korhonen</t>

          <t>Glenn McGregor</t>

          <t>Hannes Tschofenig</t>

          <t>Dave Frascone</t>
        </list></t>

      <t>We would like to thank Tolga Asveren, Glenn McGregor, and John
      Loughney for their contributions as co-authors to earlier versions of
      this document.</t>
    </section>

    <!-- *************************************************************** -->

    <section anchor="acks" title="Acknowledgments">
      <t>We greatly appreciate the insight provided by Diameter implementers
      who have highlighted the issues and concerns being addressed by this
      document. The authors would also like to thank Jean Mahoney and Ben
      Campbell for their invaluable detailed review and comments on this
      document.</t>
    </section>
  </middle>

  <back>
    <!-- <references title="Normative References">
    </references>
-->

    <references title="Informative References">
      <?rfc include="reference.RFC.3588.xml"?>

      <?rfc include="reference.RFC.6733.xml"?>

      <?rfc include="reference.RFC.4072.xml"?>

      <?rfc include="reference.RFC.4005.xml"?>

      <?rfc include="reference.RFC.4740.xml"?>

      <?rfc include="reference.RFC.4301.xml"?>

      <?rfc include="reference.RFC.5447.xml"?>

      <?rfc include="reference.RFC.2407.xml"?>

      <?rfc include="reference.RFC.2409.xml"?>

      <?rfc include="reference.RFC.5996.xml"?>

      <?rfc include="reference.RFC.5226.xml"?>

      <?rfc include="reference.RFC.5777.xml"?>

      <?rfc include="reference.I-D.asveren-dime-dupcons.xml"?>

      <reference anchor="I-D.calhoun-diameter-res-mgmt">
        <front>
          <title>Diameter Resource Management Extensions</title>

          <author fullname="Pat Calhoun" initials="P." surname="Calhoun">
            <organization/>
          </author>

          <date month="March" year="2001"/>
        </front>

        <seriesInfo name="Internet-Draft"
                    value="draft-calhoun-diameter-res-mgmt-08.txt"/>

        <format target="http://tools.ietf.org/id/draft-calhoun-diameter-res-mgmt-08.txt"
                type="TXT"/>
      </reference>

      <reference anchor="TS29.228"
                 target="http://www.3gpp.org/ftp/Specs/html-info/29272.htm">
        <front>
          <title>3GPP TS 29.228; Technical Specification Group Core Network
          and Terminals; IP Multimedia (IM) Subsystem Cx and Dx Interfaces;
          Signalling flows and message contents</title>

          <author>
            <organization abbrev="3GPP">3rd Generation Partnership
            Project</organization>
          </author>

          <date/>
        </front>
      </reference>

      <reference anchor="TS29.229"
                 target="http://www.3gpp.org/ftp/Specs/html-info/29229.htm">
        <front>
          <title>3GPP TS 29.229; Technical Specification Group Core Network
          and Terminals; Cx and Dx interfaces based on the Diameter protocol;
          Protocol details</title>

          <author>
            <organization abbrev="3GPP">3rd Generation Partnership
            Project</organization>
          </author>

          <date/>
        </front>
      </reference>

      <reference anchor="TS29.328"
                 target="http://www.3gpp.org/ftp/Specs/html-info/29328.htm">
        <front>
          <title>3GPP TS 29.328; Technical Specification Group Core Network
          and Terminals; IP Multimedia (IM) Subsystem Sh interface; signalling
          flows and message content</title>

          <author>
            <organization abbrev="3GPP">3rd Generation Partnership
            Project</organization>
          </author>

          <date/>
        </front>
      </reference>

      <reference anchor="TS29.329"
                 target="http://www.3gpp.org/ftp/Specs/html-info/29329.htm">
        <front>
          <title>3GPP TS 29.329; Technical Specification Group Core Network
          and Terminals; Sh Interface based on the Diameter protocol; Protocol
          details</title>

          <author>
            <organization abbrev="3GPP">3rd Generation Partnership
            Project</organization>
          </author>

          <date/>
        </front>
      </reference>

      <reference anchor="Q.3303.3" target="">
        <front>
          <title>ITU-T Recommendation Q.3303.3, "Resource control protocol no.
          3 (rcp3): Protocol at the Rw interface between the Policy Decision
          Physical Entity (PD-PE) and the Policy Enforcement Physical Entity
          (PE-PE): Diameter"</title>

          <author>
            <organization abbrev="3GPP">3rd Generation Partnership
            Project</organization>
          </author>

          <date year="2008"/>
        </front>
      </reference>
    </references>
  </back>
</rfc>
