idnits 2.17.1 draft-ietf-stdguide-ops-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-25) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity. ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 442 has weird spacing: '...es, and to sp...' == Line 623 has weird spacing: '... column autho...' == Line 637 has weird spacing: '...eration as se...' -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (March 1997) is 9903 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) No issues found here. Summary: 7 errors (**), 0 flaws (~~), 4 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group G. Scott, Editor 3 INTERNET DRAFT Defense Information Systems Agency 4 March 1997 6 Guide for Internet Standards Writers 7 9 Status of this Memo 11 This document is an Internet Draft. Internet Drafts are working 12 documents of the Internet Engineering Task Force (IETF), its areas, 13 and its working groups. Note that other groups may also distribute 14 working documents as Internet Drafts. 16 Internet Drafts are draft documents valid for a maximum of six months 17 and may be updated, replaced, or obsoleted by other documents at any 18 time. It is not appropriate to use Internet Drafts as reference 19 material or to cite them other than as a "working draft" or "work in 20 progress." 22 To learn the current status of any Internet-Draft, please check the 23 ``1id-abstracts.txt'' listing contained in the Internet-Drafts Shadow 24 Directories on ds.internic.net (US East Coast), nic.nordu.net 25 (Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific 26 Rim). 28 Distribution of this document is unlimited. 30 This Internet Draft expires on 17 September 1997. 32 Abstract 34 This document is a guide for Internet standard writers. It defines 35 those characteristics that make standards coherent, unambiguous, and 36 easy to interpret. Also, it singles out usage believed to have led 37 to unclear specifications, resulting in non-interoperable 38 interpretations in the past. These guidelines are to be used with 39 RFC 1543, "Instructions to RFC Authors." 41 This version of the document is a draft. It is intended to generate 42 further discussion and addition by the STDGUIDE working group. 43 Please send comments to stdguide@midnight.com. 45 CHANGES FROM THE PREVIOUS DRAFT 47 The order of section 2 was changed to emphasize security 48 considerations. 50 Section 2.1 was extensively revised to cover additional points 51 regarding security. 53 A section (2.3) was added discussing the need for each IETF Standard 54 to have a description of the target audience. 56 The protocol option section (2.9) was expanded to cover default 57 settings, separate option documents, permitting options in support of 58 future extensibility, and the impact of implementation experience on 59 proposed options. 61 The subsection on Implementation Experience was deleted. The affect 62 of implementation experience on the standard is now discussed as part 63 of subsections 2.6 and 2.9. This was done to keep related 64 information together. 66 Text in sections 2.2, 2.10, 4, and 5 were revised for clarity. 68 Section 2.12 was revised to require the standard to specify the rules 69 and procedures by which IANA will register constants and tags. 71 A section (2.13) was added to require standards to address management 72 issues. 74 A section (2.14) was added to require standards to address 75 scalability issues. 77 A section (2.15) was added to require standards to address network 78 stability. 80 A section (3.4) was added to discus how to support multilingual 81 character sets. 83 Table of Contents 85 1 Introduction 87 2 General Guidelines 88 2.1 Discussion of Security 89 2.2 Protocol Description 90 2.3 Target Audience 91 2.4 Level of Detail 92 2.5 Protocol Versions 93 2.6 Decision History 94 2.7 Response to Behavior Out of Scope 95 2.8 The Liberal/Conservative Rule 96 2.9 Handling of Protocol Options 97 2.10 Indicating Requirement Levels 98 2.11 Notational Conventions 99 2.12 IANA Considerations 100 2.13 Network Management Considerations 101 2.14 Scalability Considerations 102 2.15 Network Stability 103 2.16 Glossaries 105 3 Specific Guidelines 106 3.1 Packet Diagrams 107 3.2 Summary Tables 108 3.3 State Machine Descriptions 109 3.4 Character Sets 111 4 Document Checklist 113 5 Security Considerations 115 6 References 117 7 Acknowledgments 119 8 Editor's Address 121 1 Introduction 123 This document is a guide for Internet standard writers. It offers 124 guidelines on how to write a standards-track document with clarity, 125 precision, and completeness. These guidelines are based on both 126 prior successful and unsuccessful IETF specification experiences. 127 These guidelines are to be used with RFC 1543, "Instructions to RFC 128 Authors," or its update. Note that some guidelines may not apply in 129 certain situations. The process for standardizing protocols and 130 procedures is given in BCP 9/RFC 2026, "The Internet Standards 131 Process -- Revision 3." 133 The goal is to increase the possibility that multiple implementations 134 of a protocol will interoperate. Writing specifications to these 135 guidelines will not guarantee interoperability. However, a 136 recognized barrier to the creation of interoperable protocol 137 implementations is unclear specifications. 139 Many will benefit from having well-written protocol specifications. 140 Implementors will have a better chance to conform to the protocol 141 specification. Protocol testers can use the specification to derive 142 unambiguous testable statements. Purchasers and users of the 143 protocol will have a better understanding of its capabilities. 145 2 General Guidelines 147 It is important that multiple readers and implementors of a standard 148 have the same understanding of a document. To this end, information 149 should be orderly and detailed. The following are general guidelines 150 intended to help in the production of such a document. The IESG may 151 require that all or some of the following sections appear in a 152 standards track document. 154 2.1 Discussion of Security 156 If the Internet is to achieve its full potential in commercial, 157 governmental, and personal affairs, it must assure users that their 158 information transfers are free from tampering or compromise. Well- 159 written security sections in standards-track documents can help 160 promote the confidence level required. For an implementor will find 161 it easier to provide with the security measures specified. While 162 users will understand the security measures, and so have a higher 163 level of trust in the Internet. Above all, new protocols and 164 practices must not worsen overall Internet security. 166 A significant threat to the Internet are those individuals who are 167 motivated and capable of exploiting circumstances, events, or 168 vulnerabilities to cause harm by denying service, and/or destroying, 169 disclosing, or modifying information. Standards authors must accept 170 that the protocol they specify will be subject to attack. They are 171 responsible for determining what attacks are possible, and for 172 detailing the nature of the attacks in the document. Otherwise, they 173 must convincingly argue that attack is not realistic in a specific 174 environment, and restrict the use of the protocol to that 175 environment. 177 After the document has exhaustively identified the security risks the 178 protocol is exposed to, the authors must formulate and detail a 179 defense against those attacks. They must discuss the applicable 180 countermeasures employed, or the risk the user is accepting by using 181 the protocol. The countermeasures may be provided by a protocol 182 mechanism or by reliance on external mechanisms. Authors should be 183 knowledgeable of exiting security mechanisms, and reuse them if 184 practical. When cryptographic algorithms are use, the protocol 185 should be written to permit its substitution with another algorithm 186 in the future. Finally, the authors should discuss implementation 187 hints or guidelines, e.g., how to deal with untrustworthy data or 188 peer systems. 190 Additionally, the effects the security measures have on the 191 protocol's use and performance should be discussed. Security 192 measures will have an impact on the environment they are used in. 193 Perhaps users will now be locked out of portions of the Internet 194 previously open to them, or users will experience a degradation in 195 the speed of service. The user may decided to accept a greater risk 196 in exchange for improved access or service. But the user must be 197 able to make an informed decision. They need to understand the risks 198 they are facing and the costs of reducing their risk. 200 The discussion of security can be concentrated in the Security 201 Considerations section of the document, or throughout the document 202 where it is relevant to particular parts of the specification. If 203 the second approach is taken, the Security Considerations section 204 must summarized and make reference to the appropriate specification 205 sections. This will insure that the protocol's security measures are 206 emphasized to implementor and user both. 208 Currently, a RFC is being considered that would give guidance on how 209 to do a security analysis. It will provide a listing of classes of 210 attacks, and methods of analysis that are useful in developing 211 countermeasures to them. Standards authors should obtain a current 212 copy of this RFC to assist them in their preparation of the security 213 portion of the standard. 215 Finally, it is no longer acceptable that Security Considerations 216 sections consist solely of statements to the effect that security was 217 not considered in preparing the standard. 219 Some examples of Security Considerations sections are found in 220 STD 33/RFC 1350, STD 51/RFC 1662, and STD 53/RFC 1939. 222 2.2 Protocol Description 224 Standards track documents must include a description of the protocol. 225 This description should address the protocol's purpose, intended 226 functions, and services it provides. Also addressed should be the 227 arena, circumstances, or any special considerations of its use. 229 The authors of a protocol specification will have a great deal of 230 knowledge as to the reason for the protocol. However, the reader is 231 more likely to have general networking knowledge and experience, 232 rather than expertise in a particular protocol. An explanation of 233 it's purpose and use will give the reader a reference point for 234 understanding the protocol, and where it fits in the Internet. The 235 Draft Standard RFC 1583 was recommended to the STDGUIDE working guide 236 as providing a good example of this in it's "Protocol Overview" 237 section. 239 The protocol's general description should also provide information on 240 the relationship between the different parties to the protocol. 241 This can be done by showing typical packet sequences. 243 This also applies to the algorithms used by a protocol. A detailed 244 description of the algorithms or citation of readily available 245 references that give such a description is necessary. 247 2.3 Target Audience 249 RFCs have been written with many different purposes, ranging from the 250 technical to the administrative. Those written as standards should 251 clearly identify the intended audience, for example, designers, 252 implementors, testers, help desk personnel, educators, end users, or 253 others. If there are multiple audiences being addressed in the 254 document, what sections are for each audience needs to be identified. 255 The goal is to help the reader discover and focus on what they have 256 turned to the document for, and avoid what they may find confusing, 257 diverting, or extraneous. 259 2.4 Level of Detail 261 The author should consider what level of descriptive detail best 262 conveys the protocol's intent. Concise text has several advantages. 263 It makes the document easier to read. Such text reduces the chance 264 for conflict between different portions of the specification. The 265 reader can readily identify the required protocol mechanisms in the 266 standard. Also, it makes it easier to identify the requirements for 267 protocol implementation. A disadvantage of concise descriptions is 268 that a reader may not fully comprehend the reasoning behind the 269 protocol, and thus make assumptions that will lead to implementation 270 errors. 272 Longer descriptions may be necessary to explain purpose, background, 273 rationale, implementation experience, or to provide tutorial 274 information. This helps the reader understand the protocol. Yet 275 several dangers exist with lengthy text. Finding the protocol 276 requirements in the text is difficult or confusing. The same 277 mechanism may have multiple descriptions, which leads to 278 misinterpretations or conflict. Finally, it is more difficult to 279 comprehend, a consideration as English is not the native language of 280 the many worldwide readers of IETF standards. 282 One approach is to divide the standard into sections: one describing 283 the protocol concisely, while another section consists of explanatory 284 text. The STD 3/RFC 1122/RFC 1123 and Draft Standard RFC 1583 285 provides examples of this method. 287 2.5 Protocol Versions 289 Often the standard is specifying a new version of an existing 290 protocol. In such a case, the authors should detail the differences 291 between the previous version and the new version. This should 292 include the rationale for the changes, for example, implementation 293 experience, changes in technology, responding to user demand, etc. 295 2.6 Decision History 297 In standards development, reaching consensus requires making 298 difficult choices. These choices are made through working group 299 discussions or from implementation experience. By including the 300 basis for a contentious decision, the author can prevent future 301 revisiting of these disagreements later, when the original parties 302 have moved on. Also, the knowledge of the "why" is as useful to an 303 implementor as the description of "how." For example, the 304 alternative not taken may have been simpler to implement, so 305 including the reasons behind the choice may prevent future 306 implementors from taking nonstandard shortcuts. 308 2.7 Response to Out of Specification Behavior 310 The STDGUIDE working group recommends that detail description of the 311 actions taken in case of behavior that is deviant from or exceeds the 312 specification be included. This is an area where implementors often 313 differ in opinion as to the appropriate response. By specifying a 314 common response, the standard author can reduce the risk that 315 different implementations will come in to conflict. 317 The standard should describe responses to behavior explicitly 318 forbidden or out of the boundaries defined by the specification. Two 319 possible approaches to such cases are discarding, or invoking 320 error-handling mechanisms. If discarding is chosen, detailing the 321 disposition may be necessary. For instance, treat dropped frames as 322 if they were never received, or reset an existing connection or 323 adjacency state. 325 The specification should describe actions taken when critical 326 resource or performance scaling limits are exceeded. This is not 327 necessary for every case. It is necessary for cases where a risk of 328 network degradation or operational failure exists. In such cases, a 329 consistent behavior between implementations is necessary. 331 2.8 The Liberal/Conservative Rule 333 A rule, first stated in RFC 791, recognized as having benefits in 334 implementation robustness and interoperability is: 336 "Be liberal in what you accept, and 337 conservative in what you send." 339 Or establish restrictions on what a protocol transmits, but be able 340 to deal with every conceivable error received. Caution is urged in 341 applying this approach in standards track protocols. It has in the 342 past lead to conflicts between vendors when interoperability fails. 343 The sender accuses the receiver of failing to be liberal enough, and 344 the receiver accuses the sender of not being conservative enough. 345 Therefore, the author is obligated to provide extensive detail on 346 send and receive behavior. 348 To avoid any confusion between the two, recommend that standard 349 authors specify send and receive behavior separately. The 350 description of reception will require the most detailing. For 351 implementations will be expected to accept any packet from the 352 network without failure or malfunction. Therefore, the actions taken 353 to achieve that result, need to be laid out in the protocol 354 specification. Standard authors should consider not just how to 355 survive on the network, but achieve the highest level of cooperation 356 possible to limit the amount of network disruption. The appearance 357 of undefined information or conditions must not cause a network or 358 host failure. This requires specification on how to attempt 359 acceptance of most of the packets. Two approaches are available, 360 either using as much of the packet's content as possible, or invoking 361 error procedures. The author should specify a dividing line on when 362 to take which approach. 364 A case for consideration is that of a routing protocol, where 365 acceptance of flawed information can cause network failure. For 366 protocols such as this, the specification should identify packets 367 that could have differing interpretations and mandate that they be 368 either rejected completely or the nature of the attempt to recover 369 some information from them. For example, routing updates that 370 contain more data than the tuple count shows. The protocol authors 371 should consider whether some trailing data can be accepted as 372 additional routes, or to reject the entire packet as suspect because 373 it is non-conformant. 375 2.9 Handling of Protocol Options 377 Specifications with many optional features increase the complexity of 378 the implementation and the chance of non-interoperable 379 implementations. The danger is that different implementations may 380 specify some combination of options that are unable to interoperate 381 with each other. 383 As the document moves along the standard track, implementation 384 experience should purge options from the protocol.. Implementation 385 will show whether the option is needed or not, whether it should be a 386 mandatory part of the protocol or remain an option. If an option is 387 not implemented as the document advances, it must be removed from the 388 protocol before it reaches draft standard status. 390 Therefore, options should only be present in a protocol to address a 391 real requirement. For example, to support future extensibility of 392 the protocol, a particular market, e.g., the financial industry, or a 393 specific network environment, e.g., a network constrained by limited 394 bandwidth. They should not be included as a means to "buy-off" a 395 minority opinion. Omission of the optional item should have no 396 interoperability consequences for the implementation that does so. 398 One possible approach is to document protocol options in a separate 399 document. Doing so would make it clear that the options are not 400 integral to the implementation of the protocol, and would keep the 401 main protocol specification clean. Regardless of whether they appear 402 within the specification or in a separate document, the text should 403 discuss the full implications of either using the option or not, and 404 the case for choosing either course. As part of this, the author 405 needs to consider and describe how the options are intended to be 406 used alongside other protocols. The text must also specify the 407 default conditions of all options. For security checking options the 408 default condition is on or enabled. 410 There may be occasions when mutually exclusive options appear within 411 a protocol. That is, the implementation of an optional feature 412 precludes the implementation of the other optional feature. For 413 clarity, the author needs to state when to implement one or the 414 other, what the effect of choosing one over the other is, and what 415 problems the implementor or user may face. The choice of one or the 416 other options should have no interoperability consequences between 417 multiple implementations. 419 2.10 Indicating Requirement Levels 421 The Internet-Draft draft-bradner-key-words-03.txt, "Key words for use 422 in RFCs to Indicate Requirement Levels," defines several words that 423 are necessary for writing a standards track document. These words 424 separate the mandatory protocol features of the specification from 425 the optional features. The definitions provided are as they should 426 be interpreted in implementing IETF standards. Note that in IETF 427 Standards the intent of these words is binding on implementors and 428 other users of the document. 430 Some authors of existing IETF standards have chosen to capitalize 431 these words to clarify or stress their intent, but this is not 432 required. What is necessary, is that these words are used 433 consistently throughout the document. That is, every mandatory or 434 optional protocol requirement shall be identified by the authors and 435 documented by these words. If a requirement is not identified in 436 this manner, it will not be considered an equal part of the protocol 437 and be likely passed over by the implementor. 439 2.11 Notational Conventions 441 Formal syntax notations can be used to define complicated protocol 442 concepts or data types, and to specify values of these data types. 443 This permits the protocol to be written without concern on how the 444 implementation is constructed, or how the data type is represented 445 during transfer. The specification is simplified because it can be 446 presented as "axioms" that will be proven by implementation. 448 The formal specification of the syntax used should be referenced in 449 the text of the standard. Any extensions, subsets, alterations, or 450 exceptions to the formal syntax should be defined. 452 The STD 11/RFC 822 provides an example of this. In RFC 822 (Section 453 2 and Appendix D) the Backus-Naur Form (BNF) meta-language was 454 extended to make its representation smaller and easier to understand. 455 Note, that the Internet-Draft draft-ietf-drums-abnf-01.txt, 456 "Augmented BNF for Syntax Specifications: ABNF," captures RFC 822's 457 definition so that it can be used as a reference. Another example is 458 STD 16/RFC 1155 (Section 3.2) where a subset of the Abstract Syntax 459 Notation One (ASN.1) is defined. 461 The author of a standards track protocol needs to consider several 462 things before they use a formal syntax notation. Is the formal 463 specification language being used parseable by an existing machine? 464 If no parser exists, is there enough information provided in the 465 specification to permit the building of a parser? If not, it is 466 likely the reader will not have enough information to decide what the 467 notation means. Also, the author should remember machine parseable 468 syntax is often unreadable by humans, and can make the specification 469 excessive in length. Therefore, syntax notations cannot take the 470 place of a clearly written protocol description. 472 2.12 IANA Considerations 474 The common use of the Internet standard track protocols by the 475 Internet community requires that the unique values be assigned to the 476 parameter fields. The Internet Assigned Numbers Authority (IANA) is 477 the central coordinator for the assignment of unique parameter values 478 for Internet protocols. The authors of a developing protocol that 479 use a link, socket, port, protocol, etc., need to specify the rules 480 and procedures by which IANA will register constants and tags. The 481 author should ask IANA to review the rules and procedures for clarity 482 and feasibility prior to submitting the internet draft to the 483 standards track. For further information on parameter assignment and 484 current assignments, authors can reference STD 2/RFC 1700, "Assigned 485 Numbers." 487 2.13 Network Management Considerations 489 When relevant, each standard needs to discuss how to manage the 490 protocol being specified. This management process should be 491 compatible with the current IETF Standard management protocol. Also 492 a MIB must be defined within the standard or in a companion document. 493 The MIB must be compatible with current SMI and parseable using a 494 tool such as SMICng. Where management or a MIB is not necessary this 495 section of the standard should explain the reason it is not relevant 496 to the protocol. 498 2.14 Scalability Considerations 500 The standard should establish the limitations on the scale of use, 501 e.g., tens of millions of sessions, gigabits per second, etc., and 502 establish limits on the resources used, e.g, round trip time, 503 computing resources, etc. This is important because it establishes 504 the ability of the network to accommodate the number of users and the 505 complexity of their relations. The STD 53/RFC 1939 has an example of 506 such a section. If this is not applicable to the protocol and 507 explanation of why not should be included. 509 2.15 Network Stability 511 A standard should discuss the relationship between network topology 512 and convergence behavior. As part of this, any topology which would 513 be troublesome for the protocol should be identified. Additionally, 514 the specification should address any possible destablizing events, 515 and how the protocol resists or recovers from them. The purpose is 516 to insure that the network will stabilize, in a timely fashion, after 517 a change, and that a combination of errors or events will not plunge 518 the network into chaos. The STD 34/RFC 1058, as an example, has 519 sections which discuss how that protocol handles the affects of 520 changing topology. 522 2.16 Glossary 524 Every standards track RFC should have a glossary, as words can have 525 many meanings. By defining any new words introduced, the author can 526 avoid confusing or misleading the implementer. The definition should 527 appear on the word's first appearance within the text of the protocol 528 specification, and in a separate glossary section. 530 It is likely that definition of the protocol will rely on many words 531 frequently used in IETF documents. All authors must be knowledgeable 532 of the common accepted definitions of these frequently used words. 533 FYI 18/RFC 1983, "Internet Users' Glossary," provides definitions 534 that are specific to the Internet. Any deviation from these 535 definitions by authors is strongly discouraged. If circumstances 536 require deviation, an author should state that he is altering the 537 commonly accepted definition, and provide rationale as to the 538 necessity of doing so. The altered definition must be included in 539 the Glossary section. 541 If the author uses the word as commonly defined, she does not have to 542 include the definition in the glossary. As a minimum, FYI 18/RFC 543 1983 should be referenced as a source. 545 3 Specific Guidelines 547 The following are guidelines on how to present specific technical 548 information in standards. 550 3.1 Packet Diagrams 552 Most link, network, and transport layer protocols have packet 553 descriptions. The STDGUIDE working group recommends that packet 554 diagrams be included in the standard, as they are very helpful to the 555 reader. The preferred form for packet diagrams is a sequence of long 556 words in network byte order, with each word horizontal on the page 557 and bit numbering at the top: 559 0 1 2 3 560 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 561 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 562 |Version| Prio. | Flow Label | 563 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 565 In cases where a packet is strongly byte-aligned rather than 566 word-aligned (e.g., when byte-boundary variable-length fields are 567 used), display packet diagrams in a byte-wide format. The author can 568 use different height boxes for short and long words, and broken boxes 569 for variable-length fields: 571 0 1 2 3 4 5 6 7 572 +-+-+-+-+-+-+-+-+ 573 | Length N | 574 +-+-+-+-+-+-+-+-+ 575 | | 576 + Address + 577 ... 578 + (N bytes) + 579 | | 580 +-+-+-+-+-+-+-+-+ 581 | | 582 + 2-byte field + 583 | | 584 +-+-+-+-+-+-+-+-+ 586 3.2 Summary Tables 588 The specifications of some protocols are particularly lengthy, 589 sometimes covering a hundred pages or more. In such cases the 590 inclusion of a summary table can reduce the risk of conformance 591 failure by an implementation through oversight. A summary table 592 itemizes what in a protocol is mandatory, optional, or prohibited. 593 Summary tables do not guarantee conformance, but serve to assist an 594 implementor in checking that they have addressed all protocol 595 features. 597 The summary table will consist of, as a minimum, four (4) columns: 598 Protocol Feature, Section Reference, Status, and 599 References/Footnotes. The author may add columns if they further 600 explain or clarify the protocol. 602 In the Protocol Feature column describe the feature, for example, a 603 command word. We recommend grouping series of related transactions 604 under descriptive headers, for example, RECEPTION. 606 Section reference directs the implementor to the section, paragraph, 607 or page that describes the protocol feature in detail. 609 Status indicates whether the feature is mandatory, optional, or 610 prohibited. The author can either use a separate column for each 611 possibility, or a single column with appropriate codes. These codes 612 need to be defined at the start of the summary table to avoid 613 confusion. Possible status codes: 615 M - must 616 M - mandatory 617 MN - must not 618 O - optional 619 S - should 620 SN - should not 621 X - prohibited 623 In the References/Footnotes column authors can point to other RFCs 624 that are necessary to consider in implementing this protocol feature, 625 or any footnotes necessary to explain the implementation further. 627 The STD 3/RFC 1122/RFC 1123 provides examples of summary tables. 629 3.3 State Machine Descriptions 631 A convenient method of presenting a protocol's behavior is as a 632 state-machine model. That is, a protocol can be described by a 633 series of states resulting from a command, operation, or transaction. 634 State-machine models define the variables and constants that 635 establish a state, the events that cause state transitions, and the 636 actions that result from those transitions. Through these models, an 637 understanding of the protocol's dynamic operation as sequence of 638 state transitions that occur for any given event is possible. 639 State transitions can be detailed by diagrams, tables, or time lines. 641 Note that state-machine models are never to take the place of 642 detailed text description of the specification. They are adjuncts to 643 the text. The protocol specification shall always take precedence in 644 the case of a conflict. 646 When using a state transition diagram, show each possible protocol 647 state as a box connected by state transition arcs. The author should 648 label each arc with the event that causes the transition, and, in 649 parentheses, any actions taken during the transition. The STD 5/RFC 650 1112 provides an example of such a diagram. As ASCII text is the 651 preferred storage format for RFCs, only simple diagrams are possible. 652 Tables can summarize more complex or extensive state transitions. 654 In a state transition table, read events vertically and states 655 horizontally. The form, action/new state, represents state 656 transitions and actions. Commas separate multiple actions, and 657 succeeding lines are used as required. The authors should present 658 multiple actions in the order they must be executed, if relevant. 659 Letters that follow the state indicate an explanatory footnote. The 660 dash ('-') indicates an illegal transition. The STD 51/RFC 1661 661 provides an example of such a state transition table. The initial 662 columns and rows of that table are below as an example: 664 | State 665 | 0 1 2 3 4 5 666 Events| Initial Starting Closed Stopped Closing Stopping 667 ------+----------------------------------------------------------- 668 Up | 2 irc,scr/6 - - - - 669 Down | - - 0 tls/1 0 1 670 Open | tls/1 1 irc,scr/6 3r 5r 5r 671 Close| 0 tlf/0 2 2 4 4 672 | 673 TO+ | - - - - str/4 str/5 674 TO- | - - - - tlf/2 tlf/3 676 The STD 18/RFC 904 also presents state transitions in table format. 677 However, it lists transitions in the form n/a, where n is the next 678 state and a represents the action. The method in RFC 1661 is 679 preferred as new-state logically follows action. Also, this RFC's 680 Appendix C models transitions as the Cartesian product of two state 681 machines. This is a more complex representation that may be 682 difficult to comprehend for those readers that are unfamiliar with 683 the format. The working group recommends that authors present 684 tables as defined in the previous paragraph. 686 A final method of representing state changes is by a time line. The 687 two sides of the time line represent the machines involved in the 688 exchange. The author lists the states the machines enter as time 689 progresses (downward) along the outside of time line. Within the 690 time line, show the actions that cause the state transitions. An 691 example: 693 client server 694 | | 695 | | LISTEN 696 SYN_SENT |----------------------- | 697 | \ syn j | 698 | ----------------->| SYN_RCVD 699 | | 700 | ------------------| 701 | syn k, ack j+1 / | 702 ESTABLISHED |<---------------------- | 703 | | 705 3.4 Character Sets 707 At one time the Internet had a geographic boundary and was English 708 only. Since the Internet now extends internationally, application 709 protocols must assume that the contents of any text string may be in 710 a language other than English. Therefore, new or updated protocols 711 which transmit text must use ISO 10646 as the default Coded Character 712 Set, and RFC 2044, "UTF-8, a transformation format of Unicode and ISO 713 10646" as the default Character Encoding Scheme. An exception is the 714 use of US-ASCII for a protocol's controlling commands and replies. 715 Protocols that have a backwards compatibility requirement should use 716 the default of the existing protocol. This is in keeping with the 717 recommendations of the Character Set Workshop Report, draft-weider- 718 iab-char-wrkshop-00.txt. 720 4 Document Checklist 722 The following is a checklist based on these guidelines that can be 723 applied to a document: 725 o Does it identify the security risks? Are countermeasures for each 726 potential attack provided? Are the effects of the security 727 measures on the operating environment detailed? 728 o Does it explain the purpose of the protocol or procedure? Are the 729 intended functions and services addressed? Does it describe how it 730 relates to existing protocols? 731 o Does it consider scaling and stability issues? 732 o Are procedures for assigning numbers provided as guidance for IANA. 733 o Does it discuss how to manage the protocol being specified. Is a 734 MIB defined? 735 o Is a target audience defined? 736 o Does it reference or explain the algorithms used in the protocol? 737 o Does it give packet diagrams in recommended form, if applicable? 738 o Does it describe differences from previous versions, if applicable? 739 o Does it separate explanatory portions of the document from 740 requirements? 741 o Does it give examples of protocol operation? 742 o Does it specify behavior in the face of incorrect operation by 743 other implementations? 744 o Does it delineate which packets should be accepted for processing 745 and which should be ignored? 746 o If multiple descriptions of a requirement are given, does it 747 identify one as binding? 748 o How many optional features does it specify? Does it separate them 749 into option classes? 751 o Have all combinations of options or option classes been examined 752 for incompatibility? 753 o Does it explain the rationale and use of options? 754 o Have all mandatory and optional requirements be identified and 755 documented by the accepted key words that define Internet 756 requirement levels? 757 o Does it use the recommended Internet meanings for any terms use to 758 specify the protocol? 759 o Are new or altered definitions for terms given in a glossary? 761 5. Security Considerations 763 This document does not define a protocol or procedure that could be 764 subject to an attack. It establishes guidelines for the information 765 that should be included in RFCs that are to be submitted to the 766 standards track. In the area of security, IETF standards authors are 767 called on to define clearly the the threats faced by the protocol and 768 the way the protocol does or does not provide security assurances to the 769 user. 771 6 References 773 RFC 791 "Internet Protocol (IP)," J. Postel, September 1981. 775 RFC 904 "Exterior Gateway Protocol formal specification," D. 776 Mills, April 1984 778 RFC 1058 "Routing Information Protocol," C. Hedrick, June 1988 780 RFC 1112 "Host extensions for IP multicasting," S. Deering, 781 August 1989 783 RFC 1122 "Requirements for Internet Hosts -- Communication Layers," 784 October 1989 786 RFC 1123 "Requirements for Internet hosts -- Application and 787 Support," October 1989 789 RFC 1311 "Introduction to the STD Notes" 791 RFC 1350 "The TFTP Protocol (Revision 2)," K. Sollins, July 1992 793 RFC 1583 "OSPF Version 2" 795 RFC 1661 "The Point-to-Point Protocol (PPP)," W. Simpson, July 1994 796 RFC 1662 "PPP in HLDC-like Framing," W. Simpson, July 1994 798 RFC 1700 "Assigned Numbers," J. Reynolds, J. Postel, October 1994 800 RFC 1983 "Internet Users' Glossary" 802 RFC 1939 "Post Office Protocol - Version 3," J. Meyers, M. Rose, 803 May 1996 805 RFC 2026 "The Internet Standards Process -- Revision 3," S. 806 Bradner, October 1996 808 RFC 2044 "UTF-8, a transformation format of Unicode and ISO 10646," 809 F. Yergeau, October 1996 811 draft-ietf-drums-abnf-01.txt, "Augmented BNF for Syntax 812 Specifications: ABNF," D. Crocker 814 draft-bradner-key-words-03.txt, "Key words for use in RFCs to 815 Indicate Requirement Levels," S. Bradner 817 draft-weider-iab-char-wrkshop-00.txt, "Character Set Workshop 818 Report," C. Weider 820 7 Acknowledgments 822 8 Editor's Address 824 Gregor D. Scott 825 Director, Defense Information Systems Agency 826 ATTN: JIEO-JEBBD 827 Ft. Monmouth, NJ 07703-5613 828 USA 830 Phone: (908) 427-6856 831 Fax: (908) 532-0853 832 EMail: scottg@ftm.disa.mil