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 Message-Id: <9511222047.AA02219@midnight.midnight.com> To: internet-drafts@CNRI.Reston.VA.US Subject: draft submission Reply-To: Peter Desnoyers 617/890-1001 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 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]