The Structure, Content, and Format of IETF RFCs

By

Malachy Walsh

Technical Report Number UL-CSIS-05-5

Submitted in partial fulfillment of the requirements for the degree of

Master of Science in Software Engineering in the

University of Limerick

Supervised by Dr Norah Power

Submitted to the University of Limerick, September 2005

Abstract In this paper, the structure, information content, and format used by the Internet

engineering task force (IETF) to produce request for comments (RFC) documents is examined. The structure, content, and format of RFCs are not completely documented. Instead RFC authors use both documented guidelines and norms established in previous RFCs. In this paper a template derived from these sources using content analysis is presented. This is then compared to the IEEE 830 standard for software requirements specifications. This comparison is made to discover whether lessons can be drawn from the RFC template that are relevant to the production of software requirements specifications.

1. INTRODUCTION The Internet engineering task force (IETF) is an organisation that deals with the

creation of Internet standards. The IETF standardization process includes the creation

and publication of documents called requests for comments (RFCs). These RFCs are

created using a flexible structure, content and format that allow them to be used to

document requirements in many different situations. Some RFCs may eventually

become Internet standards but many serve other purposes such as providing information

on technologies and documenting the IETF process itself. RFCs have been very

successful in the Internet standardization process as can be seen by the success of the

Internet protocols they specify. The possibility of translating this success to other types

of specification is therefore worth investigating.

In software requirements engineering many different situations are encountered.

The size of a project and the organisations involved can influence the approach taken.

Lauesen (2002) also describes different project types including in-house development,

contract development, and off-the-shelf purchase. Lauesen (2002) also suggests that a

requirements specification may have to fill a number of roles. These include managing

requirements, setting out client needs, forming part of a contract, and even a possible

legal role in court cases. Each of these situations can call for different types of

specification to be produced. However many commonly used requirements engineering

templates do not support this. The IEEE 830 standard, the IEEE Recommended

Practice for Software Requirements Specifications (IEEE, 1998), gives examples of

different layouts for requirements but does not correlate these with requirements

engineering situations. The specification content also remains the same in each layout.

Another commonly used template, the Volere template (Robertson and Robertson,

1999), includes a description of the project situation under the title ‘project issues’.

However it does not describe different situations or how to adapt the template to suit

them.

If RFC structure, content, and format could be applied to software requirements

specifications it could possibly lead to finding ways of making software requirements

specifications more suited to certain situations. This paper will derive a template for the

structure, content, and format of RFCs and compare it with a widely known software

requirements specification template, the IEEE 830 standard template (IEEE, 1998). A

2

template must be derived because at present the structure, content, and format of an

RFC document are influenced by rules and guidelines provided in a number of different

RFCs.

The guideline RFCs examined in this paper were (Scott, 1998), (Postel and

Reynolds, 1997), (Rescorla and Korver, 2003), (Rescorla, 2005), (Rosenberg and

Schulzrinne, 2005), (Hoffman, 2004) and (Bradner, 1997). An organisation separate

from the IETF, the Internet engineering steering group (IESG) is responsible for

ensuring that each RFC follows these guidelines. This paper will only deal with RFCs

that are created by the IETF, and not those sent to the RFC Editor by external sources

for publication.

The guidelines provided are deliberately very loose. Norms established by

previously published RFCs also influence the structure of RFCs. This paper derives

these norms and their influence on RFCs using content analysis and includes them in

the derived template.

1.1 The Internet Bodies The Internet bodies are a collection of organisations that together govern the

Internet. All of the Internet bodies depend on funding provided by the Internet society

(ISOC), an international organisation set up to develop and manage the Internet. ISOC

controls the Internet architecture board (IAB) and the Internet Research Task Force

(IRTF). The IRTF carries out research related to the Internet. The Internet Architecture

Board (IAB) controls the Internet Engineering Steering Group (IESG). The IAB also

manages the RFC Editor, which publishes RFCs electronically, and the Internet

Assigned Numbers Authority (IANA), which deals with formally defined Internet

parameters such as keywords and numbers (Ohta, 1998). The IESG manages the

Internet Engineering Task Force (IETF) technical activities. It is the IETF that carries

out the work of developing protocols. This includes creating RFCs.

The IETF is divided into a number of technical areas. Each area contains a

number of working groups. Sometimes working groups can be set up to work on

different aspects of the same Internet protocol. The SIP protocol for example has three

main working groups named SIP, SIPPING, and SIMPLE. Each of these groups

develops SIP-related RFCs.

3

Working Groups

Work Areas

Internet Assigned Numbers Authority (IANA)

Internet Research Task Force (IRTF)

RFC Editor

Internet Engineering Task Force (IETF)

Internet Engineering Steering Group (IESG)

Internet Architecture Board (IAB)

Internet Society (ISOC)

Figure 1. The structure of the Internet bodies: Adapted from (Treese, 1999)

Section two of this paper outlines the content analysis research methods used in

the study of the contribution of RFC guidelines and norms to the structure, content, and

format of RFCs. Section three presents the findings of this study. In section four a

proposed RFC template derived from these findings is presented. In the fifth section

this derived template is compared to the template in IEEE 830 software requirements

specification standard. Finally, in section six, conclusions drawn from this comparison

are given. These conclusions include advice to both the IETF and requirements

engineers on possible improvements to their respective documents.

4

2. CONTENT ANALYSIS Krippendorff (1980) defines content analysis as “a research technique for

making replicable and valid inferences from data to their context”. Busch et al (2005)

describe content analysis as a research method that can be used to analyse text to extract

quantitative and qualitative data. At a basic level content analysis consists of searching

through data for defined keywords or phrases using explicit rules. These keywords or

phrases characterise the category of data the researcher is looking for, known as a code.

Examination of the matches to these codes that are found allows inferences to be made

about the data. In the study described in this paper the inferences made relate to

discovering the structure, content, and format of RFC documents.

The greatest advantage of content analysis over other research methods is that it

allows large amounts of data to be studied effectively. However without automation it

can be a lengthy process (Busch et al, 2005). Even with automation texts have to be

examined manually to determine that the codes are valid and that all relevant ones have

been considered. Keywords and phrases must be carefully chosen so that codes are as

mutually exclusive as possible and false matches are reduced.

2.1 Data Selection Krippendorff (1980) states that the context of the data being analyzed must be

made explicit in content analysis studies. In the study described in this paper the data

used was a sample of RFC documents. Twenty-five Session Initiation Protocol (SIP)

related RFCs were examined using content analysis techniques. The aim was to find the

section headings and documentation techniques used by the SIP working groups in

practice in order to derive an RFC template. SIP documents were chosen as

development of documents relating to the SIP protocol was ongoing. The researcher

also had previous experience with research involving the SIP working group (Walsh,

2005).

The RFCs examined were selected as the first twenty-five to appear in the RFC

Editor on the 12/07/05 when the “session initiation protocol” was entered as a search

string in the RFC search page, http://www.rfc-editor.org/rfcsearch.html, with the other

options at their default values. This method of selection gave the most recent RFCs

produced relating to SIP. Recent documents were chosen, as they were more likely to

5

demonstrate the current state of practice in RFC creation. Five of the documents had

informational status, three were best current practices, and the remaining seventeen

were proposed standards. This gave a selection of RFCs with different purposes, and at

different stages on the standards track. The RFCs used in this study and the sizes of

their files are listed in appendix C.

2.2 Analysis Method The selected RFCs were downloaded from the RFC Editor website as plain text

files. No editing was performed on them. The text files were then loaded into

ATLAS.ti, a software tool for qualitative data analysis. ATLAS.ti is designed to

facilitate research using the grounded theory method. However it is also suitable for use

with other methods, such as content analysis.

