RFC 8126
Guidelines for Writing an IANA Considerations Section in RFCs
Internet Engineering Task Force (IETF) M. Cotton Request for Comments: 8126 PTI BCP: 26 B. Leiba Obsoletes: 5226 Huawei Technologies Category: Best Current Practice T. Narten ISSN: 2070-1721 IBM Corporation June 2017 Guidelines for Writing an IANA Considerations Section in RFCsAbstract
Many protocols make use of points of extensibility that use constants to identify various protocol parameters. To ensure that the values in these fields do not have conflicting uses and to promote interoperability, their allocations are often coordinated by a central record keeper. For IETF protocols, that role is filled by the Internet Assigned Numbers Authority (IANA). To make assignments in a given registry prudently, guidance describing the conditions under which new values should be assigned, as well as when and how modifications to existing values can be made, is needed. This document defines a framework for the documentation of these guidelines by specification authors, in order to assure that the provided guidance for the IANA Considerations is clear and addresses the various issues that are likely in the operation of a registry. This is the third edition of this document; it obsoletes RFC 5226. Status of This Memo This memo documents an Internet Best Current Practice. This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on BCPs is available in Section 2 of RFC 7841. Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at http://www.rfc-editor.org/info/rfc8126.
Copyright Notice Copyright (c) 2017 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://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.Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 1.1. Keep IANA Considerations for IANA . . . . . . . . . . . . 4 1.2. For Updated Information . . . . . . . . . . . . . . . . . 5 1.3. A Quick Checklist Upfront . . . . . . . . . . . . . . . . 5 2. Creating and Revising Registries . . . . . . . . . . . . . . 7 2.1. Organization of Registries . . . . . . . . . . . . . . . 8 2.2. Documentation Requirements for Registries . . . . . . . . 8 2.3. Specifying Change Control for a Registry . . . . . . . . 11 2.4. Revising Existing Registries . . . . . . . . . . . . . . 11 3. Registering New Values in an Existing Registry . . . . . . . 12 3.1. Documentation Requirements for Registrations . . . . . . 12 3.2. Updating Existing Registrations . . . . . . . . . . . . . 14 3.3. Overriding Registration Procedures . . . . . . . . . . . 14 3.4. Early Allocations . . . . . . . . . . . . . . . . . . . . 15 4. Choosing a Registration Policy and Well-Known Policies . . . 15 4.1. Private Use . . . . . . . . . . . . . . . . . . . . . . . 18 4.2. Experimental Use . . . . . . . . . . . . . . . . . . . . 18 4.3. Hierarchical Allocation . . . . . . . . . . . . . . . . . 19 4.4. First Come First Served . . . . . . . . . . . . . . . . . 19 4.5. Expert Review . . . . . . . . . . . . . . . . . . . . . . 20 4.6. Specification Required . . . . . . . . . . . . . . . . . 21 4.7. RFC Required . . . . . . . . . . . . . . . . . . . . . . 22 4.8. IETF Review . . . . . . . . . . . . . . . . . . . . . . . 22 4.9. Standards Action . . . . . . . . . . . . . . . . . . . . 23 4.10. IESG Approval . . . . . . . . . . . . . . . . . . . . . . 23 4.11. Using the Well-Known Registration Policies . . . . . . . 24 4.12. Using Multiple Policies in Combination . . . . . . . . . 26 4.13. Provisional Registrations . . . . . . . . . . . . . . . . 26
5. Designated Experts . . . . . . . . . . . . . . . . . . . . . 27 5.1. The Motivation for Designated Experts . . . . . . . . . . 27 5.2. The Role of the Designated Expert . . . . . . . . . . . . 27 5.2.1. Managing Designated Experts in the IETF . . . . . . . 29 5.3. Designated Expert Reviews . . . . . . . . . . . . . . . . 29 5.4. Expert Reviews and the Document Lifecycle . . . . . . . . 31 6. Well-Known Registration Status Terminology . . . . . . . . . 31 7. Documentation References in IANA Registries . . . . . . . . . 32 8. What to Do in "bis" Documents . . . . . . . . . . . . . . . . 33 9. Miscellaneous Issues . . . . . . . . . . . . . . . . . . . . 34 9.1. When There Are No IANA Actions . . . . . . . . . . . . . 34 9.2. Namespaces Lacking Documented Guidance . . . . . . . . . 35 9.3. After-the-Fact Registrations . . . . . . . . . . . . . . 35 9.4. Reclaiming Assigned Values . . . . . . . . . . . . . . . 35 9.5. Contact Person vs Assignee or Owner . . . . . . . . . . . 36 9.6. Closing or Obsoleting a Registry/Registrations . . . . . 37 10. Appeals . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 11. Mailing Lists . . . . . . . . . . . . . . . . . . . . . . . . 37 12. Security Considerations . . . . . . . . . . . . . . . . . . . 37 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 38 14. Changes Relative to Earlier Editions of BCP 26 . . . . . . . 38 14.1. 2016: Changes in This Document Relative to RFC 5226 . . 38 14.2. 2008: Changes in RFC 5226 Relative to RFC 2434 . . . . . 39 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 40 15.1. Normative References . . . . . . . . . . . . . . . . . . 40 15.2. Informative References . . . . . . . . . . . . . . . . . 40 Acknowledgments for This Document (2017) . . . . . . . . . . . . 46 Acknowledgments from the Second Edition (2008) . . . . . . . . . 46 Acknowledgments from the First Edition (1998) . . . . . . . . . . 46 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 47
1. Introduction
Many protocols make use of points of extensibility that use constants to identify various protocol parameters. To ensure that the values in these fields do not have conflicting uses and to promote interoperability, their allocations are often coordinated by a central record keeper. The Protocol field in the IP header [RFC791] and MIME media types [RFC6838] are two examples of such coordinations. The IETF selects an IANA Functions Operator (IFO) for protocol parameters defined by the IETF. In the contract between the IETF and the current IFO (ICANN), that entity is referred to as the IANA PROTOCOL PARAMETER SERVICES Operator, or IPPSO. For consistency with past practice, the IFO or IPPSO is referred to in this document as "IANA" [RFC2860]. In this document, we call the range of possible values for such a field a "namespace". The binding or association of a specific value with a particular purpose within a namespace is called an assignment (or, variously: an assigned number, assigned value, code point, protocol constant, or protocol parameter). The act of assignment is called a registration, and it takes place in the context of a registry. The terms "assignment" and "registration" are used interchangeably throughout this document. To make assignments in a given namespace prudently, guidance describing the conditions under which new values should be assigned, as well as when and how modifications to existing values can be made, is needed. This document defines a framework for the documentation of these guidelines by specification authors, in order to assure that the guidance for the IANA Considerations is clear and addresses the various issues that are likely in the operation of a registry. Typically, this information is recorded in a dedicated section of the specification with the title "IANA Considerations".1.1. Keep IANA Considerations for IANA
The purpose of having a dedicated IANA Considerations section is to provide a single place to collect clear and concise information and instructions for IANA. Technical documentation should reside in other parts of the document; the IANA Considerations should refer to these other sections by reference only (as needed). Using the IANA Considerations section as primary technical documentation both hides it from the target audience of the document and interferes with IANA's review of the actions they need to take.
An ideal IANA Considerations section clearly enumerates and specifies
each requested IANA action; includes all information IANA needs, such
as the full names of all applicable registries; and includes clear
references to elsewhere in the document for other information.
The IANA actions are normally phrased as requests for IANA (such as,
"IANA is asked to assign the value TBD1 from the Frobozz
Registry..."); the RFC Editor will change those sentences to reflect
the actions taken ("IANA has assigned the value 83 from the Frobozz
Registry...").
1.2. For Updated Information
IANA maintains a web page that includes additional clarification
information beyond what is provided here, such as minor updates and
summary guidance. Document authors should check that page. Any
significant updates to the best current practice will have to feed
into updates to BCP 26 (this document), which is definitive.
<https://iana.org/help/protocol-registration>
1.3. A Quick Checklist Upfront
It's useful to be familiar with this document as a whole. But when
you return for quick reference, here are checklists for the most
common things you'll need to do and references to help with the less
common ones.
In general...
1. Put all the information that IANA will need to know into the
"IANA Considerations" section of your document (see Section 1.1).
2. Try to keep that section only for information to IANA and to
designated expert reviewers; put significant technical
information in the appropriate technical sections of the document
(see Section 1.1).
3. Note that the IESG has the authority to resolve issues with IANA
registrations. If you have any questions or problems, you should
consult your document shepherd and/or working group chair, who
may ultimately involve an Area Director (see Section 3.3).
If you are creating a new registry...
1. Give the registry a descriptive name and provide a brief
description of its use (see Section 2.2).
2. Identify any registry grouping that it should be part of (see
Section 2.1).
3. Clearly specify what information is required in order to register
new items (see Section 2.2). Be sure to specify data types,
lengths, and valid ranges for fields.
4. Specify the initial set of items for the registry, if applicable
(see Section 2.2).
5. Make sure the change control policy for the registry is clear to
IANA, in case changes to the format or policies need to be made
later (see Sections 2.3 and 9.5).
6. Select a registration policy -- or a set of policies -- to use
for future registrations (see Section 4, and especially note
Sections 4.11 and 4.12).
7. If you're using a policy that requires a designated expert
(Expert Review or Specification Required), understand Section 5
and provide review guidance to the designated expert (see
Section 5.3).
8. If any items or ranges in your registry need to be reserved for
special use or are otherwise unavailable for assignment, see
Section 6.
If you are registering into an existing registry...
1. Clearly identify the registry by its exact name and optionally by
its URL (see Section 3.1).
2. If the registry has multiple ranges from which assignments can be
made, make it clear which range is requested (see Section 3.1).
3. Avoid using specific values for numeric or bit assignments, and
let IANA pick a suitable value at registration time (see
Section 3.1). This will avoid registration conflicts among
multiple documents.
4. For "reference" fields, use the document that provides the best
and most current documentation for the item being registered.
Include section numbers to make it easier for readers to locate
the relevant documentation (see Sections 3.1 and 7).
5. Look up (in the registry's reference document) what information
is required for the registry and accurately provide all the
necessary information (see Section 3.1).
6. Look up (in the registry's reference document) any special rules
or processes there may be for the registry, such as posting to a
particular mailing list for comment, and be sure to follow the
process (see Section 3.1).
7. If the registration policy for the registry does not already
dictate the change control policy, make sure it's clear to IANA
what the change control policy is for the item, in case changes
to the registration need to be made later (see Section 9.5).
If you're writing a "bis" document or otherwise making older
documents obsolete, see Section 8.
If you need to make an early registration, such as for supporting
test implementations during document development, rather than waiting
for your document to be finished and approved, see [RFC7120].
If you need to change the format/contents or policies for an existing
registry, see Section 2.4.
If you need to update an existing registration, see Section 3.2.
If you need to close down a registry because it is no longer needed,
see Section 9.6.
2. Creating and Revising Registries
Defining a registry involves describing the namespaces to be created,
listing an initial set of assignments (if applicable), and
documenting guidelines on how future assignments are to be made.
When defining a registry, consider structuring the namespace in such
a way that only top-level assignments need to be made with central
coordination, and those assignments can delegate lower-level
assignments so coordination for them can be distributed. This
lessens the burden on IANA for dealing with assignments, and is
particularly useful in situations where distributed coordinators have
better knowledge of their portion of the namespace and are better
suited to handling those assignments.
2.1. Organization of Registries
All registries are anchored from the IANA "Protocol Registries" page: <https://www.iana.org/protocols> That page lists registries in protocol category groups, placing related registries together and making it easier for users of the registries to find the necessary information. Clicking on the title of one of the registries on the IANA Protocol Registries page will take the reader to the details page for that registry. Unfortunately, we have been inconsistent in how we refer to these entities. The group names, as they are referred to here, have been variously called "protocol category groups", "groups", "top-level registries", or just "registries". The registries under them have been called "registries" or "sub-registries". Regardless of the terminology used, document authors should pay attention to the registry groupings, should request that related registries be grouped together to make related registries easier to find, and, when creating a new registry, should check whether that registry might best be included in an existing group. That grouping information should be clearly communicated to IANA in the registry creation request.2.2. Documentation Requirements for Registries
Documents that create a new namespace (or modify the definition of an existing space) and that expect IANA to play a role in maintaining that space (serving as a repository for registered values) must provide clear instructions on details of the namespace, either in the IANA Considerations section or referenced from it. In particular, such instructions must include: The name of the registry This name will appear on the IANA web page and will be referred to in future documents that need to allocate a value from the new space. The full name (and abbreviation, if appropriate) should be provided. It is highly desirable that the chosen name not be easily confused with the name of another registry. When creating a registry, the group that it is a part of must be identified using its full name, exactly as it appears in the Protocol Registries list.
Providing a URL to precisely identify the registry helps IANA
understand the request. Such URLs can be removed from the RFC
prior to final publication or left in the document for reference.
If you include iana.org URLs, IANA will provide corrections, if
necessary, during their review.
Required information for registrations
This tells registrants what information they have to include in
their registration requests. Some registries require only the
requested value and a reference to a document where use of the
value is defined. Other registries require a more detailed
registration template that describes relevant security
considerations, internationalization considerations, and other
such information.
Applicable registration policy
The policy that will apply to all future requests for
registration. See Section 4.
Size, format, and syntax of registry entries
What fields to record in the registry, any technical requirements
on registry entries (valid ranges for integers, length limitations
on strings, and such), and the exact format in which registry
values should be displayed. For numeric assignments, one should
specify whether values are to be recorded in decimal, in
hexadecimal, or in some other format.
Strings are expected to be ASCII, and it should be clearly
specified whether case matters, and whether, for example, strings
should be shown in the registry in uppercase or lowercase.
Strings that represent protocol parameters will rarely, if ever,
need to contain non-ASCII characters. If non-ASCII characters are
really necessary, instructions should make it very clear that they
are allowed and that the non-ASCII characters should be
represented as Unicode characters using the "(U+XXXX)" convention.
Anyone creating such a registry should think carefully about this
and consider internationalization advice such as that in
[RFC7564], Section 10.
Initial assignments and reservations
Any initial assignments or registrations to be included. In
addition, any ranges that are to be reserved for "Private Use",
"Reserved", "Unassigned", etc. (see Section 6) should be
indicated.
For example, a document might specify a new registry by including:
---------------------------------------------------------------
X. IANA Considerations
This document defines a new DHCP option, entitled "FooBar" (see
Section y), and assigns a value of TBD1 from the DHCP Option space
<https://www.iana.org/assignments/bootp-dhcp-parameters>
[RFC2132] [RFC2939]:
Data
Tag Name Length Meaning
---- ---- ------ -------
TBD1 FooBar N FooBar server
The FooBar option also defines an 8-bit FooType field, for which
IANA is to create and maintain a new registry entitled
"FooType values" used by the FooBar option. Initial values for the
DHCP FooBar FooType registry are given below; future assignments
are to be made through Expert Review [BCP26]. Assignments consist
of a DHCP FooBar FooType name and its associated value.
Value DHCP FooBar FooType Name Definition
---- ------------------------ ----------
0 Reserved
1 Frobnitz RFCXXXX, Section y.1
2 NitzFrob RFCXXXX, Section y.2
3-254 Unassigned
255 Reserved
---------------------------------------------------------------
For examples of documents that establish registries, consult
[RFC3575], [RFC3968], and [RFC4520].
Any time IANA includes names and contact information in the public
registry, some individuals might prefer that their contact
information not be made public. In such cases, arrangements can be
made with IANA to keep the contact information private.
2.3. Specifying Change Control for a Registry
Registry definitions and registrations within registries often need to be changed after they are created. The process of making such changes is complicated when it is unclear who is authorized to make the changes. For registries created by RFCs in the IETF stream, change control for the registry lies by default with the IETF, via the IESG. The same is true for value registrations made in IETF- stream RFCs. Because registries can be created and registrations can be made outside the IETF stream, it can sometimes be desirable to have change control outside the IETF and IESG, and clear specification of change control policies is always helpful. It is advised, therefore, that all registries that are created clearly specify a change control policy and a change controller. It is also advised that registries that allow registrations from outside the IETF stream include, for each value, the designation of a change controller for that value. If the definition or reference for a registered value ever needs to change, or if a registered value needs to be deprecated, it is critical that IANA know who is authorized to make the change. For example, the Media Types registry [RFC6838] includes a "Change Controller" in its registration template. See also Section 9.5.2.4. Revising Existing Registries
Updating the registration process or making changes to the format of an already existing (previously created) registry (whether created explicitly or implicitly) follows a process similar to that used when creating a new registry. That is, a document is produced that makes reference to the existing namespace and then provides detailed guidance for handling assignments in the registry or detailed instructions about the changes required. If a change requires a new column in the registry, the instructions need to be clear about how to populate that column for the existing entries. Other changes may require similar clarity. Such documents are normally processed with the same document status as the document that created the registry. Under some circumstances, such as with a straightforward change that is clearly needed (such as adding a "status" column), or when an earlier error needs to be corrected, the IESG may approve an update to a registry without requiring a new document.
Example documents that updated the guidelines for assignments in pre-existing registries include: [RFC6895], [RFC3228], and [RFC3575].3. Registering New Values in an Existing Registry
3.1. Documentation Requirements for Registrations
Often, documents request an assignment in an existing registry (one created by a previously published document). Such documents should clearly identify the registry into which each value is to be registered. Use the exact registry name as listed on the IANA web page, and cite the RFC where the registry is defined. When referring to an existing registry, providing a URL to precisely identify the registry is helpful (see Section 2.2). There is no need to mention what the assignment policy is when making new assignments in existing registries, as that should be clear from the references. However, if multiple assignment policies might apply, as in registries with different ranges that have different policies, it is important to make it clear which range is being requested, so that IANA will know which policy applies and can assign a value in the correct range. Be sure to provide all the information required for a registration, and follow any special processes that are set out for the registry. Registries sometimes require the completion of a registration template for registration or ask registrants to post their request to a particular mailing list for discussion prior to registration. Look up the registry's reference document: the required information and special processes should be documented there. Normally, numeric values to be used are chosen by IANA when the document is approved; drafts should not specify final values. Instead, placeholders such as "TBD1" and "TBD2" should be used consistently throughout the document, giving each item to be registered a different placeholder. The IANA Considerations should ask the RFC Editor to replace the placeholder names with the IANA- assigned values. When drafts need to specify numeric values for testing or early implementations, they will either request early allocation (see Section 3.4) or use values that have already been set aside for testing or experimentation (if the registry in question allows that without explicit assignment). It is important that drafts not choose their own values, lest IANA assign one of those values to another document in the meantime. A draft can request a specific value in the IANA Considerations section, and IANA will
accommodate such requests when possible, but the proposed number
might have been assigned to some other use by the time the draft is
approved.
Normally, text-string values to be used are specified in the
document, as collisions are less likely with text strings. IANA will
consult with the authors if there is, in fact, a collision, and a
different value has to be used. When drafts need to specify string
values for testing or early implementations, they sometimes use the
expected final value. But it is often useful to use a draft value
instead, possibly including the draft version number. This allows
the early implementations to be distinguished from those implementing
the final version. A document that intends to use "foobar" in the
final version might use "foobar-testing-draft-05" for the -05 version
of the draft, for example.
For some registries, there is a long-standing policy prohibiting
assignment of names or codes on a vanity or organization-name basis.
For example, codes might always be assigned sequentially unless there
is a strong reason for making an exception. Nothing in this document
is intended to change those policies or prevent their future
application.
As an example, the following text could be used to request assignment
of a DHCPv6 option number:
IANA is asked to assign an option code value of TBD1 to the DNS
Recursive Name Server option and an option code value of TBD2 to
the Domain Search List option from the DHCP option code space
defined in Section 24.3 of RFC 3315.
The IANA Considerations section should summarize all of the IANA
actions, with pointers to the relevant sections elsewhere in the
document as appropriate. Including section numbers is especially
useful when the reference document is large; the section numbers will
make it easier for those searching the reference document to find the
relevant information.
When multiple values are requested, it is generally helpful to
include a summary table of the additions/changes. It is also helpful
for this table to be in the same format as it appears or will appear
on the IANA web site. For example:
Value Description Reference
-------- ------------------- ---------
TBD1 Foobar this RFC, Section 3.2
TBD2 Gumbo this RFC, Section 3.3
TBD3 Banana this RFC, Section 3.4
Note: In cases where authors feel that including the full table of changes is too verbose or repetitive, authors should still include the table in the draft, but may include a note asking that the table be removed prior to publication of the final RFC.3.2. Updating Existing Registrations
Even after a number has been assigned, some types of registrations contain additional information that may need to be updated over time. For example, MIME media types, character sets, and language tags typically include more information than just the registered value itself, and may need updates to items such as point-of-contact information, security issues, pointers to updates, and literature references. In such cases, the document defining the namespace must clearly state who is responsible for maintaining and updating a registration. Depending on the registry, it may be appropriate to specify one or more of: o Letting registrants and/or nominated change controllers update their own registrations, subject to the same constraints and review as with new registrations. o Allowing attachment of comments to the registration. This can be useful in cases where others have significant objections to a registration, but the author does not agree to change the registration. o Designating the IESG, a designated expert, or another entity as having the right to change the registrant associated with a registration and any requirements or conditions on doing so. This is mainly to get around the problem when a registrant cannot be reached in order to make necessary updates.3.3. Overriding Registration Procedures
Experience has shown that the documented IANA considerations for individual protocols do not always adequately cover the reality of registry operation or are not sufficiently clear. In addition, documented IANA considerations are sometimes found to be too stringent to allow even working group documents (for which there is strong consensus) to perform a registration in advance of actual RFC publication.
In order to allow assignments in such cases, the IESG is granted authority to override registration procedures and approve assignments on a case-by-case basis. The intention here is not to overrule properly documented procedures or to obviate the need for protocols to properly document their IANA considerations. Rather, it is to permit assignments in specific cases where it is obvious that the assignment should just be made, but updating the IANA process beforehand is too onerous. When the IESG is required to take action as described above, it is a strong indicator that the applicable registration procedures should be updated, possibly in parallel with the work that instigated it. IANA always has the discretion to ask the IESG for advice or intervention when they feel it is needed, such as in cases where policies or procedures are unclear to them, where they encounter issues or questions they are unable to resolve, or where registration requests or patterns of requests appear to be unusual or abusive.3.4. Early Allocations
IANA normally takes its actions when a document is approved for publication. There are times, though, when early allocation of a value is important for the development of a technology, for example, when early implementations are created while the document is still under development. IANA has a mechanism for handling such early allocations in some cases. See [RFC7120] for details. It is usually not necessary to explicitly mark a registry as allowing early allocation, because the general rules will apply.
(page 15 continued on part 2)
