INTERNET DRAFT Pat R. Calhoun Category: Standards Track Sun Microsystems, Inc. Title: draft-calhoun-diameter-05.txt Allan C. Rubens Date: July 1998 Ascend Communications DIAMETER Base Protocol Status of this Memo This document is an Internet-Draft. 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.'' To learn the current status of any Internet-Draft, please check the ``1id-abstracts.txt'' listing contained in the Internet-Drafts Shadow Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe), munnari.oz.au (Pacific Rim), ftp.ietf.org (US East Coast), or ftp.isi.edu (US West Coast). Abstract The DIAMETER base protocol is intended to provide a framework for any services which require AAA/Policy support. The protocol is inteded to be flexible enough to allow services to add building blocks to DIAMETER in order to meet their requirements. This draft MUST be supported by all DIAMETER implementations, regardless of the specific underlying service. Calhoun, Rubens expires January 1999 [Page 1] INTERNET DRAFT July 1998 Table of Contents 1.0 Introduction 1.1 Definitions 1.2 Terminology 2.0 Protocol Overview 2.1 Header Format 2.2 AVP Format 3.0 DIAMETER AVPs 3.1 DIAMETER-Command AVP 3.1.1 Unrecognized-Command-Ind 3.1.2 Device-Reboot-Ind 3.1.3 Device-Watchdog-Ind 3.1.6 Device-Config-Req 3.1.7 Device-Config-Answer 3.2 Host-IP-Address 3.3 Host-Name 3.4 State 3.5 Class 3.6 Session-Timeout 3.7 Version-Number 3.8 Extension-Id 3.9 Integrity-Check-Vector 3.10 Initialization-Vector 3.11 Timestamp 3.12 Session-Id 3.13 Vendor-Name 3.14 Firmware-Revision 3.15 Result-Code 3.16 Error-Code 3.17 Unrecognized-Command-Code 3.18 Reboot-Type 3.19 Reboot-Time 4.0 Protocol Definition 4.1 DIAMETER Bootstrap Message 4.2 Keepalive Exchange 4.3 Unrecognized Command Support 4.4 The art of AVP Tagging 4.5 Using the Integrity-Check-Vector 4.6 AVP Encryption with Shared Secrets 5.0 References 6.0 Acknowledgements 7.0 Author's Address 1.0 Introduction Since the RADIUS protocol is being used today for much more than Calhoun, Rubens expires January 1999 [Page 2] INTERNET DRAFT July 1998 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. 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] which defines extensions to the base protocol to support user authentication and [XXX] which defines extensions to support accounting. 1.1 Definitions In this document, several words are used to signify the requirements of the specification. These words are often capitalized. MUST This word, or the adjective "required", means that the definition is an absolute requirement of the specification. MUST NOT This phrase means that the definition is an absolute prohibition of the specification. SHOULD This word, or the adjective "recommended", means that there may exist valid reasons in particular circumstances to ignore this item, but the full implications must be understood and carefully weighed before choosing a different course. MAY This word, or the adjective "optional", means that this item is one of an allowed set of alternatives. An implementation which does not include this option MUST be prepared to interoperate with another implementation which does include the option. 1.2 Terminology Calhoun, Rubens expires January 1999 [Page 3] INTERNET DRAFT July 1998 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 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. 2.0 Protocol Overview 2.1 Header Format DIAMETER packets MAY be transmitted over UDP or TCP. Each Service Extensions draft SHOULD specify the transport layer. The destination port field for DIAMETER is 1812. For UDP, when a reply is generated the source and destination ports 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 |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 RADIUS backward compatibility. In order to easily distinguish Calhoun, Rubens expires January 1999 [Page 4] INTERNET DRAFT July 1998 DIAMETER packets from RADIUS a special value has been reserved and allows an implementation to support both protocols concurently 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 is set when the Next Send (Ns) and Next Received (Nr) fields are present in the header. This SHOULD be set unless the underlying layer provides reliability (i.e. TCP). 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, but using a random value is also permitted. 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 defined in [12]. Next Received This field is defined in [12]. Calhoun, Rubens expires January 1999 [Page 5] INTERNET DRAFT July 1998 AVPs AVPs is a method of encapsulating information relevant to the DIAMETER message. See section 2.2 for more information on AVPs. 2.2 AVP Format DIAMETER Attributes carry specific authentication, accounting and authorization information as well as configuration details for the request and reply. Some Attributes MAY be listed more than once. The effect of this is Attribute specific, and is specified in each case by the attribute description. Each AVP MUST be padded to align on a 32 bit boundary. Although this is not problematic for most attribute types, it does require that AVP of string and data type be padded with zeroes accordingly. The Padding size can be calculated using the following formula: if( Length mod 4 != 0 ) padding_size = 4 - ( Length mod 0 ) else padding_size = 0 The end of the list of attributes is defined by the length of the DIAMETER packet minus the length of the header. The attribute 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 | Reserved |P|T|V|E|H|M| +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Vendor ID (opt) | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Tag (opt) | Data... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ AVP Code The AVP Code field is four octets. The first 256 AVP numbers are reserved for backward RADIUS compatibility. Up-to-date values of Calhoun, Rubens expires January 1999 [Page 6] INTERNET DRAFT July 1998 the RADIUS Type field are specified in the most recent "Assigned Numbers" RFC [2]. AVP numbers 256 and above are used for DIAMETER. Each service MUST allocate AVP numbers through the IANA. If the Vendor-Specific-AVP flag is set, the AVP Code is allocated from the vendor's private address space. AVP Length The AVP Length field is two octets, and indicates the length of this Attribute including the Address Type, AVP Length, AVP Flags, Reserved, Vendor ID if present and the AVP data. If a packet is received with an Invalid attribute length, the packet SHOULD be rejected. Reserved The Reserved field MUST be set to zero (0). AVP Flags The AVP Flags field informs the DIAMETER host how each attribute must be handled. 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 request 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. When the 'E' bit is enabled it indicates that the AVP data is encrypted using end-to-end encryption. See [13] 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. Calhoun, Rubens expires January 1999 [Page 7] INTERNET DRAFT July 1998 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. The 'P' bit, known as the protected AVP bit, is used to indicate whether the AVP is protected by a Digital Signature AVP. When set, the AVP is protected and the contents cannot be changed by a DIAMETER proxy server. See [13] for more information. Vendor ID The optional four octet Vendor ID field contains the the IANA assigned "SMI Network Management Private Enterprise Codes" 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 collide with any other vendor's extensions, nor with future IETF extensions. The value zero, reserved in this protocol, corresponds to IETF adopted Attribute values, defined within this document; zero MUST NOT be used in an AVP. Tag The Tag field is two octet in length and is intended to provide a means of grouping attributes in the same packet which refer to the same tunnel. Valid values for this field are 0x01 through 0x1FFFFFFF, inclusive. If the Tag field is unused, the 'T' bit MUST NOT be set.. Data 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. 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 0-65526 octets of arbitrary data. String 0-65526 octets of string data using the UTF-8 character set. Calhoun, Rubens expires January 1999 [Page 8] INTERNET DRAFT July 1998 Address 32 bit or 48 bit value, most significant octet first. The length of the attribute is determined by the length. Integer32 32 bit value, most significant octet first. Integer64 64 bit value, most significant octet first. Time 32 bit value, most significant octet first -- seconds since 00:00:00 GMT, January 1, 1970. 3.0 DIAMETER AVPs This section will define the mandatory AVPs which MUST be supported by all DIAMETER implementations. Note the first 256 AVP numbers are reserved for RADIUS compatibility. The following AVPs are defined in this document: Attribute Name Attribute Code ----------------------------------- DIAMETER-Command 256 Host-IP-Address 4 Host-Name 32 State 24 Class 25 Session-Timeout 27 Version-Number 257 Extension-Id 258 Integrity-Check-Vector 259 Initialization-Vector 261 Timestamp 262 Session-Id 263 Vendor-Name 266 Firmware-Revision 267 Result-Code 268 Error-Code 269 Unknown-Command-Code 270 Reboot-Type 271 Reboot-Time 272 Calhoun, Rubens expires January 1999 [Page 9] INTERNET DRAFT July 1998 3.1 DIAMETER-Command AVP Description The 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. There MUST only be a single Command AVP within a given message. The format of the AVP is as follows: 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 |U|T|V|E|H|M| +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Command Code | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ AVP Code 256 DIAMETER-Command 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 'H' and 'E' MAY be set depending upon the security model used. The 'V' MAY be set if the Command Code is vendor specific. The 'T' and the 'P' 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 ----------------------------------- Command-Unrecognized-Ind 256 Device-Reboot-Ind 257 Device-Watchdog-Ind 258 Calhoun, Rubens expires January 1999 [Page 10] INTERNET DRAFT July 1998 3.1.1 Command-Unrecognized-Ind (CUI) Description Messages with the Command-Unrecognized AVP MUST be sent by a DIAMETER device to inform its peer that a message was received with an unsupported Command AVP value. Since there certainly will exist a case where an existing device does not support a new extension to the DIAMETER protocol, a device which receives a packet with an unrecognized Command code MUST return a Command-Unrecognized packet. This Command MUST also include the Unknown-Command-Code AVP. A summary of the Command-Unrecognized packet format is shown below. The fields are transmitted from left to right. Message Format ::= [] { || ::= [] [] [] [] { || ::= [] { || 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. In most cases this is performed by the client. Note that a Session-Id can be used by more than one extension. 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 |U|T|V|E|H|M| +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Data ... +-+-+-+-+-+-+-+-+ AVP Code 263 Session-Id AVP Length The length of this attribute MUST be at least 9. Calhoun, Rubens expires January 1999 [Page 25] INTERNET DRAFT July 1998 AVP Flags The 'M' bit MUST be set. The 'H' and 'E' MAY be set depending upon the security model used. The 'V', 'T' and the 'P' bits MUST NOT be set. Data The Data field contains the session identifier assigned to the session. 3.13 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 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 |U|T|V|E|H|M| +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | String ... +-+-+-+-+-+-+-+-+ AVP Code 266 Vendor-Name AVP Length The length of this attribute MUST be at least 9. AVP Flags The 'H' and 'E' MAY be set depending upon the security model Calhoun, Rubens expires January 1999 [Page 26] INTERNET DRAFT July 1998 used. The String The String field contains the vendor name. 3.14 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 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 |U|T|V|E|H|M| +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Integer32 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ AVP Code 267 Firmware-Revision AVP Length The length of this attribute MUST be at least 12. AVP Flags The 'H' and 'E' MAY be set depending upon the security model used. The Integer32 The Integer32 field contains the firmware revision number of the issuing device. Calhoun, Rubens expires January 1999 [Page 27] INTERNET DRAFT July 1998 3.15 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. All DIAMETER commands MUST specify whether the Result- Code AVP MUST be present. 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 |U|T|V|E|H|M| +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Integer32 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ AVP Code 268 Result-Code AVP Length The length of this attribute MUST be at least 12. AVP Flags The 'M' bit MUST be set. The 'H' and 'E' MAY be set depending upon the security model used. The 'V', 'T' and the 'P' 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. DIAMETER_POOR_REQUEST 2 Calhoun, Rubens expires January 1999 [Page 28] INTERNET DRAFT July 1998 The Request was poorly constructed. DIAMETER_INVALID_MAC 3 The Request did not contain a valid Integrity-Check- Vector or Digital-Signature [13]. DIAMETER_UNKNOWN_SESSION_ID 4 The Request contained an unknown Session-Id. DIAMETER_SEE_ERROR_CODE 5 The Request failed. See the Error-Code AVP for more info. 3.16 Error-Code Description The Error-Code AVP 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. 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 |U|T|V|E|H|M| +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Integer32 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ AVP Code 269 Error-Code AVP Length The length of this attribute MUST be at least 12. AVP Flags The 'M' bit MUST be set. The 'H' and 'E' MAY be set depending upon the security model used. The 'V', 'T' and the 'P' bits MUST NOT be set. Integer32 Calhoun, Rubens expires January 1999 [Page 29] INTERNET DRAFT July 1998 The Integer32 field contains the error code. 3.17 Unknown-Command-Code Description The Unknown-Command-Code AVP contains the offending Command Code that resulted in sending the Unrecognized-Command-Code message. 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 |U|T|V|E|H|M| +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Integer32 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ AVP Code 270 Unknown-Command-Code AVP Length The length of this attribute MUST be 12. AVP Flags The 'M' bit MUST be set. The 'H' and 'E' MAY be set depending upon the security model used. The 'V', 'T' and the 'P' bits MUST NOT be set. Integer32 The Integer32 field contains the unrecognized command code that resulted in sending an Unrecognized-Command-Code message. 3.18 Reboot-Type Description The Reboot-Type AVP MUST be present in the Device-Reboot- Indication message and contains an indication of the type of Calhoun, Rubens expires January 1999 [Page 30] INTERNET DRAFT July 1998 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 |U|T|V|E|H|M| +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Integer32 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 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' and 'E' MAY be set depending upon the security model used. The 'V', 'T' and the 'P' 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. Calhoun, Rubens expires January 1999 [Page 31] INTERNET DRAFT July 1998 3.19 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 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 |U|T|V|E|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' and 'E' MAY be set depending upon the security model used. The 'V', 'T' and the 'P' 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.0 Protocol Definition This section will describe how the base protocol works (or is at least an attempt to). Calhoun, Rubens expires January 1999 [Page 32] INTERNET DRAFT July 1998 4.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 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. 4.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. Redundant DIAMETER Servers use this mechanism to identify when the primary server is no longer available. Calhoun, Rubens expires January 1999 [Page 33] INTERNET DRAFT July 1998 The DIAMETER Device-Watchdog-Ind message does not require a reply. The message is acknowledged using DIAMETER's reliable transport. 4.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 peer: ::= [] { || ::= [] { || ::= [] Any AVPs in a message that is not succeeded by the Integrity-Check- Vector AVP MUST be ignored. 4.6 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. Calhoun, Rubens expires January 1999 [Page 35] INTERNET DRAFT July 1998 The SS-Encrypted-Data bit MUST only be set if a shared secret exists between both DIAMETER peers. If the SS-Encrypted-Data bit is set in any DIAMETER AVP, the Initialization-Vector 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: 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 length. For example, if the ClearText Data to be obscured is a string containing 6 characters (e.g. password 'foobar'), then 8 + n * 16 octects 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 two 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 Initialization-Vector AVP. This Initialization- Vector AVP must be placed in the message by the sender before any hidden AVPs. The same Initialization-Vector may be used for more than one hidden AVP in the same message. If a different Initialization- Vector is used for the hiding of subsequent AVPs then a new Calhoun, Rubens expires January 1999 [Page 36] INTERNET DRAFT July 1998 Initialization-Vector 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 Initialization-Vector is taken from the last Initialization-Vector 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. (Shared-Secret-1) (Shared-Secret-2) +------+ -----> +------+ ------> +------+ | | | | | | | DIA1 +-------------------+ DIA2 +-------------------+ DIA3 | | | | | | | +------+ +------+ +------+ Unfortunately in this case the non-trusted server DIA2 has access to sensitive information (such as a password). 5.0 References [1] Rigney, et alia, "RADIUS", RFC-2138, April 1997 Calhoun, Rubens expires January 1999 [Page 37] INTERNET DRAFT July 1998 [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-03.txt, May 1998. [8] Aboba, Beadles, "Network Address Identifier", Internet-Draft, draft-ietf-roamops-nai-10.txt, February 1998. [9] Kaliski, "PKCS #1: RSA Encryption Version 1.5", Internet- Draft, draft-hoffman-pkcs-rsa-encrypt-03.txt, October 1997. [10] Calhoun, Zorn, Pan, "DIAMETER Framework", Internet- Draft, draft-calhoun-diameter-framework-00.txt, May 1998 [11] Zorn, Leifer, Rubens, Shriver, "RADIUS attributes for Tunnel Protocol Support", Internet-Draft, draft-ietf-radius-tunnel-auth-05.txt, April 1998. [12] Calhoun, Bulley, "DIAMETER Reliable Transport Extension", Internet-Draft, draft-calhoun-diameter-reliable-00.txt, August 1998. [13] Calhoun, Bulley, "DIAMETER Proxy Extension". Internet- Draft, draft-calhoun-diameter-proxy-00.txt, August 1998. 6.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, Nancy Greene, Peter Heitman, Ryan Moats, Victor Muslin, Kenneth Peirce, Sumit Vakil, John R. Vollbrecht, Jeff Weisberg and Glen Zorn 7.0 Author's Address Questions about this memo can be directed to: Pat R. Calhoun Technology Development Sun Microsystems, Inc. 15 Network Circle Menlo Park, California, 94025 USA Calhoun, Rubens expires January 1999 [Page 38] INTERNET DRAFT July 1998 Phone: 1-650-786-7733 Fax: 1-650-786-6445 E-mail: pcalhoun@eng.sun.com Allan C. Rubens Ascend Communications 1678 Broadway Ann Arbor, MI 48105-1812 USA Phone: 1-734-761-6025 E-Mail: acr@del.com Calhoun, Rubens expires January 1999 [Page 39]