Internet DRAFT - draft-pjd-stdguide
draft-pjd-stdguide
HTTP/1.1 200 OK
Date: Tue, 09 Apr 2002 10:51:29 GMT
Server: Apache/1.3.20 (Unix)
Last-Modified: Thu, 23 Nov 1995 23:00:00 GMT
ETag: "361e89-5188-30b4fcf0"
Accept-Ranges: bytes
Content-Length: 20872
Connection: close
Content-Type: text/plain
Received: from CNRI.Reston.VA.US by IETF.CNRI.Reston.VA.US id aa21028;
22 Nov 95 15:49 EST
Received: from midnight.midnight.com by CNRI.Reston.VA.US id aa16928;
22 Nov 95 15:49 EST
Received: by midnight.midnight.com (4.1/SMI-4.1)
id AA02219; Wed, 22 Nov 95 15:47:34 EST
Date: Wed, 22 Nov 95 15:47:34 EST
From: Peter Desnoyers <pjd@midnight.com>
Message-Id: <9511222047.AA02219@midnight.midnight.com>
To: internet-drafts@CNRI.Reston.VA.US
Subject: draft submission
Reply-To: Peter Desnoyers 617/890-1001 <pjd@midnight.com>
I didn't get the request for a file name in until earlier today, so
I'm guessing at "draft-pjd-stdguide-00.txt". I apologize for this
mixup, and hope it doesn't cause any confusion.
Thanks,
...............................................................................
Peter Desnoyers : Midnight Networks Inc. 200 Fifth Avenue Waltham MA 02154
pjd@midnight.com : Ph. 617/890-1001 Fax -0028 The Best in Network Software
--- draft follows ---
STDGUIDE Working Group P. Desnoyers & A. Mellor
Internet Draft Midnight Networks Inc.
November 22, 1995
Guide for Internet Standards Writers
<draft-pjd-stdguide-00.txt>
Status of this Document
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).
Distribution of this document is unlimited. Please send comments to
stdguide@midnight.com or to the author.
This Internet Draft expires May 22, 1996.
Abstract
This document is a guide to Internet standards writers. It is
intended to capture some of those characteristics which have made
certain standards clear, easy to interpret, and unambiguous. At the
same time, it singles out other usages which are believed to have led
to unclear specifications and varying interpretations in the past.
This version of the document is a rough draft which is intended as a
starting point for further discussion and addition by the working
group.
1. Introduction
This document is a guide for Internet standards writers. It offers
guidelines which can be used to improve a protocol specification,
from the point of view of clarity, explanatory power, precision, and
completeness. Some of these guidelines are based on prior examples
Desnoyers & Mellor [Page 1]
Internet Draft Guide for Internet Standards Writers November 1995
of specifications which have been exceedingly clear or precise, while
others are based on negative examples of specifications which have
been difficult to understand or prone to differing and non-
interoperable interpretations. Note that these are hints, rather
than specifications or requirements, and that some of them may be
more applicable in certain situations than others.
The goal of these guidelines is to allow specifications to be created
which are more understandable and less ambiguous, thus increasing the
interoperability of implementations created from these
specifications. Clearly, guidelines such as these are only part of
the solution: although the lack of clear specifications may be a
strong barrier to the creation of interoperable implementations of a
protocol, a quality specification is certainly not sufficient to
achieve this goal.
There are a number of reasons for writing this document. The
authors' motivations come from their experience in protocol testing,
where it is necessary to understand specifications to the point of
deriving unambiguous testable statements. In addition there are many
people - both readers and implementors of Internet standards - who
are new to the Internet world, and are not necessarily "plugged in"
to the IETF process and history. Guidelines such as these should
help make specifications more accessible to these people.
2. More Understandable Specifications
The first set of recommendations in this document center on improving
the understandability of protocol specifications. To this end,
information is identified which should be included in a protocol
specification so as to provide the reader with all that is necessary
to understand what is being described.
2.1 Document approach
Specifications should include the a description of the purpose or
context of a protocol's use. Although the author of a protocol spec
will have a great deal of knowledge as to the purpose of a protocol,
the person reading the specification (even when implementing or
testing the protocol) is often only generally skilled in networking
software, rather than in the particular protocol at hand. Without an
explanation of the purpose behind a protocol it is far more difficult
to interpret a description of the protocol, and a reader is more
prone to error.
Along these lines, the author should not expect that the reader is an
expert in the problem domain of the protocol or the algorithms it
makes use of. In this case, as in the previous case, a specification
Desnoyers & Mellor [Page 2]
Internet Draft Guide for Internet Standards Writers November 1995
should either take the time to describe the algorithm or problem at
hand, or refer to materials which describe it in more detail.
2.2 Glossary
The following terms are often used in Internet specifications.
Suggested definitions when used in standards are given below.
[TBD. Terms will include MUST, SHOULD, "Silently Discard", others.]
2.3 Packet Diagrams
When describing packets that can be divided into fields, such as
those found in most link, network, and transport layer protocols,
packet diagrams are very helpful to the reader. It is recommended
that diagrams be included except in cases where they are not applica-
ble. (e.g. in a case where messages are encoded as ASCII strings or
ASN.1 sequences.) In general the preferred form for packet diagrams
is as a sequence of long words in network byte order, with each word
horizontal on the page and bit numbering at the top, as e.g.:
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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|Version| Prio. | Flow Label |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Desnoyers & Mellor [Page 3]
Internet Draft Guide for Internet Standards Writers November 1995
In cases where a packet is strongly byte-aligned rather than word-
aligned (e.g. when byte-boundary variable-length fields are used) it
may be preferable to display packet diagrams in a byte-wide format,
with different-height boxes for short and long words, and broken
boxes for variable-length fields. E.g.:
0 1 2 3 4 5 6 7
+-+-+-+-+-+-+-+-+
| Length N |
+-+-+-+-+-+-+-+-+
| |
+ Address +
...
+ (N bytes) +
| |
+-+-+-+-+-+-+-+-+
| |
+ 2-byte field +
| |
+-+-+-+-+-+-+-+-+
2.4 Explanatory information
When writing a protocol specification, there is a tradeoff between
conciseness and verbosity. Concise descriptions reduce the chance
for conflict between different portions of the specification, and
make it easier to decide the answer to questions of the form ``does
the specification require/forbid X''. A longer description may be
necessary, however, for explanatory reasons when describing e.g.
purpose or background.
The needs of both purposes are often best served by dividing a
specification into two types of sections; one set of sections forming
the specification proper, while the other sections are explanatory
only. An example of this technique can be found in the Router
Requirements specification. [RREQ]
This technique has a number of advantages over combining the
specification and explanatory text together. It allows the subject
matter of the specification to be explained at sufficient depth by
providing a designated space for this. It allows the specification
of the protocol itself to be concise, and avoids burying it within
the bulk of the explanatory text. Finally, it avoids ambiguity which
may arise due to errors in multiple descriptions of the same
mechanism, by designating one as normative rather than leaving the
choice up to the reader or implementor.
Desnoyers & Mellor [Page 4]
Internet Draft Guide for Internet Standards Writers November 1995
In other cases where the opportunity comes up to describe the same
protocol mechanism more than once (e.g. a state/event table vs.
textual descriptions of individual states and events) it is again
recommended that the multiple descriptions be included in a
specification if they contribute to the understandability of the
spec. However, if multiple such descriptions of a protocol mechanism
are included, one of them must be specified as "binding" in the case
of unintended inconsistencies.
2.5 Other Information to Include
If a standard is specifying a new version of an existing protocol,
then the differences between the previous version and the new version
should be summarized in the new document. A description of the
reasons for these differences would be very helpful, as well.
In some cases where a difficult choice had to be made when agreeing
on the document, the same disagreements are likely to recur later
when the original parties are dispersed. Recording a bit of the
history and reasoning behind such choices in the document, or
including a reference to some other source where this information can
be found, may help in ensuring that such issues stay settled. In the
case where the alternative not taken may be simpler or easier,
including the logic behind the choice may be necessary to persuade
future implementors to avoid taking non-standard shortcuts.
2.6 Sample Document Outline
The following is a sample outline for a protocol specification,
including the information described above.
1. Description of purpose and reason for protocol
2. High level "flow" or algorithm
3. Description of packets and fields, or equivalent
4. Detailed description of protocol operation / rules
5. Example situation walk-throughs: typical and complex
6. Implementation hints or issues
In most protocols the actual statements of specification will be
clustered in sections 3 (packets and fields) and 4 (protocol operation),
and possibly any appendices expanding on those sections. It is not
recommended that sections 1 (purpose and reason), 5 (example scenarios),
or 6 (implementation hints / issues) contain any statements of
specification, as by nature they are explanatory in nature.
3. Less Ambiguous Specifications
Desnoyers & Mellor [Page 5]
Internet Draft Guide for Internet Standards Writers November 1995
In addition to clarity, so that each reader can reach an understanding
of a document, it is important that protocol specifications be
unambiguous, so that multiple readers and implementors will reach the
same understanding of the document. The following guidelines are
intended to assist in the production of more unambiguous
specifications, by specifying desirable levels of completeness and
guidelines for specification of optional features.
3.1 Specifications Should Cover All Cases
This is a general design principle which applies in a number of
different areas.
Specifications should take care to describe responses to behavior
which is explicitly forbidden in the spec, as this is an area where
implementors often differ in opinion as the the appropriate behavior.
In what cases should packets be accepted as legal; in what cases
should they be discarded, and in what case should protocol
error-handling mechanisms be invoked?
The specification should consider behavior in the face of negative
cases such as bad lengths, bad field values, out of sequence packets,
overflow conditions (e.g. routing tables), etc. As in the above case,
it needs to be specified how these cases should be handled, whether by
dropping, or invoking error-handling protocol mechanisms. In both
this case and the previous case it may be necessary to further
describe the disposition of dropped frames - for instance, are they
treated as if they were never received, or do they reset any existing
state such as a connection or adjacency?
Finally, resource and performance scaling issues should be considered.
This does not mean that serious analysis need be done in the case of
every protocol. However, it does mean that in cases where it is
clear that operations may fail to succeed during operation
(e.g. routing table overflow) it is desirable to specify consistent
behavior between implementations when an operation hits such a limit.
3.2 The Liberal/Conservative Rule
The rule to be conservative in what you do, and be liberal in what you
accept [Postel 81] is well-known. To the extent which it is feasible,
this approach should be explicitly taken by a protocol specification,
rather than by the implementation. This serves to eliminate ambiguity
as to just how "liberal" an implementation should be.
This means that the specification should take care to specify send and
receive behavior separately, so that restrictions may be placed on
transmit behavior which do not apply on reception.
Desnoyers & Mellor [Page 6]
Internet Draft Guide for Internet Standards Writers November 1995
In addition, it is often necessary to draw a line between cases where
an implementation should accept packets as being essentially correct,
and where it should instead merely tolerate those packets without
failure. (although perhaps e.g. ignoring their contents or invoking
error procedures) This dividing line should be specified as clearly as
is practical in a specification, identifying those packets which
should not be accepted by any implementation.
It is worth noting that the most descriptive explanation of the
liberal/conservative dictum, the Router Requirements [RREQ 95], takes
a more conservative interpretation of "be liberal in what you accept
from others" than the interpretation used by many developers:
Software should be written to deal with every conceivable
error, no matter how unlikely. Eventually a packet will
come in with that particular combination of errors and
attributes, and unless the software is prepared, chaos can
ensue. It is best to assume that the network is filled
with malevolent entities that will send packets designed to
have the worst possible effect. This assumption will lead
to suitably protective design. The most serious problems
in the Internet have been caused by unforeseen mechanisms
triggered by low probability events; mere human malice
would never have taken so devious a course!
Under this interpretation of the liberal/conservative rule, the
implementor should take care that the implementation can accept
any packet from the network without failure or malfunction.
However, in many cases the decision as to which packets should
be accepted for processing needs to be laid out in the protocol
specification.
An example of this is the case of a routing protocol, where
acceptance of flawed information can cause network failure. For
protocols such as this which much guard against the acceptance
of flawed information, at a minimum the specification should
identify packets which could have differing interpretations and
mandate that they be ignored. (for example, routing updates
which contain more data than the tuple count indicates)
3.3 Handling of Protocol Options
[this may be a contentious recommendation]
The most prevalent current practice in the specification of
Internet standards is to identify mandatory protocol features by
the term 'MUST', and optional features by 'MAY' or 'SHOULD'. In
Desnoyers & Mellor [Page 7]
Internet Draft Guide for Internet Standards Writers November 1995
the presence of a large number of optional features, a combina-
torial explosion of options which may or may not (or should but
might not) be implemented occurs. This leads to difficulty in
testing an implementation against the protocol specification,
and in the most severe case can lead to the possibility of some
(possibly un-analyzed) combination of options resulting in two
valid implementations of the standard being unable to intero-
perate with each other.
In order to impose some order on this complexity, it is proposed
that specifications incorporating large numbers of optional
features attempt to divide these options into classes, where an
implementation is required to implement either all of the
options in an option class or none at all. By reducing a large
number of optional features into a small number of optional con-
formance classes, a sharp reduction can be achieved in the
number of option combinations which must be analyzed when the
protocol is first specified, or tested and maintained when it is
implemented.
4.0 Document Checklist
The following is a checklist based on these suggestions which
can be applied to a document:
o Does it explain the purpose of the protocol?
o Does it reference or explain the algorithms used in the protocol?
o Does it give packet diagrams in recommended form, if applicable?
o Does it use the recommended meaning for any of the terms defined in
the glossary above?
o Does it separate explanatory portions of the document from
requirements?
o Does it describe differences from previous versions, if applicable?
o Does it give examples of protocol operation?
o Does it specify behavior in the face of incorrect operation by other
implementations?
o Does it delineate which packets should be accepted for processing
and which should be ignored?
o Does it consider performance and scaling issues?
o How many optional features (MAY, SHOULD) does it specify? If more
than [X], does it separate them into option classes?
o Have all combinations of options or option classes been examined for
incompatibility?
o If multiple descriptions of a requirement are given, does it
identify one as binding?
5. Authors' Addresses
Desnoyers & Mellor [Page 8]
Internet Draft Guide for Internet Standards Writers November 1995
Peter Desnoyers
Art Mellor
Midnight Networks Inc.
200 Fifth Ave.
Waltham, MA 02154
Phone: (617) 890-1001
Fax: (617) 890-0028
EMail: pjd@midnight.com
art@midnight.com
6. References
References are to be supplied.
Desnoyers & Mellor [Page 9]
