Request for Comments: 4101 RTFM, Inc.
Category: Informational IAB
June 2005
Writing Protocol Models
Status of This Memo
This memo provides information for the Internet community. It does
not specify an Internet standard of any kind. Distribution of this
memo is unlimited.
Copyright Notice
Copyright (C) The Internet Society (2005).
Abstract
The IETF process depends on peer review. However, IETF documents are
generally written to be useful for implementors, not reviewers. In
particular, while great care is generally taken to provide a complete
description of the state machines and bits on the wire, this level of
detail tends to get in the way of initial understanding. This
document describes an approach for providing protocol "models" that
allow reviewers to quickly grasp the essence of a system.
1. Introduction
The IETF process depends on peer review. However, in many cases, the
documents submitted for publication are extremely difficult to
review. Because reviewers have only limited amounts of time, this
leads to extremely long review times, inadequate reviews, or both.
In our view, a large part of the problem is that most documents fail
to present an architectural model for how the protocol operates,
opting instead to simply describe the protocol and let the reviewer
figure it out.
This is acceptable when documenting a protocol for implementors,
because they need to understand the protocol in any case; but it
dramatically increases the strain on reviewers. Reviewers need to
get the big picture of the system and then focus on particular
points. They simply do not have time to give the entire document the
attention an implementor would.
One way to reduce this load is to present the reviewer with a
MODEL -- a short description of the system in overview form. This
provides the reviewer with the context to identify the important or
difficult pieces of the system and focus on them for review. As a
side benefit, if the model is done first, it can be serve as an aid
to the detailed protocol design and a focus for early review, prior
to protocol completion. The intention is that the model would either
be the first section of the protocol document or be a separate
document provided with the protocol.
2. The Purpose of a Protocol Model
A protocol model needs to answer three basic questions:
1. What problem is the protocol trying to achieve?
2. What messages are being transmitted and what do they mean?
3. What are the important, but unobvious, features of the protocol?
The basic idea is to provide enough information that the reader could
design a protocol which was roughly isomorphic to the protocol being
described. Of course, this doesn’t mean that the protocol would be
identical, but merely that it would share most important features.
For instance, the decision to use a KDC-based authentication model is
an essential feature of Kerberos [KERBEROS]. By contrast, the use of
ASN.1 is a simple implementation decision. S-expressions -- or XML,
had it existed at the time -- would have served equally well.
The purpose of a protocol model is explicitly not to provide a
complete or alternate description of the protocol being discussed.
Instead, it is to provide a big picture overview of the protocol so
that readers can quickly understand the essential elements of how it
works.
3. Basic Principles
In this section we discuss basic principles that should guide your
presentation.
3.1. Less is more
Humans are only capable of keeping a very small number of pieces of
information in their head at once. Because we’re interested in
ensuring that people get the big picture, we have to dispense with a
lot of detail. That’s good, not bad. The simpler you can make
things the better.
3.2. Abstraction is good
A key technique for representing complex systems is to try to
abstract away pieces. For instance, maps are better than photographs
for finding out where you want to go because they provide an
abstract, stylized, view of the information you’re interested in.
Don’t be afraid to compress multiple protocol elements into a single
abstract piece for pedagogical purposes.
3.3. A few well-chosen details sometimes help
The converse of the previous principle is that sometimes details help
to bring a description into focus. Many people work better when
given examples. Thus, it’s often a good approach to talk about the
material in the abstract and then provide a concrete description of
one specific piece to bring it into focus. Authors should focus on
the normal path. Error cases and corner cases should only be
discussed where they help illustrate an important point.
4. Writing Protocol Models
Our experience indicates that it is easiest to grasp protocol models
when they are presented in visual form. We recommend a presentation
format centered around a few key diagrams, with explanatory text for
each. These diagrams should be simple and typically consist of
"boxes and arrows" -- boxes representing the major components, arrows
representing their relationships, and labels indicating important
features.
We recommend a presentation structured in three parts to match the
three questions mentioned in the previous sections. Each part should
contain 1-3 diagrams intended to illustrate the relevant points.
4.1. Describe the problem you’re trying to solve
The most critical task that a protocol model must perform is to
explain what the protocol is trying to achieve. This provides
crucial context for understanding how the protocol works, and whether
it meets its goals. Given the desired goals, an experienced reviewer
will usually have an idea of how they would approach the problem and,
thus, be able to compare that approach with the approach taken by the
protocol under review.
The "Problem" section of the model should start with a short
statement of the environments in which the protocol is expected to be
used. This section should describe the relevant entities and the
likely scenarios under which they would participate in the protocol.
The Problem section should feature a diagram of the major
communicating parties and their inter-relationships. It is
particularly important to lay out the trust relationships between the
various parties, as these are often unobvious.
4.1.1. Example: STUN (RFC 3489)
STUN [STUN] is a UNilateral Self-Address Fixing (UNSAF) [UNSAF]
protocol that allows a machine located behind a NAT to determine what
its external apparent IP address is. Although STUN provides a
complete and thorough description of the operation of the protocol,
it does not provide a brief, up-front overview suitable for a quick
understanding of its operation. The rest of this section shows what
a suitable overview might look like.
Network Address Translation (NAT) makes it difficult to run a number
of classes of service from behind the NAT gateway. This is
particularly a problem when protocols need to advertise address/port
pairs as part of the application layer protocol. Although the NAT
can be configured to accept data destined for that port, address
translation means the address that the application knows about is not
the same as the one on which it is reachable.
Consider the scenario represented in the figure below. A SIP client
is initiating a session with a SIP server in which it wants the SIP
server to send it some media. In its Session Description Protocol
(SDP) [SDP] request it provides the IP address and port on which it
is listening. However, unbeknownst to the client, a NAT is in the
way. The NAT translates the IP address in the header, but unless it
is SIP aware, it doesn’t change the address in the request. The
result is that the media goes into a black hole.
+-----------+
| SIP |
| Server |
| |
+-----------+
^
| [FROM: 198.203.2.1:8954]
| [MSG: SEND MEDIA TO 10.0.10.5:6791]
|
|
+-----------+
| |
| NAT |
--------------+ Gateway +----------------
| |
+-----------+
^
| [FROM: 10.0.10.5:6791]
| [MSG: SEND MEDIA TO 10.0.10.5:6791]
|
10.0.10.5
+-----------+
| SIP |
| Client |
| |
+-----------+
The purpose of STUN is to allow clients to detect this situation and
determine the address mapping. They can then place the appropriate
address in their application-level messages. This is done by using
an external STUN server. That server is able to determine the
translated address and tell the STUN client, as shown below.
+-----------+
| STUN |
| Server |
| |
+-----------+
^ |
[IP HDR FROM: 198.203.2.1:8954] | | [IP HDR TO: 198.203.2.1:8954]
[MSG: WHAT IS MY ADDRESS?] | | [MSG: YOU ARE 198.203.2.1:8954]
| v
+-----------+
| |
| NAT |
--------------+ Gateway +----------------
| |
+-----------+
^ |
[IP HDR FROM: 10.0.10.5:6791] | | [IP HDR TO: 10.0.10.5:6791]
[MSG: WHAT IS MY ADDRESS?] | | [MSG: YOU ARE 198.203.2.1:8954]
| v
10.0.10.5
+-----------+
| SIP |
| Client |
| |
+-----------+
4.2. Describe the protocol in broad overview
Once the problem has been described, the next task is to give a broad
overview of the protocol. This means showing, either in "ladder
diagram" or "boxes and arrows" form, the protocol messages that flow
between the various networking agents. This diagram should be
accompanied with explanatory text that describes the purpose of each
message and the MAJOR data elements.
This section SHOULD NOT contain detailed descriptions of the
protocol messages or of each data element. In particular, bit
diagrams, ASN.1 modules, and XML schema SHOULD NOT be shown. The
purpose of this section is not to provide a complete
description of the protocol, but to provide enough of a
map that a person reading the full protocol document can see
where each specific piece fits.
In certain cases, it may be helpful to provide a state machine
description of the behavior of network elements. However, such
state machines should be kept as minimal as possible. Remember that
the purpose is to promote high-level comprehension, not complete
understanding.
4.2.1. Example: DCCP
Datagram Congestion Control Protocol [DCCP] is a protocol for
providing datagram transport with network-friendly congestion
avoidance behavior. The DCCP base protocol document is over 100
pages long and the congestion control mechanisms themselves are
separate. Therefore, it is very helpful to have a an architectural
overview of DCCP that abstracts away the details. The remainder of
this section is an attempt to do so.
NOTE: The author of this document was on the DCCP review team and
his experience with that document was one of the motivating factors
for this document. Since the review, the DCCP authors have added
some overview material, some of which derives from earlier versions
of this document.
Although DCCP is datagram-oriented like UDP, it is stateful
like TCP. Connections go through the following phases:
1. Initiation
2. Feature negotiation
3. Data transfer
4. Termination
4.2.1.1. Initiation
As with TCP, the initiation phase of DCCP involves a three-way
handshake, shown below.
Client Server
------ ------
DCCP-Request ->
[Ports, Service,
Features]
<- DCCP-Response
[Features,
Cookie]
DCCP-Ack ->
[Features,
Cookie]
DCCP 3-way handshake
In the DCCP-Request message, the client tells the server the name of
the service it wants to talk to and the ports it wants to communicate
on. Note that ports are not tightly bound to services, as they are
in TCP or UDP common practice. It also starts feature negotiation.
For pedagogical reasons, we will present feature negotiation
separately in the next section. However, realize that the early
phases of feature negotiation happen concurrently with initiation.
In the DCCP-Response message, the server tells the client that it is
willing to accept the connection and continues feature negotiation.
In order to prevent SYN flood-style DOS attacks, DCCP incorporates an
IKE-style cookie exchange. The server can provide the client with a
cookie that contains all of the negotiation state. This cookie must
be echoed by the client in the DCCP-Ack, thus removing the need for
the server to keep state.
In the DCCP-Ack message, the client acknowledges the DCCP-Response
and returns the cookie to permit the server to complete its side of
the connection. As indicated above, this message may also include
feature negotiation messages.
4.2.1.2. Feature Negotiation
In DCCP, feature negotiation is performed by attaching options to
other DCCP packets. Thus, feature negotiation can be piggybacked on
any other DCCP message. This allows feature negotiation during
connection initiation as well as during data flow.
Somewhat unusually, DCCP features are one-sided. Thus, it’s possible
to have a different congestion control regime for data sent from
client to server than from server to client.
Feature negotiation is done with the Change and Confirm options.
There are four feature negotiation options in all: Change L, Confirm
L, Change R, and Confirm R. The "L" options are sent by the feature
location, where the feature is maintained, and the "R" options are
sent by the feature remote.
A Change R message says to the peer "change this option setting on
your side". The peer can respond with a Confirm L, meaning "I’ve
changed it". Some features allow Change R options to contain
multiple values, sorted in preference order. For example:
Client Server
------ ------
Change R(CCID, 2) -->
<-- Confirm L(CCID, 2)
* agreement that CCID/Server = 2 *
Change R(CCID, 3 4) -->
<-- Confirm L(CCID, 4, 4 2)
* agreement that CCID/Server = 4 *
In the second exchange, the client requests that the server use
either CCID 3 or CCID 4, with 3 preferred. The server chooses 4 and
supplies its preference list, "4 2".
The Change L and Confirm R options are used for feature negotiations
that are initiated by the feature location. In the following
example, the server requests that CCID/Server be set to 3 or 2 (with
3 being preferred), and the client agrees.
Client Server
------ ------
<-- Change L(CCID, 3 2)
Confirm R(CCID, 3, 3 2) -->
* agreement that CCID/Server = 3 *
4.2.1.3. Data Transfer
Rather than have a single congestion control regime, as in TCP, DCCP
offers a variety of negotiable congestion control regimes. The DCCP
documents describe two congestion control regimes: additive increase,
multiplicative decrease (CCID-2 [CCID2]), and TCP-friendly rate
control (CCID-3 [CCID3]). CCID-2 is intended for applications that
want maximum throughput. CCID-3 is intended for real-time
applications that want smooth response to congestion.
4.2.1.3.1. CCID-2
CCID-2’s congestion control is extremely similar to that of TCP. The
sender maintains a congestion window and sends packets until that
window is full. Packets are Acked by the receiver. Dropped packets
and ECN [ECN] are used to indicate congestion. The response to
congestion is to halve the congestion window. One subtle difference
between DCCP and TCP is that the Acks in DCCP must contain the
sequence numbers of all received packets (within a given window), not
just the highest sequence number, as in TCP.
4.2.1.3.2. CCID-3
CCID-3 is an equation-based form of rate control, intended to provide
smoother response to congestion than CCID-2. The sender maintains a
"transmit rate". The receiver sends Ack packets that contain
information about the receiver’s estimate of packet loss. The sender
uses this information to update its transmit rate. Although CCID-3
behaves somewhat differently than TCP in its short-term congestion
response, it is designed to operate fairly with TCP over the long
term.
4.2.1.4. Termination
Connection termination in DCCP is initiated by sending a Close
message. Either side can send a Close message. The peer then
responds with a Reset message, at which point the connection is
closed. The side that sent the Close message must quietly preserve
the socket in TIMEWAIT state for 2MSL.
Client Server
------ ------
Close ->
<- Reset
[Remains in TIMEWAIT]
Note that the server may wish to close the connection but not remain
in TIMEWAIT (e.g., due to a desire to minimize server-side state).
In order to accomplish this, the server can elicit a Close from the
client by sending a CloseReq message and, thus, keep the TIMEWAIT
state on the client.
4.3. Describe any important protocol features
The final section (if there is one) should contain an explanation of
any important protocol features that are not obvious from the
previous sections. In the best case, all the important features of
the protocol would be obvious from the message flow. However, this
isn’t always the case. This section is an opportunity for the author
to explain those features. Authors should think carefully before
writing this section. If there are no important points to be made,
they should not populate this section.
Examples of the kind of feature that belongs in this section include:
high-level security considerations, congestion control information,
and overviews of the algorithms that the network elements are
intended to follow. For instance, if you have a routing protocol,
you might use this section to sketch out the algorithm that the
router uses to determine the appropriate routes from protocol
messages.
4.3.1. Example: WebDAV COPY and MOVE
The WebDAV standard [WEBDAV] is fairly terse, preferring to define
the required behaviors and let the reader work out the implications.
In some situations, explanatory material that details those