draft-ietf-stdguide-ops-04.txt   draft-ietf-stdguide-ops-05.txt 
Network Working Group G. Scott, Editor Network Working Group G. Scott, Editor
INTERNET DRAFT Defense Information Systems Agency INTERNET DRAFT Defense Information Systems Agency
December 1997
Guide for Internet Standards Writers Guide for Internet Standards Writers
<draft-ietf-stdguide-ops-04.txt> <draft-ietf-stdguide-ops-05.txt>
Status of this Memo Status of this Memo
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 months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
skipping to change at page 1, line 29 skipping to change at page 1, line 31
progress." 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 Shadow
Directories on ds.internic.net (US East Coast), nic.nordu.net Directories on ds.internic.net (US East Coast), nic.nordu.net
(Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific (Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific
Rim). Rim).
Distribution of this document is unlimited. Distribution of this document is unlimited.
This Internet Draft expires on 5 December 1997. This Internet Draft expires on 30 June 1997.
Abstract Abstract
This document is a guide for Internet standard writers. It defines This document is a guide for Internet standard writers. It defines
those characteristics that make standards coherent, unambiguous, and those characteristics that make standards coherent, unambiguous, and
easy to interpret. Also, it singles out usage believed to have led easy to interpret. Also, it singles out usage believed to have led
to unclear specifications, resulting in non-interoperable to unclear specifications, resulting in non-interoperable
interpretations in the past. These guidelines are to be used with interpretations in the past. These guidelines are to be used with
RFC 1543, "Instructions to RFC Authors." RFC 1543, ''Instructions to RFC Authors.''
This version of the document is a draft. It is intended to generate This version of the document is a draft.
further discussion and addition by the STDGUIDE working group.
Please send comments to stdguide@midnight.com.
CHANGES FROM PREVIOUS DRAFT CHANGES FROM PREVIOUS DRAFT
Section 2.10 was rewritten to avoid conflict with BCP 14/RFC 2119, A paragraph pointing to a pending document that further addresses
"Key words for use in RFCs to Indicate Requirement Level." security was updated.
References to RFC 1583 were changed to RFC 2178 which obsoleted it.
Editorial changes and corrections were also made.
Table of Contents Table of Contents
1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2
2 General Guidelines . . . . . . . . . . . . . . . . . . . . . . 3 2 General Guidelines . . . . . . . . . . . . . . . . . . . . . . 3
2.1 Discussion of Security . . . . . . . . . . . . . . . . . . . . 3 2.1 Discussion of Security . . . . . . . . . . . . . . . . . . . . 3
2.2 Protocol Description . . . . . . . . . . . . . . . . . . . . . 5 2.2 Protocol Description . . . . . . . . . . . . . . . . . . . . . 5
2.3 Target Audience . . . . . . . . . . . . . . . . . . . . . . . . 6 2.3 Target Audience . . . . . . . . . . . . . . . . . . . . . . . 6
2.4 Level of Detail . . . . . . . . . . . . . . . . . . . . . . . . 6 2.4 Level of Detail . . . . . . . . . . . . . . . . . . . . . . . 6
2.5 Protocol Versions . . . . . . . . . . . . . . . . . . . . . . . 6 2.5 Protocol Versions . . . . . . . . . . . . . . . . . . . . . . 6
2.6 Decision History . . . . . . . . . . . . . . . . . . . . . . . 7 2.6 Decision History . . . . . . . . . . . . . . . . . . . . . . . 7
2.7 Response to Out of Specification Behavior . . . . . . . . . . . 7 2.7 Response to Out of Specification Behavior . . . . . . . . . . 7
2.8 The Liberal/Conservative Rule . . . . . . . . . . . . . . . . . 7 2.8 The Liberal/Conservative Rule . . . . . . . . . . . . . . . . 7
2.9 Handling of Protocol Options . . . . . . . . . . . . . . . . . 8 2.9 Handling of Protocol Options . . . . . . . . . . . . . . . . . 8
2.10 Indicating Requirement Levels . . . . . . . . . . . . . . . . . 9 2.10 Indicating Requirement Levels . . . . . . . . . . . . . . . . 9
2.11 Notational Conventions . . . . . . . . . . . . . . . . . . . . 9 2.11 Notational Conventions . . . . . . . . . . . . . . . . . . . . 10
2.12 IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 10 2.12 IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10
2.13 Network Management Considerations . . . . . . . . . . . . . . . 10 2.13 Network Management Considerations . . . . . . . . . . . . . . 11
2.14 Scalability Considerations . . . . . . . . . . . . . . . . . . 11 2.14 Scalability Considerations . . . . . . . . . . . . . . . . . . 11
2.15 Network Stability . . . . . . . . . . . . . . . . . . . . . . . 11 2.15 Network Stability . . . . . . . . . . . . . . . . . . . . . . 11
2.16 Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 2.16 Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
3 Specific Guidelines . . . . . . . . . . . . . . . . . . . . . . 12 3 Specific Guidelines . . . . . . . . . . . . . . . . . . . . . 12
3.1 Packet Diagrams . . . . . . . . . . . . . . . . . . . . . . . . 12 3.1 Packet Diagrams . . . . . . . . . . . . . . . . . . . . . . . 12
3.2 Summary Tables . . . . . . . . . . . . . . . . . . . . . . . . 13 3.2 Summary Tables . . . . . . . . . . . . . . . . . . . . . . . . 13
3.3 State Machine Descriptions . . . . . . . . . . . . . . . . . . 14 3.3 State Machine Descriptions . . . . . . . . . . . . . . . . . . 14
3.4 Character Sets . . . . . . . . . . . . . . . . . . . . . . . . 16 3.4 Character Sets . . . . . . . . . . . . . . . . . . . . . . . . 16
4 Document Checklist . . . . . . . . . . . . . . . . . . . . . . 16 4 Document Checklist . . . . . . . . . . . . . . . . . . . . . . 16
5 Security Considerations . . . . . . . . . . . . . . . . . . . . 17 5 Security Considerations . . . . . . . . . . . . . . . . . . . 17
6 References . . . . . . . . . . . . . . . . . . . . . . . . . . 17 6 References . . . . . . . . . . . . . . . . . . . . . . . . . . 17
7 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . 18 7 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 18
8 Editor's Address . . . . . . . . . . . . . . . . . . . . . . . 19 8 Editor's Address . . . . . . . . . . . . . . . . . . . . . . . 19
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 standards-track document with clarity, guidelines on how to write a standards-track document with clarity,
precision, and completeness. These guidelines are based on both precision, and completeness. These guidelines are based on both
prior successful and unsuccessful IETF specification experiences. prior successful and unsuccessful IETF specification experiences.
These guidelines are to be used with RFC 1543, "Instructions to RFC These guidelines are to be used with RFC 1543, "Instructions to RFC
Authors," or its update. Note that some guidelines may not apply in Authors," or its update. Note that some guidelines may not apply in
certain situations. The process for standardizing protocols and certain situations.
procedures is given in BCP 9/RFC 2026, "The Internet Standards
Process -- Revision 3."
The process for standardizing protocols and procedures is given in
BCP 9/RFC 2026, "The Internet Standards Process -- Revision 3." Some
considerations for protocol design are given in RFC 1958,
Architectural Principles of the Internet."
The goal is to increase the possibility that multiple implementations The goal is to increase the possibility that multiple implementations
of a protocol will interoperate. Writing specifications to these of a protocol will interoperate. Writing specifications to these
guidelines will not guarantee interoperability. However, a guidelines will not guarantee interoperability. However, a
recognized barrier to the creation of interoperable protocol recognized barrier to the creation of interoperable protocol
implementations is unclear specifications. 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 derive
unambiguous testable statements. Purchasers and users of the unambiguous testable statements. Purchasers and users of the
skipping to change at page 5, line 9 skipping to change at page 5, line 16
not taken may be appropriate. There may be several security not taken may be appropriate. There may be several security
mechanisms that were not selected for a variety of reasons: cost or mechanisms that were not selected for a variety of reasons: cost or
difficulty of implementation; ineffectiveness for a given network difficulty of implementation; ineffectiveness for a given network
environment; or export control. By listing the mechanisms they did environment; or export control. By listing the mechanisms they did
not use and the reasons, editors can demonstrate that the protocol's not use and the reasons, editors can demonstrate that the protocol's
WG gave security the necessary thought. Also, this gives the WG gave security the necessary thought. Also, this gives the
protocol's users the information they need to consider whether one of protocol's users the information they need to consider whether one of
the non-selected mechanisms would be better suited to their the non-selected mechanisms would be better suited to their
particular requirements. particular requirements.
Currently, a RFC is being considered that would give guidance on how A document giving further guidance on security topics is in
to do a security analysis. It will provide a listing of classes of developmemnt. Authors should obtain a copy of the completed RFC to
attacks, and methods of analysis that are useful in developing help them prepare the security portion of the standard.
countermeasures to them. Standards authors should obtain a current
copy of this RFC to assist them in their preparation of the security
portion of the standard.
Finally, it is no longer acceptable that Security Considerations Finally, it is no longer acceptable that Security Considerations
sections consist solely of statements to the effect that security was sections consist solely of statements to the effect that security was
not considered in preparing the standard. not considered in preparing the standard.
Some examples of Security Considerations sections are found in Some examples of Security Considerations sections are found in
STD 33/RFC 1350, STD 51/RFC 1662, and STD 53/RFC 1939. STD 33/RFC 1350, STD 51/RFC 1662, and STD 53/RFC 1939.
2.2 Protocol Description 2.2 Protocol Description
skipping to change at page 5, line 36 skipping to change at page 5, line 40
This description must address the protocol's purpose, intended This description must address the protocol's purpose, intended
functions, services it provides, and, the arena, circumstances, or functions, services it provides, and, the arena, circumstances, or
any special considerations of the protocol's use. any special considerations of the protocol's use.
The authors of a protocol specification will have a great deal of The authors of a protocol specification will have a great deal of
knowledge as to the reason for the protocol. However, the reader is knowledge as to the reason for the protocol. However, the reader is
more likely to have general networking knowledge and experience, more likely to have general networking knowledge and experience,
rather than expertise in a particular protocol. An explanation of rather than expertise in a particular protocol. An explanation of
it's purpose and use will give the reader a reference point for it's purpose and use will give the reader a reference point for
understanding the protocol, and where it fits in the Internet. The understanding the protocol, and where it fits in the Internet. The
Draft Standard RFC 1583 was recommended to the STDGUIDE working guide Draft Standard RFC 2178 was recommended to the STDGUIDE working guide
as providing a good example of this in it's "Protocol Overview" as providing a good example of this in it's "Protocol Overview"
section. section.
The protocol's general description should also provide information on The protocol's general description must also provide information on
the relationship between the different parties to the protocol. the relationship between the different parties to the protocol.
This can be done by showing typical packet sequences. 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 description of the algorithms or citation of readily available
references that give such a description is necessary. references that give such a description is necessary.
2.3 Target Audience 2.3 Target Audience
RFCs have been written with many different purposes, ranging from the RFCs have been written with many different purposes, ranging from the
skipping to change at page 6, line 42 skipping to change at page 6, line 42
information. This helps the reader understand the protocol. Yet information. This helps the reader understand the protocol. Yet
several dangers exist with lengthy text. Finding the protocol several dangers exist with lengthy text. Finding the protocol
requirements in the text is difficult or confusing. The same requirements in the text is difficult or confusing. The same
mechanism may have multiple descriptions, which leads to mechanism may have multiple descriptions, which leads to
misinterpretations or conflict. Finally, it is more difficult to misinterpretations or conflict. Finally, it is more difficult to
comprehend, a consideration as English is not the native language of comprehend, a consideration as English is not the native language of
the many worldwide readers of IETF standards. the many worldwide readers of IETF standards.
One approach is to divide the standard into sections: one describing One approach is to divide the standard into sections: one describing
the protocol concisely, while another section consists of explanatory the protocol concisely, while another section consists of explanatory
text. The STD 3/RFC 1122/RFC 1123 and Draft Standard RFC 1583 text. The STD 3/RFC 1122/RFC 1123 and Draft Standard RFC 2178
provides examples of this method. provides examples of this method.
2.5 Protocol Versions 2.5 Protocol Versions
Often the standard is specifying a new version of an existing Often the standard is specifying a new version of an existing
protocol. In such a case, the authors should detail the differences protocol. In such a case, the authors should detail the differences
between the previous version and the new version. This should between the previous version and the new version. This should
include the rationale for the changes, for example, implementation include the rationale for the changes, for example, implementation
experience, changes in technology, responding to user demand, etc. experience, changes in technology, responding to user demand, etc.
2.6 Decision History 2.6 Decision History
In standards development, reaching consensus requires making In standards development, reaching consensus requires making
difficult choices. These choices are made through working group difficult choices. These choices are made through working group
discussions or from implementation experience. By including the discussions or from implementation experience. By including the
basis for a contentious decision, the author can prevent future basis for a contentious decision, the author can prevent future
revisiting of these disagreements later, when the original parties revisiting of these disagreements when the original parties have
have moved on. Also, the knowledge of the "why" is as useful to an moved on. Also, the knowledge of the "why" is as useful to an
implementor as the description of "how." For example, the implementor as the description of "how." For example, the
alternative not taken may have been simpler to implement, so alternative not taken may have been simpler to implement, so
including the reasons behind the choice may prevent future including the reasons behind the choice may prevent future
implementors from taking nonstandard shortcuts. implementors from taking nonstandard shortcuts.
2.7 Response to Out of Specification Behavior 2.7 Response to Out of Specification Behavior
The STDGUIDE working group recommends that detail description of the The STDGUIDE working group recommends that detail description of the
actions taken in case of behavior that is deviant from or exceeds the actions taken in case of behavior that is deviant from or exceeds the
specification be included. This is an area where implementors often specification be included. This is an area where implementors often
skipping to change at page 8, line 47 skipping to change at page 9, line 4
2.9 Handling of Protocol Options 2.9 Handling of Protocol Options
Specifications with many optional features increase the complexity of Specifications with many optional features increase the complexity of
the implementation and the chance of non-interoperable the implementation and the chance of non-interoperable
implementations. The danger is that different implementations may implementations. The danger is that different implementations may
specify some combination of options that are unable to interoperate specify some combination of options that are unable to interoperate
with each other. with each other.
As the document moves along the standard track, implementation As the document moves along the standard track, implementation
experience shall determine the need for each option. Implementation experience shall determine the need for each option. Implementation
sahll show whether the option should be a mandatory part of the shall show whether the option should be a mandatory part of the
protocol or remains an option. If an option is not implemented as protocol or remains an option. If an option is not implemented as
the document advances, it must be removed from the protocol before it the document advances, it must be removed from the protocol before it
reaches draft standard status. reaches draft standard status.
Therefore, options shall only be present in a protocol to address a Therefore, options shall only be present in a protocol to address a
real requirement. For example, options can support future real requirement. For example, options can support future
extensibility of the protocol, a particular market, e.g., the extensibility of the protocol, a particular market, e.g., the
financial industry, or a specific network environment, e.g., a financial industry, or a specific network environment, e.g., a
network constrained by limited bandwidth. They shall not be included network constrained by limited bandwidth. They shall not be included
as a means to "buy-off" a minority opinion. Omission of the optional as a means to "buy-off" a minority opinion. Omission of the optional
skipping to change at page 14, line 5 skipping to change at page 14, line 8
Section reference directs the implementor to the section, paragraph, Section reference directs the implementor to the section, paragraph,
or page that describes the protocol feature in detail. or page that describes the protocol feature in detail.
Status indicates whether the feature is mandatory, optional, or Status indicates whether the feature is mandatory, optional, or
prohibited. The author can either use a separate column for each prohibited. The author can either use a separate column for each
possibility, or a single column with appropriate codes. These codes possibility, or a single column with appropriate codes. These codes
need to be defined at the start of the summary table to avoid need to be defined at the start of the summary table to avoid
confusion. Possible status codes: confusion. Possible status codes:
M - must M - must or mandatory
M - mandatory
MN - must not MN - must not
O - optional O - optional
S - should S - should
SN - should not SN - should not
X - prohibited X - prohibited
In the References/Footnotes column authors can point to other RFCs In the References/Footnotes column authors can point to other RFCs
that are necessary to consider in implementing this protocol feature, that are necessary to consider in implementing this protocol feature,
or any footnotes necessary to explain the implementation further. or any footnotes necessary to explain the implementation further.
skipping to change at page 15, line 4 skipping to change at page 15, line 8
Tables can summarize more complex or extensive state transitions. 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. The form, action/new state, represents state horizontally. The form, action/new state, represents state
transitions and actions. Commas separate multiple actions, and transitions and actions. Commas separate multiple actions, and
succeeding lines are used as required. The authors should present succeeding lines are used as required. The authors should present
multiple actions in the order they must be executed, if relevant. multiple actions in the order they must be executed, if relevant.
Letters that follow the state indicate an explanatory footnote. The Letters that follow the state indicate an explanatory footnote. The
dash ('-') indicates an illegal transition. The STD 51/RFC 1661 dash ('-') indicates an illegal transition. The STD 51/RFC 1661
provides an example of such a state transition table. The initial provides an example of such a state transition table. The initial
columns and rows of that table are below as an example: columns and rows of that table follow 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 18, line 28 skipping to change at page 18, line 32
7 Acknowledgments 7 Acknowledgments
Peter Desnoyers and Art Mellor began the work on this document. The Peter Desnoyers and Art Mellor began the work on this document. The
area directors that oversaw the STDGUIDE WG's efforts were area directors that oversaw the STDGUIDE WG's efforts were
Scott Bradner, Mike O'Dell, and John Curran. Others that contributed Scott Bradner, Mike O'Dell, and John Curran. Others that contributed
to this document were: to this document were:
Bernard Aboba Bernard Aboba
Harald T. Alvestrand Harald T. Alvestrand
Fred Baker Fred Baker
Brian Carpenter
Robert Elz Robert Elz
Dirk Fieldhouse Dirk Fieldhouse
Dale Francisco Dale Francisco
Gary Malkin Gary Malkin
Neal McBurnett Neal McBurnett
Craig Partridge Craig Partridge
Henning Schulzrinne Henning Schulzrinne
Kurt Starsinic Kurt Starsinic
James Watt James Watt
8 Editor's Address 8 Editor's Address
Gregor D. Scott Gregor D. Scott
Director, Defense Information Systems Agency Director, Defense Information Systems Agency
ATTN: JIEO-JEBBD ATTN: JIEO-JEBBC
Ft. Monmouth, NJ 07703-5613 Ft. Monmouth, NJ 07703-5613
USA USA
Phone: (908) 427-6856 Phone: (732) 427-6856
Fax: (908) 532-0853 Fax: (732) 532-0853
EMail: scottg@ftm.disa.mil EMail: scottg@ftm.disa.mil
This Internet Draft expires on 30 June 1997.
 End of changes. 26 change blocks. 
44 lines changed or deleted 47 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/