Protocol Registration Procedures

How to write an IANA Considerations section

RFC 5226bis is the authoritative source for information on writing an IANA Considerations section. This is additional information to help guide authors and will be updated periodically.

When writing an Internet Draft, authors are required to include a section called IANA Considerations. This section describes the registry actions, if any, that the IANA Services Operator must complete after the IESG approves the document for publication. These actions might include any of the following:

  • creating new registries
  • registering parameters in existing registries
  • modifying parameters in existing registries
  • updating registration procedures for existing registries
  • updating the structure of a registry (for example, adding a new column)
  • updating references in registries

Whether you want to create a new registry, register a parameter, or modify an existing registration, our primary concern is that the request is clear, complete and valid, and that the IANA Considerations section provides all of the information that should appear in the registry.

This help page includes additional information on the following topics:

  1. Glossary of terms
  2. How to create a new registry
  3. How to add registrations to existing registries
  4. How to modify registrations in an existing registry
  5. How to modify the structure of an existing registry
  6. What to do when a document doesn’t request any registry actions
  7. What to leave out of the IANA Considerations section

Glossary of terms

  • Unassigned: This value is available for assignment. There is usually no reference associated with unassigned values.
  • Reserved: This value is not available for assignment. Reserved values can be made available through redefinition in an RFC.
  • Registry page: A webpage or file that contains registries. The title of the page that contains the AEAD Algorithms registry, for example, is “Authenticated Encryption with Associated Data (AEAD) Parameters.”
  • Registry vs. sub-registry: Sub-registries are associated with specific registrations. A registry called “Error Codes,” for example, might be followed by a sub-registry called “Subcodes for Error Code 2.”
  • Value: usually a numerical value.
  • Registration template: A template that must be filled out by future applicants. If you want the registry to include some or all template data, we can either a) link to the templates or b) create a registry column for whichever fields in the template you wish to include. The IANA Considerations section should provide instructions.

How to create a new registry

Preparation:

Before creating a new registry, please consider whether there is truly a need to have a publicly-maintained registry outside the RFC. Check to see whether an existing registry could be used instead.

If you do need a new registry, where should it be placed? See www.iana.org/protocols for the current listing of protocol parameter registries.

Should it be added to an existing registry page, or does it require its own URL? If the latter, what should be the title of the new registry page? Does it need a general title that could cover additional registries in the future? Should that registry title appear as a new category at www.iana.org/protocols, or should the registry be filed under an existing category?

If a suitable registry page already exists, is this a sub-registry of an existing registry on the page, like a sub-TLV registry under a TLV registry?

The registry has a header that consists of the name of the registry, the name of the registration procedure(s), the name(s) of the designated expert(s) (if any), and the reference for the registry. Some registries also include a short note at the top. When you’re creating a registry, consider the following:

  • What is the exact name of the new registry? Is there a naming pattern used by related registries? (For example, are you adding it to a page where other registries use the term “Identifier” rather than the term “ID”? Did those authors use hyphens differently?)
  • URIs your document the only defining reference?
  • What’s the registration procedure? Should different ranges or names require different procedures? See RFCXXXX for a list of frequently-used procedures.
  • We can’t advise you on which registration procedures should apply, whether any ranges or values should be listed as “Reserved,” or any other technical issues.
  • If you choose “Expert Review” or “Specification Required,” note that the expert will be designated by the IESG (with assistance from the relevant AD). The expert should not be named in the document.
  • Should your document have a section or sub-section that provides guidelines for experts?

About the contents of the registry:

  • If the registry has numerical values, what’s the maximum value?
  • If “0” doesn’t have an assignment, should it be listed as “Reserved” (see RFC5226), listed as “Unassigned” (i.e. available for assignment, per RFC5226), or left out of the registry?
  • Should the values be listed in decimal, hexadecimal, or both? (If both, please provide both sets of values.)
  • Should any value ranges be marked “Reserved for Private Use,” or reserved for any other purpose?
  • If the registry is a list of names, should the names be alphabetized?
  • If there’s a registration template, how many fields should be posted in the registry?
  • If the registry won’t have an IESG-designated expert (i.e. the registration procedure isn’t Expert Review or Specification Required), is there anything we and/or applicants need to know about the way registrations should be assigned or formatted? If so, please describe the requirements clearly, and consider whether this might require a brief note at the top of the registry.
  • We can create internal notes about formatting, if needed.
  • If it’s necessary to create a “lockstep” registry that replicates data from an existing registry and must be kept up to date with it, please instruct us to include a note that says something like, “This registry must replicate any new entries in the Example registry at http://www.iana.org/assignments/example, and vice versa.” Likewise, provide the text of a similar note for the corresponding registry, and ask us to add your document as a reference for that registry.
  • For FCFS or Expert Review registries, we will create a change controller column in order to document who or what organization is responsible for the registration.
  • If the document’s version of the registry doesn’t include a reference column, unless instructed otherwise, we will add a column that lists your document as the reference for each registration.

Here are some examples of IANA Considerations sections that create registries:

Section X.

This document is creating one registry and one sub-registry in the page called “Fruit.”

Section X.1

Registry Name:  Fruit
Registration Procedure:
0-100: FCFS
101-200: Expert Review
Reference: [this document]

