Internet Draft
INTERNET DRAFT Pat R. Calhoun
Category: Standards Track Sun Laboratories, Inc.
Title: draft-calhoun-diameter-08.txt Allan C. Rubens
Date: August 1999 Ascend Communications
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.
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.
Table of Contents
1.0 Introduction
1.1 Copyright Statement
1.2 Requirements language
1.3 Terminology
1.4 Changes in Revision 8
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
5.0 Protocol Definition
5.1 DIAMETER Bootstrap Message
5.1.1 State Machine
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 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
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 [XXX] 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
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.
- 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.
- 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).
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
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
2.0 for more information.
AVPs
AVPs is a method of encapsulating information relevant to the
DIAMETER message. See section 2.2 for more information on AVPs.
2.1.1 ZLB Message Format
Zero Length Body messages are used to explicitly acknowledge one or
more DIAMETER message, and contain no additional Authentication,
Authorization or Accounting related AVPs. ZLB messages must contain
authentication AVPs, otherwise attacks could be mounted against
DIAMETER nodes. Consider the following example.
+------+ -----> +------+
| | Ns=10 | |
| DIA1 +--------------------+ DIA3 |
| | Ns=40 | |
+------+ <----- +-+----+
/
/
+------+ / Nr = 41
|Malici| /
| ous +-/
| Node |
+------+
In the above figure, DIA3 sends a stream of messages to DIA, 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:
::=
{ ||
2].
AVP numbers 256 and above are used for DIAMETER. Each service MUST
allocate AVP numbers through the IANA (see section 6.0).
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 AVP Code, AVP Length, AVP Flags,
Reserved, the Tag and Vendor ID fields if present and the AVP
data. If a packet is received with an Invalid attribute length,
the packet SHOULD be rejected.
Command Flags
The Command Flag field is a bit-field that can be used by
individual command codes. Any Command Code that makes use of these
bits MUST define their value, and how they are used. Note that
only AVPs with the AVP Code set to Command-Code may use these
bits, otherwise the bits MUST be set to zero (0).
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. Note that subsequent DIAMETER extensions MAY
define bits to be used within the AVP Header, and an unrecognized
bit should be considered an error.
The 'M' Bit, known as the Mandatory bit, indicates whether support
of the AVP is required. If an AVP is received with the 'M' bit
enabled and the receiver does not support the AVP, the message
MUST be rejected.
AVPs without the 'M' bit enabled are informational only and a
receiver that receives a message with such an AVP that is not
supported MAY simply ignore the AVP.
When the 'H' bit is enabled it indicates that the AVP data is
encrypted using hop-by-hop encryption. See section 4.5 for more
information.
The 'V' bit, known as the Vendor-Specific bit, indicates whether
the optional Vendor ID field is present in the AVP header. When
set the AVP Code belongs to the specific vendor code address
space.
The 'T' bit, known as the Tag bit, is used to group sets of AVPs
together. Grouping of AVPs is necessary when more than one AVP is
needed to express a condition. If this bit is set, the optional
Tag field will be present.
Vendor ID
The optional four octet Vendor ID field contains 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 four octet in length and is intended to provide a
means of grouping attributes in the same packet which refer to the
same tunnel. 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-65400 octets of arbitrary data.
String
0-65400 octets of string data using the UTF-8 character set.
Address
32 bit or 128 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 unsigned value, most significant octet first -- seconds
since 00:00:00 GMT, January 1, 1900. Note that this field has
the problem that it will expire sometime in 2038, as will the
current NTP time format. More investigation is needed here to
determine whether there exists a 64 bit time format.
2.3 Error Reporting
There are five different types of errors within DIAMETER. The first
being where a DIAMETER message is poorly formatted and
unrecognizable, indicated below by "Bad Packet". This error condition
applies if a message is received with an unexpected AVP (e.g. more
than one Session-Id or DIAMETER-Command AVP).
The second case involves receiving a DIAMETER-Command AVP that is not
supported, which is shown below by "Unknown Command". The third case
is where an AVP is received, marked mandatory and is unknown by the
receiver, which is labeled below as "Unknown AVP".
This fourth case involves receiving a message with a known AVP, yet
the value is either unknown or illegal, which is shown below as "Bad
Value". The last case occurs when an error occurs while processing a
specific extension command, which is not related to the packet format
and is labeled "Extension Error" below.
Error Type Ignore Message Send Extension
Message-Reject-Ind Response /w
Result-Code
Bad Packet X
Unknown Command X
Unknown AVP X
Bad Value X
Extension Error X
"Ignore Message" indicates that the message is simply dropped. The
"Message-Reject-Ind" indicates that a Message-Reject-Ind message MUST
be sent to the peer as described in the appropriate section. The
"Extension Error w/ Result-Code" indicates that the appropriate
Response to the message MUST be sent with the Result-Code or Error-
Code AVP set to a value that enables the peer to understand the
nature of the problem.
3.0 Reliable Transport
This section provides a detailed overview of how DIAMETER is reliably
transported over UDP.
3.1 Flow Control
There are two different types of DIAMETER messages; A DIAMETER
message that only contains the header and no Attribute-Value Pairs
(AVPs) is known as a zero length body message (ZLB). ZLB messages are
used for explicitly acknowledging packets to the peer, and contain no
additional data.
Two fields in the DIAMETER header that are important for DIAMETER to
be operated reliable over UDP are the Nr (Next Received) and Ns (Next
Send). A single sequence number state is maintained for all DIAMETER
messages to a given peer. The sequence number starts at 0. Each
subsequent non-ZLB packet is sent with the next increment of the
sequence number.
The sequence number is thus a free running counter represented modulo
65536. For purposes of detecting duplication, a received sequence
value is considered less than or equal to the last received value if
its value lies in the range of the last value and its 32767 successor
values. For example, if the last received sequence number was 15,
then received packets with Ns values in the range ( 32783, ... 65535,
0, ... 15 ) would be considered duplicates and would be silently
discarded. A packet with sequence number 16 would be treated as the
next in-sequence packet and packets with other sequences numbers are
out-of-order.
It is an implementation decision as to whether DIAMETER Messages
received out-of-order are queued for later processing or silently
discarded. The former is recommended when possible.
In this document, the sequence number state for each peer is
represented for clarity of discussion by distinct pairs of state
variables, Sr and Ss. Sr represents the value of the next in-
sequence message expected to be received for a given session by a
peer. Ss represents the sequence number to be placed in the Ns field
of the next message sent to a given peer. Each state is initialized
such that the first message sent and the first message expected to be
received to/from each peer has an Ns value of 0. This corresponds to
initializing Ss and Sr to 0 for each peer.
As messages are sent to a given peer, Nr is set in these messages to
reflect one more than the Ns value of the highest (modulo 2^16) in-
order message received from that peer; if sent before any packet is
received Nr will be 0, indicating that the peer expects the next new
Ns value to be 0.
When a non-ZLB message is received with an Ns value that matches the
peer's current Sr value, Sr is incremented by 1 (modulo 2^16). It is
important to note that Sr is not modified if a message is received
with a value of Ns greater than the current Sr value. Retransmission
of lost packets will eventually provide the receiving peer with its
next expected message.
Every time a peer sends a non-ZLB message it increments its Ss value
for that peer by 1 (modulo 2^16). This increment takes place after
the current Ss value is copied to Ns in the message to be sent. New
outgoing messages normally include the current value of Sr for the
corresponding peer in their Nr field. A peer may not wish to send
the latest Sr value back to its peer due to congestion (i.e., its
receive buffer for the session is full). In this case it is
permissible for the peer to send back an Nr value containing the Ns
value of the first message in the window. It is preferable to return
an acknowledgment with this old Nr value rather than to withhold
acknowledgments entirely when the receive window is full.
Retransmitted messages should also include the current value of Sr in
their Nr field, but some implementations may choose not to update Nr
to avoid having to perform another hash in the Integrity-Check-Vector
AVP. Note that the hash would only have to be recomputed if the Nr
value had changed. This restriction does not apply to end-to-end
integrity since the Ns and Nr fields are mutable. When retransmitting
a message the identifier in the protocol header MUST NOT be changed.
If the Nr value changes, and the ICV must be re-computed, it is
strongly recommended that the time in the Timestamp AVP be updated as
well.
When transmitting packets, a DIAMETER peer must obey the receive
window size offerred by its peer. The default window size is 7. A
DIAMETER peer MUST NOT send new packets when its peer's window is
closed (the number of packets unacknowledged is equal to the
advertised, or assumed, window size). Previously transmitted packets
may be retransmitted while the peer's window is closed. A peer
communicating via UDP can specify the window size it is providing to
its peer by specifying this value in the Device-Reboot-Ind message.
A ZLB message is used to communicate Nr and Ns fields. The Nr and the
Ns fields are filled in as above, but the sequence number state, Ss,
is not modified. Thus a ZLB message sent after a non-ZLB message will
contain the new Ss value while a non-ZLB message sent after a ZLB
message will contain the same value of Ns as the ZLB message did.
Upon receipt of an in-order non-ZLB message, the receiving peer must
increment its Sr value and may acknowledge the message by sending
back the updated value of Sr in the Nr field of the next outgoing
message. This updated Sr value can be piggybacked in the Nr field of
any outgoing messages that the peer may happen to send back.
If a peer does not have a message queued to transmit at the time a
non-ZLB message is received then it should delay a short time before
sending a ZLB message containing the latest values of Sr and Ss, as
described above. This short delay is to allow for the possible
arrival of a message to be transmitted back to its peer, thus
avoiding the need to issue a ZLB. The suggested value for this time
delay is 1/4 the receiving peer's value of Round-Trip-Time (RTT - see
Appendix A), if it computes RTT, or a maximum of 1/2 of its fixed
acknowledgment timeout interval otherwise. This timeout should
provide a reasonable opportunity for the receiving peer to obtain a
payload message destined for its peer, upon which the ACK of the
received message can be piggybacked. Note that if a peer's window is
full, it MAY advertise an older Nr value if it is not ready to accept
new messages.
This delay value should be treated as a suggested maximum; an
implementation could make this delay quite small without adversely
affecting the protocol. The default time delay is 2 seconds. To
provide for better throughput, the receiving peer should skip this
delay entirely and send a ZLB message immediately in the case where
its receive window is filled and it has no queued data to send for
this connection or it can't send queued data because the transmit
window is closed.
See Appendix B for some examples of how sequence numbers progress.
3.2 Suggested implementation
A suggested implementation of this delay is as follows: Upon
receiving a non-ZLB message, the receiver starts a timer that will
expire in the recommended time interval. A variable, Lr (Last Nr
value sent), is used by the transmitter to store the last value sent
in the Nr field of a transmitted payload message for this connection.
Upon expiration of this timer, Sr is compared to Lr and, if they are
not equal, a ZLB ACK is issued. If they are equal, then no ACK's are
outstanding and no action needs to be taken.
This timer should not be reinitialized if a new message is received
while it is active since such messages will be acknowledged when the
timer expires. This ensures that periodic ACK's are issued with a
maximum period equal to the recommended delay time interval. This
interval should be short enough to not cause false acknowledgement
timeouts at the transmitter when payload messages are being sent in
one direction only. Since such ACK's are being sent on what would
otherwise be an idle data path, their affect on performance should be
small, of not negligible.
In order for a DIAMETER implementation to be able to retransmit
messages, it MUST queue transmitted messages until the messages are
acknowledged. It must also maintain a retransmission timer that
determines when to assume that either a sent message did not arrive
at the peer or the acknowledgment sent by the peer was lost. See
Appendix A for a recommended retransmit timer implementation. There
are two recommended methods for implementing the retransmission
procedure. One method is for the sender to resend the entire window
of unacknowledged messages when the retransmit timeout expires. This
is the simplest method, but is inefficient when a receiver is not
rotating the window due to congestion. The alternative method is to
only resend the first message in the window (the first unacknowledged
message) until an acknowledgment is received. This acknowledgment
will indicate to the receiver the next, if any, message in the
current window that needs to be retransmitted. A particular
implementation may use either or both methods if desired.
When a DIAMETER node has retransmitted a message to a given peer the
maximum number of times (the recommended value is 3), it may send the
request to an alternate DIAMETER server. This procedure may continue
until either all of the servers have been tried, or the node
selectively issues a failure to the requestor.
3.3 Peer failure recovery
A DIAMETER message with the Command-Code AVP set to Device-Reboot-Ind
and the Ns and Nr values set to zero (0) indicates that the peer has
rebooted. This message MUST be recognized and supported by a
DIAMETER implementation. When this event occurs, the Ss and Sr values
must be reset and the retransmission queue MUST be cleared. Since the
protocol requires that all new messages include a random identifier
in the protocol header, a Device-Reboot-Ind that is received with the
same identifier as the last processed Device-Reboot-Ind is considered
a retransmission and SHOULD NOT change the peer's state to inactive.
Messages other than the Device-Reboot-Ind MUST NOT be sent to the
peer until both the acknowledgement for the transmitted Device-
Reboot-Ind AND the peer's Device-Reboot-Ind have been received. When
both of these have been received, the peer is considered to be in the
active state.
4.0 DIAMETER AVPs
This section will define the mandatory AVPs that MUST be supported by
all DIAMETER implementations. 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
Extension-Id 258
Integrity-Check-Vector 259
Nonce 261
Timestamp 262
Session-Id 263
Vendor-Name 266
Firmware-Revision 267
Result-Code 268
Error-Code 269
Unrecognized-Command-Code 270
Reboot-Type 271
Reboot-Time 272
Failed-AVP-Code 279
Receive-Window 277
Proxy-State 33
4.1 DIAMETER-Command AVP
Description
The DIAMETER-Command AVP MUST be the first AVP following the
DIAMETER header. This AVP is used in order to communicate the
command associated with the message. A DIAMETER message can have
at most one DIAMETER-Command AVP. Unless noted otherwise, all
command codes defined in this document will use the following
format:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| AVP Code |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| AVP Length | Cmd Flags | Reserved |T|V|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.
Command Flags
All Command Codes defined in this spec MUST set all bits in
this field to zero (0).
AVP Flags
The 'M' bit MUST be set. The 'V' MAY be set if the Command Code
is vendor specific. The 'H', 'T' bits MUST NOT be set.
Command Code
The Command Code field contains the command number. The
following commands are defined and MUST be supported by all
DIAMETER implementations in order to conform to the base
protocol specification:
Command Name Command Code
-----------------------------------
Message-Reject-Ind 256
Device-Reboot-Ind 257
Device-Watchdog-Ind 258
4.1.1 Message-Reject-Ind (MRI)
Description
The Message-Reject-Ind command provides a generic means of
completing transactions by indicating errors in the messages which
initiated them. The Message-Reject-Ind command is a possible
response to any DIAMETER command, but some DIAMETER commands MAY
expect more specialized error messages, depending on the error
type.
The Message-Reject-Ind message MUST contain the same
identification in the header and include the Session-Id if it was
present in the original message that it is responding to, even if
the identification is erroneous. The receiver of a Message-Reject-
Ind SHOULD examine the Result-Code AVP provided before processing
the identification, in order to handle the letter appropriately.
Message Format
The structure of the Message-Reject message is defined 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
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
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
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
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].
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.
4.15 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.
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
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 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
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
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
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 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 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
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.
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.
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
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.
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
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.
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
peer:
::=
[]
{ ||
::=
[]
{ ||
::=
[]
Any AVPs in a message that is not succeeded by the Integrity-Check-
Vector AVP MUST be ignored.
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
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.
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 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
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.
(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).
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].
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",
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.
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
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
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
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.
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
(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.
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.
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