Internet Info 1997 December/Internet_Info_CD-ROM_Walnut_Creek_December_1997.iso/drafts/draft_n_r/draft-pjd-stdguide-00.txt

Internet Message Format | 1995-11-23 | 21KB

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 <[e-mail]>
Message-Id: <[e-mail]>
To: [e-mail]
Subject: draft submission
Reply-To: Peter Desnoyers 617/890-1001 <[e-mail]>

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
  [e-mail] : 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
   [e-mail] 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:  [phone]
   Fax:    [phone]
   EMail:  [e-mail]
           [e-mail]

6. References

   References are to be supplied.





































Desnoyers & Mellor                                              [Page 9]