INTERNET DRAFT Pat R. Calhoun Category: Standards Track Sun Laboratories, Inc. Title: draft-calhoun-diameter-10.txt Allan C. Rubens Date: October 1999 Tut Systems, Inc. Haseeb Akhtar Nortel Networks DIAMETER Base Protocol Status of this Memo This document is an individual contribution for consideration by the AAA Working Group of the Internet Engineering Task Force. Comments should be submitted to the diameter@ipass.com mailing list. Distribution of this memo is unlimited. This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at: http://www.ietf.org/ietf/1id-abstracts.txt The list of Internet-Draft Shadow Directories can be accessed at: http://www.ietf.org/shadow.html. Abstract The DIAMETER base protocol is intended to provide a framework for access technology services that require AAA support. The protocol is intended to be flexible enough to allow services to add building blocks (or extensions) to DIAMETER in order to meet their requirements. Calhoun, Rubens, Akhtar expires April 2000 [Page 1] INTERNET DRAFT October 1999 This draft specifies the message format and transport to be used by all DIAMETER extensions and MUST be supported by all DIAMETER implementations. Calhoun, Rubens, Akhtar expires April 2000 [Page 2] INTERNET DRAFT October 1999 Table of Contents 1.0 Introduction 1.1 Copyright Statement 1.2 Requirements language 1.3 Terminology 2.0 Protocol Overview 2.1 Header Format 2.1.1 ZLB Message Format 2.2 AVP Format 2.2.1 AVP Header 2.2.2 Optional Header Elements 2.2.3 AVP Value Formats 2.3 Error Reporting 3.0 Reliable Transport 3.1 Flow Control 3.2 Peer failure recovery 4.0 DIAMETER AVPs 4.1 DIAMETER-Command AVP 4.1.1 Message-Reject-Ind 4.1.2 Device-Reboot-Ind 4.1.3 Device-Watchdog-Ind 4.2 Host-IP-Address 4.3 Host-Name 4.4 State 4.5 Class 4.6 Session-Timeout 4.7 Extension-Id 4.8 Integrity-Check-Value 4.9 Nonce 4.10 Timestamp 4.11 Session-Id 4.12 Vendor-Name 4.13 Firmware-Revision 4.14 Result-Code 4.15 Error-Code 4.16 Unrecognized-Command-Code 4.17 Reboot-Type 4.18 Reboot-Time 4.19 Failed-AVP-Code 4.20 User-Name 4.21 Receive-Window 4.22 Proxy-State 4.23 Redirected-Host 4.24 Broker-Issued-Certificate 5.0 Protocol Definition 5.1 Session Identifiers 5.2 DIAMETER Bootstrap Message Calhoun, Rubens, Akhtar expires April 2000 [Page 3] INTERNET DRAFT October 1999 5.2.1 State Machine 5.3 Keepalive Exchange 5.4 AVP Handling Rules 5.4.1 Unrecognized Command Support 5.4.2 The art of AVP Tagging 5.5 DIAMETER Message Security 5.5.1 Using the Integrity-Check-Value 5.5.2 AVP Encryption with Shared Secrets 5.6 DIAMETER Message Routing 5.6.1 DIAMETER Proxying 5.6.2 Message Redirection 6.0 IANA Considerations 6.1 AVP Attributes 6.2 Command Code AVP Values 6.3 Extension Identifier Values 6.4 Result Code AVP Values 6.5 Integrity Check Value Transform Values 6.7 AVP Header Bits 6.6 Reboot Type Values 7.0 Open Issues 8.0 DIAMETER protocol related configurable parameters 9.0 Security Considerations 10.0 References 11.0 Acknowledgements 12.0 Author's Address 13.0 Full Copyright Statement Appendix A: Acknowledgment Timeouts A.1 Calculating Adaptive Acknowledgment Timeout A.2 Flow Control: Adjusting for Timeout Appendix B: Examples of sequence numbering B.1 Lock-step tunnel establishment B.2 Multiple messages acknowledged B.3 Lost message with retransmission Appendix C: Backward Compatibility with RADIUS Appendix D: Delayed Acknowledgement Optimization Appendix E: Device-Reboot-Ind Message Flow Appendix F: Device-Watchdog-Ind Message Flow Appendix G: Message-Reject-Ind Message Flow Calhoun, Rubens, Akhtar expires April 2000 [Page 4] INTERNET DRAFT October 1999 1.0 Introduction The DIAMETER is a peer to peer protocol that provides Authentication, Authorization and Accounting (AAA) services for access technologies, such as PPP dial-in, Mobile IP, etc. This document describes the base DIAMETER protocol, which is used as the transport for all DIAMETER extensions. This document in itself is not complete and MUST be used with an accompanying applicability extension document. An example of such a document would be [7] that defines extensions to the base protocol to support Dial-in PPP user authentication and [15], which defines extensions to support accounting. The DIAMETER protocol is recognized as a peer to peer protocol since any node can initiate a request. However, a client is the device that normally initiates a request for authentication and/or authorization of a user. A server is the device that performs the actual authentication and/or authorization of the user based on some profile. A server can issue a request to a client, but this is typically not a request for authentication and/or authorization, but rather a different request, such as a request for an accounting update. 1.1 Copyright Statement Copyright (C) The Internet Society 1999. All Rights Reserved. 1.2 Requirements language In this document, the key words "MAY", "MUST, "MUST NOT", "optional", "recommended", "SHOULD", and "SHOULD NOT", are to be interpreted as described in [13]. 1.3 Terminology Refer to [9] for terminology used in this document. 2.0 Protocol Overview The DIAMETER protocol allows peers to exchange a variety of messages. The base protocol provides the following facilities: Calhoun, Rubens, Akhtar expires April 2000 [Page 5] INTERNET DRAFT October 1999 - Sequenced in-order reliable delivery of UDP datagram messages - Support for congestion control (receiver window) - Timely detection of failed or unresponsive peers - Delivery of AVPs (attribute value pairs) - Extensibility, through addition of new commands and AVPs All data delivered by the is protocol in the form of an AVP. Some of these AVP values are used by the DIAMETER protocol itself, while others deliver data associated with particular applications which employ DIAMETER. AVPs may be added arbitrarily to DIAMETER messages, so long as the required AVPs are included and AVPs which are explicitly excluded are not included. AVPs are used by base DIAMETER protocol to support the following required features: - All messages carry either an Integrity Check Vector (ICV) or a digital signature[11]. They also carry a timestamp and a nonce to aid in providing replay protection. - To carry user authentication information, for the purposes of enabling the DIAMETER server to authenticate the user. - To allow authorization information to be exchanged for a particular user's session between a DIAMETER client and server. - To exchange resource usage information, which can be used for accounting purposes, capacity planning, etc. The DIAMETER base protocol provides the minimum requirements needed for an AAA transport protocol. The base protocol is not intended to be used by itself, and must be used with an application-specific extension, such as Mobile IP. The DIAMETER protocol was heavily inspired and builds upon the tradition of the RADIUS [1] protocol. 2.1 Header Format The base DIAMETER protocol is run over UDP port 1812. Implementations MAY send packets from any source port, but SHOULD be prepared to receive packets on port 1812. When a request is received, in order to send a reply, the source and destination ports in the reply are reversed. A summary of the DIAMETER data format is shown below. The fields are transmitted from left to right. Calhoun, Rubens, Akhtar expires April 2000 [Page 6] INTERNET DRAFT October 1999 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | RADIUS PCC |Flags|A|W| Ver | Message Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Identifier | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Next Send (Ns) | Next Received (Nr) | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | AVPs ... +-+-+-+-+-+-+-+-+-+-+-+-+- RADIUS PCC (Packet Compatibility Code) The RADIUS PCC field is a one octet field which is used for backward compatibility with RADIUS. In order to easily distinguish DIAMETER messages from RADIUS a special value has been reserved and allows an implementation to support both protocols concurrently using the first octet in the header. The RADIUS PCC field MUST be set as follows: 254 DIAMETER message PKT Flags The Message Flags field is five bits, and is used in order to identify any options. This field MUST be initialized to zero. The following flag may be set: The 'W' bit (Window-Present) is set when the Next Send (Ns) and Next Received (Nr) fields are present in the header. Should DIAMETER be implemented over a reliable transport, the 'W' should not be set. The 'A' bit is set to indicate that the message is an acknowledgement only and does not contain a Command-Code AVP following the header. Note that the Security AVPs MUST still be present within an acknowledgment message. Version This field MUST be set to 1 to indicate DIAMETER Version 1. Message Length The Message Length field is two octets. It indicates the length of the DIAMETER message including the header fields. Identifier The Identifier field is four octets, and aids in matching requests and replies. The sender MUST ensure that the identifier in a message is locally unique (to the sender) at any given time, and Calhoun, Rubens, Akhtar expires April 2000 [Page 7] INTERNET DRAFT October 1999 MAY attempt to ensure that the number is unique across reboots. The identifier is normally a monotonically increasing number, whose start value was randomly generated. DIAMETER servers should consider a message to be unique by examining the source address, source port and Identifier field of the message. Next Send This field is present when the Window-Present bit is set in the header flags. The Next Send (Ns) is copied from the send sequence number state variable, Ss, at the time the message is transmitted. Ss is incremented after copying if the message is not a ZLB ACK. Next Received This field is present when the Window-Present bit is set in the header flags. Nr is copied from the receive sequence number state variable, Sr, and indicates the sequence number, Ns, +1 of the highest (modulo 2^16) in-sequence message received. See section 3.0 for more information. AVPs AVPs is a method of encapsulating information relevant to the DIAMETER message. See section 2.2 for more information on AVPs. 2.1.1 ZLB Message Format Zero Length Body messages are used to explicitly acknowledge one or more DIAMETER message, and contain no additional Authentication, Authorization or Accounting related AVPs. ZLB messages must contain authentication AVPs, otherwise attacks could be mounted against DIAMETER nodes. The format of a ZLB message will be as follows: ::= { || [11] } 2.2 AVP Format DIAMETER AVPs carry specific authentication, accounting and authorization information as well as configuration details for the request and reply. Some AVPs MAY be listed more than once. The effect of this is AVP Calhoun, Rubens, Akhtar expires April 2000 [Page 8] INTERNET DRAFT October 1999 specific, and is specified in each case by the AVP description. Each AVP of type 'string' and 'data' MUST be padded to align on a 32 byte boundary. Zero bytes are added to the end of the AVP value till a word boundary is reached. 2.2.1 AVP Header The AVP format is shown below and MUST be sent in network byte order. 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | AVP Code | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | AVP Length | Cmd Flags | Reserved |T|V|H|M| +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Vendor ID (opt) | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Tag (opt) | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Data ... +-+-+-+-+-+-+-+-+ AVP Code The AVP Code identifies the attribute uniquely. If the Vendor- Specific-AVP is set, the AVP Code is allocated from the vendor's private address space. The first 256 AVP numbers are reserved for backward compatibility with RADIUS and are to be interpreted as per RADIUS [1]. AVP numbers 256 and above are used for DIAMETER, which are allocated by IANA (see section 6.0). AVP Length The AVP Length field is two octets, and indicates the length of this Attribute including the AVP Code, AVP Length, AVP Flags, Reserved, the Tag and Vendor ID fields if present and the AVP data. If a message is received with an Invalid attribute length, the message SHOULD be rejected. Command Flags The Command Flag field is a bit-field that can be used by individual command codes. Any Command Code that makes use of these bits MUST define their value, and how they are used. Note that only AVPs with the AVP Code set to Command-Code may use these bits, otherwise the bits MUST be set to zero (0). Calhoun, Rubens, Akhtar expires April 2000 [Page 9] INTERNET DRAFT October 1999 AVP Flags The AVP Flags field informs the DIAMETER host how each attribute must be handled. Note that subsequent DIAMETER extensions MAY define bits to be used within the AVP Header, and an unrecognized bit should be considered an error. Reserved bits should be set to 0 and ignored on receipt. The 'M' Bit, known as the Mandatory bit, indicates whether support of the AVP is required. If an AVP is received with the 'M' bit enabled and the receiver does not support the AVP, the message MUST be rejected. AVPs without the 'M' bit enabled are informational only and a receiver that receives a message with such an AVP that is not supported MAY simply ignore the AVP. When the 'H' bit is enabled it indicates that the AVP data is encrypted using hop-by-hop encryption. See section 4.5 for more information. The 'V' bit, known as the Vendor-Specific bit, indicates whether the optional Vendor ID field is present in the AVP header. When set the AVP Code belongs to the specific vendor code address space. The 'T' bit, known as the Tag bit, is used to group sets of AVPs together. Grouping of AVPs is necessary when more than one AVP is needed to express a condition. If this bit is set, the optional Tag field will be present. Unless otherwise noted, AVPs will have the following default AVP Flags field settings: The 'M' bit MUST be set. The 'V' bit MUST NOT be set. The 'H' and 'T' bits MAY be set. 2.2.2 Optional Header Elements The AVP Header consists of several optional fields. These fields are only present if their respective bit-flags are enabled. Vendor ID The Vendor Id field is present in the 'V' bit is set in the AVP Flags field. The optional four octet Vendor ID field contains the IANA assigned "SMI Network Management Private Enterprise Codes" [2] value, encoded in network byte order. Any vendor wishing to implement DIAMETER extensions can use their own Vendor ID along with private Attribute values, guaranteeing that they will not Calhoun, Rubens, Akhtar expires April 2000 [Page 10] INTERNET DRAFT October 1999 collide with any other vendor's extensions, nor with future IETF extensions. A vendor id value of zero (0) corresponds to the IETF adopted AVP values, as managed by the IANA. Since the absence of the vendor id field implies that the AVP in question is not vendor specific, implementations SHOULD not use the zero (0) vendor id. Tag The Tag field is four octet in length and is intended to provide a means of grouping attributes in the same message which refer to the same set. If the Tag field is unused, the 'T' bit MUST NOT be set. 2.2.3 AVP Value Formats The Data field is zero or more octets and contains information specific to the Attribute. The format and length of the Data field is determined by the AVP Code and AVP Length fields. Note that messages which are larger than the path MTU will cause IP fragmentation and messages SHOULD be kept to that size wherever possible. In any case UDP limits messages to 2^16 bytes. The format of the value field MAY be one of six data types. It is possible for an attribute to have a structure and this MUST be defined along with the attribute. Data The data contains a variable length of arbitrary data. Unless otherwise noted, the AVP Length field MUST be set to at least 9. String The data contains a variable length string using the UTF-8 character set. Unless otherwise noted, the AVP Length field MUST be set to at least 9. Address 32 bit (IPv4) [17] or 128 bit (IPv6) [16] address, most significant octet first. The format of the address (IPv4 or IPv6) is determined by the length. If the attribute value is an IPv4 address, the AVP Length field MUST be 12, otherwise the AVP Length field MUST be set to 24 for IPv6 addresses. Integer32 32 bit value, most significant octet first. The AVP Length field MUST be set to 12. Calhoun, Rubens, Akhtar expires April 2000 [Page 11] INTERNET DRAFT October 1999 Integer64 64 bit value, most significant octet first. The AVP Length field MUST be set to 16. Time 32 bit unsigned value, most significant octet first -- seconds since 00:00:00 GMT, January 1, 1900. The AVP Length field MUST be set to 12. 2.3 Error Reporting There are five different types of errors within DIAMETER. The first being where a DIAMETER message is poorly formatted and unrecognizable, indicated below by "Bad Message". This error condition applies if a received message creates a fatal error (e.g. fails transport level authentication, cannot be parsed, etc). The second case involves receiving a DIAMETER-Command AVP that is not supported, which is shown below by "Unknown Command". The third case is where an AVP is received, marked mandatory and is unknown by the receiver, which is labeled below as "Unknown AVP". This fourth case involves receiving a message with a known AVP, yet the value is either unknown or illegal, which is shown below as "Bad Value". The last case occurs when an error occurs while processing a specific extension command, which is not related to the message format and is labeled "Extension Error" below. Error Type Ignore Message Send Extension Message-Reject-Ind Response + Result-Code Bad Message X Unknown Command X Unknown AVP X Bad Value X Extension Error X "Ignore Message" indicates that the message is simply dropped. The "Message-Reject-Ind" indicates that a Message-Reject-Ind message MUST be sent to the peer as described in the appropriate section. The "Extension Response + Result-Code" indicates that the appropriate Response to the message MUST be sent with the Result-Code or Error- Code AVP set to a value that enables the peer to understand the nature of the problem. 3.0 Reliable Transport Calhoun, Rubens, Akhtar expires April 2000 [Page 12] INTERNET DRAFT October 1999 This section provides a detailed overview of how DIAMETER is reliably transported over UDP. DIAMETER provides its own reliable transport due to its unique requirements, which include: -Rapid discovery of the failure of a communicating peer. -Transactions of few messages will be the norm, so the TCP slow start algorithm is in appropriate. -The retransmission scheme required is more agressive than TCP provides. 3.1 Flow Control ZLB messages are used to acknowledge DIAMETER messages to the communicating peer. The DIAMETER header contains two fields used for reliable transport: Nr (Next Received) and Ns (Next Send). The sequence number state for each peer is represented (for clarity of discussion) as Sr (the next in-sequence message expected to be received) and Ss (the next in- sequence message to be sent). Sr and Ss are initialized to 0. The sequence number is a free ranging counter modulo 65536. For purposes of detecting duplication, a received sequence value is considered less than or equal to the last received value if its value lies in the range of the last value and its 32767 successor values. For example if the last received sequence number was 15, the packets received with Ns values in the range 32783..65535, or 0..15 would be considered duplicates. Duplicate messages are silently discarded. Each subsequent non-ZLB message is sent with a sequence number incremented by one (modulo 2^16). The following rules apply: - When a non-ZLB message is received with a Ns value which matches the peer's Sr value, Sr is incremented by one. Sr is not modified if a message is received with a Ns value greater than the current Sr value. - In messages which are sent to a peer, Nr is set to reflect one higher than the Ns value of the highest (module 2^16) in-order message received from the peer. - Every time a peer sends a non-ZLB message, it sends the message with Ns set to the current value of Ss. The value of Ss for that peer is then incremented by one (modulo 2^16). - Every time a peer receives an in-order non-ZLB message, the receiving peer must increment its Sr value. The peer MUST acknowledge the message, either by sending a ZLB message with the Calhoun, Rubens, Akhtar expires April 2000 [Page 13] INTERNET DRAFT October 1999 updated Nr value, or by piggybacking the acknowledgement in any outgoing message sent to the communicating peer. In this piggybacked message, the Nr field will be set to its updated value. Appendix D defines an OPTIONAL algorithm for delaying acknowledgments, to wait for outgoing messages to piggyback acknowledgements on. - Messages which are sent MUST be queued and retransmitted till the peer sends an acknowlegment. Messages SHOULD be retransmitted at least three times. Appendix A recommends a retransmission timer algorithm. Retransmitted messages SHOULD include the current value of Sr in the Nr field. An implementation MAY choose not to update Nr field (and Timestamp AVP) for retransmitted messages, in order to avoid having to perform another hash in the Integrity-Check- Vector AVP. The message identifier in the retransmitted message MUST NOT be changed. A DIAMETER implementation MAY queue out of order DIAMETER messages for subsequent processing. The receive window is the number of unacknowledged packets which can be outstanding to a DIAMETER peer. When transmitting packets, a DIAMETER peer must obey the receive window size offered by its peer. The default window size is 7. Once the number of unacknowledged messages equals the window size, the window is 'closed.' Previously transmitted packets may be retransmitted when the peer's window is closed. A peer can explicitly specify its window size in the Device-Reboot-Ind message in the Receive-Window AVP. A peer MAY return a Nr value in a ZLB or piggybacked in a non-ZLB message which is less than the latest Sr value, due to congestion. Returning a value in Nr of the first value in the window will have the effect of preventing the communicating peer from sending any new messages. See Appendix B for some examples of how sequence numbers progress. 3.2 Peer failure recovery A DIAMETER message with the Command-Code AVP set to Device-Reboot-Ind and the Ns and Nr values set to zero (0) indicates that the peer has rebooted. This message MUST be recognized and supported by a DIAMETER implementation. When this event occurs, the Ss and Sr values must be reset and the retransmission queue MUST be cleared. Since the protocol requires that all new messages include a random identifier in the protocol header, a Device-Reboot-Ind that is received with the Calhoun, Rubens, Akhtar expires April 2000 [Page 14] INTERNET DRAFT October 1999 same identifier as the last processed Device-Reboot-Ind is considered a retransmission and SHOULD NOT change the peer's state to inactive. Messages other than the Device-Reboot-Ind MUST NOT be sent to the peer until both the acknowledgement for the transmitted Device- Reboot-Ind AND the peer's Device-Reboot-Ind have been received. When both of these have been received, the peer is considered to be in the active state. 4.0 DIAMETER AVPs This section will define the mandatory AVPs that MUST be supported by all DIAMETER implementations. The following AVPs are defined in this document: Attribute Name Attribute Code Definition in Section ------------------------------------------------------------ DIAMETER-Command 256 4.1 Host-IP-Address 4 [1], 4.2 Host-Name 32 [1], 4.3 State 24 [1], 4.4 Class 25 [1], 4.5 Session-Timeout 27 [1], 4.6 Extension-Id 258 4.7 Integrity-Check-Value 259 4.8 Nonce 261 4.9 Timestamp 262 4.10 Session-Id 263 4.11 Vendor-Name 266 4.12 Firmware-Revision 267 4.13 Result-Code 268 4.14 Error-Code 269 4.15 Unrecognized-Command-Code 270 4.16 Reboot-Type 271 4.17 Reboot-Time 272 4.18 Failed-AVP-Code 279 4.19 User-Name 1 [1], 4.20 Receive-Window 277 4.21 Proxy-State 33 [1], 4.22 Redirect-Host 278 4.23 Broker-Issued-Certificate 280 4.24 4.1 DIAMETER-Command AVP Description Calhoun, Rubens, Akhtar expires April 2000 [Page 15] INTERNET DRAFT October 1999 The DIAMETER-Command AVP MUST be the first AVP following the DIAMETER header. This AVP is used in order to communicate the command associated with the message. A DIAMETER message can have at most one DIAMETER-Command AVP. Unless noted otherwise, all command codes defined in this document will use the following format: 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ AVP Header (AVP Code = 256) +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Command Code | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ AVP Length The length of this attribute MUST be at least 12. The exact length of the AVP is determined by the actual Command and is defined with each command. AVP Flags The 'M' bit MUST be set. The 'V' MAY be set if the Command Code is vendor specific. The 'H', 'T' bits MUST NOT be set. Command Code The Command Code field contains the command number. The following commands are defined and MUST be supported by all DIAMETER implementations in order to conform to the base protocol specification: Command Name Command Code ----------------------------------- Message-Reject-Ind 256 Device-Reboot-Ind 257 Device-Watchdog-Ind 258 4.1.1 Message-Reject-Ind (MRI) Description The Message-Reject-Ind command provides a generic means of completing transactions by indicating errors in the messages which initiated them. The Message-Reject-Ind command is a possible response to any DIAMETER command. Some some DIAMETER commands MAY expect more specialized error messages, depending on the error type. Calhoun, Rubens, Akhtar expires April 2000 [Page 16] INTERNET DRAFT October 1999 The Message-Reject-Ind message MUST contain the same identification in the header and include the Session-Id if it was present in the original message that it is responding to, even if the identification is erroneous. The receiver of a Message- Reject-Ind SHOULD examine the Result-Code AVP provided before processing the identification, in order to handle the latter appropriately. Message Format The structure of the Message-Reject message is defined as follows: ::= [] [] [ ] { || } { || [11]} where the Identifier value in the message header and optionally the Session-Id AVP are copied from the message being rejected and the DIAMETER-Command AVP has the format described below. The Result-Code and conditionally-present Error-Code AVPs indicate the nature of the error causing rejection, and the conditionally- present Failed-AVP-Code AVP provides some minimal debugging data by indicating a specific AVP type which caused the problem. See the description of the Result-Code AVP for indication of when the Error-Code and/or Failed-AVP-Code AVPs will be present in the message. The Unrecognized-Command-Code AVP is present only when the reason for message rejection is an unrecognized or unsupported command code. The length of the DIAMETER Command AVP must be 12 when the Command Code is set to 256 (Message-Reject-Ind). 4.1.2 Device-Reboot-Ind (DRI) Description A DIAMETER device sends the Device-Reboot-Ind message to inform Calhoun, Rubens, Akhtar expires April 2000 [Page 17] INTERNET DRAFT October 1999 all of its peers either of an upcoming reboot or that it has just rebooted. The Reboot-Type AVP MUST be present and indicates the type of reboot associated with this command. Note that a DIAMETER device should only send this message once it is able to receive network traffic. This message is also used by a DIAMETER device in order to exchange the supported protocol version number as well as all supported extensions. The originator of this message SHOULD insert it's highest supported version number within the DIAMETER header. Similarly the originator of this message MUST include all supported extensions within the message. It is desirable for a DIAMETER device to retain the supported extensions in order to ensure that only requests/responses are sent to peers that support the extension in question. This message MUST contain the Vendor-Name and Extension-Id AVPs. In the case where a DIAMETER device is configured to communicate with many peers, this message MUST be issued to each peer. The DRI SHOULD be periodically retransmitted until an acknowledgement is received. This retransmission timer MAY be different from the timer used when the communication has been established, and SHOULD be configurable. No explicit DIAMETER message is necessary to acknowledge this message since it is handled by DIAMETER's reliable transport. Message Format ::= [] [] [] [] { || [11]} Calhoun, Rubens, Akhtar expires April 2000 [Page 18] INTERNET DRAFT October 1999 The length of the DIAMETER Command AVP must be 12 when the Command Code is set to 257 (Device-Reboot-Ind). 4.1.3 Device-Watchdog-Ind (DWI) Description The Device-Watchdog-Ind is used as a keepalive mechanism between two DIAMETER peers, and SHOULD be sent during after a configurable period of inactivity. The lower the timer value is set to, the quicker a host can pro-actively detect that a peer is no longer reachable. However, the timer SHOULD NOT be set to a value that is considered too low (e.g. 2 seconds), since it will generate considerable traffic. This message MUST contain the Host-IP- Address or Host-Name AVP as well as any security related AVPs. No explicit DIAMETER message is necessary to acknowledge this message since it is handled by DIAMETER's reliable transport. Message Format ::= { || } { || [11]} The length of the Command Code AVP MUST be 12 when the Command Code field is set to 258 (Device-Watchdog-Ind). 4.2 Host-IP-Address The Host-IP-Address AVP (AVP Code 4) is of type Address and is used to inform a DIAMETER peer of the sender's identity. The data portion of this AVP contains the IP address of the originator of the DIAMETER message. The AVP flags for this AVP are different from the default value, and have the following rules: The 'M' bit MUST be set. The 'H' SHOULD NOT be set since implementations could use this information to determine the shared secret information necessary to authenticate the message. The 'T' and 'V' bits MUST NOT be set. Calhoun, Rubens, Akhtar expires April 2000 [Page 19] INTERNET DRAFT October 1999 4.3 Host-Name The Host-Name AVP (AVP Code 32) is of type String, and is used to inform a DIAMETER peer of the sender's identity. The data portion of this AVP contains the host name of the originator of the DIAMETER message. The host name MUST follow the NAI [8] naming conventions. The AVP flags for this AVP are different from the default value, and have the following rules: The 'M' bit MUST be set. The 'H' SHOULD NOT be set since implementations could use this information to determine the shared secret information necessary to authenticate the message. The 'T' and 'V' bits MUST NOT be set. 4.4 State The State AVP (AVP Code 24) is sent by the server to the client when the DIAMETER exchange can span multiple round-trip messages and is used to maintain server state information. The opaque data MUST be sent unmodified by the client to the server in subsequent messages for the same Session-Id. The data portion of the AVP is of type Data and the format of the information is site or application specific, and SHOULD be treated as opaque octets. 4.5 Class The server sends the Class AVP (AVP Code 25) to the client during authentication or authorization and MUST be sent unmodified by the client to the accounting server as part of the accounting message if accounting is supported. No interpretation of the opaque data should be made by the client. The data portion of the AVP is of type Data and the format of the information is site or application specific, and SHOULD be treated as opaque octets. 4.6 Session-Timeout The Session-Timeout AVP (AVP Code 27) is of type Integer32 and contains the maximum number of seconds of service to be provided to the user before termination of the session. A value of zero means that this session has an unlimited number of seconds before termination. Calhoun, Rubens, Akhtar expires April 2000 [Page 20] INTERNET DRAFT October 1999 This AVP can be provided by the client as a hint of the maximum duration that it is willing to accept. However, the server DOES NOT have to observe the hint and can return any value. A value of zero provided by a client DOES NOT imply that service is being terminated. 4.7 Extension-Id The Extension-Id AVP (AVP Code 258) is of type Integer32 and is used in order to identify a specific DIAMETER extension. This AVP SHOULD be used in the Device-Reboot-Ind command in order to inform the peer what extensions are locally supported. Each DIAMETER extension draft MUST have an Extension-Id assigned to it by the IANA (see section 6.3). The base protocol does not require a Extension-Id since its support is mandatory. There MAY be more than one Extension-Id AVP within a DIAMETER message. 4.8 Integrity-Check-Value The Integrity-Check-Value AVP (AVP Code 259) is used for hop-by-hop authentication and integrity, and is not recommended for use with untrusted proxy servers. The DIAMETER header as well as all AVPs (including padding) up to this AVP is protected by the Integrity-Check-Value. Note that the Message Length field in the DIAMETER header MUST be set to zero (0) prior to the ICV calculation. The Timestamp AVP MUST be present to provide replay protection and the Nonce AVP must be present to add randomness to the message. All AVPs following this AVP must be ignored. The Integrity-Check-Value is generated in the method described in section 5.5.1 All DIAMETER implementations MUST support this AVP. Calhoun, Rubens, Akhtar expires April 2000 [Page 21] INTERNET DRAFT October 1999 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ AVP Header (AVP Code = 259) +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Transform ID | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Data ... +-+-+-+-+-+-+-+-+ AVP Length The length of this attribute MUST be at least 13. AVP Flags The 'M' bit MUST be set and the 'T' bit MAY be set. The 'V' and 'H' bits MUST NOT be set. Transform ID The Transform ID field contains a value that identifies the transform that was used to compute the ICV. The following values are defined in this document: HMAC-MD5-96[6] 1 Data The Data field contains an ICV of the message up to this AVP. 4.9 Nonce The Nonce AVP (AVP Code 261) is of type Data and MUST be present prior to the Integrity-Check-Value AVPs within a message and is used to ensure randomness within a message. The content of this AVP MUST be a random value of at least 128 bits. The AVP flags for this AVP are different from the default value, and have the following rules: The 'M' bit MUST be set and the 'T' bit MAY be set. The 'V' and 'H' bits MUST NOT be set. 4.10 Timestamp The Timestamp AVP (AVP Code 262) is of type Time and is used to add replay protection to the DIAMETER protocol. This AVP MUST appear prior to the Integrity-Check-Value AVP or any other Integrity AVP defined in separate extensions. The value of time is the most significant four octets returned from an NTP server that indicates Calhoun, Rubens, Akhtar expires April 2000 [Page 22] INTERNET DRAFT October 1999 the number of seconds expired since Jan. 1, 1900. The AVP flags for this AVP are different from the default value, and have the following rules: The 'M' bit MUST be set and the 'T' bit MAY be set. The 'V' and 'H' bits MUST NOT be set. Messages which are older than a certain maximum age SHOULD be rejected and a MRI message with the Result-Code AVP value set to DIAMETER_SEE_ERROR_CODE and the Error-Code AVP set to DIAMETER_TIMEOUT. The recommended value for the maximum age of an outstanding message is 4 seconds. Note that the larger the value, the more susceptible one is to a replay attack. However, one does have to take into account the possibility for clock drift, and the latency involved in the transmission of the message over the network. The timestamp AVP SHOULD be updated prior to retransmission. 4.11 Session-Id The Session-Id AVP (AVP Code 263) is of type Data and is used to identify a specific session (see section 5.1). All messages pertaining to a specific session MUST include only one Session-Id AVP and the same value MUST be used throughout the life of a session. When present, the Session-Id SHOULD appear immediately following the DIAMETER-Command AVP. For any other messages that does not pertain to a specific session, multiple Session-Id AVPs MAY be present as long as the 'T' bit is set. The Session-Id MUST be globally unique at any given time since it is used by the server to identify the session (or flow). The format of the session identifier SHOULD be as follows: It is suggested that the monotonically increasing 32 bit value NOT start at zero upon reboot, but rather start at a random value. This will minimize the possibility of overlapping Session-Ids after a reboot. Alternatively, an implementation MAY keep track of the increasing value in non-volatile memory. The optional value is implementation specific but may include a modem's device Id, a layer 2 address, timestamp, etc. Calhoun, Rubens, Akhtar expires April 2000 [Page 23] INTERNET DRAFT October 1999 The session Id is created by the DIAMETER device initiating the session, which in most cases is done by the client. Note that a Session-Id can be used by more than one extension. 4.12 Vendor-Name The Vendor-Name AVP (AVP Code 266) is of type String and is used to inform a DIAMETER peer of the Vendor Name of the DIAMETER device. This MAY be used in order to know which vendor specific attributes may be sent to the peer. It is also envisioned that the combination of the Vendor-Name and the Firmware-Revision AVPs can provide very useful debugging information. The AVP flags for this AVP are different from the default value, and have the following rules: The 'H' bits MAY be set. The 'T', 'V' and 'M' bits MUST NOT be set. 4.13 Firmware-Revision The Firmware-Revision AVP (AVP Code 267) is of type Integer32 and is used to inform a DIAMETER peer of the firmware revision of the issuing device. For devices which do not have a firmware revision (general purpose computers running DIAMETER software modules, for instance), the revision of the DIAMETER software module may be reported instead. The AVP flags for this AVP are different from the default value, and have the following rules: The 'H' bits MAY be set. The 'T', 'V' and 'M' bits MUST NOT be set. 4.14 Result-Code The Result-Code AVP (AVP Code 268) is of type Integer32 and indicates whether a particular request was completed successfully or whether an error occurred. The Result-Code AVP MUST be present in all DIAMETER messages of type *-Response or *-Answer. The following codes have been defined: DIAMETER_SUCCESS 0 The Request was successfully completed. DIAMETER_FAILURE 1 Calhoun, Rubens, Akhtar expires April 2000 [Page 24] INTERNET DRAFT October 1999 The Request was not successfully completed for an unspecified reason. A DIAMETER Message-Reject message returning this result SHOULD whenever possible also contain one or more Failed-AVP-Code AVPs indicating the attributes which caused the failure. DIAMETER_POOR_REQUEST 2 The Request was poorly constructed. A DIAMETER Message-Reject message returning this result SHOULD whenever possible also contain one or more Failed-AVP-Code AVPs indicating the attributes which caused the failure. DIAMETER_INVALID_AUTH 3 The Request did not contain a valid Integrity-Check-Value or Digital-Signature [11]. DIAMETER_UNKNOWN_SESSION_ID 4 The Request contained an unknown Session-Id. DIAMETER_SEE_ERROR_CODE 5 The Request failed. The message MUST also contain an Error-Code AVP which provides command-specific information on the failure. A DIAMETER Message-Reject-Ind message returning this result SHOULD whenever possible also contain one or more Failed-AVP- Code AVPs indicating the attributes which caused the failure. DIAMETER_COMMAND_UNSUPPORTED 6 The Request contained a command code which the DIAMETER implementation does not recognize or does not support. The Message-Reject-Ind message MUST also contain an Unrecognized- Command-Code AVP which contains the Command Code value which was rejected. DIAMETER_TIMEOUT This error MAY be returned if a request if a message has been received that has a Timestamp AVP that is older than the maximum age that the communicating peer accepts. DIAMETER_ATTRIBUTE_UNSUPPORTED 8 The Request contained an AVP with an AVP Code which the DIAMETER implementation does not recognize or does not support. An DIAMETER Message-Reject-Ind message returning this result MUST also contain one or more Failed-AVP-Code AVPs indicating the AVP Codes which caused the failure. DIAMETER_REDIRECT_INDICATION 9 A proxy or broker has determined that the request could not be satisfied locally and the initiator of the request should Calhoun, Rubens, Akhtar expires April 2000 [Page 25] INTERNET DRAFT October 1999 direct the request directly to the server, whose contact information has been added to the response. DIAMETER_DOMAIN_NOT_SERVED 10 A proxy or broker has determined that it is unable to forward the request or provide redirect information since the domain requested is unknown. DIAMETER_INVALID_TRANSFORM 11 A message was received that included an Integrity-Check-Value or Digital-Signature that made use of an unsupported transform. 4.15 Error-Code The Error-Code AVP (AVP Code 269) is of type Integer32 and contains the message specific error code, if any. This AVP only needs to be present if the Result-Code AVP is present with the DIAMETER_SEE_ERROR_CODE. Error-Code values and corresponding semantics are specific to the command to which the Error-Code is a response, and MUST therefore be documented as part of the description of that command. 4.16 Unrecognized-Command-Code The Unrecognized-Command-Code AVP (AVP Code 270) is of type Integer32 and contains the offending Command Code that resulted in sending the Message-Reject-Ind message. 4.17 Reboot-Type The Reboot-Type AVP (AVP Code 271) is of type Integer32 and MUST be present in the Device-Reboot-Indication message. This AVP contains an indication of the type of that has or will occur. The following values are currently supported: REBOOT_IMMINENT 1 When the Reboot-Type AVP is set to this value it is an indication that the DIAMETER peer is about to reboot and should not be sent any additional DIAMETER messages besides the acknowledgement. REBOOTED 2 When the Reboot-Type AVP is set to this value it is an indication that the DIAMETER peer has recently rebooted and is Calhoun, Rubens, Akhtar expires April 2000 [Page 26] INTERNET DRAFT October 1999 ready to accept new DIAMETER messages. 4.18 Reboot-Time The Reboot-Time AVP (AVP Code 272) is of type Integer32 and MAY be present in the DRI. The value of this AVP indicates the number of seconds before the issuer expects to be ready to receive new DIAMETER messages. This AVP MAY only be present when the Reboot-Type AVP is set to REBOOT_IMMINENT. The value indicated by this AVP should be used as an estimate and is not a hard rule. 4.19 Failed-AVP-Code The Failed-AVP-Code AVP (AVP Code 279) is of type Data and provides debugging information in cases where a request is rejected or not fully processed due to erroneous information in a specific AVP. The documentation of the Result-Code AVP and of the Message-Reject-Ind command provide information on the use of the Failed-AVP-Code AVP. The Data field contains the complete AVP that could not be processed successfully. Possible reasons for this are an improperly-constructed AVP, an unsupported or unrecognized AVP Code, or an invalid value. 4.20 User-Name The User-Name AVP (AVP Code 1) is of type String and contains the User-Name in a format consistent with the NAI specification [8]. All DIAMETER systems SHOULD support usernames of at least 72 octets in length. 4.21 Receive-Window The Receive-Window AVP (AVP Code 277) is of type Integer32 and contains the maximum number of outstanding unacknowledged messages that it is willing to accept for a given peer. Once the number of unacknowledged messages has reached this number, the receive window is considered closed. The default value for the receive window is 7, and SHOULD be configurable. A node MUST stop sending messages when it detects that the number of unacknowledged messages is equal to the peer's receive window size. 4.22 Proxy-State Calhoun, Rubens, Akhtar expires April 2000 [Page 27] INTERNET DRAFT October 1999 The Proxy-State AVP (AVP Code 33) is used by proxy servers when forwarding requests and contains opaque data that is used by the proxy to further process the response. Such data may include AVPs that are to be added to the response, information about the downstream peer, etc. A DIAMETER node that receives such an AVP in a request MUST return the identical AVP in the response. Furthermore, only one such AVP may be present in a message at any given time, so implementations MUST ensure that they remove any Proxy-State AVPs before adding their own. If the Proxy-State AVP was removed from a request, the same AVP must be inserted in the corresponding response before forwarding the message to the downstream peer. The Proxy-State AVP's Address field is intended to be used by DIAMETER hosts in order to assist in determining if the AVP was locally generated. 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ AVP Header (AVP Code = 33) +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 128-bit Address... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Data ... +-+-+-+-+-+-+-+-+ AVP Flags The 'M' bit MUST be set. The 'V', 'H' and 'T' bits MUST NOT be set. Address The Address field is a 128-bit field that contains the IP address of the system that created the Proxy-State AVP. If the host creating the AVP has an IPv4 address, the leading 96 bits MUST be set to zero. This field is intended to assist hosts in determining if a Proxy-State AVP in a message was locally created. Data The Data field is one or more octets. The actual format of the information is site or application specific, and SHOULD be treated as undistinguished octets. 4.23 Redirect-Host Calhoun, Rubens, Akhtar expires April 2000 [Page 28] INTERNET DRAFT October 1999 The Redirect-Host AVP (AVP Code 278) is of type Address and is returned in a response that has the Result-Code AVP set to DIAMETER_REDIRECT_REQUEST. This AVP includes address information about the DIAMETER host to which the request must be redirected. Upon receipt of such a Result-Code, and this AVP, a DIAMETER host SHOULD send the request directly to the host. A proxy server or broker MAY return more than one Redirect-Host AVP if there is a group of DIAMETER servers that can satisfy the request. 4.24 Broker-Issued-Certificate The Broker-Issued-Certificate AVP (AVP Code 280) is typically added by a broker in a network where the broker's organization also provides certificate authority services. In such networks, certificates are issued to all DIAMETER servers within the roaming consortium. The Broker-Issued-Certificate AVP contains a timestamp and an expiration time, which CAN be used by DIAMETER hosts in order to determine whether they should further validate the certificate against a certification validation infrastructure (see section 5.6.2 for more information). 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ AVP Header (AVP Code = 280) +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Timestamp | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Expiration Time | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Certificate Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Digital Signature Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Certificate ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Digital Signature ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ AVP Length The length of this attribute MUST be at least 24. Timestamp The Timestamp field contains the time when the AVP was created. This field is in the data format defined in Section 2.2.3. Expiration Calhoun, Rubens, Akhtar expires April 2000 [Page 29] INTERNET DRAFT October 1999 The Expiration field contains the time after which the broker recommends that a new Broker-Certificate be retrieved. This field is in the data format defined in Section 2.2.3. Certificate Length The Certificate Length field contains the number of octets of the certificate in the certificate field. Digital-Signature Length The Digital-Signature Length field contains the number of octets of the signature found in the Digital Signature field. Certificate The certificate field contains the X.509 certificate [19]. Digital-Signature The Digital-Signature field contains the broker's digital signature [11]. 5.0 Protocol Definition The base DIAMETER protocol is never used on its own. It is always extended for a particular application. The base DIAMETER protocol concerns how messages are sent, resent and how peers may eventually be abandoned. The base protocol also defines certain rules which apply to all exchanges of messages between DIAMETER peers. It is important to note that the base protocol requires that every message includes some AVPs (Nonce, Timestamp, Integrity-Check-Vector or Digital-Signature). Communication between DIAMETER peers begins with one peer sending a message to another DIAMETER peer. The set of AVPs included in the message is determined by a particular application of or extension to DIAMETER. (We will refer to this as the DIAMETER extension). One AVP which is included in the initial communication is the Session-Id. The communicating party may accept or reject the request which contains a new Session-Id, or return Result-Code and Error-Code AVPs if the request cannot be processed. The behavior of the communicating peer depends on the DIAMETER extension employed. Exchanges of messages are either request/reply oriented, or in some special cases, do not require replies. All such messages which do not require replies (or acknowledgments) have names which end with '-Ind' (short for Indication). All messages require a transport level acknowledgement, either through a ZLB, or by piggybacking an acknowledgement in a non-ZLB message. Calhoun, Rubens, Akhtar expires April 2000 [Page 30] INTERNET DRAFT October 1999 Communicating DIAMETER peers retain state relating to transport (sequence numbers and the like). This state information may be discarded when the communicating peer is determined to be unreachable. This occurs when the peer does not acknowledge receipt of a DIAMETER message that has been retransmitted a maximum number of times. The Device-Watchdog-Ind is used to pro-actively probe the peer to ensure that communication is still possible. Freeing the transport state associated with a communication with a DIAMETER peer is entirely independent of freeing session state (associated with a Session-Id). This can only be done according to rules established in a particular extension/application of DIAMETER. DIAMETER extensions MUST define an explicit exchange of messages which allow a peer to inform the other party that a session has been terminated. 5.1 Session Identifiers When a user requests access to the network, a DIAMETER client issues an authentication and authorization request to its local server. The request contains a Session-Id AVP, which is used in subsequent messages (e.g. subsequent authorization, accounting, etc) relating to the user's session. The Session-Id AVP is a means for the client and servers to correlate a DIAMETER message with a user session. When a DIAMETER server authorizes a user to use network resources, it typically adds the Session-Timeout AVP to the response. The Session- Timeout AVP defines how long the user can make use of the resources before another authorization request is sent to the server. Should the server not receive another authorization request before the timeout occurs, it SHOULD release any state information related to the user's session. The base protocol does not include any authorization request messages, since these are largely application-specific and are defined in a DIAMETER protocol extension document. Such extensions SHOULD provide a message that allows a client to inform a server that the user's session has been released. This would enable the server to free state information instead of having to wait for the timeout to occur. 5.2 DIAMETER Bootstrap Message DIAMETER provides a message that is used to indicate either an imminent reboot, or that a reboot has occurred. The DRI message MUST Calhoun, Rubens, Akhtar expires April 2000 [Page 31] INTERNET DRAFT October 1999 be sent to all known DIAMETER peers both previous to a reboot when possible as well as following a reboot. The Reboot-Type AVP is used to indicate the type of reboot associated with the DRI. When set to REBOOT_IMMINENT, all peers should be warned that any new DIAMETER requests sent to the issuer will probably not be received or processed. If a request MUST be sent it would be preferable to issue the request to an alternate peer if available. The message includes an optional Reboot-Time AVP that specifies an estimate of how long before the issuer is available to receive new DIAMETER messages. Upon reboot, the host MUST issue a DRI message with the Reboot-Type AVP set to REBOOTED. This is an indication that new DIAMETER messages may be sent to the transmitter of the DRI. Note that the Reboot-Time AVP is not required, and when present provides an estimate and should not be used as a hard value. In the case of a software implementation (server) running on a general purpose operating system, the Reboot-Time AVP will probably not be present since it is possible that the DIAMETER server has been stopped and it is not possible to know how long before (and if) it will be restarted. Upon receipt of this message the peer's Ss and Sr variables must be reset. It is possible for this message to be received outside the window (Ns and Nr set to zero) when it follows a reboot. The DIAMETER Reboot-Ind message does not require a reply. The message is acknowledged using DIAMETER's reliable transport. See appendix E for more information. 5.2.1 State Machine A DIAMETER node initially considers all known peers to be in the closed state, and should not process any DIAMETER message with the exception of acknowledgements and the DRI. Once the DIAMETER peer is set to the open state, any DIAMETER message may be accepted and processed. The following is a suggested state machine. If at any time no transport level acknowledgement is received and the message was retransmitted the maximum number of times, the session with the peer MUST be closed, and all associated state with the peer MUST be freed. Calhoun, Rubens, Akhtar expires April 2000 [Page 32] INTERNET DRAFT October 1999 State Event Action New State ----- ----- ------ --------- closed Local Open send DRI wait-ack1 Request closed receive DRI send ACK wait-ack2 send DRI closed receive invalid cleanup closed DRI wait-ack1 receive ACK accept Incoming wait-ack1 Messages wait-ack1 receive DRI send ACK open Accept Incoming Messages wait-ack1 no ACK received cleanup closed wait-ack2 received ACK Accept Incoming open Messages wait-ack2 no ACK received cleanup closed open receive DRI send ACK wait-ack2 Rebooted send DRI open receive DRI cleanup closed Imminent-Reboot open receive DWI send ACK open open receive other send ACK open messages open no ACK received cleanup closed 5.3 Keepalive Exchange DIAMETER uses the Device-Watchdog-Ind message as a keepalive mechanism. DIAMETER entities that need to ensure that connectivity with a peer is not lost may use this mechanism. Each node is responsible for sending their own Device-Watchdog-Ind message to its peer when no activity is present for some time, which can be configurable. Note that it is possible for each node in the network Calhoun, Rubens, Akhtar expires April 2000 [Page 33] INTERNET DRAFT October 1999 to have a different inactivity timer configured. The more aggressive the timer, the more traffic is generated, but the quicker it can detect if a peer is no longer reachable. A DIAMETER Client can use this mechanism to ensure that fail-over to an alternate server occurs even without any AAA traffic. DIAMETER Servers use this mechanism to identify when a particular client is no longer reachable. Redundant DIAMETER Servers can use this mechanism to identify when the primary server is no longer available. Proxy Servers can equally use this method to identify when a particular domain's server is no longer reachable. The DIAMETER Device-Watchdog-Ind message does not require a reply. The message is acknowledged using DIAMETER's reliable transport. See appendix F for more information. 5.4 AVP Handling Rules 5.4.1 Unrecognized Command Support The DIAMETER protocol provides a message that is used to inform a peer that a DIAMETER message was received with an unrecognized command (see appendix G for more information). The following provides a DIAMETER message that is sent to a peer: ::= [] { || [11] } Upon receipt of the above message, the receiver notices that it does not support the command and sends the following message: ::= [] { || [11] } Calhoun, Rubens, Akhtar expires April 2000 [Page 34] INTERNET DRAFT October 1999 5.4.2 The art of AVP Tagging The AVP Header provides the 'T' bit that is used for grouping AVPs together. Although the base protocol does not define any AVPs that need to be grouped, it is envisioned that DIAMETER extensions will require tag support. In the case where multiple AVPs are needed to indicate a specific authorization "rule" tagging is appropriate. Such an example is taken from [10] that discusses Tunneling attributes. In this case multiple AVPs are required in order to specify tunnel parameter, and more than one set of AVPs MAY be present in the message. This is necessary in order to support redundant tunnel servers. In this case, the AVPs that need to be grouped together would have a specific tag value, and each group would use a different tag value. 5.5 DIAMETER Message Security 5.5.1 Using the Integrity-Check-Value The use of the Integrity-Check-Value (ICV) AVP requires a pre- configured shared secret. Although this mechanism does not scale as well as the Digital Signature, it may be desirable to use this mechanism in the case where asymmetric technology is not required or available. It is recommended that the key size used in the computation of the ICV be sufficiently long (e.g. 128 bits), and that different keys be used for both authentication and encryption (see section 5.5.2). Note that in the case where two DIAMETER nodes need to communicate through an intermediate node (i.e. Proxy) it does not offer any end- to-end data integrity or encryption as each node must re-compute the Integrity-Check-Value AVP. The Timestamp and Nonce AVPs MUST be present in the message PRIOR to the Integrity-Check-Value AVP. The Timestamp AVP provides replay protection and the Nonce AVP provides randomness. The Data field of the AVP contains an HMAC-MD5-96[6] of the message up to the ICV AVP. Prior to computing the hash value, the Message Length field in the DIAMETER header (see section 2.1) MUST be set to zero. Using the example code provided in [6], the following call would be used to generate the Integrity-Check-Value: hmac_md5(DiameterMessage, MessageLength, Secret, Secretlength, Calhoun, Rubens, Akhtar expires April 2000 [Page 35] INTERNET DRAFT October 1999 Output) The following is an example of a message that include hop-by-hop security: ::= [] Any AVPs in a message that is not succeeded by the Integrity-Check- Value AVP MUST be ignored. 5.5.2 AVP Encryption with Shared Secrets This method of encrypting AVP data is the simplest to use and MUST be supported by all DIAMETER implementations. However, local policy MAY determine that the use of this mechanism is not permitted. The 'H' bit MUST only be set if a shared secret exists between both DIAMETER peers. If the 'H' bit is set in any DIAMETER AVP, the Nonce AVP MUST be present prior to the first encrypted AVP. The length of the AVP value to be encrypted is first encoded in the following Subformat, which is included in the AVP's data field. 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | length of plain text data | plain text data ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Padding ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Length The Length field contains the length of the decrypted data. plain text data Data of AVP that is to be obscured. Padding If the plain text does not align on the byte boundary required by Calhoun, Rubens, Akhtar expires April 2000 [Page 36] INTERNET DRAFT October 1999 the hashing algorithm (e.g. 16 octets for MD5), it is highly recommended that random padding be added to obscure the length of the plain text data. The resulting subformat MAY be padded to a multiple of 16 octets in length. For example, if the plain text data to be obscured is a string containing 6 characters (e.g. password 'foobar'), then 8 + n * 16 octets of padding would be applied. Padding does NOT alter the value placed in the Length of the ClearText Data, only the length of the AVP itself. Next, An MD5 hash is performed on the concatenation of: - the four octet Command Code of the AVP - the shared authentication secret - an arbitrary length random vector The value of the random vector used in this hash is passed in the Data field of a Nonce AVP. This Nonce AVP must appear in the message before any hidden AVPs. The same Nonce may be used for more than one hidden AVP in the same message. If a different Nonce is used for the hiding of subsequent AVPs then a new Nonce AVP must be placed before the first AVP to which it applies. The MD5 hash value is then XORed with the first 16 octet or less segment of the AVP Subformat and placed in the Data field of the AVP. If the AVP Subformat is less than 16 octets, the Subformat is transformed as if the Value field had been padded to 16 octets before the XOR, but only the actual octets present in the Subformat are modified, and the length of the AVP is not altered. If the Subformat is longer than 16 octets, a second one-way MD5 hash is calculated over a stream of octets consisting of the shared secret followed by the result of the first XOR. That hash is XORed with the second 16 octet or less segment of the Subformat and placed in the corresponding octets of the Data field of the AVP. If necessary, this operation is repeated, with each XOR result being used along with the shared secret to generate the next hash to XOR the next segment of the value with. This technique results in the content of the AVP being obscured, although the length of the AVP is still known. On receipt, the Nonce is taken from the last Nonce AVP encountered in the message prior to the AVP to be decrypted. The above process is then reversed to yield the original value. For more details on this hiding method, consult RFC2138 [1]. Calhoun, Rubens, Akhtar expires April 2000 [Page 37] INTERNET DRAFT October 1999 Please note that in the case where the DIAMETER message needs to be processed by an intermediate non-trusted DIAMETER server (also known as a proxy server, depicted as DIA2 in the figure below) the AVP needs to be decrypted using Shared-Secret-1 and re-encrypted by DIA2 using Shared-Secret-2. (Shared-Secret-1) (Shared-Secret-2) +------+ -----> +------+ ------> +------+ | | | | | | | DIA1 +-------------------+ DIA2 +-------------------+ DIA3 | | | | | | | +------+ +------+ +------+ Figure 1: Message Forwarding Unfortunately in this case the non-trusted server DIA2 has access to sensitive information (such as a password). It is recommended that the key size used in the encryption of AVPs be sufficiently long (e.g. 128 bits), and that different keys be used for both authentication and encryption (see section 5.5.1). 5.6 DIAMETER Message Routing 5.6.1 DIAMETER Proxying This section will describe how DIAMETER server implementations can proxy requests to upstream servers. Consider the following diagram, which depicts DIA1 sending a request to DIA2. Typically, the request will contain the User-Name AVP (section 4.20), which conforms to the format defined in the NAI specification [8]. Server DIA2 will extract that realm portion of the NAI to determine if the request can be locally processed, or if the request must be proxied to an upstream server (in this case DIA3). (Request) (Request) (User-Name = joe@abc.com) (Proxy-State=1) +------+ ------> +------+ ------> +------+ | | | | | | | DIA1 +-------------------+ DIA2 +-------------------+ DIA3 | | | | | | | +------+ <------ +------+ <------ +------+ (Response) (Response) (Proxy-State=1) mno.net xyz.com abc.com Figure 2: DIAMETER Proxying Prior to forwarding the request, DIA2 must establish some state information in order to be able to forward the corresponding response Calhoun, Rubens, Akhtar expires April 2000 [Page 38] INTERNET DRAFT October 1999 from DIA3 to DIA1. There are two methods of doing so: 1. DIA2 can maintain state information locally, and using the session-Id and possible the Identifier in the header, can match the request with the response. The state information would contain sufficient information for it to know where the response should be forwarded. Additionally, it may be necessary for DIA2 to attach AVPs to the response that were created when the request was received. These AVPs could be kept in the state table. 2. DIA2 can attach a Proxy-State AVP (section 4.22), which may contain any information, including information regarding the source of the request, additional AVPs that must be attached to the response, etc. Upon receipt of the response, DIA2 must find the Proxy-State AVP, determine if the AVP was created locally, and if so use the information included within the AVP. If AVPs were found within the Proxy-State AVP, they could easily be attached to the response. Finally, the Proxy-State AVP is removed from the response before being forwarded to DIA1. Although both methods work, the latter is much simpler as it reduces the amount of state information each proxy must maintain on a per request basis. When DIA3 receives a request that includes the Proxy-State AVP, it MUST include the same AVP in the corresponding response. Furthermore, should DIA3 have to proxy the request to another upstream server, it would have to replace the existing Proxy-State AVP with its own. It must, however, be able to replace the Proxy- State AVP in the corresponding response back to the one it had received in the request. One suggested implementation is to include the Proxy-State AVPs in a newly created Proxy-State AVP, allowing a server to easily replace the Proxy-State AVPs in the responses. 5.6.2 Message Redirection There are cases where a DIAMETER proxy, known as a broker, may wish to request that a server contact another directly instead of forwarding the message (figure 3). This is typically done when the broker provides simple NAI to Home DIAMETER Server address resolution services. In the example provided in figure 3, abc.net's DIAMETER server issues a request to its broker, which in turn returns a response that includes the Result-Code AVP set to a specific value (see section 4.14). When a response is received with such a value, the message Calhoun, Rubens, Akhtar expires April 2000 [Page 39] INTERNET DRAFT October 1999 MUST also include one or more Redirect-Host AVPs. These AVPs contain address information that can be then used to directly communicate with the Home DIAMETER Server. Note that the servers COULD cache the home server information in order to reduce the latency involved in any future messages destined for that home server. +------------------+ +---------+ | DIAMETER | | CRL DB/ | | Broker | | OCSP | +------------------+ +---------+ /|\ Request | Response w+ | Result Code = | Redirect \|/ +----------+ +----------+ | abc.net |/ \| xyz.net | | DIAMETER |--------------| DIAMETER | | Server |\ /| Server | +----------+ Direct +----------+ Communication Figure 3: DIAMETER Broker Returning Redirect Indication When returning the response with the Result-Code set to indicate a redirect indication, the broker can also include the certificates of both the requesting server, and the target server. These certificates are encapsulated in the Broker-Certificate AVP, which also includes a timestamp and an expiration time. The requesting server can forward the Broker-Certificate that belongs to it in the subsequent request to the home DIAMETER server. The Broker-Certificate is intended to allow the peers to communicate without having to validate the certificate against a certificate validation infrastructure, such as Certificate Revocation Lists (CRLs) or using Online Certificate Status Protocol (OCSP) [14]. Local policy at the individual servers will dictate whether they can trust the Broker-Certificate, or whether they must validate the certificate themselves. 6.0 IANA Considerations This document defines a number of assigned numbers to be maintained by the IANA. This section explains the criteria to be used by the IANA to assign additional numbers in each of these lists. The following subsections describe the assignment policy for the namespaces defined elsewhere in this document. 6.1 AVP Attributes Calhoun, Rubens, Akhtar expires April 2000 [Page 40] INTERNET DRAFT October 1999 As defined in Section 4.0, AVPs contain vendor ID, Attribute and Value fields. For vendor ID value of 0, IANA will maintain a registry of assigned Attributes and in some case also values. Attribute 0-254 are assigned from the RADIUS protocol [1], whose attributes are also maintained through IANA. Attributes 256-280 are assigned within this document in section 4.0. The remaining values are available for assignment through Designated Expert [12]. 6.2 Command Code AVP Values As defined in Section 4.1, the Command Code AVPs (AVP Code 256) have an associated value maintained by IANA. Values 0-255 are reserved for backward RADIUS compatibility, and values 256-258 are defined in this specification. The remaining values are available for assignment via Designated Expert [12]. 6.3 Extension Identifier Values as defined in Section 4.7, the Extension Identifier is used to identify a specific DIAMETER Extension. All values, other than zero (0) are available for assignment via Designated Expert [12]. 6.4 Result Code AVP Values As defined in Section 4.14, the Result Code AVP (AVP Code 268) defines the values 0-8. All remaining values are available for assignment via IETF Consensus [12]. 6.5 Integrity Check Value Transform Values Section 4.8 defines the Integrity-Check-Value AVP (AVP Code 259) which contains a field called the Transform. This document reserves the value 1. All remaining values are available for assignment via Designated Expert [12]. 6.6 Reboot Type Values Section 4.17 defines the Reboot-Type AVP (AVP Code 271), which is used to inform the peer of the cause for the reboot. This document defines the values 1-3. All remaining values are available for assignment via Designated Expert [12]. Calhoun, Rubens, Akhtar expires April 2000 [Page 41] INTERNET DRAFT October 1999 6.7 AVP Header Bits There are six remaining reserved bits in the AVP header. Additional bits should only be assigned via a Standards Action [12]. 7.0 Open Issues The following are the open issues that SHOULD be addressed in future versions of the DIAMETER protocol: - AVPs of type 'Time" are 32 bits in size and contain the a timestamp consistent with NTP [18]. This field is expected to expire sometime in 2038. Future investigation SHOULD be done to determine if a 64 bit time format could be used. - The fact that the Sender's IP Address is used in the construction of the Session-Id means that the introduction of Network Address Translation can cause two hosts to represent the same Session Identifier. This area needs to be investigated further to be able to support DIAMETER hosts on a private network. - Some crypto algorithms are known to have weaknesses if a random value is not found early within the plaintext, therefore it is recommended that the Nonce AVP be added early in a message if possible. More investigation on this subject is needed in order to determine if there exists any possibility for such attacks. - When additional hashing transforms are supporting by the DIAMETER base protocol, there SHOULD be a method to negotiate the transform to be used. This negotiation MUST NOT be prone to a bidding down attack to the lowest secure transform. 8.0 DIAMETER protocol related configurable parameters This section contains the configurable parameters that can be found throughout this document: Device-Reboot-Ind Timer This timer is used to determine how long an implementation should issue another DRI message if no response is received. Device-Watchdog-Ind Timer This is the timer that determines the period of inactivity that must occur before a DWI is transmitted to the communicating peer. Calhoun, Rubens, Akhtar expires April 2000 [Page 42] INTERNET DRAFT October 1999 Receive Window The Receive window determines how many DIAMETER messages a node can handle from a communicating peer. This is normally configured to a value that allows the node to effectively manage its receive buffers. Retransmission Timer The retransmission timer is the time period that a node will retransmit a message if not transport level acknowledgement was received. Maximum Retransmissions This is the maximum number of times a DIAMETER message will be retransmitted before it is determined that the communicating peer is no longer reachable. Delayed Acknowlegement Timer This is an optional timer, described in appendix D, that specifies how long an implementation could wait before sending a ZLB. The idea is that if there is a non-ZLB message that would be sent within this window, an acknowledgement would be piggybacked onto the message. Shared Secret The shared secret is a value that is known by two communicating peers, and is used to generate the Integrity-Check-Value. 9.0 Security Considerations Security issues are the primary topic of this document. 10.0 References [1] Rigney, et alia, "RADIUS", RFC-2138, April 1997 [2] Reynolds, Postel, "Assigned Numbers", RFC 1700, October 1994. [3] Postel, "User Datagram Protocol", RFC 768, August 1980. [4] Rivest, "The MD5 Message-Digest Algorithm", RFC 1321, April 1992. [5] Kaufman, Perlman, Speciner, "Network Security: Private Communications in a Public World", Prentice Hall, March 1995, ISBN 0-13-061466-1. [6] Krawczyk, Bellare, Canetti, "HMAC: Keyed-Hashing for Message Authentication", RFC 2104, January 1997. [7] Calhoun, Bulley, "DIAMETER User Authentication Extensions", draft-calhoun-diameter-authen-06.txt, Work in Progress, Calhoun, Rubens, Akhtar expires April 2000 [Page 43] INTERNET DRAFT October 1999 August 1999. [8] Aboba, Beadles "The Network Access Identifier." RFC 2486. January 1999. [9] Calhoun, Zorn, Pan, Akhtar, "DIAMETER Framework", draft-calhoun-diameter-framework-04.txt, Work in Progress, October 1999. [10] Zorn, Leifer, Rubens, Shriver, "RADIUS attributes for Tunnel Protocol Support", draft-ietf-radius-tunnel-auth-05.txt, Work in Progress, April 1998. [11] Calhoun, Bulley, "DIAMETER Secure Proxy Extension", draft-calhoun-diameter-proxy-03.txt, Work in Progress, October 1999. [12] Narten, Alvestrand,"Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 2434, October 1998 [13] S. Bradner, "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [14] Myers, Ankney, Malpani, Galperin, Adams, "X.509 Internet Public Key Infrastructure Online Certificate Status Protocol (OCSP)", RFC 2560, June 1999. [15] Arkko, Calhoun, Patel, Zorn, "DIAMETER Accounting Extension", draft-calhoun-diameter-accounting-00.txt, IETF Work in Progress, September 1999. [16] Hinden, Deering, "IP Version 6 Addressing Architecture", RFC 2373, July 1998. [17] ISI, "Internet Protocol", RFC 791, September 1981. [18] Mills, "Simple Network Time Protocol (SNTP) Version 4 for IPv4, IPv6 and OSI, RFC 2030, October 1996. [19] Housley, Ford, Polk, Solo, "Internet X.509 Public Key Infrastructure Certificate and CRL Profile", RFC 2459, January 1999. 11.0 Acknowledgements The authors would like to thank Nenad Trifunovic, Tony Johansson and Pankaj Patel for their participation in the Document Reading Party. Erik Guttman provided alot of good suggestions that were instrumental in reducing the size of the document, while making the text generally clearer. The authors would also like to acknowledge the following people for their contribution in the development of the DIAMETER protocol: Bernard Aboba, Jari Arkko, William Bulley, Daniel C. Fox, Lol Grant, Ignacio Goyret, Nancy Greene, Peter Heitman, Paul Krumviede, Fergal Ladley, Ryan Moats, Victor Muslin, Kenneth Peirce, Sumit Vakil, John Calhoun, Rubens, Akhtar expires April 2000 [Page 44] INTERNET DRAFT October 1999 R. Vollbrecht, Jeff Weisberg and Glen Zorn 12.0 Author's Address Questions about this memo can be directed to: Pat R. Calhoun Network and Security Research Center, Sun Labs Sun Microsystems, Inc. 15 Network Circle Menlo Park, California, 94025 USA Phone: 1-650-786-7733 Fax: 1-650-786-6445 E-mail: pcalhoun@eng.sun.com Allan C. Rubens Tut Systems, Inc. 220 E. Huron, Suite 260 Ann Arbor, MI 48104 USA Phone: 1-734-995-1697 E-Mail: arubens@tutsys.com Haseeb Akhtar Wireless Technology Labs Nortel Networks 2221 Lakeside Blvd. Richardson, TX 75082-4399 USA Phone: 1-972-684-8850 E-Mail: haseeb@nortelnetworks.com 13.0 Full Copyright Statement Copyright (C) The Internet Society (1999). All Rights Reserved. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without Calhoun, Rubens, Akhtar expires April 2000 [Page 45] INTERNET DRAFT October 1999 restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this docu- ment itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Inter- net organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English. The limited permis- sions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns. This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WAR- RANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE." Calhoun, Rubens, Akhtar expires April 2000 [Page 46] INTERNET DRAFT October 1999 Appendix A: Acknowledgment Timeouts DIAMETER uses sliding windows and timeouts to provide flow-control across the underlying medium and to perform efficient data buffering to keep two DIAMETER peers' receive window full without causing receive buffer overflow. DIAMETER requires that a timeout be used to recover from dropped messages. When the timeout for a peer expires, the previously transmitted message with Ns value equal to the highest in-sequence value of Nr received from the peer is retransmitted. The receiving peer does not advance its value for the receive sequence number state, Sr, until it receives a message with Ns equal to its current value of Sr. This rule assures that all subsequent acknowledgements to this peer will contain an Nr value equal to the Ns value of the first missing message until a message with the missing Ns value is received. The exact implementation of the acknowledgment timeout is vendor- specific. It is suggested that an adaptive timeout be implemented with back-off for flow control. The timeout mechanism proposed here has the following properties: Independent timeouts for each peer. A device will have to maintain and calculate timeouts for every active peer. An administrator-adjustable maximum timeout, MaxTimeOut, unique to each device. An adaptive timeout mechanism that compensates for changing throughput. To reduce message processing overhead, vendors may choose not to recompute the adaptive timeout for every received acknowledgment. The result of this overhead reduction is that the timeout will not respond as quickly to rapid network changes. Timer back-off on timeout to reduce congestion. The backed-off timer value is limited by the configurable maximum timeout value. Timer back-off is done every time an acknowledgment timeout occurs. In general, this mechanism has the desirable behavior of quickly backing off upon a timeout and of slowly decreasing the timeout value as messages are delivered without errors. A.1 Calculating Adaptive Acknowledgment Timeout We must decide how much time to allow for acknowledgments to return. Calhoun, Rubens, Akhtar expires April 2000 [Page 47] INTERNET DRAFT October 1999 If the timeout is set too high, we may wait an unnecessarily long time for dropped messages. If the timeout is too short, we may time out just before the acknowledgment arrives. The acknowledgment timeout should also be reasonable and responsive to changing network conditions. The suggested adaptive algorithm detailed below is based on the TCP 1989 implementation and is explained in Richard Steven's book TCP/IP Illustrated, Volume 1 (page 300). 'n' means this iteration of the calculation, and 'n-1' refers to values from the last calculation. DIFF[n] = SAMPLE[n] - RTT[n-1] DEV[n] = DEV[n-1] + (beta * (|DIFF[n]| - DEV[n-1])) RTT[n] = RTT[n-1] + (alpha * DIFF[n]) ATO[n] = MIN (RTT[n] + (chi * DEV[n]), MaxTimeOut) DIFF represents the error between the last estimated round-trip time and the measured time. DIFF is calculated on each iteration. DEV is the estimated mean deviation. This approximates the standard deviation. DEV is calculated on each iteration and stored for use in the next iteration. Initially, it is set to 0. RTT is the estimated round-trip time of an average message. RTT is calculated on each iteration and stored for use in the next iteration. Initially, it is set to PPD. ATO is the adaptive timeout for the next transmitted message. ATO is calculated on each iteration. Its value is limited, by the MIN function, to be a maximum of the configure MaxTimeOut value. Alpha is the gain for the round trip estimate error and is typically 1/8 (0.125). Beta is the gain for the deviation and is typically 1/4 (0.250). Chi is the gain for the timeout and is typically set to 4. To eliminate division operations for fractional gain elements, the entire set of equations can be scaled. With the suggested gain constants, they should be scaled by 8 to eliminate all division. To simplify calculations, all gain values are kept to powers of two so that shift operations can be used in place of multiplication or division. The above calculations are carried out each time an acknowledgment is received for a message that was not retransmitted (no timeout occurred). Calhoun, Rubens, Akhtar expires April 2000 [Page 48] INTERNET DRAFT October 1999 A.2 Flow Control: Adjusting for Timeout This section describes how the calculation of ATO is modified in the case where a timeout does occur. When a timeout occurs, the timeout value should be adjusted rapidly upward. To compensate for shifting internetwork time delays, a strategy must be employed to increase the timeout when it expires. A simple formula called Karn's Algorithm is used in TCP implementations and may be used in implementing the back-off timers for the DIAMETER peers. Notice that in addition to increasing the timeout, we also shrink the size of the window as described in the next section. Karn's timer back-off algorithm, as used in TCP, is: NewTIMEOUT = delta * TIMEOUT Adapted to our timeout calculations, for an interval in which a timeout occurs, the new timeout interval ATO is calculated as: RTT[n] = delta * RTT[n-1] DEV[n] = DEV[n-1] ATO[n] = MIN (RTT[n] + (chi * DEV[n]), MaxTimeOut) In this modified calculation of ATO, only the two values that contribute to ATO and that are stored for the next iteration are calculated. RTT is scaled by delta, and DEV is unmodified. DIFF is not carried forward and is not used in this scenario. A value of 2 for Delta, the timeout gain factor for RTT, is suggested. Appendix B: Examples of sequence numbering This appendix uses several common scenarios to illustrate how sequence number state progresses and is interpreted. B.1 Lock-step session establishment In this example, a DIAMETER host establishes communication with a peer, with the exchange involving each side alternating in the sending of messages. This example is contrived, in that the final acknowledgement typically would be included in the Device-Watchdog- Ind message. Calhoun, Rubens, Akhtar expires April 2000 [Page 49] INTERNET DRAFT October 1999 DIAMETER Host A DIAMETER Host B -> Device-Reboot-Ind Nr: 0, Ns: 0 (ZLB) <- Nr: 1, Ns: 0 -> Device-Watchdog-Ind Nr: 0, Ns: 1 (delay) (ZLB) <- Nr: 2, Ns: 0 B.2 Multiple messages acknowledged This example shows a flow of messages from DIAMETER Host B to Host A, with Host A having no traffic of its own. Host A is waiting 1/4 of its timeout interval, and then acknowledging all messages seen since the last interval. DIAMETER Host A DIAMETER Host B (previous message flow precedes this) -> (ZLB) Nr: 7000, Ns: 1000 (non-ZLB) <- Nr: 1000, Ns: 7000 (non-ZLB) <- Nr: 1000, Ns: 7001 (non-ZLB) <- Nr: 1000, Ns: 7002 (Host A's timer indicates it should acknowledge pending traffic) -> (ZLB) Nr: 7003, Ns: 1000 B.3 Lost message with retransmission Host A attempts to communicate with Host B. The Device-Reboot-Ind sent from B to A is lost and must be retransmitted by Host B. Calhoun, Rubens, Akhtar expires April 2000 [Page 50] INTERNET DRAFT October 1999 DIAMETER Host A DIAMETER Host B -> Device-Reboot-Ind Nr: 0, Ns: 0 (message lost) Device-Reboot-Ind <- Nr: 1, Ns: 0 (pause; Host A's timer started first, so fires first) -> Device-Reboot-Ind Nr: 0, Ns: 0 (Host B realizes it has already seen this message) (Host B might use this as a cue to retransmit, as in this example) Device-Reboot-Ind <- Nr: 1, Ns: 0 -> Device-Watchdog-Ind Nr: 1, Ns: 1 (delay) (ZLB) <- Nr: 2, Ns: 1 Appendix C Backward Compatibility with RADIUS The DIAMETER protocol was designed with RADIUS [1] compatibility in mind. A DIAMETER node MAY listen for incoming RADIUS and DIAMETER packets on the same UDP port. The first octet in the message would indicate whether the message is of type RADIUS or DIAMETER. The RADIUS protocol defines a one octet attribute space, and the DIAMETER protocol reserves the first 255 attribute identifiers to be the same as those defined in RADIUS. This allows DIAMETER servers to easily perform protocol conversion, since a dictionary lookup would not be necessary in order to map a RADIUS attribute to a DIAMETER AVP. By re-using the RADIUS attribute space, a DIAMETER server could easily read a typical RADIUS user profile without any additional conversions. This reduces the need to create duplicate user profiles for both protocols, and also does not require any database conversion while reading the profiles. Calhoun, Rubens, Akhtar expires April 2000 [Page 51] INTERNET DRAFT October 1999 Appendix D Delayed Acknowledgement Optimization This optimization will potentially reduce the amount of traffic sent between DIAMETER peers. This optimization affects when acknowledgments are sent, as presented in Section 3.1. If a peer does not have a message queued to transmit at the time a non-ZLB message is received then it should delay a short time before sending a ZLB message containing the latest values of Sr and Ss, as described above. This short delay is to allow for the possible arrival of a message to be transmitted back to its peer, thus avoiding the need to issue a ZLB. The suggested value for this time delay is 1/4 the receiving peer's value of Round-Trip-Time (RTT - see Appendix A), if it computes RTT, or a maximum of 1/2 of its fixed acknowledgment timeout interval otherwise. This timeout should provide a reasonable opportunity for the receiving peer to obtain a payload message destined for its peer, upon which the ACK of the received message can be piggybacked. Note that if a peer's window is full, it MAY advertise an older Nr value if it is not ready to accept new messages. This delay value should be treated as a suggested maximum; an implementation could make this delay quite small without adversely affecting the protocol. The default time delay is 2 seconds. To provide for better throughput, the receiving peer should skip this delay entirely and send a ZLB message immediately in the case where its receive window is filled and it has no queued data to send for this connection or it can't send queued data because the transmit window is closed. Appendix E Device-Reboot-Ind Message Flow The following figure depicts a sample flow of Device-Reboot-Ind between three DIAMETER peers, one being a proxy or broker server. In this example DIA1 initiates the bootstrap sequence with DIA2, and later DIA3 initiates the bootstrap sequence with DIA2. After some time DIA1 needs to reboot and informs DIA2. The details of each message is provided below. Calhoun, Rubens, Akhtar expires April 2000 [Page 52] INTERNET DRAFT October 1999 +-------+ +-------+ +-------+ | DIA1 | | PROXY | | DIA3 | | | | DIA2 | | | +-------+ +-------+ +-------+ | | | |DRI (ns=0, nr=0) | | | Rebooted | | | version 1, | | | extensions 1, 4 | | (a) |------------------->| | |DRI (ns=0, nr=1) | | | Rebooted | | | version 1, | | | extension 1 | | (b) |<-------------------| | |ZLB (ns=0, nr=1) | | (c) |------------------->| | | . |DRI (ns=0, nr=0) | | . | Rebooted | | | version 1, | | | extensions 1, 2 | (d) | |<------------------| | |DRI (ns=0, nr=1) | | | Rebooted | | | version 1, | | | extension 1 | (e) | |------------------>| | |ZLB (ns=0, nr=1) | (f) | |<------------------| |DRI (ns=x, nr=y) | . | | Upcoming Reboot | . | (g) |------------------->| | | . | | | . | | |DRI (ns=0, nr=0) | | | Rebooted | | | version 1, | | | extensions 1, 4 | | (h) |------------------->| | | | | Figure 4: Sample DRI Message Flow in a Proxy Environment (a) DIA1 sends a DRI message to DIA2 indicating that its version is one (1) and that its supported extensions are 1 (Roamops) and 4 (Mobile-IP). (b) DIA2 sends a DRI message to DIA1 indicating that its version is one (1) and that its supported extension is 1 (Roamops). This Calhoun, Rubens, Akhtar expires April 2000 [Page 53] INTERNET DRAFT October 1999 message also includes a piggy-backed acknowledgement of (a). (c) DIA1 sends an acknowledgement of (b) (d) DIA3 sends a DRI message to DIA2 indicating that its version is one (1) and that its supported extensions are 1 (Roamops) and 2 (Secure Proxy). (e) DIA2 sends a DRI message to DIA3 indicating that its version is one (1) and that its supported extension is 1 (Roamops). This message also includes a piggy-backed acknowledgement of (d). (f) DIA3 sends an acknowledgement of (e) (g) after some time DIA1 sends an indication to DIA2 that it is about to reboot. All messages destined to the domain for which DIA1 is responsible for should be redirected to an alternate DIAMETER Server. (h) Once the reboot is complete, DIA sends the DRI, which causes steps (a) through (c) to be repeated. Appendix F Device-Watchdog-Ind Message Flow The following figure provides an example of how the Device-Watchdog- Ind message is used in a proxy environment. The details of each message is provided below. Calhoun, Rubens, Akhtar expires April 2000 [Page 54] INTERNET DRAFT October 1999 +-------+ +-------+ +-------+ | DIA1 | | PROXY | | DIA3 | | | | DIA2 | | | +-------+ +-------+ +-------+ | | | |CMD-X (ns=23, nr=40)| | (a) |------------------->| | |ZLB (ns=40, nr=24) | | (b) |<-------------------| | | . | | | . | | | |CMD-Y (ns=12, nr=20)| (c) | |------------------->| | |ZLB (ns=20, nr=13) | (d) | |<-------------------| |WDI (ns=24, nr=40) | . | (e) |------------------->| . | |ZLB (ns=40, nr=25) | | (f) |<-------------------| | | |WDI (ns=21, nr=13) | (g) | |<-------------------| | |ZLB (ns=13, nr=22) | (h) | |------------------->| | | | Figure 5: Sample WDI Message in a Proxy Environment (a) DIA1 issues a message to DIA2 (b) DIA2 acknowledges the receipt of (a) (c) DIA2 issues a message to DIA3 (d) DIA3 acknowleges the receipt of (c) (e) After some time of inactivity, DIA1 issues a WDI to DIA2 (f) DIA2 acknowledges the receipt of (e) (g) After some period of inactivity, DIA3 issues a WDI to DIA2 (h) DIA2 acknowledges the receipt of (g) Appendix G Message-Reject-Ind Message Flow The following figure show sample flows of MRI command between two DIAMETER peers.In this example DIA1 and DIA2 servers generates error messages. The details of the messages are provided below. Calhoun, Rubens, Akhtar expires April 2000 [Page 55] INTERNET DRAFT October 1999 +-------+ +-------+ | DIA1 | | DIA2 | +-------+ +-------+ | | |Unknown command | (a) |------------------------------------>| |MRI(Unrecognized Command Code) | (b) |<------------------------------------| | . | | . | |Unknown AVP | (c) |<------------------------------------| |MRI(Failed AVP Code) | (d) |------------------------------------>| | . | | . | |Bad value in a valid AVP | (e) |------------------------------------>| |MRI (Error Code | Failed AVP Code) | (f) |<------------------------------------| Figure 6: Sample MRI Message Flow (a) DIA2 receives an unknown command from DIA1. (b) DIA2 recognizes that it received an unknown command and hence sends an MRI with Unrecognized Command Code AVP. (c) DIA1 receives an unknown AVP in a message sent by DIA2. (d) DIA1 recognizes that it received an unknown AVP and returns an MRI with Failed AVP Code to DIA2. (e) DIA2 receives a bad parameter within a otherwise valid AVP from DIA1. (f) As soon as it discovers that it has received a bad parameter, it returns an MRI message to DIA1 with Error Code AVP and Failed AVP Code. Calhoun, Rubens, Akhtar expires April 2000 [Page 56]