ATLAS.ti allows multiple documents to be analyzed simultaneously. Analysis

takes the form of associating code words with selections of data, a process known as

coding. ATLAS.ti allows automatic or semi-automatic coding of text using a subset of

GREP. GREP is a formal syntax that allows powerful searching of text using regular

expressions.

An a priori coding technique was used in this study. Codes were formed before

the content analysis from examination of the RFC guidelines. Related codes were

grouped into categories in order to show what aspect of RFCs they addressed. The

codes and categories used are listed in appendix A.

For each code, an expression that indicated text relevant to that code was

searched for using ATLAS.ti’s automatic coding function. Searching for these codes

investigated whether the guidelines were actually used in practice, and if so, how they

were implemented. ATLAS.ti flagged lines containing text matching the expression

automatically. The matches found by this coding process are known as quotations. A

list of quotations for each code was created. It was necessary to examine these

quotations manually to find whether they were actually relevant to the code or were

false matches. If many quotations were found to be false matches the search expression

was altered to improve the search. Some initial codes did not provide any relevant

quotations and so were deleted. When a list of relevant quotations had been obtained

they were examined to find information on the code. The number of quotations, and

which of the documents they appeared in, also provided information about the code.

6

This information was interpreted by the researcher and used to form a proposed RFC

template.

The choice of content analysis as a research method in this study is validated by

the ability of content analysis to reveal the presence and strength of constructs in data

(Neuendorf, 2002). The validity of content analysis can be defined as the degree to

which the inferences made are supported by evidence (Krippendorff, 1980). Using a

structured and unbiased data-gathering process, and a priori codes, ensured validity in

this study. The correspondence between the inferences made, RFC creation guidelines,

and academic literature was also checked. These guidelines were the source for many

of the codes used. As they specified what should be in RFCs, they were valid

constructs for finding actual RFC structure, content, and format.

7

3. CONTRIBUTIONS OF THE RFC GUIDELINES AND NORMS

The Guide for Internet Standards Writers working group, chaired by Scott

(1998) state in their RFC ‘Guide for Internet standards writers’ that their primary aim is

to help produce RFCs that are clear, precise, and complete. This aims to ensure that

every reader of an RFC has a common understanding, in order to lead to interoperable

implementations of the RFC. The goal is to increase the possibility that multiple implementations of a protocol will interoperate

The RFC guideline documents help to achieve this goal by ensuring that good

documentation practices developed by the IETF are used consistently. The guidelines

can also ensure that important considerations that need to be taken into account when

creating a specification, such as security issues, are given due attention.

Because RFCs are used in so many different ways, RFC guidelines cannot

completely specify the format or structure of every RFC. RFC norms are needed to

show authors how to deal with different situations. Examining how previous RFCs

dealt with situations can show an RFC author how to proceed. Equally as important,

they can see where previous documents were wrong, and correct these mistakes. The

guidelines actively encourage the use of norms. They even suggest RFCs with

particular features that should be emulated. For example Scott (1998) writes. The STD 34/RFC 1058, as an example, has sections which discuss how that protocol handles the affects (sic) of changing topology. The following sections show the contributions of the guidelines and norms to the

structure, content, and format of RFCs, as shown by the content analysis and

examination of the RFC guidelines. These are then summarised. The objective of this

analysis was to derive a proposed RFC template representing what all RFCs have in

common. Numbers shown enclosed in brackets such as [1] refer to the RFCs used in

the content analysis. These are numbered and listed in Appendix C

8

3.1 Structure The RFC guidelines make some sections mandatory in every RFC document.

These include an introduction section, references, and a discussion of security

considerations. Other sections, such as a version history, may be required by the IESG

if they are seen as relevant. However, other than these sections, the content analysis

found the structure of RFCs to be very loose, allowing RFCs to be used for purposes as

diverse as defining common IETF terminology and specifying protocols. Each situation

had its own issues to be addressed and norms for dealing with these issues. Documents

with similar purposes were found to have similar structures.

The following sections detail the common sections found in the RFCs analyzed.

Some sections were found in all RFCs, while others were left out when not needed.

3.1.1 Abstract

Every RFC examined included an abstract, which was used to briefly explain the

purpose and scope of the document. The guidelines state that the abstract should be

shorter than 20 lines, include no references, and expand any acronyms used. The

normal practice found was to keep the abstract short. Only one of the abstracts of the

RFCs examined had more than one paragraph in length [16]. The average length of an

abstract section was found to be seven lines.

3.1.2 Introduction

An introduction section is required by the guidelines as the first numbered

section in every RFC. It can give a general overview of the document as well as further

explaining the purpose of the document. Possible purposes for the document given in

the guidelines are description of a protocol, discussion of a particular issue, making

proposals, and reporting the status of projects. An example introduction section is given

for each of these situations. This list of situations is not exhaustive however, as RFCs

are used for many other purposes. This is recognised in the guidelines. These paragraphs need not be followed word for word, but the general intent of the RFC must be made clear. In the RFC s examined, almost all had an introduction section except one, [9],

which had a section entitled ‘background and appropriateness’, and two whose first

section was entitled ‘overview’, [13] and [14]. Interestingly some RFCs with an

9

introduction section also included an overview section. These overviews mainly gave

descriptions of the behaviour of the system documented in the RFC rather than

discussing the document itself.

3.1.3 Terminology

The RFC guidelines state that a glossary, or section for definition of terms and

acronyms, should be present in every RFC that wishes to become a standard. The

reason given for this is to avoid confusion among those using the document.

Definitions are also recommended at the first mention of a new term or acronym in the

main text. The IETF also has its own organisational glossary, contained in a separate

RFC (Malkin, 1996). The guidelines require that RFC authors use the definitions in this

glossary unless circumstances require otherwise.

In the RFCs analyzed, a ‘terminology’ section was found placed either as a

subsection in, or after the introduction section in thirteen of the documents. However

this terminology section usually contained only a reference to the RFC that specifies

terms used to indicate requirement levels. 2. Terminology In this document, the key words "MUST", "MUST NOT", "REQUIRED","SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in RFC 2119 [3] and indicate requirement levels for compliant implementations.

In two instances, [14] and [15], the terminology section was replaced by a section called

‘requirements notation’ indicating that the only specific terminology used was the

requirements levels. This also indicates that RFC text can be written in plain language

without the need for technical terminology. In documents that had a section called

terminology any new terms were usually defined in a section after terminology, named

‘definitions’. 3. Definitions The following terms are used throughout this document:

Another approach that was used in five of the documents is a section entitled

‘conventions’. This conventions section usually included both a reference to

requirement level terms and definition of document-specific terms. These approaches

coexist, as indicated by the publication dates on the documents.

10

3.1.4 Main Content Sections

The structure of the main content section was found to vary depending on the

purpose of the RFC. Most of the RFCs were specifications for protocols and contained

requirements sections structured as outlined below. However RFCs for other purposes

also used requirements. For example two of the RFCs used in the content analysis, [6]

and [21], provided guidelines for RFC authors. These guidelines were expressed as

requirements. Seven RFCs were created to register new parameters with IANA. These

usually had a main content section dealing with the behaviour or use of the parameter

followed by an examples section. The registration of the new parameter was dealt with

in the IANA considerations section. Four of the analyzed RFCs expressed requirements

for future specification work. These requirements were organised by feature in contrast

to specification requirements, which were organised by function. Seven of the RFCs

described how to use or handle certain situations related to protocols. Their main

content was scenarios intended to explain what should be done. Obviously many more

types of RFC exist. However, from the content analysis, it appears that the main

content of RFCs usually includes requirements, examples, guidelines, or discussion.

Documents with similar purposes were also found to use similar structures, indicating

that their authors follow guidelines or norms.

3.1.5 Requirements

