Internet Draft Pat R. Calhoun Category: Experimental US Robotics Access Corp. expires in six months Allan Rubens Merit Network Inc. March 1997 DIAMETER Status of this Memo Distribution of this memo is unlimited. 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 ds.internic.net (US East Coast), nic.nordu.net (Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific Rim). Abstract This original document was named Enhanced RADIUS and was changed at the request of the WG since this protocol is different from the former. This document describes a management protocol used between Network Access Servers and DIAMETER Servers for authentication, authorization, accounting of dial-up users. A considerable amount of effort was put into the design of this protocol to ensure that an implementation could support both DIAMETER and RADIUS at the same time. Calhoun, Rubens expires in six months [Page 1] DRAFT DIAMETER March 1997 1. 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 WEB 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 will describe the packet headers for the DIAMETER protocol as well as any commands and attributes which MUST be supported. Note that this document in itself is not complete and MUST be used with the RADIUS RFC[1] which describes the authentication and accounting messages as well as the necessary attributes. 1.1. Specification of Requirements 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. Calhoun, Rubens expires in six months [Page 2] DRAFT DIAMETER March 1997 2. Packet Format Exactly one DIAMETER packet is encapsulated in the Data field of a UDP Packet[3], where the UDP Destination Port field indicates 1645. 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 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Code | Flags | Ver | Command | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Identifier | Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | | Authenticator | | | | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | | Message Integrity Code | | | | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Attributes ... +-+-+-+-+-+-+-+-+-+-+-+-+- Code The Code field is a one octet field which is used in the RADIUS protocol to identify the command type. In order to easily distinguish DIAMETER packets from RADIUS a special value has been reserved. A Server implementation can now support both RADIUS and DIAMETER and identify the packet type by looking at the first octet in the header. The Code field MUST be set as follow: 254 DIAMETER packet Calhoun, Rubens expires in six months [Page 3] DRAFT DIAMETER March 1997 Flags The Flags field is five bits, and is used in order to identify any options. This field MUST be set to zero unless any options are used. The following flags are defined globally for all commands: 0x1 - (Bit 12) TimeStamp is included in the Authenticator Field. 0x2 - (Bit 11) All attributes in packets are encrypted. When the encryption feature is set, all data following the DIAMETER header is XORed using MD5 with the shared secret (see section 3). 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 2. Command The Command field is two octet, and identifies the type of DIAMETER packet. When a packet is received with an invalid Code field, a Command-Unrecognized message SHOULD be returned. See section 4 for a list of supported commands. Identifier The Identifier field is two octets, and aids in matching requests and replies. Length The Length field is two octets. It indicates the length of the packet including the header fields. Octets outside the range of the Length field should be treated as padding and should be ignored on reception. Authenticator The Authenticator field is a random 16 octet value. This field adds randomness to the packets and makes the guessing of the shared secret much more diffcult to the malicious user. If the Timestamp option is supported, the first four octets contains a timestamp of when the packet was sent from the peer. This allows the protocol to detect replay attacks. The Timestamp value is the current time relative to a base of 0:0:0 GMT January 1, 1900. Calhoun, Rubens expires in six months [Page 4] DRAFT DIAMETER March 1997 Message Integrity Code (MIC) This field contains an MD5 hash of the following: MD5( packet | Shared Secret ) When creating a message, the MIC must be set to all zeros before calculating the MD5 hash. When receiving a message, the receiver must save the MIC, set the field to all zeroes and perform the hash function. The resulting value MUST be identical to the value which was in the message. Attributes See section 6 for more information of attribute formats. 3. Data Encryption When the encryption flag is enabled (either for a specific attribute or for all attributes following the header) the MD5[4] algorithm is used. However, since the MD5 algorithm works specifically with strings of up to 16 octets and most attributes will have a length of greater than 16 octets, the following method is used: e(1) = MD5( SS | IV ) v(1) = d(1) XOR e(1) e(2) = MD5( SS | v(1) ) v(2) = d(2) XOR e(2) . . . e(x) = MD5( SS | v(x) ) v(x) = d(x) XOR e(x) Where: | - Concatenate SS - Shared Secret IV - Initialization Vector, this value is derived from the Authenticator field in the Diameter header. d(n) - data partitioned into 16 octets chunks. This value MUST be padded with NULLs to 16 characters if the length is less than 16 octets. e(n) - 16 octet hash resulting from the MD5 algorithm v(n) - 16 octet encrypted data Calhoun, Rubens expires in six months [Page 5] DRAFT DIAMETER March 1997 The above formula MUST be executed in order to encrypt the data. The number of times which the formula must be executed is length/16. In the case of attribute encryption, only the data following the attribute header is encrypted. In the case of the encryption bit set in the header, all data following the header is passed through the above formula. Which ever the case, it is imperative that the data be padded with NULLs to a 16 octet boundary. The encrypted data MUST then be concatenated as v(1)|v(2)|...v(x). Since this process is reverseable, the receiver MUST inverse the process in order to extract the data from the encrypted hash. Read [5] for more information on the use of this algorithm, 4. Command Name and Command Code Command Name: Command-Unrecognized Command Code: 256 Command Name: NAS-Reboot-Indicationr Command Code: 267 Command Name: NAS-Reboot-Ack Command Code: 268 Command Name: Vendor-Specific Command Code: 269 5. Command Meanings The DIAMETER Packet type is determined by the Command Code field in the second and third octets of the Packet. This section will not describe the existing RADIUS codes as defined in [1]. 5.1. Command-Unrecognized Description Command-Unrecognized packets are sent by the NAS or the DIAMETER server to inform its peer that a previous packet received is unrecognized. Calhoun, Rubens expires in six months [Page 6] DRAFT DIAMETER March 1997 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. For backward compatibility with RADIUS, a device SHOULD support the fact that its peer may silently discard the packet. A summary of the Command-Unrecognized packet 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 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Code | Flags | Ver | Command | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Identifier | Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | | Authenticator | | | | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | | Message Integrity Code | | | | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Code 254 for DIAMETER. Flags The Flag field is used as described above. Version MUST be set to 2 Command 256 for Command-Unrecognized. Calhoun, Rubens expires in six months [Page 7] DRAFT DIAMETER March 1997 Identifier The Identifier field is a copy of the Identifier field of the packet which caused this event. Length The total length of the message, including this header. Authenticator The Authenticator field is a random 16 octet value. If the Timestamp option is supported, the first four octets contains a timestamp of when the packet was sent from the peer. Message Integrity Code This field contains an MD5 hash of the following: MD5( packet | Shared Secret ) 5.2. NAS-Reboot-Indication Description The NAS-Reboot-Indication message is sent from the NAS to the DIAMETER Server in order for the NAS to inform the local server that it has rebooted. The server MUST respond to the message with a successful acknowledge, indicating its version. This message is used by both the NAS and the DIAMETER Server in order to exchange protocol version numbers which it supports. The NAS MUST insert the highest version number which it supports. The DIAMETER Server must respond with the highest version which it supports, but may not be higher than the version number requested by the NAS. In the case of a proxy server, the proxy is responsible for inserting the highest version number which it supports in the version field before sending the proxy request to the remote DIAMETER server. The proxy server may then retain the version number of the remote server as received in the response, and must insert its highest version number (with the limitations described above) in the response to the NAS. Calhoun, Rubens expires in six months [Page 8] DRAFT DIAMETER March 1997 The Server may discard this information if it wishes to do so, however it is envisioned that the Server would retain the NAS' and remote DIAMETER server's version numbers to retain backward and forward protocol compatibility. A NAS MUST support the fact that it may not receive an acknowledge to this message if the DIAMETER Server does not support this version of the protocol. In this case, if no acknowledgment was received within the maximum retransmission period, it MAY default to using messages as described in [1]. If a NAS is configured to communicate with more than one DIAMETER server it MUST issue NAS-Reboot-Indications to each such server. 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 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Code | Flags | Ver | Command | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Identifier | Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | | Authenticator | | | | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | | Message Integrity Code | | | | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Code 254 for DIAMETER Flags The Flag field is used as described above. Version The version field is used by the NAS to indicate the highest supported version of the DIAMETER protocol. This will allow the NAS and DIAMETER Server to be able to negotiate a version of the protocol to use between both peers. Calhoun, Rubens expires in six months [Page 9] DRAFT DIAMETER March 1997 Command 267 for NAS-Reboot-Indication. Identifier The Identifier field MUST be changed whenever the content of the Attributes field changes, and whenever a valid reply has been received for a previous request. For retransmissions, the Identifier MAY remain unchanged. Length The total length of the message, including this header. Authenticator The Authenticator field is a random 16 octet value. If the Timestamp option is supported, the first four octets contain a timestamp of when the packet was sent from the peer. Message Integrity Code This field contains an MD5 hash of the following: MD5( packet | Shared Secret ) 5.3. NAS-Reboot-Ack Description The NAS-Reboot-Ack message is sent from the DIAMETER Server to the NAS to acknowledge the receipt of the NAS-Reboot message. The Server MUST replace the version value in the version field with the highest version number which it supports, up to and including the version which was included in the NAS-Reboot's version field. The NAS may wish to ignore the version number contained in the Flag field, however it is envisioned that the NAS would retain this information to remove any backward compatibility problems with any future versions of the protocol. Calhoun, Rubens expires in six months [Page 10] DRAFT DIAMETER March 1997 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 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Code | Flags | Ver | Command | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Identifier | Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | | Authenticator | | | | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | | Message Integrity Code | | | | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Code 254 for DIAMETER. Flags The Flag field is used as described above. Version The Version field is used by the DIAMETER Server to inform the NAS the highest version which it supports. The Server MUST not insert a version which is higher than requested by the NAS. The client MUST use the version which is reported by the Server. If the NAS does not support the version returned by the Server, it should default to using the RADIUS protocol. Command 268 for NAS-Reboot-Ack. Identifier The Identifier field is a copy of the Identifier field of the packet which caused this event. Length The total length of the message, including this header. Calhoun, Rubens expires in six months [Page 11] DRAFT DIAMETER March 1997 Authenticator The Authenticator field is a random 16 octet value. If the Timestamp option is supported, the first four octets contain a timestamp of when the packet was sent from the peer. Message Integrity Code This field contains an MD5 hash of the following: MD5( packet | Shared Secret ) 6. Attributes Formats DIAMETER Attributes carry the specific authentication 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 by each such attribute description. The end of the list of attributes is indicated by the length of the DIAMETER packet. A summary of the attribute 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 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Attribute Type | Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Flags | Vendor ID (optional) | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |Vendor ID (opt)| Value ... | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Type The Type field is two octets. RADIUS reserves the lowest 256 attribute numbers. Up-to-date values of the RADIUS Type field are specified in the most recent "Assigned Numbers" RFC [2]. Calhoun, Rubens [Page 12] DRAFT DIAMETER March 1997 DIAMETER will use attribute numbers 257 and above. Vendor Specific attributes reside within this space when the Vendor Specific bit is set (see flags). This will allow up to 65535 trouble-free vendor specific attributes (per vendor). Length The Length field is two octets, and indicates the length of this Attribute including the Type, Length, Flag, Vendor ID is present and Value fields. If a packet is received with an Invalid length, the packet SHOULD be rejected. Flags The Flags field indicates how the NAS or DIAMETER Server MUST react to the attribute. The following values are currently supported: 1 - The Device MUST support this attribute. If the attribute is NOT supported, the device MUST reject the Command. If this flag is not set, then the device MAY accept the command regardless of whether or not the particular attribute is recognized. 2 - If this bit is set, the contents of the attributes are encrypted. Note that the attribute header is NOT encrypted in this case. See section 3 for more information. NOTE That this bit MUST NOT be turned on if the encryption bit is set in the DIAMETER header which means that all attributes are encrypted. 128 - If this bit is set, the optional Vendor ID field will be present. When set, the attribute is a vendor specific attribute Value The Value field is zero or more octets and contains information specific to the Attribute. The format and length of the Value field is determined by the Type and Length fields. The format of the value field is one of five data types. string 0-65526 octets. address 32 bit value, most significant octet first. Calhoun, Rubens expires in six months [Page 13] DRAFT DIAMETER March 1997 extended address Address Length is determined from the Length field, most significant octet first. This is required in order to support protocols which require an address length greater than 32 bits (i.e. IPNG). Note that this type is differentiated from the previous type by the value of length. integer 32 bit value, most significant octet first. time 32 bit value, most significant octet first -- seconds since 00:00:00 GMT, January 1, 1970. 7. Attribute Name and Attribute Code Attribute Name: Command-Code Attribute Code: 263 8. Command Meanings The DIAMETER Packet type is determined by the Command Code field in the second and third octets of the Packet. This section will not describe the existing RADIUS codes as defined in [1]. 8.1. Command-Code Description The Command-Code attribute MAY be used in conjunction with the Vendor-Specific command code set in the header. This attribute MUST include a Vendor-ID in the attribute header. A vendor-ID set to zero (0) indicates a standard (non-proprietary) command. 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 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Attribute Type | Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Flags | Vendor ID (optional) | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |Vendor ID (opt)| Value ... | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Type 263 for EAP-Packet Calhoun, Rubens expires in six months [Page 14] DRAFT DIAMETER March 1997 Length >= 13 Flags The Flags field indicates how the NAS or DIAMETER Server MUST react to the attribute. The following values are currently supported: 1 - The Device MUST support this attribute. If the attribute is NOT supported, the device MUST reject the Command. If this flag is not set, then the device MAY accept the command regardless of whether or not the particular attribute is recognized. This bit MUST be set. 2 - If this bit is set, the contents of the attributes are encrypted. Note that the attribute header is NOT encrypted in this case. See section 3 for more information. 128 - This bit (Vendor ID present) MUST be set in the attribute. Vendor ID The Vendor ID field MUST contain a value. A value of zero (0) indicates that the command contains a standard command code. Identifier The identifier field is used in order to build a "history" of the transaction. The EAP-Packet attribute with the highest identifier represents the current packet to process. The history is passed along in each request/responses in order for an EAP authentication to span multiple DIAMETER servers (in order to support the concept of backup servers). Value The Value attribute MUST contain the Command Code associated with this message. It MAY be set the a standard Command Code as defined in this draft if the Vendor ID is set to zero (0). Calhoun, Rubens expires in six months [Page 15] DRAFT DIAMETER March 1997 9. References [1] Rigney, et alia, "RADIUS", RFC-2058, Livingston, January 1997 [2] Reynolds, J., and J. Postel, "Assigned Numbers", RFC 1700, USC/Information Sciences Institute, October 1994. [3] Postel, J., "User Datagram Protocol", RFC 768, USC/Information Sciences Institute, August 1980. [4] Rivest, R., and S. Dusse, "The MD5 Message-Digest Algorithm", MIT Laboratory for Computer Science and RSA Data Security, Inc., RFC 1321, April 1992. [5] Kaufman, C., Perlman, R., and Speciner, M., "Network Security: Private Communications in a Public World", Prentice Hall, March 1995, ISBN 0-13-061466-1. 10. Authors' Addresses Pat R. Calhoun US Robotics Access Corp. 8100 N. McCormick Blvd. Skokie, IL 60076-2999 Phone: 847-342-6898 EMail: pcalhoun@usr.com Allan C. Rubens Merit Network, Inc. 4251 Plymouth Rd. Ann Arbor, MI 48105-2785 Phone: 313-647-0417 EMail: acr@merit.edu Calhoun, Rubens expires in six months [Page 16]