Writing Protocol Models
RFC 4101

• Status
• IESG evaluation record
• IESG writeups
• Email expansions
• History

• Versions
• 03

Network Working Group                                        E. Rescorla
Request for Comments: 4101                                    RTFM, Inc.
Category: Informational                                              IAB
                                                               June 2005

                        Writing Protocol Models

Status of This Memo

   This memo provides information for the Internet community.  It does
   not specify an Internet standard of any kind.  Distribution of this
   memo is unlimited.

Copyright Notice

   Copyright (C) The Internet Society (2005).

Abstract

   The IETF process depends on peer review.  However, IETF documents are
   generally written to be useful for implementors, not reviewers.  In
   particular, while great care is generally taken to provide a complete
   description of the state machines and bits on the wire, this level of
   detail tends to get in the way of initial understanding.  This
   document describes an approach for providing protocol "models" that
   allow reviewers to quickly grasp the essence of a system.

1.  Introduction

   The IETF process depends on peer review.  However, in many cases, the
   documents submitted for publication are extremely difficult to
   review.  Because reviewers have only limited amounts of time, this
   leads to extremely long review times, inadequate reviews, or both.
   In our view, a large part of the problem is that most documents fail
   to present an architectural model for how the protocol operates,
   opting instead to simply describe the protocol and let the reviewer
   figure it out.

   This is acceptable when documenting a protocol for implementors,
   because they need to understand the protocol in any case; but it
   dramatically increases the strain on reviewers.  Reviewers need to
   get the big picture of the system and then focus on particular
   points.  They simply do not have time to give the entire document the
   attention an implementor would.

Rescorla                     Informational                      [Page 1]
RFC 4101                Writing Protocol Models                June 2005

   One way to reduce this load is to present the reviewer with a
   MODEL -- a short description of the system in overview form.  This
   provides the reviewer with the context to identify the important or
   difficult pieces of the system and focus on them for review.  As a
   side benefit, if the model is done first, it can be serve as an aid
   to the detailed protocol design and a focus for early review, prior
   to protocol completion.  The intention is that the model would either
   be the first section of the protocol document or be a separate
   document provided with the protocol.

2.  The Purpose of a Protocol Model

   A protocol model needs to answer three basic questions:

   1. What problem is the protocol trying to achieve?
   2. What messages are being transmitted and what do they mean?
   3. What are the important, but unobvious, features of the protocol?

   The basic idea is to provide enough information that the reader could
   design a protocol which was roughly isomorphic to the protocol being
   described.  Of course, this doesn't mean that the protocol would be
   identical, but merely that it would share most important features.
   For instance, the decision to use a KDC-based authentication model is
   an essential feature of Kerberos [KERBEROS].  By contrast, the use of
   ASN.1 is a simple implementation decision.  S-expressions -- or XML,
   had it existed at the time -- would have served equally well.

   The purpose of a protocol model is explicitly not to provide a
   complete or alternate description of the protocol being discussed.
   Instead, it is to provide a big picture overview of the protocol so
   that readers can quickly understand the essential elements of how it
   works.

3.  Basic Principles

   In this section we discuss basic principles that should guide your
   presentation.

3.1.  Less is more

   Humans are only capable of keeping a very small number of pieces of
   information in their head at once.  Because we're interested in
   ensuring that people get the big picture, we have to dispense with a
   lot of detail.  That's good, not bad.  The simpler you can make
   things the better.

Rescorla                     Informational                      [Page 2]
RFC 4101                Writing Protocol Models                June 2005

3.2.  Abstraction is good

   A key technique for representing complex systems is to try to
   abstract away pieces.  For instance, maps are better than photographs
   for finding out where you want to go because they provide an
   abstract, stylized, view of the information you're interested in.
   Don't be afraid to compress multiple protocol elements into a single
   abstract piece for pedagogical purposes.

3.3.  A few well-chosen details sometimes help

   The converse of the previous principle is that sometimes details help