Requirements sections form the central part of those RFCs examined that define

or update protocols and their extensions. Most of the requirements sections examined

were long and included many sub-sections. They had many different structures. One

example of a requirements structure specific to one type of RFC was found in

Rosenberg and Schulzrinne (2005). This document provides guidelines on how to

structure requirements in documents specifying extensions to the SIP protocol. SIP extensions MUST clearly define the semantics of the extensions. Specifically, the extension MUST specify the behaviors expected of a UAC, UAS and proxy in processing the extension. This is often best described by having separate sections for each of these three elements. Each section SHOULD step through the processing rules in temporal order of the most common messaging scenario.

The structure described above shows that, in RFCs specifying SIP extensions,

requirements are structured by function or behaviour. Other types of RFC use different

structures. For example, structuring requirements by feature is not ideal in protocol

11

extensions as an extension usually adds a single feature to an existing protocol.

Structuring by function is more suitable in that situation.

In the requirement sections examined during the content analysis, requirements

were structured into paragraphs. Each paragraph generally contained one main

requirement. Other requirements related to the main requirement, such as quality

requirements and requirements preventing certain undesired interpretations of the text

were generally included in the same paragraph, as in the following example. When the current time equals or passes the session expiration for a session, the proxy MAY remove associated call state, and MAY free any resources associated with the call. Unlike the UA, it MUST NOT send a BYE.

3.1.6 Security Considerations

Security considerations are one of the sections that must be included in every

RFC. This was a deliberate choice on the part of the IETF to ensure that security was

not neglected in any document they produced (Rescorla and Korver, 2003). It may also

be seen an attempt to influence the development process through document constraints.

By requiring that security considerations be addressed in all documents, the IETF

ensures increased focus on security in the design of protocols. The IETF guidelines

state: The purpose of this is both to encourage document authors to consider security in their designs and to inform the reader of relevant security issues In all the RFCs examined security considerations sections were placed

immediately after the main content of the RFCs. This may be because security issues

are directly related to the main content.

The content analysis revealed a variety of structures to document security

considerations. One structure used was to deal with security issues throughout the

document and provide references to the relevant sections in the security considerations

section. Two of the RFCs examined, [4] and [22], used this structure. [4] is shown here

as an example. 4. Security Considerations Security is a critical requirement of the SIP-AAA Interface. Section 2.1.9 describes the threats and security requirements. Sections 2.2 and 2.3 elaborate on the authentication and authorization requirements.

12

In most of the RFCs examined the security considerations section was divided into

subsections. These subsections either detailed various attacks that could be made

against implementations of the specification, or the security risks introduced by

different features of the specification. Sometimes security was not a single

consideration. In some RFCs issues such as confidentiality, encryption, and

authentication were dealt with in subsections such as this example in [11]. 9. Security Considerations............................ 20 9.1. Confidentiality................................. 20 9.2. Message Integrity and Authenticity.............. 21 9.3. Outbound Authentication......................... 22 9.4. Replay Prevention............................... 22 9.5. Denial of Service Attacks Against Third Parties. 22 9.6. Denial Of Service Attacks Against Servers....... 23

A third structure used was to reference other RFCs that provided solutions to security

problems as in this extract from [8]. 11. Security Considerations The presence of caller preferences in a request has an effect on the ways in which the request is handled at a server. As a result, requests with caller preferences SHOULD be integrity-protected with the sips mechanism specified in RFC 3261, Section 26.

Some of the RFCs did not have any security considerations that applied to their content.

They dealt with this by including a short paragraph explaining why security

considerations were not relevant. This is seen in [10]. 4. Security Considerations The migration of the S/MIME requirement from Triple-DES to AES is not known to introduce any new security considerations.

Some security considerations sections examined included requirements. However it

was found that few of these requirements were vital to the specification. They were

more commonly recommendations on security rather than MUST or SHOULD level

requirements.

13

3.1.7 IANA considerations

The Internet Assigned Names Authority (IANA) keeps track of all numbers and

names used in Internet protocols. According to the RFC guidelines, RFCs that define

new numbers or names must register them with IANA. Of the RFCs examined, only

those that were on the track towards becoming Internet standards had IANA

considerations sections. Eight of the RFCs did not include this section. When present,

IANA considerations were usually placed after security considerations. Most

documents examined registered only one item with IANA. When more than one item

was registered as shown, in [17], a named sub-section was allocated to each. 10. IANA Considerations 10.1. Registration of "Join" SIP header Name of Header: Join Short form: none Normative description: section 7.1 of this document 10.2. Registration of "join" SIP Option-tag Name of option: join Description: Support for the SIP Join header SIP headers defined: Join Normative description: This document

Other possible consideration sections were described in the RFC guidelines. These

included scalability and network considerations. However none of these is mandatory

and none were found in the RFCs examined. These requirements were dealt with within

the main requirements themselves.

3.1.8 Acknowledgements and Contributors

The RFC guidelines suggest that contributors or acknowledgements sections can

be included in RFCs. All except four of the RFCs examined used an

Acknowledgements section before the references section. This section generally

consisted of a single paragraph thanking people who provided indirect input such as

comments to the document, or gave technical help or advice during its development.

The section is usually very brief as seen in an extract from [3] below. 6. Acknowledgements Jonathan Rosenberg, Henning Schulzrinne, Rohan Mahy, Dean Willis, and Allison Mankin provided useful comments on this document.

14

A Contributors section was less frequently used. Only six of the RFCs included

one. It was found to acknowledge individuals who were not part of the document

creation team but had contributed substantially or directly to the document.

Contributors were generally either former authors or IETF experts as seen in this

example from [9]. 8. Contributors Ilya Slain came up with the initial format of the text body contained in this document. He was previously listed as a co-author, however, he is no longer reachable.

3.1.9 Examples and scenarios

Document sections dealing with examples or scenarios were included in sixteen

of the RFCs analyzed. These sections were always positioned after the parts of the

specification they dealt with. However the actual location in the document varied.

Examples could be placed in the same section as the requirements they dealt with, in

separate sections, or both. Separate example sections were usually positioned at the end

of the document, before or after the security considerations section. 6. Syntax.. . . . . . . . . . . . . . . . . . . . . . . . . 7 6.1. The Replaces Header . . . . . . . . . . . . . . . 7 6.2. New Option Tag for Require and Supported Headers . 8 7. Usage Examples . . . . . . . . . . . . . . . . . . . . . 9 7.1. Replacing an Early Dialog at the Originator . . . . . . 9

Examples were found to use text, flow diagrams, formal syntax, and sometimes a

combination of these. When a flow diagram was used in an example it was almost

always followed by details in formal syntax.

3.1.10 References

A references section is required in every RFC that references other documents. It

is positioned at the end of the document. The IETF guidelines distinguish two types of

reference: normative references and informative references. Normative references in an

RFC are references to documents that are necessary to understand and use that RFC.

Informative references, also called informational references, list documents that provide

relevant but not vital information to the RFC reader. The content analysis revealed that

these two types of reference were placed in different sections or sub-sections in every

RFC examined. The informative references were placed after the normative ones.

15

Their numbers continued from the number of the last normative reference. Using a

single numbering scheme for both normative and informative references avoids

confusion. Every RFC examined included normative references. All but three of the

RFCs had informative references; [2], [3], and [23].

3.1.11 Authors’ addresses

This section was only found in the standard track documents examined. These

are documents that were being worked on to advance them towards becoming Internet

standards. Other documents had become informational RFCs and were no longer

worked on. The section includes all information necessary to contact the authors of the

document, including e-mail and phone numbers. This is important as it helps ensure

that documents do not become frozen. This section was usually positioned after the

references section.

3.1.12 Change Logs

The guidelines require a change log section in every RFC that has more than one