Value   Description Reference
------- --------------- -------------
0   Reserved    [this document]
1   Apples       [this document]
2   Oranges [an older RFC]
3   Lemons  [this document]
4   Grapes      [this document]
5-254   Unassigned
255 Reserved for Private Use   [this document]

Section X.2

Sub-Registry Name: Apple (value 1) Types
Registration Procedure: First Come First Served
Reference: [this document]

Value   Description Reference
------- --------------- -------------
0   Reserved    [this document] (note: you can also cite an older document)
1   Red     [this document]
2   Green       [this document]
3   Pink        [another standards organization’s document]
4-65535  Unassigned

Here’s another example:

    This document is creating a registry for Lunch Types.  This registry requires that future applicants fill out the registration template included in Appendix A. Approved templates should be hosted on iana.org and linked from the registry.

Registry Name: Lunch
Registration Procedure: Expert Review
Reference: [RFCXXXX]

Name  Description Reference
------- --------------- -------------
No entries yet

Another example:

    This document is creating a registry called “Foo Types” under the new heading “Foo Parameters.” The registration procedure is “Standards Action,” as defined in RFC 5226. The maximum value is 255. The initial registrations follow:

Value : 0
Description: Reserved
Reference: this document

Value: 1
Description: Bar
Reference: this document




Other Kinds of Registries:

Y/N Columns for Each Registration:
http://www.iana.org/assignments/isis-tlv-codepoints (see “Sub-TLVs for TLV 22, 141, and 222)

http://www.iana.org/assignments/tls-parameters

URIs:

http://www.iana.org/assignments/xml-registry

Templates:

http://www.iana.org/assignments/media-types
http://www.iana.org/assignments/message-headers

MIBs:

http://www.iana.org/assignments/ianaiftype-mib

How to add registrations to existing registries

When adding an item to an existing registry, authors should include the exact text they wish to see in each column of the registry.

The IANA Considerations section needs to include

  • The exact name of the registry as it appears at http://www.iana.org/protocols
  • Data for every column in the registry

EXAMPLE:

This document has registered the following value in “Sub-TLVs of TLV 47,” at http://www.iana.org/assignments/example:

Value: TBD1 (suggested value: 13) Name: Foo Description: Extra bar Length: 4 Reference: This document

We prefer that registration data be presented in list or table form rather than in a paragraph.

For an example of an RFC that uses tables, see the IANA Considerations section in RFC 6940.

For an example of an RFC that uses lists, see RFC 5804.

If you include the URL for an existing registry, please use the “short version” that doesn’t include a file extension.

That is, use: http://www.iana.org/assignments/iax-parameters Do not use: http://www.iana.org/assignments/iax-parameters/iax-parameters.xhtml

A NOTE ON REQUESTING SPECIFIC VALUES AND NEEDING REGISTRATIONS EARLY

You don’t have to suggest a value, but you can’t require a value, either, because we can’t guarantee that someone else won’t register that value first.

If you need a specific value, and the registration procedure in question is First Come First Served, Expert Review, or Specification Required (see RFC XXXX for definitions), you can apply at any time using the relevant application form at http://www.iana.org/protocols/apply. The IESG-designated expert may, however, refuse to approve the request until the I-D has been approved for publication by the IESG.

If registrations are needed before RFC publication, and they are being requested in Standards Action, IETF Review, RFC Required, or Specification Required registries, the RFC 7120 procedures can be used. If your early allocation request is approved, the registration request should still be included in the IANA Considerations section, even after registration. Inclusion in the IANA Considerations section will ensure that we update the reference both upon approval and after the RFC Editor assigns a number.

How to modify an existing registration

Identify the exact name/value of the registration, the name of the registry, and the URL (using the format http://www.iana.org/assignments/example).

Let us know whether the document should replace the current reference or be listed as an additional reference.

If you’re writing a –bis document, please note whether we should replace all references to the previous document or only some. If there are any exceptions, note them here.

List any and all information that needs to be changed, including all of the information that should appear in the registry. Check the registry for other columns beside “Value” and “Description.”

If you’re updating a reference, or (as with a –bis document) existing many references, you might use some variation on these sentences:

All references to RFC YYYY in the XYZ Parameters registry should be replaced with references to this document, except for the reference associated with XYZ TLV Type value 37, “ABC TLV.”

This document will be listed as an additional reference for the Bar Parameter registration “foo.”

The following change should be made in the XXXXX registry:

OLD: Value: 12 Description: Bar Reference: RFC YYYY

NEW: Value: 12 Description: Bar Reference: this document

How to modify the structure of an existing registry

If you want to add a column to an existing registry, you need to provide column data for all the previous entries in the registry if possible, or indicate that they can be left blank. The document will be listed as an additional reference for the registry itself and any existing registrations it modifies by adding new column data.

What to do when a document doesn’t request any registry actions

If you don’t need to register/create/modify anything on iana.org, your IANA Considerations section should confirm that fact by saying something like “This document has no registry actions.” You can instruct the RFC Editor to remove it after approval, but we recommend keeping it, so as to assure future readers that no registrations were missed.

What to leave out of an IANA Considerations section

  • Descriptions of how registered values should/should not be used (unless the discussion is required by a registration template, like the one used to register media types)
  • Registration requests directed at other organizations
  • Lists of existing registrations that are related to the document but that don’t need to be modified, unless it is clearly stated that these registrations don’t require modification