draft-ietf-stdguide-ops-00.txt   draft-ietf-stdguide-ops-01.txt 
st
Network Working Group G. Scott Network Working Group G. Scott
INTERNET DRAFT Defense Information Systems Agency INTERNET DRAFT Defense Information Systems Agency
August 1996 November 1996
Guide for Internet Standards Writers Guide for Internet Standards Writers
<draft-ietf-stdguide-ops-00.txt> <draft-ietf-stdguide-ops-01.txt>
Status of this Document Status of this Document
This document is an Internet Draft. Internet-Drafts are working This document is an Internet Draft. Internet Drafts are working
documents of the Internet Engineering Task Force (IETF), its areas, documents of the Internet Engineering Task Force (IETF), its areas,
and its working groups. Note that other groups may also distribute and its working groups. Note that other groups may also distribute
working documents as Internet Drafts. working documents as Internet Drafts.
Internet Drafts are draft documents valid for a maximum of six months Internet Drafts are draft documents valid for a maximum of six
and may be updated, replaced, or obsoleted by other documents at any months and may be updated, replaced, or obsoleted by other
time. It is not appropriate to use Internet Drafts as reference documents at any time. It is not appropriate to use Internet
material or to cite them other than as a "working draft" or "work in Drafts as reference material or to cite them other than as a
progress." "working draft" or "work in progress."
To learn the current status of any Internet Draft, please check the To learn the current status of any Internet-Draft, please check the
``1id-abstracts.txt'' listing contained in the Internet-Drafts Shadow ``1id-abstracts.txt'' listing contained in the Internet-Drafts
Directories on ds.internic.net (US East Coast), nic.nordu.net Shadow Directories on ds.internic.net (US East Coast),
(Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific nic.nordu.net (Europe), ftp.isi.edu (US West Coast), or
Rim). munnari.oz.au (Pacific Rim).
Distribution of this document is unlimited. Distribution of this document is unlimited.
This Internet Draft expires 21 February 1997. This Internet Draft expires 23 May 1997.
Abstract Abstract
This document is a guide for Internet standard writers. It defines those This document is a guide for Internet standard writers. It defines
characteristics that make standards coherent, unambiguous, and easy to those characteristics that make standards coherent, unambiguous,
interpret. Also, it singles out usage believed to have led to unclear and easy to interpret. Also, it singles out usage believed to have
specifications, resulting in non-interoperable interpretations in the past. led to unclear specifications, resulting in non-interoperable
interpretations in the past. These guidelines are to be used with |
RFC 1543, "Instructions to RFC Authors." |
This version of the document is a draft. It's intended to generate further This version of the document is a draft. It is intended to
discussion and addition by the STDGUIDE working group. Please send comments generate further discussion and addition by the STDGUIDE working
to stdguide@midnight.com or to the author. group. Please send comments to stdguide@midnight.com.
Table of Contents Table of Contents
1 Introduction 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . .
2 General Guidelines
2.1 Protocol Description
2.2 Discussion of Security
2.3 Level of Detail
2.4 Protocol Versions
2.5 Decision History
2.6 Response to Behavior Out of Scope
2.7 The Liberal/Conservative Rule
2.8 Handling of Protocol Options 2 General Guidelines . . . . . . . . . . . . . . . . . . . . . .
2.9 BNF Notation 2.1 Protocol Description . . . . . . .
2.10 Implementation Experience 2.2 Discussion of Security . . . . . .
3 Specific Guidelines 2.3 Level of Detail. . . . . . . .
3.1 Packet Diagrams 2.4 Protocol Versions. . . . . . .
3.2 Summary Tables 2.5 Decision History . . . . . . .
3.3 State Machine Descriptions 2.6 Response to Behavior Out of Scope. . . . . .
4 Glossary 2.7 The Liberal/Conservative Rule. . . . . . . .
5 Document Checklist
6 Author's Addresses 2.8 Handling of Protocol Options . . . . . . . .
7 References 2.9 Indicating Requirement Levels. . . . . . . . |
2.10 Notational Conventions . . . . . . |
2.11 Implementation Experience. . . . . . . . . .
2.12 Glossaries . . . . . . . . . . |
3 Specific Guidelines. . . . . . . . . . . . . . . . . . . . . .
3.1 Packet Diagrams. . . . . . . .
3.2 Summary Tables . . . . . . . .
3.3 State Machine Descriptions . . . . . . . . .
4 Document Checklist . . . . . . . . . . . . . . . . . . . . . .
5 Security Considerations. . . . . . . . . . . . . . . . . . . . |
6 Working Group Chair's Address . . . . . . . . . . . . . . . .
7 References . . . . . . . . . . . . . . . . . . . . . . . . . .
CHANGES FROM PREVIOUS DRAFT. . . . . . . . . . . . . . . . . . . . |
1 Introduction 1 Introduction
This document is a guide for Internet standard writers. It offers This document is a guide for Internet standard writers. It offers
guidelines on how to write a protocol specification with clarity, guidelines on how to write a protocol specification with clarity,
precision, and completeness. These guidelines are based on both prior precision, and completeness. These guidelines are based on both
successful and unsuccessful IETF specification experiences. Note that some prior successful and unsuccessful IETF specification experiences.
guidelines may not apply in certain situations. These guidelines are to be used with RFC 1543, "Instructions to RFC |
Authors," or its update. Note that some guidelines may not apply |
in certain situations.
The goal is to increase the possibility that multiple implementations of a The goal is to increase the possibility that multiple
protocol will interoperate. Writing specifications to these guidelines implementations of a protocol will interoperate. Writing
will not guarantee interoperability. However, a recognized barrier to the specifications to these guidelines will not guarantee
creation of interoperable protocol implementations is unclear interoperability. However, a recognized barrier to the creation of
specifications. interoperable protocol implementations is unclear specifications.
Many will benefit from having well-written protocol specifications. Many will benefit from having well-written protocol specifications.
Implementors will have a better chance to conform to the protocol Implementors will have a better chance to conform to the protocol
specification. Protocol testers can use the specification to derive specification. Protocol testers can use the specification to
unambiguous testable statements. Purchasers and users of the protocol will derive unambiguous testable statements. Purchasers and users of
have a better understanding of its capabilities. the protocol will have a better understanding of its capabilities.
2 General Guidelines 2 General Guidelines
It is important that multiple readers and implementors of a standard have It is important that multiple readers and implementors of a
the same understanding of a document. To this end, information should be standard have the same understanding of a document. To this end,
orderly and detailed. The following are general guidelines intended to information should be orderly and detailed. The following are
help in the production of such a document. general guidelines intended to help in the production of such a
document.
2.1 Protocol Description 2.1 Protocol Description
Standards must include a description of the purpose or context of a Standards track documents must include a description of the purpose |
protocol's use. The author of a protocol specification will have a great or context of the protocol's use. The author of a protocol
deal of knowledge as to the purpose of a protocol. However, the reader is specification will have a great deal of knowledge as to the purpose
more likely to have general networking knowledge and experience, rather of the protocol. However, the reader is more likely to have
than expertise in a particular protocol. Without an explanation of the general networking knowledge and experience, rather than expertise
purpose behind a protocol interpreting it is far more difficult, and a in a particular protocol. An explanation of the purpose will |
reader is more prone to error. give the reader a reference point for understanding the protocol |
and where it fits in the Internet. The Draft Standard RFC 1583 was |
recommended to the STDGUIDE working guide as providing a good |
example of this in it "Protocol Overview" section. |
The protocol's general description should also provide information |
on the relationship between the different parties to the protocol. |
This can be done by showing typical packet sequences. |
This also applies to the algorithms used by a protocol. A detailed This also applies to the algorithms used by a protocol. A detailed
description of the algorithms or citation of readily available references description of the algorithms or citation of readily available
that give such a description is necessary. references that give such a description is necessary.
2.2 Discussion of Security 2.2 Discussion of Security
If the Internet is to achieve its full potential in commercial, If the Internet is to achieve its full potential in commercial,
governmental, and personal affairs, it must assure users that deliveries of governmental, and personal affairs, it must assure users that
their information transfers are free from tampering or compromise. deliveries of their information transfers are free from tampering
Well-written security sections in standard protocol documents can do much to or compromise. Well-written security sections in standard protocol
achieve that condition. Implementors will find it easier to comply and do documents can do much to achieve that condition. Implementors will
security. Users can understand the security measures in place, and so have find it easier to comply and do security. Users can understand the
faith in the Internet. security measures in place, and so have faith in the Internet.
The security section should address several topics. Very important is a
description of the security issues the protocol solves, and what issues
remain unsolved. The effects the security measures have on the protocol's
use and performance. If possible, the discussion should address how much
insurance the implementation of the security measures achieves.
An author may not include security measures or considerations in the The security section should address several topics. Every |
protocol standard. If so, a detail explanation why they did not is standards track document must discuss the security risks inherent |
necessary. This discussion could present the reasons why the security in the protocol being specified. After the document's author has |
issues are unresolvable at this time. Alternatively, the author could set out the security risks the protocol is open to, he then must |
present a case why security is unneeded when using the protocol. discuss the remedies offered. Additionally, the effects the |
security measures have on the protocol's use and performance. If
possible, the discussion should address how much insurance the
implementation of the security measures achieves.
These security sections should be complete and stand alone. If security When no security measures are offered, the author must provide a |
measures are part of the general protocol text, they will be difficult to detailed explanation why. This discussion could present the |
find. If the security measures are not clear they may not be implemented, reasons why the security issues are unresolvable at this time.
nor will a user be assured that they exist. Alternatively, the author could present a case why security is
unneeded when using the protocol.
Finally, it is no longer acceptable that security sections consist solely These security sections should be complete and separate. If |
of statements similar to: "Security issues are not discussed in this RFC." security measures are part of the general protocol text, they will
be difficult to find. If the security measures are not clear they
may not be implemented, nor will a user be assured that they exist.
Finally, it is no longer acceptable that security sections consist
solely of statements similar to: "Security issues are not
discussed in this RFC."
2.3 Level of Detail 2.3 Level of Detail
The author should consider whether concise or verbose text best conveys the The author should consider what level of descriptive detail best |
protocol's intent. Concise text has several advantages. It makes the conveys the protocol's intent. Concise text has several
document easier to read. Such text reduces the chance for conflict between advantages. It makes the document easier to read. Such text
different portions of the specification. The reader can readily identify reduces the chance for conflict between different portions of the
the required protocol mechanisms in the standard. Also, it makes it easier specification. The reader can readily identify the required
to identify the requirements for protocol implementation. A disadvantage protocol mechanisms in the standard. Also, it makes it easier to
of concise descriptions is that a reader may not fully comprehend the identify the requirements for protocol implementation. A
reasoning behind the protocol, and thus make assumptions that will lead to disadvantage of concise descriptions is that a reader may not fully
implementation errors. comprehend the reasoning behind the protocol, and thus make
assumptions that will lead to implementation errors.
Longer descriptions may be necessary, however, to explain purpose, Longer descriptions may be necessary to explain purpose, |
background, rationale, implementation experience, or to provide tutorial background, rationale, implementation experience, or to provide |
information. This permits explanations at sufficient depth to insure tutorial information. This helps the reader understand the |
understanding of the protocol. Yet several dangers exist with lengthy protocol. Yet several dangers exist with lengthy text. Finding
text. Finding the protocol requirements in the text is difficult or the protocol requirements in the text is difficult or confusing.
confusing. An increased risk that the same mechanism may have multiple The same mechanism may have multiple descriptions, which leads to |
descriptions, which leads to misinterpretations or conflict. Lengthy text misinterpretations or conflict. Lengthy text is a challenge to the
is a challenge to the attention span of some readers. Finally, it is more attention span of some readers. Finally, it is more difficult to
difficult to comprehend, a consideration as English is not the native comprehend, a consideration as English is not the native language
language of the many worldwide readers of IETF standards. of the many worldwide readers of IETF standards.
One approach is to divide the standard into sections: one describing the One approach is to divide the standard into sections: one
protocol concisely, while another section consists of explanatory text. describing the protocol concisely, while another section consists
The STD 3/RFC 1122/RFC 1123 1812 provides examples of this method. of explanatory text. The STD 3/RFC 1122/RFC 1123 and Draft |
Standard RFC 1583 provides examples of this method. |
2.4 Protocol Versions 2.4 Protocol Versions
Often the standard is specifying a new version of an existing protocol. In Often the standard is specifying a new version of an existing
such a case, the authors should detail the differences between the previous protocol. In such a case, the authors should detail the
version and the new version. This should include the rationale for the differences between the previous version and the new version. This
changes, for example, implementation experience, changes in technology, should include the rationale for the changes, for example,
responding to user demand, etc. implementation experience, changes in technology, responding to
user demand, etc.
2.5 Decision History 2.5 Decision History
In standards development, reaching consensus requires making difficult In standards development, reaching consensus requires making
choices. Including a discussion history and rationales for a decision can difficult choices. By including a discussion history and |
prevent future revisiting of these disagreements later, when the original rationales for a decision, the author can prevent future revisiting |
parties have moved on. Occasionally, the alternative not taken may have of these disagreements later, when the original parties have moved
been simpler to implement, so including the logic behind the choice may on. Also, the knowledge of the "why" is as useful to an |
prevent future implementors from taking nonstandard shortcuts. implementor as the description of "how." For example, the |
alternative not taken may have been simpler to implement, so
including the logic behind the choice may prevent future
implementors from taking nonstandard shortcuts.
2.6 Response to Out of Specification Behavior 2.6 Response to Out of Specification Behavior
Recommend that detail description of the actions taken in case of behavior The STDGUIDE working group recommends that detail description of |
that is deviant from or exceeds the specification be included. This is an the actions taken in case of behavior that is deviant from or
area where implementors often differ in opinion as to the appropriate exceeds the specification be included. This is an area where
response. By specifying a common response, the standard author can strike implementors often differ in opinion as to the appropriate
a blow against the law of unintended consequences. response. By specifying a common response, the standard author can
reduce the risk that different inplementations will come in to |
conflict. |
The standard should describe responses to behavior explicitly forbidden or The standard should describe responses to behavior explicitly
out of the boundaries defined by the specification. Two possible forbidden or out of the boundaries defined by the specification.
approaches to such cases are discarding, or invoking error-handling Two possible approaches to such cases are discarding, or invoking
mechanisms. If discarding is chosen, detailing the disposition may be error-handling mechanisms. If discarding is chosen, detailing the
necessary. For instance, treat dropped frames as if they never were disposition may be necessary. For instance, treat dropped frames
received, or reset an existing connection or adjacency state. as if they were never received, or reset an existing connection or
adjacency state.
The specification should describe actions taken when critical resource or The specification should describe actions taken when critical
performance scaling limits are exceeded. This is not necessary for every resource or performance scaling limits are exceeded. This is not
case. It is necessary for cases where a risk of network degradation or necessary for every case. It is necessary for cases where a risk
operational failure exists. In such cases, a consistent behavior between of network degradation or operational failure exists. In such
implementations is necessary. cases, a consistent behavior between implementations is necessary.
2.7 The Liberal/Conservative Rule 2.7 The Liberal/Conservative Rule
A rule, first stated in RFC 791, recognized as having benefits in A rule, first stated in RFC 791, recognized as having benefits in
implementation robustness and interoperability is: implementation robustness and interoperability is:
"Be liberal in what you accept, and "Be liberal in what you accept, and
conservative in what you send." conservative in what you send."
Or establish restrictions on what a protocol transmits, but have few Or establish restrictions on what a protocol transmits, but be able |
restrictions on what it will receive. To avoid any confusion between the to deal with every conceivable error received. Caution is urged |
two, recommend that standard authors specify send and receive behavior in applying this approach in standards track protocols. It has in |
separately. the past lead to conflicts between vendors when interoperability |
fails. The sender accuses the receiver of failing to be liberal |
enough, and the receiver accuses the sender of not being |
conservative enough. Therefore, the author is obligated to provide |
extensive detail on send and receive behavior. |
The effect of this approach is that the description of reception will To avoid any confusion between the two, recommend that standard
require the most detailing. For implementations will be expected to accept authors specify send and receive behavior separately. The
any packet from the network without failure or malfunction. Therefore, the description of reception will require the most detailing. For |
actions taken to achieve that result, need to be laid out in the protocol implementations will be expected to accept any packet from the
specification. Standard authors should consider not just how to survive on network without failure or malfunction. Therefore, the actions
the network, but achieve the highest level of cooperation possible to limit taken to achieve that result, need to be laid out in the protocol
the amount of network disruption. The appearance of undefined information specification. Standard authors should consider not just how to
or conditions must not cause a network or host failure. This requires survive on the network, but achieve the highest level of
specification on how to attempt acceptance of most of the packets. Two cooperation possible to limit the amount of network disruption.
approaches are available, either using as much of the packet's content as The appearance of undefined information or conditions must not
possible, or invoking error procedures. Specify a dividing line on when to cause a network or host failure. This requires specification on
take which approach. how to attempt acceptance of most of the packets. Two approaches
are available, either using as much of the packet's content as
possible, or invoking error procedures. The author should specify |
a dividing line on when to take which approach.
A case for consideration is that of a routing protocol, where acceptance of A case for consideration is that of a routing protocol, where
flawed information can cause network failure. For protocols such as this, acceptance of flawed information can cause network failure. For
the specification should identify packets that could have differing protocols such as this, the specification should identify packets
interpretations and mandate that they be ignored. For example, routing that could have differing interpretations and mandate that they be |
updates contain more data than the tuple count shows. either rejected completely or the nature of the attempt to recover |
some information from them. For example, routing updates that |
contain more data than the tuple count shows. The protocol authors |
should consider whether some trailing data can be accepted as |
additional routes, or to reject the entire packet as suspect |
because it is non-conformant. |
2.8 Handling of Protocol Options 2.8 Handling of Protocol Options
Standards with many optional features increase the chance of Standards with many optional features increase the chance of
non-interoperable implementations. The danger is that different protocol non-interoperable implementations. The danger is that different
implementations may specify some optional combinations that are unable to protocol implementations may specify some optional combinations
interoperate with each other. Ideally, implementation experience purges that are unable to interoperate with each other. Ideally,
options from the protocol while the document moves along the standard implementation experience purges options from the protocol while
track. the document moves along the standard track.
Options should only be present in cases where the protocol has an item that Therefore, options should only be present in a protocol to |
a particular marketplace requires, or because it enhances the product. The support a particular market, e.g., the financial industry, or |
protocol specification must explain the full implications of either using network environment, e.g., a network constrained by limited |
the option or not, and the case for choosing either course. However, bandwidth. The protocol specification must explain the full |
omission of the optional item should have no interoperability consequences implications of either using the option or not, and the case for
for the implementation that does so. choosing either course. As part of this, the author needs to |
consider and describe how the options are intended to be used |
alongside other protocols. However, omission of the optional item |
should have no interoperability consequences for the implementation
that does so.
Certain cases will require the specifying of mutually exclusive options Certain cases will require the specifying of mutually exclusive
within a protocol. That is, the implementation of an optional feature options within a protocol. That is, the implementation of an
precludes the implementation of the other optional feature. For clarity, optional feature precludes the implementation of the other optional
provide details on when to implement one or the other, what the effect of feature. For clarity, the author needs to state when to implement |
choosing one over the other is, and what problems the implementor or user one or the other, what the effect of choosing one over the other
may face. The choice of one or the other options should have no is, and what problems the implementor or user may face. The choice
interoperability consequences between multiple implementations. of one or the other options should have no interoperability
consequences between multiple implementations.
The most prevalent current practice in the specification of Internet 2.9 Indicating Requirement Levels |
standards is to identify mandatory protocol features by the term "MUST,"
and optional features by "MAY" or "SHOULD."
2.9 Notational Conventions The Internet-Draft draft-bradner-key-words-03.txt, "Key words for |
use in RFCs to Indicate Requirement Levels," defines several words |
that can be used in many standards track documents to signify the |
mandatory protocol features from the optional features of the |
specification. The definitions provided are as they should be |
interpreted in implementing IETF standards. Note that the force of |
these words is modified by the requirement level of the document in |
which they are used. |
Formal syntax notations can be used to define complicated protocol concepts Some authors of existing IETF standards have chosen to capitalize |
or data types, and also to specify values of these data types. This these words to clarify or stress their intent, but this is not |
permits the protocol to be written with out concern on how the required. What is necessary, is that these words are used |
implementation is constructed or how the data type is represented during consistently throughout the document. That is, every mandatory or |
transfer. The specification is simplifed because it can be presented as optional protocol requirement shall be identified by the authors |
"axioms" that will be proven by implementation. and documented by these words. If a requirement is not identified |
in this manner, it will not be considered an equal part of the |
protocol and be likely passed over by the implementor. |
The formal specification of the syntax used should be referenced in the 2.10 Notational Conventions
text of the standard. Any extensions, subsets, alterations, or exceptions
to the formal syntax should be defined.
The STD 11/RFC 822 provides an example of this. In RFC 822 (Section 2 and Formal syntax notations can be used to define complicated protocol
Appendix D) the Backus-Naur Form (BNF) meta-language was extended to make concepts or data types, and to specify values of these data types. |
its representation smaller and easier to understand. Another example is This permits the protocol to be written without concern on how the
STD 16/RFC 1155 (Section 3.2) where a subset of the Abstract Syntax implementation is constructed, or how the data type is represented
Notation One (ASN.1) is defined. during transfer. The specification is simplified because it can be
presented as "axioms" that will be proven by implementation.
2.10 Implementation Experience The formal specification of the syntax used should be referenced in
the text of the standard. Any extensions, subsets, alterations, or
exceptions to the formal syntax should be defined.
For a protocol to be designated a standard, it must go through the rigors The STD 11/RFC 822 provides an example of this. In RFC 822
of actual implementation. This implementation experience should be (Section 2 and Appendix D) the Backus-Naur Form (BNF) meta-language
captured in the final document. For example, lessons learned from bakeoffs was extended to make its representation smaller and easier to
between multiple vendors. understand. Note, that the Internet-Draft |
draft-ietf-drums-abnf-01.txt, "Augmented BNF for Syntax |
Specifications: ABNF," captures |
RFC 822's definition so that it can be used as a reference. |
Another example is STD 16/RFC 1155 (Section 3.2) where a subset of
the Abstract Syntax Notation One (ASN.1) is defined.
The author of a standards track protocol needs to consider several |
things before they use a formal syntax notation. Is the formal |
specification language being used parseable by an existing machine? |
If no parser exists, is there enough information provided in the |
specification to permit the building of a parser? If not, it is |
likely the reader will not have enough information to decide what |
the notation means. Also, the author should remember machine |
parseable syntax is often unreadable by humans, and can make the |
specification excessive in length. Therefore, syntax notations |
cannot in place of a clearly written protocol description. |
2.11 Implementation Experience
For a protocol to be designated a standard, it must go through the
rigors of actual implementation. This implementation experience
should be captured in the final document. For example, lessons
learned from bake-offs between multiple vendors.
2.12 Glossary |
Every standards track RFC should have a glossary, as words can have |
many meanings. By defining any new words introduced, the author |
can avoid confusing or misleading the implementer. The definition |
should appear on the word's first appearance within the text of the |
protocol specification, and in a separate glossary section. |
It is likely that definition of the protocol will rely on many |
words frequently used in IETF documents. All authors must be |
knowledgeable of the common accepted definitions of these |
frequently used words. FYI 18/RFC 1983, "Internet Users' |
Glossary," provides definitions that are specific to the Internet. |
Any deviation from these definitions by authors is strongly |
discouraged. If circumstances require deviation, an author should |
state that he is altering the commonly accepted definition, and |
provide rationale as to the necessity of doing so. The altered |
definition must be included in the Glossary section. |
If the author uses the word as commonly defined, she does not have |
to include the definition in the glossary. As a minimum, FYI |
18/RFC 1983 should be referenced as a source. |
2.13 Protocol Parameter Assignment |
The common use of the Internet standard track protocols by the |
Internet community requires that the unique values be assigned to |
the parameter fields. The Internet Assigned Numbers Authority |
(IANA) is the central coordinator for the assignment of unique |
parameter values for Internet protocols. The authors of a |
developing protocol that use a link, socket, port, protocol, etc., |
need to contact the IANA to receive a number assignment. For |
further information on parameter assignment and current |
assignments, authors should reference STD 2/RFC 1700, "Assigned |
Numbers." |
3 Specific Guidelines 3 Specific Guidelines
The following are guidelines on how to present specific technical The following are guidelines on how to present specific technical
information in standards. information in standards.
3.1 Packet Diagrams 3.1 Packet Diagrams
Most link, network, and transport layer protocols have packet descriptions. Most link, network, and transport layer protocols have packet
Recommend that packet diagrams be included in the standard, as they are descriptions. The STDGUIDE working group recommends that packet |
very helpful to the reader. The preferred form for packet diagrams is a diagrams be included in the standard, as they are very helpful to
sequence of long words in network byte order, with each word horizontal on the reader. The preferred form for packet diagrams is a sequence
of long words in network byte order, with each word horizontal on
the page and bit numbering at the top: the page and bit numbering at the top:
0 1 2 3 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 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 | |Version| Prio. | Flow Label |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
In cases where a packet is strongly byte-aligned rather than word-aligned In cases where a packet is strongly byte-aligned rather than
(e.g., when byte-boundary variable-length fields are used), display packet word-aligned (e.g., when byte-boundary variable-length fields are
diagrams in a byte-wide format. Use different height boxes for short and used), display packet diagrams in a byte-wide format. The author |
long words, and broken boxes for variable-length fields: can use different height boxes for short and long words, and broken |
boxes for variable-length fields:
0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7
+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+
| Length N | | Length N |
+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+
| | | |
+ Address + + Address +
... ...
+ (N bytes) + + (N bytes) +
| | | |
+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+
| | | |
+ 2-byte field + + 2-byte field +
| | | |
+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+
3.2 Summary Tables 3.2 Summary Tables
The specifications of some protocols are particularly lengthy, sometimes The specifications of some protocols are particularly lengthy,
covering a hundred pages or more. In such cases the inclusion of a summary sometimes covering a hundred pages or more. In such cases the
table can reduce the risk of conformance failure by an implementation inclusion of a summary table can reduce the risk of conformance
through oversight. A summary table itemizes what in a protocol is failure by an implementation through oversight. A summary table
mandatory, optional, or prohibited. Summary tables do not guarantee itemizes what in a protocol is mandatory, optional, or prohibited.
conformance, but serve to assist an implementor in checking that they have Summary tables do not guarantee conformance, but serve to assist an
addressed all protocol features. implementor in checking that they have addressed all protocol
features.
The summary table will consist of, as a minimum, four (4) columns: The summary table will consist of, as a minimum, four (4) columns:
Protocol Feature, Section Reference, Status, and References/Footnotes. Use Protocol Feature, Section Reference, Status, and
additional columns if they further explain or clarify the protocol. References/Footnotes. The author may add columns if they further |
explain or clarify the protocol. |
In the Protocol Feature column describe the feature, for example, a command In the Protocol Feature column describe the feature, for example, a
word. Group series of related transactions under descriptive headers, for command word. We recommend grouping series of related |
example, RECEPTION. transactions under descriptive headers, for example, RECEPTION.
Section reference directs the implementor to the section, paragraph, or Section reference directs the implementor to the section,
page that describes the protocol feature in detail. paragraph, or page that describes the protocol feature in detail.
Status indicates whether the feature is mandatory, optional, or prohibited. Status indicates whether the feature is mandatory, optional, or
Provide a separate column for each possibility, or a single column with prohibited. The author can either use a separate column for each |
appropriate codes. These codes need to be defined at the start of the possibility, or a single column with appropriate codes. These
summary table to avoid confusion. Possible status codes: codes need to be defined at the start of the summary table to avoid
confusion. Possible status codes:
M - must M - mandatory M - must
MN - must not O - optional M - mandatory
S - should X - prohibited MN - must not
O - optional
S - should
X - prohibited
SN - should not SN - should not
Use the References/Footnotes column to point to other RFCs that are In the References/Footnotes column authors can point to other |
necessary to consider in implementing this protocol feature, or any RFCs that are necessary to consider in implementing this protocol
footnotes necessary to further explain the implementation. feature, or any footnotes necessary to explain the implementation
further.
RFCs 1122 and 1123 provide examples of summary tables. The STD 3/RFC 1122/RFC 1123 provides examples of summary tables.
3.3 State Machine Descriptions 3.3 State Machine Descriptions
A convenient method of presenting a protocol's behavior is as a A convenient method of presenting a protocol's behavior is as a
state-machine model. That is, a protocol can be described by as a series state-machine model. That is, a protocol can be described by a
of states resulting from a command, operation, or transaction. series of states resulting from a command, operation, or
State-machine models define the variables and constants that establish a transaction. State-machine models define the variables and
state, the events that cause state transitions, and the actions that result constants that establish a state, the events that cause state
from those transitions. Through these models, understanding the dynamic transitions, and the actions that result from those transitions.
operation of the protocol as sequence of state transitions that occur for Through these models, an understanding of the protocol's dynamic |
any given event. Detailed text description of the state machines is operation as sequence of state transitions that occur for any |
necessary. Also, recommend the use of diagrams, tables, or timelines to given event is possible. State transitions can be detailed by |
detail state transitions. diagrams, tables, or time lines. |
When using a state transition diagram, show each possible protocol state as Note that state-machine models are never to take the place of |
a box connected by state transition arcs. Label each arc with the event detailed text description of the specification. They are adjuncts |
that causes the transition, and, in parentheses, any actions taken during to the text. The protocol specification shall always take |
the transition. The STD 5/RFC 1112 provides an example of such a diagram. precedence in the case of a conflict. |
As ASCII text is the preferred storage format for RFCs, only simple
diagrams are possible. Tables can summarize more complex or extensive When using a state transition diagram, show each possible protocol
state transitions. state as a box connected by state transition arcs. The author |
should label each arc with the event that causes the transition, |
and, in parentheses, any actions taken during the transition. The
STD 5/RFC 1112 provides an example of such a diagram. As ASCII
text is the preferred storage format for RFCs, only simple diagrams
are possible. Tables can summarize more complex or extensive state
transitions.
In a state transition table, read events vertically and states In a state transition table, read events vertically and states
horizontally. Represent state transitions and actions in the form horizontally. The form, action/new state, represents state |
action/new-state. Use commas to separate multiple actions, and go on transitions and actions. Commas separate multiple actions, and |
succeeding lines as required. Present multiple actions in the order they succeeding lines are used as required. The authors should present |
must be executed, if relevant. Letters that follow the state indicate an multiple actions in the order they must be executed, if relevant.
explanatory footnote. The dash ('-') indicates an illegal transition. The Letters that follow the state indicate an explanatory footnote.
STD 51/RFC 1661 provides an example of such a state transition table. The The dash ('-') indicates an illegal transition. The STD 51/RFC
1661 provides an example of such a state transition table. The
initial columns and rows of that table are below as an example: initial columns and rows of that table are below as an example:
| State | State
| 0 1 2 3 4 5 | 0 1 2 3 4 5
Events| Initial Starting Closed Stopped Closing Stopping Events| Initial Starting Closed Stopped Closing Stopping
------+----------------------------------------------------------- ------+-----------------------------------------------------------
Up | 2 irc,scr/6 - - - - Up | 2 irc,scr/6 - - - -
Down | - - 0 tls/1 0 1 Down | - - 0 tls/1 0 1
Open | tls/1 1 irc,scr/6 3r 5r 5r Open | tls/1 1 irc,scr/6 3r 5r 5r
Close| 0 tlf/0 2 2 4 4 Close| 0 tlf/0 2 2 4 4
skipping to change at page 11, line ? skipping to change at page 11, line 4
| 0 1 2 3 4 5 | 0 1 2 3 4 5
Events| Initial Starting Closed Stopped Closing Stopping Events| Initial Starting Closed Stopped Closing Stopping
------+----------------------------------------------------------- ------+-----------------------------------------------------------
Up | 2 irc,scr/6 - - - - Up | 2 irc,scr/6 - - - -
Down | - - 0 tls/1 0 1 Down | - - 0 tls/1 0 1
Open | tls/1 1 irc,scr/6 3r 5r 5r Open | tls/1 1 irc,scr/6 3r 5r 5r
Close| 0 tlf/0 2 2 4 4 Close| 0 tlf/0 2 2 4 4
| |
TO+ | - - - - str/4 str/5 TO+ | - - - - str/4 str/5
TO- | - - - - tlf/2 tlf/3 TO- | - - - - tlf/2 tlf/3
The STD 18/RFC 904 also presents state transitions in table format. The STD 18/RFC 904 also presents state transitions in table format.
However, it lists transitions in the form n/a, where n is the next state However, it lists transitions in the form n/a, where n is the next
and a represents the action. The method in RFC 1661 is preferred as state and a represents the action. The method in RFC 1661 is
new-state logical follows action. Also, this RFC's Appendix C models preferred as new-state logically follows action. Also, this RFC's |
transitions as the Cartesian product of two state machines. This is a more Appendix C models transitions as the Cartesian product of two state
complex representation that may be difficult to comprehend for those machines. This is a more complex representation that may be
readers that are unfamiliar with the format. Recommend that authors difficult to comprehend for those readers that are unfamiliar with
present tables as defined in the previous paragraph. the format. The working group recommends that authors present |
tables as defined in the previous paragraph.
A final method of representing state changes is by a timeline. The two A final method of representing state changes is by a timeline. The
sides of the timeline represent the machines involved in the exchange. two sides of the timeline represent the machines involved in the
List the states the machines enter as time progresses (downward) along the exchange. The author lists the states the machines enter as time |
outside of timeline. Within the timeline, show the actions that cause the progresses (downward) along the outside of timeline. Within the
state transitions. An example: timeline, show the actions that cause the state transitions. An
example:
client server client server
| | | |
| | LISTEN | | LISTEN
SYN_SENT |----------------------- | SYN_SENT |----------------------- |
| \ syn j | | \ syn j |
| ----------------->| SYN_RCVD | ----------------->| SYN_RCVD
| | | |
| ------------------| | ------------------|
| syn k, ack j+1 / | | syn k, ack j+1 / |
ESTABLISHED |<---------------------- | ESTABLISHED |<---------------------- |
| | | |
4 Glossary 4 Document Checklist
Internet standards are to use the following terms. Deviations from the The following is a checklist based on these guidelines that can be |
definitions given are discouraged, as it will likely cause applied to a document:
misinterpretations among readers.
MAY 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 Internet meanings for any terms use |
to specify the protocol? |
o Are new or altered definitions for terms given in a glossary? |
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 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 Does it explain the rational and use of options?
o If multiple descriptions of a requirement are given, does it
identify one as binding?
o Have all mandatory and optional requirements be identified and |
documented by the accepted key words that define Internet |
requirement levels? |
This word defines the existence of an item that is optional. 5. Security Considerations |
MUST This document does not define any security service or mechanism. It|
does call on IETF standards authors to define clearly the way the |
protocol they are specifying does or does not provide security |
assurances to the user. |
This word defines the existence of an item that is an absolute requirement 6 Working Group Chair's Address
of the specification.
MUST NOT Gregor D. Scott
Director, Defense Information Systems Agency
ATTN: JIEO-JEBBD
Ft. Monmouth, NJ 07703-5613
USA
This phrase prohibits the use of the item. Phone: (908) 427-6856 |
Fax: (908) 532-0853 |
EMail: scottg@ftm.disa.mil
OPTIONAL 7 References
This word specifies that implementation of an item is discretionary. RFC 791 "Internet Protocol (IP)," J. Postel, September 1981.
RECOMMENDED RFC 904 "Exterior Gateway Protocol formal specification," D.
This word specifies an item that there may exist valid reasons in RFC 1112 "Host extensions for IP multicasting," S. Deering,
particular circumstances to ignore. August 1989
REQUIRED RFC 1122 "Requirements for Internet Hosts -- Communication Layers,"
October 1989
This word specifies an item that is an absolute requirement of the RFC 1123 "Requirements for Internet hosts -- Application and
specification. Support," October 1989
SHOULD RFC 1311 "Introduction to the STD Notes"
This word defines the existence of an item that there may exist valid RFC 1583 "OSPF Version 2" |
reasons in particular circumstances to ignore.
SHOULD NOT RFC 1602 "The Internet Standards Process - Revision 2"
RFC 1700 "Assigned Numbers," J. Reynolds, J. Postel, October 1994 |
This phrase means that there may exist circumstances when the described RFC 1983 "Internet Users' Glossary" |
behavior is acceptable or even useful. Even so, describe the full draft-ietf-drums-abnf-01.txt, "Augmented BNF for Syntax |
implications so that the implementor can carefully weigh the pros and cons Specifications: ABNF," D. Crocker |
of the behavior.
The above definitions are of a "contractual" nature. This RFC does not draft-bradner-key-words-03.txt, "Key words for use in RFCs to |
define technical terms. These definitions have been evolving with Indicate Requirement Levels," S. Bradner |
technology. Extensive and detailed technical definitions in documents aid CHANGES FROM PREVIOUS DRAFT
understanding.
5.0 Document Checklist Changes are marked by "|" along the right margin. Many of the changes
are editorial in nature. Some were rewriting sentences for clarity.
Others are noted as follows:
The following is a checklist based on these suggestions which can be 1. A reference to RFC 1543 was added to the Abstract and Introduction
applied to a document: so that authors would know that this was not a stand alone document.
That they had to comply to RFC 1543 as well.
o Does it explain the purpose of the protocol? 2. In section 2.1, text recommending a "Protocol Overview" and a
o Does it reference or explain the algorithms used in the protocol? description of how the parties to the protocol relate was added.
o Does it give packet diagrams in recommended form, if applicable? Reference to Draft Standard RFC 1583 was added.
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?
6. Author's Addresses 3. In section 2.2, text was added calling for discussion of all the
security risks a protocol faces, rather than just the security problems
the protocol solves.
Gregor D. Scott 4. In section 2.7, cautionary text regarding the use of the
Director, Defense Information Systems Agency liberal/conservative rule was added.
ATTN: JIEO-JEBBD
Ft. Monmouth, NJ 07703-5613 USA
Phone: (908) 532-7726 5. In section 2.8, text calling on authors to consider how protocol
Fax: (908) 532-7723 options are used with other protocols was added.
EMail: scottg@ftm.disa.mil
7. References 6. A new section, "2.9 Indicating Requirement Levels," was added to
discuss the use of key words to identify protocol mandatory and option
features.
RFC 791 "Internet Protocol (IP)," J. Postel, September 1981. 7. In section 2.10, a reference to DRUMS work in defining ABNF, and
cautionary text on using formal syntax notation was added.
RFC 904 "Exterior Gateway Protocol formal specification," D. Mills, 8. A new section, "2.12 Glossary," was added calling on standards
track protocol authors to include a glossary of new or revised terms.
RFC 1122 "Requirements for Internet Hosts -- Communication Layers," 9. A new section, "2.13 Protocol Parameter Assignment," calls on
October 1989 authors to get such assignments from IANA.
RFC 1123 "Requirements for Internet hosts -- Application and Support," 10. In section 3.3, a statement that text takes precedence over state
October 1989 machine models was added.
RFC 1311 "Introduction to the STD Notes" 11. The previous draft's section 4, "Glossary," was deleted. In its
place, a reference to draft-bradner-key-words-03.txt is made in the new
section 2.9.
RFC 1602 "The Internet Standards Process - Revision 2" 12. New items were added to section 4, "Document Checklist," to reflect
This Internet Draft expires 21 February 1997. changes above.
13. A new section 5, "Security Considerations," was added.
 End of changes. 91 change blocks. 
337 lines changed or deleted 495 lines changed or added

This html diff was produced by rfcdiff 1.33. The latest version is available from http://tools.ietf.org/tools/rfcdiff/