version. This is a form of version control and prevents uncontrolled change to a

document. The change log can also provide a rationale for the changes made, giving

readers of the document valuable insight into the development process. Since the RFCs

used in the content analysis were recently created, none had a change log. However one

was found in Hoffman (2004). It is structured as a list of the changes made from the

previous document version, and the parts of the document they apply to. Changes from -00 to -01 - Small editorial changes throughout based on comments from the rfc-interest mailing list. - Removed open questions throughout. - 2.1: Moved the previous section 7 (RFC Tools) to section 2.1, and expanded on xml2rfc. Renumbered the rest of section 2.

Another type of change log was found in Rosenberg et al (2002): the specification of the

SIP protocol. This one listed functional and non-functional changes separately. We break the differences into functional behavior that is a substantial change from RFC 2543, which has impact on interoperability or correct operation in some cases, and

16

functional behavior that is different from RFC 2543 but not a potential source of interoperability problems.

This format was also found in Schulzrinne et al (2003): the RTP protocol specification.

These similarities in format between RFCs of the same type suggest that change logs

have a number of different formats, depending on RFC type and status.

3.1.13 Appendices

Only two of the documents examined, [7] and [6], had appendices. In [6] the

acknowledgements section was placed in an appendix. This demonstrates that RFCs

have a very flexible structure and that structure is not strictly enforced. In [7] the

appendix was used to provide an overview of other RFCs. The intent of this overview

was to explain concepts found in other RFCs necessary to understanding the current

one. This section provides a brief overview of RFC 2533 and related specifications that form the content negotiation framework.

Appendices can be used for many other purposes and can be as long or short as

required. The guidelines leave the structure and content of appendices to the authors,

who can be guided by structures used in previous RFCs.

3.1.14 Full copyright statement

Every RFC examined during the content analysis included the same page of

predefined text as a copyright statement. The only difference was the year of

publication. The copyright statement was always on the last page, after even the

appendices. This may be because it is of no interest in general to readers of an RFC. Its

inclusion in every RFC is an important precaution against legal difficulties however. A

single predefined line on the first page of every RFC also states that the copyright of the

documents belongs to the Internet Society. Copyright (C) The Internet Society (). All Rights Reserved.

Both of these statements are required in every RFC.

17

3.2 Content The RFC guidelines and norms specify the information content necessary in

RFCs. The guidelines also specify many considerations that must be taken into account.

Some of these considerations can be dealt with in separate sections while others apply

throughout the document. The content analysis revealed what information was included

in practice and how this was done.

3.2.1 Level of granularity

The IETF guidelines on the level of detail or granularity to use in an RFC allow

the author to choose between conciseness and longer descriptions (Scott, 1998). The author should consider what level of descriptive detail best conveys the protocol's intent

Both have some advantages and disadvantages. Concise text is considered by the

guidelines to increase readability and reduce the chance of conflicting statements. The

main disadvantage seen to concise text is that it can reduce understandability, leading a

reader to make incorrect assumptions. These assumptions could lead to implementation

errors.

The guidelines recommend longer descriptions to explain background

information and rationales. These can increase understanding of what the document

wants to communicate. However authors are warned that lengthy text can lead to reader

confusion and conflicting text.

One approach recommended in the guidelines to resolving the conflict between

conciseness and longer descriptions is to separate them. One section or paragraph then

contains concise text while another contains explanations.

In the RFCs examined during the content analysis, requirements were seldom

stated concisely. They were almost always written in plain language, not numbered,

and distinguishable from explanations only by the keywords showing their level.

Generally a paragraph containing an explanation was followed by a paragraph

containing two or more requirement as shown in this extract from [16] For each successful PUBLISH request, the ESC will generate and assign an entity-tag and return it in the SIP-ETag header field of the 2xx response. When updating previously published event state, PUBLISH requests MUST contain a single SIP-If-Match header field

18

identifying the specific event state that the request is refreshing, modifying or removing. This header field MUST contain a single entity-tag that was returned by the ESC in the SIP-ETag header field of the response to a previous publication. Requirements were sometimes followed by example paragraphs. This structure

makes it hard to identify individual requirements and to refer to them in documents.

However it may improve the understandability of the documents by making them easier

to read.

This finding implies that it is seen as more important to ensure that readers of an

RFC understand the document correctly than to allow them to refer to individual

requirements easily. The reason for this may be that RFCs are designed as possible

future standards. In standards it is vital that every reader has the same understanding of

a document to ensure conformity.

3.2.2 Known weaknesses

The IETF guidelines state that known weaknesses, i.e. situations that could

cause errors in implementations, and responses to these situations should be included in

all specifications. These situations could include when the performance limits of a

specification are reached and when abnormal behaviour in external entities occurs. By

including this information in the specification document, implementations of the

specification can be made more consistent in their behaviour.

In the RFCs examined this was sometimes done using examples and scenarios in

separate sections. An example of one of these sections from [22] is given below. 4.3.5.3. Network-initiated De-registration, Network

Maintenance There might be cases in which the SIP serving proxy has to shutdown; e.g., due to maintenance operation. Although this situation is not likely to happen in everyday situations, it is desirable to have a mechanism to inform the UA that his current registration is being cancelled...

In more cases however, methods of preventing and responding to abnormal situations

were documented as extra requirements in the main requirements sections. This ensures

that different implementations use consistent strategies to deal with these situations as

in this quote from [11]. Finally, HTTP digest authentication (which MUST be implemented by watchers and PAs) MAY be used to prevent

19

replay attacks, when there is a shared secret between the PA and the watcher.

3.2.3 Purpose and scope

RFCs can be written for many different purposes. The IETF guidelines suggest

identifying the target audience of each document. If there are multiple target audiences

they should be addressed separately. This allows the readers of a document to access

the information relevant to them and avoid confusion.

This guideline did not seem to be followed in the RFCs analyzed. Few mentions

of the nature of the intended audience could be found in any of the documents. The

reason for this may be that, as stated by Rescorla (2005), most RFCs are written to be

useful to those implementing specifications. This is shown in [25]. The RFC Editor has chosen to publish this document at its discretion. Readers of this document should exercise caution in evaluating its value for implementation and deployment.

The main RFC readers outside the IETF are generally people working for organisations

whose products implement RFCs, as stated in [24]. At present, some user agents, ... do not support a different media line per direction. Implementers are encouraged to build support for this feature.

As most RFCs have the same audience, authors may feel that they do not need make an

explicit statement.

3.2.4 Options

The IETF guidelines discourage the inclusion of optional features or

requirements in RFCs as they can compromise interoperability of implementations.

However in some cases, such as in constrained implementation environments, optional

features are needed. The guidelines suggest dealing with optional features of a

document by removing them to a separate document. Implementation experience can

also show whether an option should be removed or made a full part of a document. All

options must include text that defines the situations the option is intended for, the

consequences, and default choice. This information allows implementers to make

informed decisions.

20

Few examples of optional features were found during the content analysis. This

suggests that options were being avoided, as recommended by the guidelines. Those

options that were found included the information required by the guidelines in the form

of explanations and examples. One such example in [9] is shown here. The use of callee capabilities is optional but encouraged. If callee capabilities are used, a messaging notifier MAY ... as shown in the example below. To further distinguish itself, the messaging notifier MAY also ... An example of this kind of registration follows below...

3.2.5 Rationale

The IETF guidelines recommend including the rationales for controversial

decisions made in specifications. In some cases including the reason an alternative was

rejected can help stakeholders to accept the specification. It can also help to avoid

repeating the controversy in future work. This information can be in the form of a

history of decisions made in a separate section, or explanatory text next to the relevant

requirements.

Only one instance of this was found in the RFCs examined [6]. However this

