INTERNET DRAFT Pat R. Calhoun Category: Standards Track Sun Laboratories, Inc. Title: draft-calhoun-diameter-09.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 any services which require AAA/Policy 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 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, regardless of the specific underlying service. Calhoun, Rubens 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 1.4 Changes in Revision 8 1.5 Changes in Revision 9 2.0 Protocol Overview 2.1 Header Format 2.1.1 ZLB Message Format 2.2 AVP Format 2.3 Error Reporting 3.0 Reliable Transport 3.1 Flow Control 3.2 Suggested implementation 3.3 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-Vector 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-Certificate 5.0 Protocol Definition 5.1 DIAMETER Bootstrap Message 5.1.1 State Machine Calhoun, Rubens expires April 2000 [Page 3] INTERNET DRAFT October 1999 5.2 Keepalive Exchange 5.3 Unrecognized Command Support 5.4 The art of AVP Tagging 5.5 Using the Integrity-Check-Vector 5.6 DIAMETER Proxying 5.7 Message Redirection 5.8 AVP Encryption with Shared Secrets 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 Vector Transform Values 6.7 AVP Header Bits 6.6 Reboot Type Values 7.0 References 8.0 Acknowledgements 9.0 Author's Address 10.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 packets acknowledged B.3 Lost packet with retransmission Calhoun, Rubens expires April 2000 [Page 4] INTERNET DRAFT October 1999 1.0 Introduction Since the RADIUS protocol is being used today for much more than simple authentication and accounting of dial-up users (i.e. authentication of WWW clients, etc), a more extensible protocol was necessary which could support new services being deployed in the internet and corporate networks. RADIUS in itself is not an extensible protocol largely due to its very limited command and attribute address space. In addition, the RADIUS protocol assumes that there cannot be any unsolicited messages from a server to a client. In order to support new services it is imperative that a server be able to send unsolicited messages to clients on a network, and this is a requirement for any DIAMETER implementation. 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 user authentication and [15] which defines extensions to support accounting. 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 AVP The DIAMETER protocol consists of a header followed by objects. Each object is encapsulated in a header known as an Attribute- Value-Pair (AVP). DIAMETER Device Calhoun, Rubens expires April 2000 [Page 5] INTERNET DRAFT October 1999 A Diameter device is a client or server system that supports the Diameter Base protocol and 0 or more extensions. ICV An Integrity Check Vector (ICV) is a hash of the packet with a shared secret. Session The DIAMETER protocol is session based. When an authentication request is initially transmitted, it includes a session identifier that is used for the duration of the session. The Session- Identifier AVP contains the identifier and must be globally unique. Section 4.11 describes the semantics of a session identifier. 1.4 Changes in Revision 8 The following changes were made to version 8 of this specification: - Added text to clear up the Identifier field description. - Clarified the text for all AVPs of type "time". - Added a warning about all "time" AVPs in regards to the end of life of a 32 bit time value. - Added a placeholder in the Session-Id AVP description about the protocol's interactions with NAT. - Renamed the Initialization-Vector AVP to the Nonce AVP. This makes sense since the IV was also used for authentication purposes, and an IV is normally used for encryption purposes. - Added a placeholder to the Nonce AVP section regarding the fact that some crypto transforms have known attacks if there is no random value in the plaintext early within a message. - Clarification of the "Tag" and the "Mandatory" bits in the AVP header. - Added text specifying that the Session-Id AVP can only appear once in a message. - Clarified the conditions that cause a "Bad Packet" situation. Calhoun, Rubens expires April 2000 [Page 6] INTERNET DRAFT October 1999 - Removed all support for TCP. - Removed all references to the 'P' and 'E' bits, given that these bit are defined in the proxy draft, and should not be specified in the base protocol. - The removal of the 'E' bit caused a shift in the bits, changing the AVP header. - A statement was added in the AVP Header definition that new AVP flags may be added in the future and that an unrecognized flag SHOULD be considered an error. - Most AVPs flag field requirements have changed. - Added descriptions for the 'A' bit, the Ns and Nr in the DIAMETER header in section 2.1. - Added section 2.1.1, which describes DIAMETER Acknowledgements. - Added Command-Specific bits in the AVP Header in section 2.2. This will eliminate the overlap problem found between the proxy draft and the authent draft. - Added section 3.0 (Reliable Transport) (from the Reliable Transport document). - Fixed up text in section 3.1 about updating the time in the Timestamp AVP in retransmissions. - Section 4.1 does not allow the Command Code AVP to be encrypted. - Cleaned up some language in section 4.2, describing when a Device-Reboot-Ind should be used. - The Integrity-Check-Vector description now clearly states that any AVPs found after it must be ignored. - Added section 4.21, which is the Receive-Window AVP (from the Reliable Transport document). - Added section 4.22, which is the Proxy-State AVP. This AVP used to be defined in the proxy extension, but has been deemed more appropriate in the base protocol. - The Timestamp AVP (section 4.10) was incorrect since it stated that NTP time started on January 1st, 1970 instead of 1900. Calhoun, Rubens expires April 2000 [Page 7] INTERNET DRAFT October 1999 - Added section 5.1.1 that describes the DIAMETER state machine. - Fixed up a problem in the definition of Hop-by-Hop encryption (section 4.6) since the original text defined using the two octet Command Code instead of four octets. - Added section 5.6, which provides a detailed description of how DIAMETER server should proxy messages. - Added IANA Considerations - Removed all references to the DIAMETER Reliable Transport document. - Added appendix A and B (from the Reliable Transport document). 1.5 Changes in Revision 9 The following changes were made to version 9 of this specification: - Added the missing reference to the Accounting Extension. - Added the DIAMETER_REDIRECT_REQUEST and DIAMETER_PEER_NOT_IN_GOOD_STANDING Result-Code in Section 4.14., - Removed some text in section 4.1.2 that pertained to proxies. The DRI message SHOULD not be proxied. This section also has some small change in the text to state that only packets of extensions supported by the peer should be sent to it. A new sentence stating that the DRI should be periodically transmitted to a peer until an acknowlegement has been received. - Added the Redirect-Host AVP in Section 4.23. - Added the Broker-Certificate AVP in Section 4.24. - Added section 5.7, which describes how the Redirect-Host AVP and the new Result-Code are used. - Added a Device-Reboot-Ind message flow figure and explanation to section 5.1 - Added a Device-Watchdog-Ind message flow figure and explanation to section 5.2 - Added a Message-Reject-Ind message flow figure and explanation to section 5.3 Calhoun, Rubens expires April 2000 [Page 8] INTERNET DRAFT October 1999 2.0 Protocol Overview 2.1 Header Format The base DIAMETER protocol is run over UDP port 1812. Due to the fact that both the client and server can receive unsolicited messages, it is highly recommended that the source and destination field for all DIAMETER messages be 1812. When a request is received, 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. 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 | Packet 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 packets 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 packet PKT Flags The Packet 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 Calhoun, Rubens expires April 2000 [Page 9] INTERNET DRAFT October 1999 DIAMETER be implemented over a reliable transport, the 'W' should not be set. The 'A' bit is set to indicate that the packet 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 The Version field is three bits, and indicates the version number which is associated with the packet received. This field MUST be set to 1 to indicate DIAMETER Version 1. Packet Length The Packet Length field is two octets. It indicates the length of the packet including the header fields. For messages received via UDP, octets outside the range of the Length field should be treated as padding and should be ignored upon receipt. 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 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. The random algorithm used should ensure low probability of duplication. Given the size of the Identifier field it is unlikely that 2^32 requests could be outstanding at any given time. 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. Calhoun, Rubens expires April 2000 [Page 10] INTERNET DRAFT October 1999 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. Consider the following example. +------+ -----> +------+ | | Ns=10 | | | DIA1 +--------------------+ DIA3 | | | Ns=40 | | +------+ <----- +-+----+ / / +------+ / Nr = 41 |Malici| / | ous +-/ | Node | +------+ Figure 1: DIAMETER Message Sequencing In the above figure, DIA3 sends a stream of messages to DIA1, with sequence number 40 being the last message sent. A malicious user could send an acknowledgement for Ns 40 to DIA3, effectively opening up the window. Furthermore, if any of the messages from DIA3 were lost in transit to DIA1, DIA3 would not attempt to retransmit them since it received an acknowledgement. Therefore, it is necessary that all acknowledgement messages also include the same authentication related AVPs are normal DIAMETER messages. The format of a ZLB message will 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. The optional value is implementation specific but may include a modem's device Id, a random value, etc. 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. NOTE: 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. AVP Format Calhoun, Rubens expires April 2000 [Page 35] 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 Code | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | AVP Length | Reserved |T|V|H|M| +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Data ... +-+-+-+-+-+-+-+-+ AVP Code 263 Session-Id AVP Length The length of this attribute MUST be at least 9. AVP Flags The 'M' bit MUST be set. The 'T' and 'H' bits MAY be set. The 'V' bit MUST NOT be set. Data The Data field contains the session identifier assigned to the session. 4.12 Vendor-Name Description The Vendor-Name attribute is used in order 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. AVP Format Calhoun, Rubens expires April 2000 [Page 36] 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 Code | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | AVP Length | Reserved |T|V|H|M| +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | String ... +-+-+-+-+-+-+-+-+ AVP Code 266 Vendor-Name AVP Length The length of this attribute MUST be at least 9. AVP Flags The 'H' bits MAY be set. The 'T', 'V' and 'M' bits MUST NOT be set. String The String field contains the vendor name. 4.13 Firmware-Revision Description The Firmware-Revision AVP 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. AVP Format Calhoun, Rubens expires April 2000 [Page 37] 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 Code | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | AVP Length | Reserved |T|V|H|M| +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Integer32 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ AVP Code 267 Firmware-Revision AVP Length The length of this attribute MUST be at least 12. AVP Flags The 'H' bits MAY be set. The 'T', 'V' and 'M' bits MUST NOT be set. Integer32 The Integer32 field contains the firmware revision number of the issuing device. 4.14 Result-Code Description The Result-Code AVP is used in order to indicate whether a particular command was completed successfully or whether an error occurred. The Result-Code AVP MUST be present in all DIAMETER messages of type -Request or -Answer. AVP Format Calhoun, Rubens expires April 2000 [Page 38] 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 Code | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | AVP Length | Reserved |T|V|H|M| +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Integer32 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ AVP Code 268 Result-Code AVP Length The length of this attribute MUST be 12. AVP Flags The 'M' bit MUST be set. The 'H' bits MAY be set. The 'T' and 'V' bits MUST NOT be set. Integer32 The Integer32 field contains the result code associated with the DIAMETER command. The following codes have been defined: DIAMETER_SUCCESS 0 The Request was successfully completed. DIAMETER_FAILURE 1 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_MAC 3 The Request did not contain a valid Integrity-Check- Vector or Digital-Signature [11]. Calhoun, Rubens expires April 2000 [Page 39] INTERNET DRAFT October 1999 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_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 direct the request directly to the server, whose contact information has been added to the response. DIAMETER_PEER_NOT_IN_GOOD_STANDING 10 A proxy or broker has determined that the request could not be forwarded because the destination DIAMETER server is no longer in good standing. This is typically used by a broker to indicate that the relationship with the requested domain is not longer valid. 4.15 Error-Code Description The Error-Code AVP contains the message specific error code, if Calhoun, Rubens expires April 2000 [Page 40] INTERNET DRAFT October 1999 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. AVP 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 Code | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | AVP Length | Reserved |T|V|H|M| +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Integer32 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ AVP Code 269 Error-Code AVP Length The length of this attribute MUST be 12. AVP Flags The 'M' bit MUST be set. The 'H' bits MAY be set. The 'T' and 'V' bits MUST NOT be set. Integer32 The Integer32 field contains the error code. 4.16 Unrecognized-Command-Code Description The Unrecognized-Command-Code AVP contains the offending Command Code that resulted in sending the Message-Reject-Ind message. AVP Format Calhoun, Rubens expires April 2000 [Page 41] 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 Code | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | AVP Length | Reserved |T|V|H|M| +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Integer32 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ AVP Code 270 Unrecognized-Command-Code AVP Length The length of this attribute MUST be 12. AVP Flags The 'M' bit MUST be set. The 'H' bits MAY be set. The 'T' and 'V' bits MUST NOT be set. Integer32 The Integer32 field contains the unrecognized command code that resulted in sending an Message-Reject-Ind message. 4.17 Reboot-Type Description The Reboot-Type AVP MUST be present in the Device-Reboot- Indication message and contains an indication of the type of reboot. AVP 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 Code | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | AVP Length | Reserved |T|V|H|M| +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Integer32 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Calhoun, Rubens expires April 2000 [Page 42] INTERNET DRAFT October 1999 AVP Code 271 Reboot-Type AVP Length The length of this attribute MUST be 12. AVP Flags The 'M' bit MUST be set. The 'H' bits MAY be set. The 'T' and 'V' bits MUST NOT be set. Integer32 The Integer32 field contains the reboot type associated with the DRI command. The following value are currently defined: 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 ready to accept new DIAMETER messages. CLEAN_REBOOT 3 When the Reboot-Type AVP is set to this value the server is in the process of shutting down and MAY be available at some time in the future. 4.18 Reboot-Time Description The Reboot-Time AVP MAY be present in the DRI and indicates the number of seconds before the issuer expects to be ready to receive new DIAMETER messages. This AVP MUST 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. AVP Format Calhoun, Rubens expires April 2000 [Page 43] 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 Code | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | AVP Length | Reserved |T|V|H|M| +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Integer32 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ AVP Code 272 Reboot-Time AVP Length The length of this attribute MUST be 12. AVP Flags The 'M' bit MUST be set. The 'H' bits MAY be set. The 'T' and 'V' bits MUST NOT be set. Integer32 The Integer32 field contains the expected amount of seconds before the issuer of the DRI expects to be receive to receive new DIAMETER messages. 4.19 Failed-AVP-Code Description The Failed-AVP-Code AVP 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. This AVP has the following format: AVP Format Calhoun, Rubens expires April 2000 [Page 44] 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 Code | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | AVP Length | Reserved |T|V|H|M| +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Data... +-+-+-+-+-+-+-+-+ AVP Code 279 Failed-AVP-Code AVP Length The length of this attribute MUST be 12. AVP Flags The 'M' bit MUST be set. The 'H' bits MAY be set. The 'T' and 'V' bits MUST NOT be set. Data 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 Description This attribute contains the User-Name in a format consistent with the NAI specification [8]. A summary of the User-Name AVP format is shown below. The fields are transmitted from left to right. AVP 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 Code | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Calhoun, Rubens expires April 2000 [Page 45] INTERNET DRAFT October 1999 | AVP Length | Reserved |T|V|H|M| +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | String ... +-+-+-+-+-+-+-+-+ Type 1 for User-Name. AVP Length The length of this AVP MUST be at least 9. AVP Flags The 'M' bit MUST be set. The 'H' bits MAY be set. The 'T' and 'V' bits MUST NOT be set. String The String field is one or more octets. All DIAMETER systems SHOULD support User-Name lengths of at least 63 octets. The format of the User-Name SHOULD follow the format defined in [8]. 4.21 Receive-Window Description This AVP is used by a peer to inform its peer of its local receive window size. The size indicated is the number of packets that it is willing to accept before the window is full. A sending peer MUST stop sending new DIAMETER messages when this many messages are outstanding (sent but not yet acknowledged). If a peer does not issue this attribute, a receive window size of 7 is assumed by its peer. This attribute is only valid in the Device-Reboot-Ind message. AVP Format Calhoun, Rubens expires April 2000 [Page 46] 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 Code | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | AVP Length | Reserved |T|V|H|M| +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Integer32 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ AVP Code 277 Receive-Window AVP Length The length of this attribute MUST be 12. AVP Flags The 'M' bit MUST be set. The 'H' bits MAY be set. The 'T' and 'V' bits MUST NOT be set. Integer32 This field contains the receive window size. 4.22 Proxy-State Description The Proxy-State AVP 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 implmentations 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. Calhoun, Rubens expires April 2000 [Page 47] INTERNET DRAFT October 1999 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. AVP Format A summary of the Proxy-State AVP format is shown below. The fields are transmitted from left to right. 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 | Reserved |T|V|H|M| +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Address | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Data ... +-+-+-+-+-+-+-+-+ AVP Code 33 for Proxy-State. AVP Length The length of this attribute MUST be at least 13. AVP Flags The 'M' bit MUST be set. The 'V', 'H' and 'T' bits MUST NOT be set. Address The Address field contains the IP Address of the system that created the Proxy-State AVP. 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 a robust implementation SHOULD support the field as undistinguished octets. Calhoun, Rubens expires April 2000 [Page 48] INTERNET DRAFT October 1999 4.23 Redirect-Host Description The Redirect-Host AVP is returned in a response that has the Result-Code AVP set to DIAMETER_REDIRECT_REQUEST, and includes 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, whose address information is found in this AVP. A proxy server returning such an AVP may include more than one, if there is a group of DIAMETER servers that can satisfy the request. AVP Format A summary of the Redirect-Host AVP format is shown below. The fields are transmitted from left to right. 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 | Reserved |T|V|H|M| +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Address | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ AVP Code 278 for Redirect-Host. AVP Length The length of this attribute MUST be at least 12. AVP Flags The 'M' bit MUST be set. The 'V', 'H' and 'T' bits MUST NOT be set. Address The Address field contains the IP Address of a DIAMETER server that can satisfy the request that generated the response containing this AVP. Calhoun, Rubens expires April 2000 [Page 49] INTERNET DRAFT October 1999 4.24 Broker-Certificate Description The Broker-Certificate AVP 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- 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.7 for more information). AVP Format A summary of the Broker-Certificate AVP format is shown below. The fields are transmitted from left to right. 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 | Reserved |T|V|H|M| +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Timestamp | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Expiration Time | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Certificate Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Digital Signature Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Certificate ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Digital Signature ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ AVP Code 280 for Broker-Certificate. AVP Length The length of this attribute MUST be at least 24. AVP Flags Calhoun, Rubens expires April 2000 [Page 50] INTERNET DRAFT October 1999 The 'M' bit MUST be set. The 'V', 'H' and 'T' bits MUST NOT be set. Timestamp The Timestamp field contains the number of seconds since Jan. 1, 1900 when the AVP was created. Expiration The Expiration field contains the time after which the broker recommends that a new Broker-Certificate be retrieved. 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. Digital-Signature The Digital-Signature field contains the broker's digital signature. 5.0 Protocol Definition This section will describe how the base protocol works (or is at least an attempt to). 5.1 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 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 Calhoun, Rubens expires April 2000 [Page 51] INTERNET DRAFT October 1999 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. 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 DIA, and later DIA3 initiates the bootstrap sequence with DIA. After some time DIA1 needs to reboot and informs DIA2. The details of each message is provided below. Calhoun, Rubens 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 2: 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 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 DIA1 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) DIA1 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. 5.1.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. 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 Calhoun, Rubens expires April 2000 [Page 54] INTERNET DRAFT October 1999 wait-ack2 received ACK Accept Incoming open Messages open receive DRI cleanup closed open receive DWI send ACK open open receive other send ACK open messages 5.2 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. A DIAMETER Client can use this mechanism to ensure that failover 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. The following figure provides an example of how the Device-Watchdog- Ind message is used in a proxy environment. 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 to have a different inactivity timer configured. The more aggresive the timer, the more traffic is generated, but the quicker it can detect if a peer is no longer reachable. The details of each message is provided below. Calhoun, Rubens expires April 2000 [Page 55] 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 3: Sample WDI Message in a Proxy Environment (a) DIA1 issues a packet to DIA2 (b) DIA2 acknowledges the receipt of (a) (c) DIA3 issues a packet to DIA2 (d) DIA2 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) 5.3 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. The following provides a DIAMETER message that is sent to a Calhoun, Rubens expires April 2000 [Page 56] INTERNET DRAFT October 1999 peer: ::= [] { || ::= [] { || | |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 4: 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. 5.4 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 Calhoun, Rubens expires April 2000 [Page 58] INTERNET DRAFT October 1999 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 Using the Integrity-Check-Vector The use of the Integrity-Check-Vector (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. 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-Vector AVP. The Data field of the AVP contains an HMAC-MD5-96[6] of the message up to the ICV AVP. Using the example code provided in [6], the following call would be used to generate the Integrity-Check-Vector: The Timestamp and Nonce AVPs MUST be present in the message PRIOR to the Integrity-Check-Vector AVP. The Timestamp AVP provides replay protection and the Nonce AVP provides randomness. hmac_md5(DiameterMessage, MessageLength, Secret, Secretlength, 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- Vector AVP MUST be ignored. Calhoun, Rubens expires April 2000 [Page 59] INTERNET DRAFT October 1999 5.6 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 normally will extract that domain name 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 5: DIAMETER Proxying Prior to forwarding the request, DIA2 must establish some state information in order to be able to forward the corresponding response 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. Althought 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. Calhoun, Rubens expires April 2000 [Page 60] INTERNET DRAFT October 1999 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.7 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 x). This is typically done when the broker provides simple NAI to Home DIAMETER Server address resolution services. +------------------+ +---------+ | DIAMETER | | CRL DB/ | | Broker | | OCSP | +------------------+ +---------+ /|( Request | Response w/ | Result Code = | Redirect / +----------+ +----------+ | abc.net |/ xyz.net | | DIAMETER |--------------| DIAMETER | | Server | /| Server | +----------+ Direct +----------+ Communication Figure 6: DIAMETER Broker Returning Redirect Indication In the example provided in figure 6, 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 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. When returning the response with the Result-Code set to indicate a redirect indication, the broker can also include the certificates of Calhoun, Rubens expires April 2000 [Page 61] INTERNET DRAFT October 1999 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. 5.8 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 ClearText Data | ClearText Data ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Padding ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Length The Length field contains the length of the decrypted data. ClearText Data Data of AVP that is to be obscured. Padding Random additional octets used to obscure length of the ClearText Data. The resulting subformat MAY be padded to a multiple of 16 octets in Calhoun, Rubens expires April 2000 [Page 62] INTERNET DRAFT October 1999 length. For example, if the ClearText 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]. 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. Calhoun, Rubens expires April 2000 [Page 63] INTERNET DRAFT October 1999 (Shared-Secret-1) (Shared-Secret-2) +------+ -----> +------+ ------> +------+ | | | | | | | DIA1 +-------------------+ DIA2 +-------------------+ DIA3 | | | | | | | +------+ +------+ +------+ Figure 7: Message Forwarding Unfortunately in this case the non-trusted server DIA2 has access to sensitive information (such as a password). 6.0 IANA Considerations This document defines a number of "magic" 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 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 IETF Consensus [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 IETF Consensus [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 IETF Consensus [12]. Calhoun, Rubens expires April 2000 [Page 64] INTERNET DRAFT October 1999 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 Vector Transform Values Section 4.8 defines the Integrity-Check-Vector 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 IETF Consensus [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 IETF Consensus [12]. 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 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, Dusse, "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, August 1999. [8] Aboba, Beadles "The Network Access Identifier." RFC 2486. January 1999. [9] Calhoun, Zorn, Pan, "DIAMETER Framework", Calhoun, Rubens expires April 2000 [Page 65] INTERNET DRAFT October 1999 draft-calhoun-diameter-framework-02.txt, Work in Progress, December 1998. [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 Proxy Extension", draft-calhoun-diameter-proxy-02.txt, Work in Progress, August 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. 8.0 Acknowledgements The Authors would 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, Erik Guttman, Peter Heitman, Paul Krumviede, Fergal Ladley, Ryan Moats, Victor Muslin, Kenneth Peirce, Nenad Trifunovic, Sumit Vakil, John R. Vollbrecht, Jeff Weisberg and Glen Zorn 9.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 Calhoun, Rubens expires April 2000 [Page 66] INTERNET DRAFT October 1999 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 10.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 implmentation may be prepared, copied, published and distributed, in whole or in part, without 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 Calhoun, Rubens expires April 2000 [Page 67] INTERNET DRAFT October 1999 WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE." 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 packets. 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 backoff 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 packet 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 backoff on timeout to reduce congestion. The backed-off timer value is limited by the configurable maximum timeout value. Timer backoff 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 packets are delivered without errors. Calhoun, Rubens expires April 2000 [Page 68] INTERNET DRAFT October 1999 A.1 Calculating Adaptive Acknowledgment Timeout We must decide how much time to allow for acknowledgments to return. If the timeout is set too high, we may wait an unnecessarily long time for dropped packets. 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 packet. 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 packet. ATO is calculated on each iteration. Its value is limited, by the MIN function, to be a maximum of the configured 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 packet that was not retransmitted Calhoun, Rubens expires April 2000 [Page 69] INTERNET DRAFT October 1999 (no timeout occured). 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 backoff 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 backoff 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 expires April 2000 [Page 70] 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 packets acknowledged This example shows a flow of packets 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 packets seen since the last interval. DIAMETER Host A DIAMETER Host B (previous packet 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 packet 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 expires April 2000 [Page 71] INTERNET DRAFT October 1999 DIAMETER Host A DIAMETER Host B -> Device-Reboot-Ind Nr: 0, Ns: 0 (packet 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 packet) (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 Calhoun, Rubens expires April 2000 [Page 72]