verifies that this guideline is used in practice. ... the exact way in which the two should cooperate has been a subject of some controversy... ...The following, then, is a statement of the particular philosophy that has motivated the recommendations in this document:...

3.2.6 Summaries

When an RFC is very long or detailed, as occurs frequently in protocol

specifications, summary tables or checklists can be included to ensure that no

considerations are overlooked. These tables and lists can also help a reader to quickly

look up desired sections in a document.

None of the RFCs examined used summary tables, as none was more than thirty-

six pages long. An example of summary tables was found in (Braden et al, 1989). This

document was ninety-eight pages long. Summary tables were placed at the end of every

requirements section. They list features, the sections that contain them, their

requirement level, and the level for each of the requirements within the feature.

21

| | | | |S| | | | | | |H| |F | | | | |O|M|o | | |S| |U|U|o | | |H| |L|S|t | |M|O| |D|T|n | |U|U|M| | |o | |S|L|A|N|N|t | |T|D|Y|O|O|t FEATURE |SECTION | | | |T|T|e -----------------------------------------------|----------|-|-|-|-|-|- | | | | | | | User interfaces: | | | | | | | Allow host name to begin with digit |2.1 |x| | | | | Host names of up to 635 characters |2.1 |x| | | | | Figure 2. Summary Table

None of the RFCs in the content analysis used checklists. However this may be

due to the nature of the RFCs examined. Checklists were found in (Scott, 1998) and

(Kermode and Vicisano, 2002), which are both guideline RFCs. They go through the

considerations that must be taken into account when putting the guidelines into practice

to ensure none is missed. The following is a checklist based on the above guidelines that can be applied to a document: o Does it identify the security risks? Are countermeasures for each potential attack provided? Are the effects of the security measures on the operating environment detailed? o Does it explain the purpose of the protocol or procedure? Are the intended functions and services addressed? Does it describe how it relates to existing protocols? ...

3.2.7 Formal syntax

IETF authors were found to use formal syntax to detail many aspects of

protocols. In technical situations this may be clearer and more precise than natural

language. The IETF allows a formal syntax to be defined in a separate document as

long as the RFC using it references where it can be found. Any change to syntax

introduced in an RFC is defined in the same document.

One advantage of formal syntax is the ability to parse it automatically. However

machine-parseable syntax may not be understandable to a person without a parser and

may add unnecessary length to a specification. The IETF therefore recommends that

preference be given to clear language over formal syntax. This recommendation was

22

found to be followed in the RFCs examined. Formal syntax was generally used only in

examples and syntax definitions. Requirements were specified in plain language.

In the RFCs examined during the content analysis, formal syntax was usually

defined in a section before the security considerations section. Only five of the RFCs

included this section. No consistent title for this section was found. The various names

were ‘Augmented BNF’, ‘Formal syntax’, ‘Syntax’ twice and ‘Augmented BNF

definitions’. The only type of formal syntax used was the augmented Backus-Naur

form (ABNF) specified by Crocker and Overell (1997). 5. Formal Syntax The following syntax specification uses the augmented Backus-Naur Form (BNF) as described in RFC 2234 [6]. This suggests that this syntax is widely used, at least in SIP-related documents.

Backus-Naur Form is a formal notation that is used to specify syntax. In RFCs

examined it was used in examples and to specify the syntax of data message headers

used by protocols, such as the following. msg-status-line = "Messages-Waiting" HCOLON msg-status msg-status = "yes" / "no" msg-account = "Message-Account" HCOLON Account-URI Account-URI = SIP-URI / SIPS-URI / absoluteURI

Formal syntax was found in eleven of the RFCs analyzed. These RFCs had different

purposes, suggesting that formal syntax is widely used in different types of RFC

3.2.8 Requirement levels

The IETF was found to use keywords in its standard track specification

documents to indicate requirement levels (Bradner, 1997). These levels show the

importance of each particular requirement to the specification. The words are “MUST",

"MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD

NOT", "RECOMMENDED", “MAY", and "OPTIONAL". This technique is useful as

it allows levels of importance to be documented as part of the requirements.

Requirements that are not MUSTs or REQUIRED may in some circumstances be

ignored. This can be useful, as it can allow re-scoping of implementations of the

specification without needing to change the document. All the RFCs examined, except

those that did not deal with requirements, used these terms. MUST was by far the most

23

commonly used level. This was not surprising, as most functional requirements were

MUSTs. The Subscriber MUST be prepared to receive and process a NOTIFY with new state immediately after sending a new SUBSCRIBE, a SUBSCRIBE renewal, an unsubscribe, a fetch, or at any other time during the subscription.

3.2.9 Data requirements

The protocols specified in the RFCs examined were found to involve many data

requirements. As most of the RFCs were organised by function rather than features

they contained many data structure and data-flow descriptions. These were usually

specified in sections separate from other requirements sections. Formal syntax and

diagrams were the most common structures used to convey these data requirements.

Diagrams in RFCs are kept simple by the requirement that they be text-based.

Diagrams are created in ASCII using lines made of dashes or other non-alphanumeric

characters. This format ensures that diagrams are laid out horizontally or vertically on

the page, making the diagrams easy to read.

The IETF guidelines define two types of diagram. Packet diagrams show the

structure of the data sent and received by a protocol while flow diagrams show the flow

of this data. Packet diagrams are formed of a series of boxes arranged horizontally or

vertically with each box representing a data field. In the RFCs used in the content

analysis they were mainly used to specify header fields as shown below. +---------------+-----+-----+---+---+---+---+---+---+---+---+---+---+ | Header |where|proxy|ACK|BYE|CAN|INV|OPT|REG|PRA|UPD|SUB|NOT| +---------------+-----+-----+---+---+---+---+---+---+---+---+---+---+ |Session-Expires| R | amr | - | - | - | o | - | - | - | o | - | - | | | | | | | | | | | | | | | |Session-Expires| 2xx | ar | - | - | - | o | - | - | - | o | - | - | | | | | | | | | | | | | | | |Min-SE | R | amr | - | - | - | o | - | - | - | o | - | - | | | | | | | | | | | | | | | |Min-SE | 422 | | - | - | - | m | - | - | - | m | - | - | +---------------+-----+-----+---+---+---+---+---+---+---+---+---+---+ Figure 3. Header Field Diagram

Flow diagrams, also called timelines, are used to show state changes in

protocols. They consist of two or more vertical lines representing entities involved in a

data exchange. The data passed is shown as arrows going between these entities. The

states of the entities can also be shown. The following is a typical example found in [1]

during the content analysis.

24

A Controller B |(1) INVITE no SDP | | || | | |(3) INVITE offer1 | | |------------------>| | |(4) 200 OK answer1 | | || |(6) ACK answer1 | | |

are not official as they may have minor differences from the ASCII text. The text

document is seen as the official version.

A number of strict guidelines govern the number of characters in a line, lines on

a page, and spacing in RFC. Page header and footer information is also specified.

Techniques that are forbidden in RFCs include text justification, underlining, footnotes,

and hyphenation of words at the right margin. As anyone can write an RFC and submit

it, strict controls on format are necessary to ensure consistent quality. The RFC Editor

can change an RFC’s format before publication to ensure consistency in the styles used.

This may mean that the format of RFCs is mainly derived from the RFC Editor. This

helps in the derivation of an RFC template as it means that a single vision for the format

of all RFCs exists, rather than many different formats.

These rules on format do not specify every detail however. For example no

guideline specifies the exact numbering of sections. There is also no defined reference

format. This may be because the main source of RFC formatting information is the

norms of previous RFCs rather than explicit guidelines. Postel and Reynolds (1997)

recommend that authors emulate the format of recent RFCs. The RFC Editor attempts to ensure a consistent RFC style. To do this the RFC Editor may choose to reformat the RFC submitted. It is much easier to do this if the submission matches the style of the most recent RFCs. Please do look at some recent RFCs and prepare yours in the same style.

The influence of current RFC norms on RFC format is demonstrated by the fact that all

the RFCs in the content analysis were found to use a common format for references.

This copying of styles may have led to gradual evolution of RFC formats over

time. More successful styles may be more likely to be reused in other RFCs. This may

be the reason that no specific reference format is required. This could not be verified by

the study described in this paper however, as all the RFCs examined were produced in

the same general time period from February 2004 to July 2005.

3.3.1 Capitalisation

RFC specification sections generally consist of paragraphs of plain text. This

can make it difficult to distinguish requirements from explanatory text and examples.

The IETF solution to this is to mandate that every requirement have a capitalised

requirement level keyword. These levels serve both as flags showing that requirements

are present in the text, and as indicators of the necessity of particular requirements. The

26

only other capitalised words used are acronyms, which can be easily distinguished from

requirement level keywords.

During the content analysis the titles for each section were found to begin with

capital letters. This greatly aided content analysis as it allowed the presence of sections

in documents to be determined by searching for the title using a case sensitive search.

3.4 Summary The structure of RFCs is arranged so that they can be fully understood rather

than quickly referenced. One factor that helps understanding is the placement of

examples and explanations along with the requirements they deal with. The removal of

extra considerations such as security to separate sections also helps the reader to avoid

confusion.

The content of RFCs is also geared towards ensuring that the reader understands

the entire document. The RFCs examined used extensive explanations and examples as

well as overviews to aid understanding. The importance of ensuring that every reader

understood and implemented the document in the same way was shown by the attention

paid to clarifying complex requirements and the introduction of requirements explicitly

preventing incorrect implementations.

The format of RFCs is well defined despite the looseness of the guidelines used

to specify it. This is possibly due to the existence of a single vision for the format of

RFCs. The RFC Editor has the authority to change the format of an RFC before

publication and they actively try to maintain a standard format for RFCs. RFC norms

also play a role in the format of RFCs. The guidelines point out examples of RFCs

where certain sections were handled well. These are then emulated and may eventually

become best practices.

27

4. THE RFC TEMPLATE The proposed template shown here was derived from the content analysis of

recent SIP-related RFCs and examination of the RFC guidelines. Many of the sections

may be left out if not relevant to a particular RFC. The template could be used to

construct RFCs. However the main intention in deriving it was to compare it to the

IEEE 830 standard template to find if lessons can be drawn that are applicable to

requirements engineering specifications.

Angular brackets in the template indicate placeholders where the enclosed

text should be replaced with information or text in the actual RFC.

Status of this Memo Copyright Notice Copyright (C) The Internet Society (). All Rights Reserved. Abstract Table of Contents

tion

1. Introduction

28

Overview

e ocuses on the product of the

cument, not the document itself>

Terminology

to laced in this

ction. Otherwise this section can be left out>

Definitions

hat document. If none are present, the

ction can be left out>

Main Content

this section can vary depending on the purpose of e document.

f

e

ecified using tables or flow diagrams formed using ASCII text.

NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", “MAY", "OPTIONAL".

ices, or other text arranged in ctions as the author sees fit.

yphenated

ntain only 50 lines of content before going onto the next page>

2.

6. Summary 7. Formal Syntax 8. Security Considerations 9. IANA Considerations 10. Additional considerations 11. Contributors 12. Acknowledgements

30

13. Examples and scenarios | |(1) message | | | | 14. References 14.1. Normative References 14.2. Informative References

31

o

. Appendices

. The

an integral part of an RFC, or as separate

formation>

. Auth rs' Addresses

. This section is required so that RFC authors can co tacted>

ame> ddr ss>

ber> -ma l>

. C ange Log

ch ersion since the first and their locations in the document>

. F ll Copyright Statement

C except for e year of publication. It is required in every RFC>

15

5. COMPARISON WITH THE IEEE 830 STANDARD The IEEE 830 standard (IEEE, 1998) is a widely known standard for creating

and structuring requirements specifications. It specifies what information should be

included in a requirements specification. It also includes a requirements specification

template with several possible organisations for the requirements that details how

documents should be organised and laid out. It is accompanied by guidelines that

suggest the qualities of a good specification. However these guidelines are not

explicitly supported in the IEEE template, as is the case in the derived RFC template.

The IEEE template was chosen for comparison with the derived RFC template

in order to discover if lessons could be drawn that could be of benefit in improving both

templates. The RFC template and the IEEE template initially appear similar. They deal

with the same issues of structure, format, and information content. However the

templates take different approaches to these issues. The following sections compare the

two templates by their structures, information contents, and formats. Conclusions

drawn from this comparison are then presented.

5.1 Structure 5.1.1 Introduction

The IEEE template begins with an introduction section with defined subsections

and does not have an abstract. The RFC template uses an abstract section to briefly

describe the document. As the abstract must be kept short, other sections that contain

more detail such as introduction and overview sections are used. Having an abstract is

an advantage as it can allow a reader to see at a glance whether the document contains

material relevant to them or not. This should be included to save time when a document

is difficult to understand.

The IEEE template has specific subsections for the purpose and scope of the

document. This ensures that they are defined in every document. The RFC template by

contrast leaves it up to the author to include the purpose and scope of the document in

the text of the introduction section. This could lead to confusion if the introduction is

not written clearly. To guarantee that the purpose and scope of RFCs are defined, RFC

authors should explicitly include subsections in the introduction section dealing with

them.

33

1. Introduction

1.1 Purpose 1.2 Scope 1.3 Definitions, acronyms, and abbreviations 1.4 References 1.5 Overview

2. Overall description 2.1 Product perspective 2.2 Product functions 2.3 User characteristics 2.4 Constraints 2.5 Assumptions and dependencies

Beginning of IEEE template

Abstract

1. Introduction

2. Overview

3. Terminology

4. Definitions

Beginning of RFC template

Figure 6. Organisation of Initial Information in both Templates

5.1.2 Definitions, acronyms, and abbreviations

Both templates require that all definitions, acronyms, and abbreviations must

have their meanings given in the document near the start. This allows the specification

to be interpreted by readers. Both also allow references to be made to definitions in

other documents. RFCs use separate sections entitled definitions, conventions, or

terminology to distinguish definitions that refer to other documents from definitions

created for the current document. The reason for this practice is unclear. It may help

readers in looking up definitions or allow these sections to be independently changed,

which may be necessary if external definitions are updated.

5.1.3 References

In both templates authors must provide full information on where references

were obtained. The IETF guidelines advise authors to copy reference styles used in

recent RFCs. The IEEE also does not provide guidance on reference style but requires

that information such as each references title, number (if any), date, and publisher are

included.

The main difference in references between the two templates is the RFC

template’s distinction between normative and informative references. This distinction

allows those implementing a specification to see what other documents they may need

to implement. Those who read the specification in order to understand it can use the

informative references. Requirements engineers should emulate this distinction as it

34

provides a means of documenting the dependencies of a specification as well as

providing sources of information for those who want to learn about the context of a

specification.

Another difference is the position of the references in the documents. In RFCs

they are placed at the end of the document, while in IEEE specifications they are placed

at the start. Both of these methods allow the references to be found easily. Neither

seems to have an obvious advantage over the other, although placing references at the

end of a document is more conventional.

5.1.4 Overview

An overview section contains different things in each template. In the IEEE

template the overview section describes what the specification contains and how it is

organised. This information is included in the introduction section in the RFC template.

In the RFC template an overview section discusses the product or content of the

document and not the document itself. This section is used only when the product has

complex behaviour that needs to be explained. The scope of simpler products can be

given in a document’s abstract. In the IEEE template a section titled Product Functions

provides a summary of the major product functions. The same information is therefore

present in both templates although it is structured differently. Both templates could be

improved by adopting clearer names for these sections. For example the discussion of

the document could be called Document Overview' and discussion of the product could

be called ‘Product Description’.

5.1.6 Specific requirements

Both templates include sections for specific requirements. The IEEE template

defines a number of methods for structuring requirements sections such as by function,

by feature, by mode, or by stimulus. This reflects the many different types of

specification the IEEE template applies to. Because of its origin in specifying protocols

and their extensions, the RFC template generally structures requirements along

functional lines, with each function in a separate section. However this template can be

changed to use a different structure if a situation calls for it. For example, RFCs

specifying requirements for proposed protocols were found to organise their

requirements by feature.

34

5.1.7 Appendices

The IEEE standard states that appendices are not always necessary but can

include many different considerations, from technical data to background information.

The RFC template uses them in the same way. Appendices in both templates may or

may not be an integral part of the specification.

5.1.8 Index and table of contents

A table of contents is vital in both templates. However the IEEE states that an

index is also as important. This illustrates that the main goal of their template is to

create a document that can be referred to easily. The RFC template uses other forms of

index such as checklists and summary tables. These aid readers in attempting to

understand and implement the document, which was identified as the primary goal of

RFCs.

5.1.9 Standards compliance

The IEEE template includes a subsection used to specify requirements necessary

for compliance to standards. This is necessary in some software requirements

specifications, but is not included in the RFC template. Instead RFCs that apply

external requirements generally include normative references to the documents that

specify these requirements.

5.2 Content 5.2.1 Intended Audience

The IEEE template recommends that the introduction section include the

purpose of the document and its intended audience. A document intended for a

particular set of readers must describe them. This provides a rationale for the level of

detail and the type of requirements used. The RFC guidelines also recommend that the

intended audience should be identified (Scott, 1998). The reason given for this by the

guidelines is that it allows a reader to focus on the documents and sections intended for

them and skip others. However it was found that this was not carried out in practice in

RFCs as it was assumed that all readers of the document would be involved in

implementing the specification. RFC authors should include this information. In

software requirements situations this information is necessary, as documents have to be

read by a variety of stakeholders such as managers, clients, and developers.

35

5.2.2 Assumptions and dependencies

The IEEE template includes a section for documenting the assumptions and

dependencies of a specification. This is useful as most software specifications involve

some external dependencies such as language or platform dependencies. If not

addressed these dependencies pose considerable risk to any implementation.

The IETF tries to eliminate this risk before implementation. There is no specific

section in the RFC template to document assumptions or dependencies. Instead they try

to eliminate assumptions and dependencies to ensure that the RFC implementers are not

constrained unnecessarily. It is not always feasible to eliminate dependencies however

and those that remain should be documented. The IETF method for doing this is to

include the documents that an RFC depends on as normative references. The IEEE

method in this case has the advantage and the IETF should include a dependency

section in their documents.

5.2.3 Product perspective

In the IEEE template this section describes the products relation to other

products including all interfaces and operations. This section is not included in RFCs as

interfaces and operations are already the core of most RFC specifications. RFC

specifications are created with interoperability in mind, as it is the most important

quality of Internet protocols and their extensions. A description of the overall system of

products is not generally included in RFCs, as the overall Internet system is not mapped

out beforehand. Extensions can be added to protocols at any time. A description of a

protocol and its extensions would quickly become obsolete. If a system of products

were to be described using the RFC template it should be placed in a separate document

so that it could be updated independently.

5.2.5 Non-functional requirements

The IEEE divides non-functional requirements into performance requirements,

design constraints, external interface requirements, and software system attributes.

These are documented is separate sections from the functional requirements. The main

advantage of separating them is that it can make it easier for a reader to focus on the

core functional requirements. However some non-functional requirements may be

difficult to categorise. Non-functional requirements may also be difficult to understand

outside the context of the functional requirements they apply to.

36

The division imposed suggests that the IEEE does not give non-functional

requirement the same importance as functional requirements. In the RFC template both

types of requirement are treated as equally important.

In the RFC template, non-functional requirements can either dealt with in

separate considerations sections, or included with the sections functional requirements

they apply to. Judging from findings of the content analysis the second method is

preferred. The only considerations sections found to be used were security and IANA

sections, which are mandatory. This quotation from [3] shows how functional and non-

functional requirements are documented together. SIP and SIPS URI parameters and values for these parameters MUST be documented in a standards-track RFC in order to be registered by IANA. This documentation MUST fully explain the syntax, intended usage, and semantics of the parameter. The intent of this requirement is to assure interoperability between independent implementations, There are many possible advantages of including non-functional requirements in

the same sections as functional requirements. One advantage is that it can help ensure

that these requirements are not overlooked. It also allows more specific non-functional

requirements. Non-functional requirements can be specified for each individual

functional requirement. It also preserves the flow of a document and spares the reader

from having to refer to different sections to find non-functional requirements that apply

to a functional requirement. Requirements engineers should therefore place non-

functional requirements with functional ones in their specifications.

5.2.6 Design constraints

Design constraints usually occur when a specification must interface with

existing specifications, implementations, or the real world. The IEEE template suggests

documenting them as requirements in their own section.

Design constraints are not dealt with in separate sections in RFCs. They are

mentioned wherever they occur in functional requirement sections. Design constraints

in the RFCs examined were expressed as negative requirements i.e. using the

requirement levels MUST NOT, SHALL NOT or SHOULD NOT. Implementations MUST NOT utilize "private" or "locally defined" SIP header field parameters or parameter values that conflict with registered parameters.

37

The IETF attempts to minimise design constraints in order to allow implementers room

to innovate. Negative requirements have the advantage of limiting design options less

than requiring a stated design. This allows implementers and those who extend the

specification more freedom to find an optimal design, as stated in [13]. This extension was designed to take advantage of future signature or authorization schemes defined in standards track extensions. In general, call control features benefit considerably from such work.

5.2.7 Data requirements

The IEEE template uses information flow, process, and data specifications in

documents that are organised by function. These are similar to the data flows and data

structures found in RFCs. However the IEEE template does not define standard

methods of documenting these flows and constructs. Most RFCs are organised by

function, with functions being specified in terms of operations on data entities. This has

led to RFCs developing formalised methods of dealing with data requirements,

including defined diagram types and use of formal syntax. These diagrams and formal

syntax should also be applied to data requirements in software requirements

specifications. Using consistent methods of specifying data requirements could help

readers to understand them more easily.

5.3 Format The IEEE template does not define the format of its specifications as strictly as

the RFC template. For example it does not specify diagram structures or a standard

character set. RFCs use a strictly defined format as their specifications are intended for

many different implementers who must each have the same understanding of the

specification. Software requirements specifications are usually implemented once only.

It is still important however to ensure that individuals working on the same

implementation have a common understanding.

There are other advantages to having a defined document format. It can help to

produce consistent documentation where information can easily be located. It could

also help eliminate ambiguities caused by the use of different documentation tools, i.e.

text editors and printers. For these reasons it would be beneficial for users of the IEEE

template to define and use a consistent format in their specifications.

38

5.4 Template evolution The RFC guidelines are growing and evolving over time. In each of the

guideline RFCs initially examined, other RFCs were referenced as examples of how to

create a good document. This suggests that best practices for creating RFCs are being

documented as guidelines and emulated. This process is far from complete: RFCs do

not yet have a consistent structure or content.

The IEEE standard template has had three versions. The first version was

produced in 1984, the second in 1993, and the current version in 1998. This time

between versions allows the IEEE template to evolve only very slowly.

Requirements engineers using the IEEE template should therefore consider

evolving their own template by reusing the successful aspects of the structure, content,

and format of specifications they have already produced. This would allow them to

improve the template as they use it, as is done with the RFC guidelines. This should

eventually lead to a template more suited to the readers’ particular needs than the basic

IEEE standard.

39

6. CONCLUSIONS The RFC template presented in this paper was derived from the guidelines and

norms that dictate the general structure, content, and format of RFCs. This template

could be used produce different types of document in different situations. The IETF

could benefit from using a template similar to this to create RFCs rather than the current

divided collection of guidelines and norms. Such a template could be documented in a

single RFC. This would prevent divergent RFC structures appearing and would be

easier to update.

Comparison with the IEEE software requirements specification template

revealed that the derived RFC template integrated structure, content, and format much

better than the IEEE template. In the IEEE 830 standard, characteristics of a good

specification such as being unambiguous and having priorities for requirements are

addressed separately from the template specifying the parts of a specification. This

leaves it up to implementers of the standard to decide how to achieve these

characteristics when using the template. In the derived RFC template these

characteristics are built in. For example ambiguity is avoided by including descriptive

text with requirements, and requirement priorities are given by requirement level

keywords. Using a similar template with built-in good practices could reduce the effort

needed by requirements engineers to produce high quality specifications.

There were also differences in the intended purpose of documents produced with

these two templates. The IETF seems to assume that readers of RFCs will take time to

read through the documents and try to understand them. The RFC template aids

understanding of the overall specification by allowing the inclusion of examples and

scenarios with requirements and by structuring requirements in paragraphs of text to

increase readability. It also ensures a common understanding of the document among

all its readers by using a strictly defined format.

The IEEE on the other hand assumes that readers of their specifications want to

use the document mainly to reference requirements. These different assumptions may

stem from the differences between standardisation and requirements engineering.

Both organisations could benefit from using aspects of each other’s approaches

to requirements in certain situations. The IEEE could make their requirements more

descriptive to ensure that they are understood. This would help in situations where

40

requirements are complicated or technical and must be understood by people lacking

technical knowledge. They should also adopt the distinction between normative and

informative references. The IETF could also benefit by including sections dealing with

the purpose, scope and intended audience of an RFC. They should also structure their

requirements so that they can be referenced more easily, perhaps by numbering each

requirement individually.

The IEEE template suggests a number of different methods of structuring

requirements that can be used in different situations. The IETF could learn from this by

explicitly defining structures for common RFC purposes such as creating new header

fields or extending protocols. This could allow a more customisable RFC template to

be derived, which could be configured to meet the needs of different situations.

The IETF method of handling non-functional requirements, including them with

the functional requirements they apply to, offers substantial advantages over the IEEE

method. The IEEE separates non-functional requirements into their own sections. This

can lead to reduced focus on non-functional attributes, which could harm quality. The

IEEE should adopt the IETF method by linking the non-functional requirements to the

functional requirements, either by putting them in the same paragraphs or sections or by

linking them using a numbering system.

These conclusions were derived from a very limited study. The sample of RFCs

used in the study was very small in comparison to the number available. A larger

sample might have led to a more complete understanding of the structure, content, and

format of RFCs. The sample RFCs were also very diverse in purpose. Examination of

RFCs used for protocol specifications only, could have yielded a template closer to a

requirements specification. However the analysis was confined to deriving the template

common to all RFCs, as this could be applied in many different kinds of document.

In summary the RFC template does have many features that requirements

engineers could learn from. However it has many features that are not easily applied to

general requirements engineering. Future studies could make comparisons with other

well-known requirements engineering templates, or perhaps test a modified form of the

derived template in actual requirements engineering situations.

41

7. REFERENCES

Braden, R. (ed), 1989. Requirements for Internet Hosts -- Application and Support. RFC 1123. United States: RFC Editor.

Bradner, S., 1997. Key words for use in RFCs to indicate requirement levels. RFC 2119. BCP 14. United States: RFC Editor.

Busch, C., and others, 2005. Content Analysis. Writing@CSU. Colorado State University Department of English. Retrieved [25/07/05] from http://writing.colostate.edu/references/research/content/.

Crocker, D., and P. Overell, 1997. Augmented BNF for Syntax Specifications: ABNF. RFC 2234. United States: RFC Editor.

Hoffman, P. (ed.), 2004. Instructions to Request for Comments (RFC) Authors. Work in progress. http://www.ietf.org/internet-drafts/draft-rfc-editor-rfc2223bis-08.txt. Accessed 9 July 2005.

Hovey, R., and S. Bradner, 1996. The Organizations Involved in the IETF Standards Process. RFC 2028. BCP 11. United States: RFC Editor.

IEEE, 1998. IEEE Recommended Practice for Software Requirements Specifications. IEEE standard 830. USA: Software Engineering Standards Committee of the IEEE Computer Society.

Kermode, R., and L. Vicisano, 2002. Author Guidelines for Reliable Multicast Transport (RMT) Building Blocks and Protocol Instantiation documents. RFC 3269. United States: RFC Editor.

Krippendorff, K., 1980. Content analysis: An Introduction to its Methodology. The Sage CommText Series. 5. Beverly Hills, California, United States: Sage Publications, Inc.

Lausen, Soren, 2002. Software requirements styles and techniques. ISBN 0-201-74570-4, Great Britain: Pearson education limited.

Malkin, G. (ed.), 1996. Internet Users' Glossary. RFC 1983. FYI 18. United States: RFC Editor.

Neuendorf. K., 2002. The Content Analysis Guidebook. Thousand Oaks, California, United States: Sage Publications, Inc.

Ohta, M., 1998. IETF and Internet standards. IEEE communications., 36(9), 126-129.

Postel, J., and J. Reynolds, 1997. Instructions to RFC authors. RFC 2223. United States: RFC Editor.

Rescorla, E., 2005. Writing Protocol Models. RFC 4101. United States: RFC Editor.

42

Rescorla, E., and B. Korver, 2003. Guidelines for Writing RFC Text on Security Considerations. RFC 2360. BCP 72. United States: RFC Editor.

Robertson, S., and J. Robertson, 1999. Mastering the Requirements Process. ISBN:0-201-36046-2. New York, NY, USA: Addison-Wesley.

Rosenberg, J., and H. Schulzrinne, 2005. Guidelines for Authors of Extensions to the Session Initiation Protocol (SIP). Work in progress. http://www.ietf.org/internet-drafts/draft-ietf-sip-guidelines-09.txt. Accessed 9 July 2005.

Rosenberg, J., and others, 2002. SIP: Session Initiation Protocol. RFC 3261. United States: RFC Editor.

Schulzrinne, H., and others, 2003. RTP: A Transport Protocol for Real-Time Applications. RFC 3550. United States: RFC Editor.

Scott, G., 1998. Guide for Internet standards writers. RFC 2360. United States: RFC Editor.

Siemens, R., 1993. Practical content analysis techniques for text-retrieval in large, un-tagged text-bases. ACM Special Interest Group for Design of Communications. Proceedings of the 11th annual international conference on Systems documentation. Waterloo, Ontario, Canada. 293-299. 1993. New York, NY, USA: ACM Press.

Treese, W., 1999. Putting it Together; Engineering the Net: The IETF. NetWorker, 3(1), 13-19. New York, NY, USA: ACM Press.

Walsh, M., 2005. The Structure, Content, and Format of IETF RFCs. Technical Report UL-CSIS-05-4, Department of Computer Science and Information Systems, University of Limerick, http://www1.csis.ul.ie/research/tech/, 2005.

43

APPENDIX A: CODES (cs) = case sensitive _ = space character Category Codes Search Expression Matches

This RFC defines a new header Defines (in abstract section) 7

Section Abstract Abstract (cs) 25

This RFC defines an extension extension (i