Homogenize markup used for section headings
Plus other minor cleanups
Change-Id: I356642e8d4c379ffb1b70789cba24497a7f8f393
diff --git a/changelog.rst b/changelog.rst
index c6b611a..1842f7c 100644
--- a/changelog.rst
+++ b/changelog.rst
@@ -8,29 +8,9 @@
- Require shortest encoding for TLV-TYPE and TLV-LENGTH numbers
-- **Interest**
-
- + Remove ``Selectors`` element
- + Add optional ``CanBePrefix`` element after Name
- + Move optional ``MustBeFresh`` element after ``CanBePrefix``
- + Move optional ``ForwardingHint`` element after ``MustBeFresh`` (before ``Nonce``)
- + Add optional ``HopLimit`` element
- + Add optional ``ApplicationParameters`` element
- + Define a new specification for Signed Interest using two new elements: ``InterestSignatureInfo`` and ``InterestSignatureValue``
- + Redefine the contents of the ``ForwardingHint`` (remove numerical preference and nesting inside the ``Delegation`` TLV)
-
-- **Data**
-
- + Make ``MetaInfo`` and ``Content`` elements optional
- + Change semantics of omitted (or set to zero) ``FreshnessPeriod`` element: it cannot be used to satisfy Interests with ``MustBeFresh``
-
-- **LinkObject**
-
- + The content is now just a list of names (remove numerical preference)
-
- **Name**
- + Lift restriction on name component types, allowing types in the range 1-65535
+ + Lift restriction on name component types, allowing types in the range [1, 65535]
+ Correct definition of name URI encoding: disallow unescaped encoding of PLUS (``+``) and allow TILDE (``~``)
+ Add well-known special-use component types:
@@ -42,12 +22,33 @@
- ``TimestampNameComponent`` (type 56)
- ``SequenceNumNameComponent`` (type 58)
+- **Interest**
+
+ + Remove ``Selectors`` element
+ + Add optional ``CanBePrefix`` element after Name
+ + Move optional ``MustBeFresh`` element after ``CanBePrefix``
+ + Move optional ``ForwardingHint`` element after ``MustBeFresh`` (before ``Nonce``)
+ + Redefine the contents of the ``ForwardingHint`` (remove numerical preference and nesting inside the ``Delegation`` TLV)
+ + Add optional ``HopLimit`` element
+ + Add optional ``ApplicationParameters`` element
+ + Define a new specification for Signed Interest using two new elements: ``InterestSignatureInfo`` and ``InterestSignatureValue``
+
+- **Data**
+
+ + Make ``MetaInfo`` and ``Content`` elements optional
+ + Change semantics of omitted (or set to zero) ``FreshnessPeriod`` element: it cannot be used to satisfy Interests with ``MustBeFresh``
+
- **Signature**
+ Require all compliant implementations to support the ``SignatureSha256WithEcdsa`` signature type using NIST curve P-256
+ Redefine the signed portion of Data packets to be more future-proof
+ Add ``SignatureEd25519`` signature type
+- **LinkObject**
+
+ + The content is now just a list of names (remove numerical preference)
+
+
Version 0.2.1
-------------
@@ -55,12 +56,13 @@
- **Interest**
- + Add default of leftmost child if ChildSelector element not present
- + Add specification of ForwardingHint element
+ + Add default of leftmost child if ``ChildSelector`` element not present
+ + Add specification of ``ForwardingHint`` element
- **Data**
- + Updated Content Store semantics for Data packets that do not carry FreshnessPeriod.
+ + Updated Content Store semantics for Data packets that do not carry ``FreshnessPeriod``.
+
Version 0.2
-----------
@@ -70,10 +72,6 @@
+ Allow zero-length name component
+ Require implicit digest to be specified using ``ImplicitSha256Digest`` name component
-- **Signature**
-
- + Add spec for ``SignatureHmacWithSha256``
-
- **Interest**
+ Delete deprecated ``Scope`` guider
@@ -81,11 +79,16 @@
- **Data**
- + Redirect ContentType number assignments to the `wiki page <https://redmine.named-data.net/projects/ndn-tlv/wiki/ContentType>`__
+ + Redirect ``ContentType`` number assignments to the `wiki page <https://redmine.named-data.net/projects/ndn-tlv/wiki/ContentType>`__
+
+- **Signature**
+
+ + Add spec for ``SignatureHmacWithSha256``
- **TLV-TYPE**
- + Reserve 800-1000 range for link protocol
+ + Reserve range [800, 1000] for link protocol
+
Version 0.1.1
-------------
@@ -97,6 +100,7 @@
+ ``KeyLocator`` element is now defined to be optionally present in generic ``SignatureInfo`` element.
``SignatureSha256WithRsa`` and ``SignatureSha256WithEcdsa`` still require ``KeyLocator`` to be always present.
+
Version 0.1
-----------
diff --git a/data.rst b/data.rst
index 221a994..16bdabf 100644
--- a/data.rst
+++ b/data.rst
@@ -1,9 +1,9 @@
.. _Data:
Data Packet
------------
+===========
-NDN Data packet is TLV defined as follows::
+The NDN Data packet is a TLV defined as follows::
Data = DATA-TYPE TLV-LENGTH
Name
@@ -18,7 +18,7 @@
Name
-~~~~
+----
See :ref:`Name`.
@@ -26,7 +26,7 @@
.. _MetaInfo:
MetaInfo
-~~~~~~~~
+--------
::
@@ -36,7 +36,7 @@
[FinalBlockId]
ContentType
-+++++++++++
+^^^^^^^^^^^
::
@@ -50,19 +50,19 @@
| BLOB | 0 | payload identified by the data name; this is the default |
| | | ContentType |
+-----------------+-----------------+--------------------------------------------------------------+
-| LINK | 1 | a list of delegations (see :ref:`link`) |
+| LINK | 1 | list of delegations (see :ref:`Link`) |
+-----------------+-----------------+--------------------------------------------------------------+
| KEY | 2 | public key |
+-----------------+-----------------+--------------------------------------------------------------+
| NACK | 3 | application-level NACK |
+-----------------+-----------------+--------------------------------------------------------------+
-Other ContentType numbers are assigned and maintained in `NDN Packet Specification Wiki <https://redmine.named-data.net/projects/ndn-tlv/wiki/ContentType>`__.
+Other ContentType numbers are assigned and maintained in the `NDN Packet Specification Wiki <https://redmine.named-data.net/projects/ndn-tlv/wiki/ContentType>`__.
.. _FreshnessPeriod:
FreshnessPeriod
-+++++++++++++++
+^^^^^^^^^^^^^^^
::
@@ -80,7 +80,7 @@
When an exact duplicate of the "non-fresh" Data packet with a positive ``FreshnessPeriod`` value arrives at the node, the node SHOULD re-mark it as "fresh" for the specified duration.
FinalBlockId
-++++++++++++
+^^^^^^^^^^^^
::
@@ -94,10 +94,16 @@
.. _Content:
Content
-~~~~~~~
+-------
::
Content = CONTENT-TYPE TLV-LENGTH *OCTET
The ``Content`` element can carry any arbitrary sequence of bytes.
+
+
+DataSignature
+-------------
+
+See :ref:`DataSignature`.
diff --git a/interest.rst b/interest.rst
index f7f366c..792e327 100644
--- a/interest.rst
+++ b/interest.rst
@@ -1,11 +1,9 @@
.. _Interest:
Interest Packet
----------------
+===============
-NDN Interest packet is TLV defined as follows:
-
-::
+The NDN Interest packet is a TLV defined as follows::
Interest = INTEREST-TYPE TLV-LENGTH
Name
@@ -28,16 +26,18 @@
As recommended by :ref:`TLV evolvability guidelines <evolvability>`, unrecognized non-critical TLV elements may appear in the Interest packet.
However, they must not appear before the ``Name`` element.
-Name
-~~~~
-See :ref:`Name section <Name>` for details.
+Name
+----
+
+See :ref:`Name` for details.
The ``Name`` element that can be put in the Interest is further restricted to have at least one name component.
Interests that include Name TLV that has zero name components MUST be discarded.
+
CanBePrefix
-~~~~~~~~~~~
+-----------
::
@@ -52,8 +52,9 @@
- if the last component has any other type, Interest is matched to Data if all name components in Interest's ``Name`` element equal to components in Data's ``Name`` element, without consideration of the implicit digest component.
+
MustBeFresh
-~~~~~~~~~~~
+-----------
::
@@ -61,10 +62,11 @@
TLV-LENGTH ; == 0
The presence or absence of the ``MustBeFresh`` element indicates whether a content store may satisfy the Interest with stale Data.
-Refer for :ref:`FreshnessPeriod section <FreshnessPeriod>` for more information.
+See :ref:`FreshnessPeriod` for more information.
+
ForwardingHint
-~~~~~~~~~~~~~~
+--------------
::
@@ -74,12 +76,11 @@
Presence of the forwarding hint implies that Data can be retrieved by forwarding the Interest over path(s) pointed by the listed Names.
Specifics of the forwarding logic for Interests with ``ForwardingHint`` will be defined in a separated document.
+
.. _Nonce:
Nonce
-~~~~~
-
-Nonce defined as follows:
+-----
::
@@ -91,8 +92,9 @@
The combination of Name and Nonce should uniquely identify an Interest packet.
This is used to detect looping Interests.
+
InterestLifetime
-~~~~~~~~~~~~~~~~
+----------------
::
@@ -107,8 +109,9 @@
If the ``InterestLifetime`` element is omitted, a default value of 4 seconds is used (4000).
The missing element may be added before forwarding.
+
HopLimit
-~~~~~~~~
+--------
::
@@ -116,7 +119,7 @@
TLV-LENGTH ; == 1
OCTET
-The optional ``HopLimit`` element indicates the number of hops the Interest is allowed to be forwarded. The value is encoded as a 1-byte unsigned integer value in the range 0-255.
+The optional ``HopLimit`` element indicates the number of hops the Interest is allowed to be forwarded. The value is encoded as a 1-byte unsigned integer value in the range [0, 255].
If element is present:
@@ -132,12 +135,19 @@
- when desired, a node can augment the Interest with the ``HopLimit`` element.
+
ApplicationParameters
-~~~~~~~~~~~~~~~~~~~~~
+---------------------
::
ApplicationParameters = APPLICATION-PARAMETERS-TYPE TLV-LENGTH *OCTET
The ``ApplicationParameters`` element can carry any arbitrary data that parameterizes the request for Data.
-The Interest's name MUST include a Interest parameters digest component to ensure uniqueness and integrity of the parameterized Interest (see :ref:`Interest Parameters Digest Component` section for additional details).
+The Interest's name MUST include a Interest parameters digest component to ensure uniqueness and integrity of the parameterized Interest (see :ref:`ParametersDigestComponent` for additional details).
+
+
+InterestSignature
+-----------------
+
+See :ref:`InterestSignature`.
diff --git a/intro.rst b/intro.rst
index d1c877a..b9491c6 100644
--- a/intro.rst
+++ b/intro.rst
@@ -1,5 +1,5 @@
Introduction
-------------
+============
This version of specification aims to describe the NDN packet format only, a much narrower scope than a full NDN protocol specification.
Full protocol specification will be published as a separate document. For more information about the overall protocol refer to `"Named Data Networking" by Lixia Zhang, Alexander Afanasyev, Jeffrey Burke, Van Jacobson, kc claffy, Patrick Crowley, Christos Papadopoulos, Lan Wang, and Beichuan Zhang, ACM SIGCOMM Computer Communication Review (CCR), July 2014 <https://named-data.net/publications/named_data_networking_ccr/>`__ and other publications on `Named Data Networking website <https://named-data.net>`__.
@@ -12,4 +12,4 @@
- `"SNAMP: Secure Namespace Mapping to Scale NDN Forwarding" by Alexander Afanasyev, Cheng Yi, Lan Wang, Beichuan Zhang, and Lixia Zhang, 18th IEEE Global Internet Symposium, April 2015 <https://named-data.net/publications/snamp-ndn-scalability/>`__
-- `"NDN Technical Memo: Naming Conventions" by NDN Project Team. NDN, Technical Report NDN-0022 <https://named-data.net/publications/techreports/ndn-tr-22-2-ndn-memo-naming-conventions/>`__
+- `"NDN Technical Memo: Naming Conventions" by NDN Project Team. NDN, Technical Report NDN-0022 <https://named-data.net/publications/techreports/ndn-tr-22-3-ndn-memo-naming-conventions/>`__
diff --git a/link.rst b/link.rst
index 24c022e..65444a3 100644
--- a/link.rst
+++ b/link.rst
@@ -1,7 +1,7 @@
.. _Link:
Link Object
------------
+===========
The Link Object is a specialized form of a :ref:`Data packet <Data>`, defined as follows::
diff --git a/name.rst b/name.rst
index d018701..f2594e1 100644
--- a/name.rst
+++ b/name.rst
@@ -1,18 +1,17 @@
.. _Name:
Name
-----
+====
An NDN Name is a hierarchical name for NDN content, which contains a sequence of name components.
-NDN Name Format
-~~~~~~~~~~~~~~~
+
+Name TLV Encoding
+-----------------
We use a 2-level nested TLV to represent a name.
The NAME-TYPE in the outer TLV indicates this is a Name.
-Inner TLVs should be ``NameComponent`` elements, as defined in the following:
-
-::
+Inner TLVs should be ``NameComponent`` elements, defined as follows::
Name = NAME-TYPE TLV-LENGTH *NameComponent
@@ -47,8 +46,9 @@
``Name`` element containing a sub-element out of this range is invalid and the packet SHOULD be dropped.
This requirement overrides the TLV evolvability guidelines.
+
NDN URI Scheme
-~~~~~~~~~~~~~~
+--------------
For textual representation, it is often convenient to use URI to represent NDN names.
Please refer to :rfc:`3986` (URI Generic Syntax) for background.
@@ -93,21 +93,21 @@
Such alternate representations should be defined in `Name Component Assignment policy <https://redmine.named-data.net/projects/ndn-tlv/wiki/NameComponentType>`__.
-.. _Implicit Digest Component:
Implicit Digest Component
-~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------
The full name of every Data packet includes a logical final implicit digest component, which makes the name of every Data packet unique.
The implicit digest (``ImplicitSha256DigestComponent``) MAY appear in an Interest as the last component of the Interest name to request a specific Data packet.
``ImplicitSha256DigestComponent`` is never included explicitly in the Data packet when it is transmitted on the wire and, if needed, must be computed by all nodes based on the Data packet content.
-The **implicit digest component** consists of the SHA-256 digest of the entire Data packet bits. Having this digest as the last name component allows identifying one specific Data packet and no other.
+The implicit digest component consists of the SHA-256 digest of the entire Data packet bits. Having this digest as the last name component allows identifying one specific Data packet and no other.
-.. _Interest Parameters Digest Component:
+
+.. _ParametersDigestComponent:
Parameters Digest Component
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------
The parameters digest component (``ParametersSha256DigestComponent``) contains the SHA-256 digest computed over the portion of an Interest starting from and including the ``ApplicationParameters`` element until the end of the Interest.
This digest provides uniqueness of the Interest name for a given set of parameters and securely ensures that the retrieved Data packet is a response generated against the correct set of parameters.
@@ -117,8 +117,9 @@
Generally, it should be at the end of the name but before version/segment numbers.
Producers should recompute the digest over the specified portion of a received Interest, and drop the Interest if the computed digest does not match the parameters digest component in the name.
+
Canonical Order
-~~~~~~~~~~~~~~~
+---------------
In several contexts in NDN packet processing, it is necessary to have a consistent ordering of names and name components.
diff --git a/requirements.txt b/requirements.txt
index 3b2379e..7639064 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -1,2 +1,2 @@
-furo == 2022.9.15
+furo == 2022.9.29
sphinx ~= 5.0
diff --git a/signature.rst b/signature.rst
index d9f5367..afdc238 100644
--- a/signature.rst
+++ b/signature.rst
@@ -103,7 +103,7 @@
KeyDigest = KEY-DIGEST-TYPE TLV-LENGTH *OCTET
-See :ref:`Name specification <Name>` for the definition of ``Name``.
+See :ref:`Name` for the definition of the ``Name`` element.
The specific definition of the proper usage of the ``Name`` and ``KeyDigest`` options in the ``KeyLocator`` field is outside the scope of this specification.
Generally, ``Name`` names the Data packet containing the corresponding certificate.
diff --git a/signed-interest.rst b/signed-interest.rst
index 40a004d..2d2dcf3 100644
--- a/signed-interest.rst
+++ b/signed-interest.rst
@@ -10,53 +10,54 @@
* Name ends with ``ParametersSha256DigestComponent``.
* ``InterestSignature`` is present.
-See :ref:`Interest Signature section <InterestSignature>` for details on ``InterestSignature``.
+See :ref:`InterestSignature` for details on the format of the ``InterestSignature`` element.
-Construction of Signed Interest
--------------------------------
+Construction of Signed Interests
+--------------------------------
The following procedure describes the signing of an Interest:
-1. Remove all ``ParametersSha256DigestComponent`` components from ``Name`` if present, regardless of the location.
+#. Remove all ``ParametersSha256DigestComponent`` components from ``Name`` if present, regardless of the location.
-2. If ``ApplicationParameters`` element is absent, append a zero-length ``ApplicationParameters`` element to the Interest.
+#. If ``ApplicationParameters`` element is absent, append a zero-length ``ApplicationParameters`` element to the Interest.
-3. Prepare an ``InterestSignatureInfo`` element and append it at the end of the Interest.
+#. Prepare an ``InterestSignatureInfo`` element and append it at the end of the Interest.
-4. Compute the cryptographic signature according to :ref:`Interest Signature section <InterestSignature>`.
+#. Compute the cryptographic signature according to the :ref:`InterestSignature` section.
-5. Insert the computed signature as an ``InterestSignatureValue`` element at the end of the Interest.
+#. Insert the computed signature as an ``InterestSignatureValue`` element at the end of the Interest.
-6. Compute the ``ParametersSha256DigestComponent`` according to :ref:`Interest Parameters Digest Component <Interest Parameters Digest Component>` section and append it at the end of ``Name``.
+#. Compute the ``ParametersSha256DigestComponent`` according to the :ref:`ParametersDigestComponent` section and append it at the end of ``Name``.
-Signed Interest processing
---------------------------
+Processing of Signed Interests
+------------------------------
Upon receiving an Interest, the producer, according to the Interest name prefix, should be able to tell whether the Interest is required to be signed.
-If the received Interest is required to be signed, the application protocol or the producer should also explicitly define whether ``SignatureNonce``/``SignatureTime``/``SignatureSeqNum`` must be present in the ``InterestSignatureInfo`` or not.
+If the received Interest is required to be signed, the application protocol or the producer should also explicitly define whether ``SignatureNonce``, ``SignatureTime``, and/or ``SignatureSeqNum`` must be present in ``InterestSignatureInfo`` or not.
If any of the required elements is missing, treat the Interest as invalid.
Additionally, a signed Interest must be treated as invalid if any of the following conditions is true:
-1. The last name component is not ``ParametersSha256DigestComponent``, or its TLV-VALUE is incorrect according to :ref:`Interest Parameters Digest Component <Interest Parameters Digest Component>` section.
+#. The last name component is not ``ParametersSha256DigestComponent``, or its TLV-VALUE is incorrect according to the :ref:`ParametersDigestComponent` section.
-2. The ``InterestSignatureInfo`` element is missing or any mandatory sub-element is missing from the ``InterestSignatureInfo`` element.
+#. The ``InterestSignatureInfo`` element is missing or any mandatory sub-element is missing from the ``InterestSignatureInfo`` element.
-3. The ``InterestSignatureValue`` element is missing.
+#. The ``InterestSignatureValue`` element is missing.
-4. The signature cannot be cryptographically verified.
+#. The signature cannot be cryptographically verified.
-5. The key used to create the signature is not trusted for signing the Interest.
+#. The key used to create the signature is not trusted for signing the Interest.
-6. If ``SignatureTime`` (`t`) is present in the ``InterestSignatureInfo``:
+#. If ``SignatureTime`` (*t*) is present in the ``InterestSignatureInfo``:
- Lookup the last recorded ``SignatureTime`` (`t0`) used in conjunction with the same key. Use ``CurrentTime - GracePeriod`` if no previous record exists. The recommended grace period is 60 seconds.
- If `t0` >= `t`, consider the Interest as invalid.
- Update `t0` to `t` if the signed Interest has been validated according to this and all other rules.
+ Lookup the last recorded ``SignatureTime`` (*t*\ :sub:`0`) used in conjunction with the same key.
+ Use ``CurrentTime - GracePeriod`` if no previous record exists. The recommended grace period is 60 seconds.
+ If *t*\ :sub:`0` >= *t*, consider the Interest as invalid.
+ Set *t*\ :sub:`0` to *t* if the signed Interest has been validated according to this and all other rules.
.. note::
Sharing private keys is not recommended. If private key sharing is inevitable, it is the key owner's responsibility to keep clocks synchronized.
-7. If ``SignatureNonce`` is present:
+#. If ``SignatureNonce`` is present:
To perform this check, the recipient must remember a list of ``SignatureNonce`` carried in previously received Signed Interests used in conjunction with the specific signing key.
Check whether the ``SignatureNonce`` carried in the current signed Interest is a repetition of a recorded ``SignatureNonce`` used with the same key.
@@ -66,12 +67,14 @@
.. note::
The size of the ``SignatureNonce`` list and the lifetime of each ``SignatureNonce`` remembered by the receiver depend on the application protocol's need.
-8. If ``SignatureSeqNum`` (`s`) is present:
+#. If ``SignatureSeqNum`` (*s*) is present:
- Lookup the last recorded ``SignatureSeqNum`` (`s0`) used in conjunction with the same key. If `s0` >= `s`, consider the Interest as invalid.
- If no previous record exists, check `s` against the application policy.
- If `s` does not satisfy the application policy, treat the signed Interest as invalid.
- Update `s0` to `s` if the signed Interest has been validated according to this and all other rules.
+ Lookup the last recorded ``SignatureSeqNum`` (*s*\ :sub:`0`) used in conjunction with the same key.
+ If *s*\ :sub:`0` >= *s*, consider the Interest as invalid.
+ If no previous record exists, check *s* against the application policy.
+ If *s* does not satisfy the application policy, treat the signed Interest as invalid.
+ Set *s*\ :sub:`0` to *s* if the signed Interest has been validated according to this and all other rules.
.. note::
- The first ``SignatureSeqNum`` received is considered valid only if it satisfies the application's policy. For example, application can decide the first ``SeqNum`` can only be a minimum value like 0 or 1, or a value that both sender and receiver agree on.
+ The first ``SignatureSeqNum`` received is considered valid only if it satisfies the application's policy.
+ For example, application can decide the first ``SeqNum`` can only be a minimum value like 0 or 1, or a value that both sender and receiver agree on.
diff --git a/tlv.rst b/tlv.rst
index 240af02..35d4edb 100644
--- a/tlv.rst
+++ b/tlv.rst
@@ -1,5 +1,5 @@
Type-Length-Value (TLV) Encoding
---------------------------------
+================================
Each NDN packet is encoded in :abbr:`TLV (Type-Length-Value)` format.
NDN Interest and Data packets are distinguished by the type number in the first and outermost TLV\ :sub:`0`\ .
@@ -10,8 +10,9 @@
There is also no packet fragmentation support at network level.
Whenever needed, NDN packets may be fragmented and reassembled hop-by-hop\ [#f1]_.
+
Variable-Size Encoding for Type and Length
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------------------------
.. note::
The text below and that in the :ref:`TLV` section are adapted from an earlier packet specification draft by Mark Stapp.
@@ -42,13 +43,14 @@
- If the first octet is 255 (``0xFF``), the number is encoded in the following 8 octets, in network byte-order.
This number must be greater than 4294967295 (``0xFFFFFFFF``).
-A number MUST be encoded in the shortest format.
+A number MUST be encoded using the shortest possible format.
For example, the number 1024 is encoded as ``%xFD0400`` in ``VAR-NUMBER-3`` format, not ``%xFE00000400`` in ``VAR-NUMBER-5`` format.
+
.. _TLV:
NDN TLV Encoding
-~~~~~~~~~~~~~~~~
+----------------
TLV encoding for NDN packets is defined as follows::
@@ -57,20 +59,21 @@
TLV-LENGTH = VAR-NUMBER-1 / VAR-NUMBER-3 / VAR-NUMBER-5 / VAR-NUMBER-9
TLV-VALUE = *OCTET
-TLV-TYPE MUST be in the range ``1-4294967295`` (inclusive).
-Zero is reserved to indicate an invalid TLV element and MUST NOT appear on the wire.
-TLV-TYPE SHOULD be unique at all nested levels.
-Section :ref:`types` of this document lists initial TLV-TYPE assignments.
+``TLV-TYPE`` MUST be in the range [1, 4294967295].
+Type 0 is reserved to indicate an invalid TLV element and MUST NOT appear on the wire.
+``TLV-TYPE`` SHOULD be unique at all nested levels.
+Section :ref:`types` of this document lists the initial ``TLV-TYPE`` assignments.
The ``TLV-LENGTH`` field indicates number of bytes that ``TLV-VALUE`` uses.
-It **does not** include number of bytes that ``TLV-TYPE`` and ``TLV-LENGTH`` fields themselves occupy.
-In particular, empty payload TLV will carry ``TLV-LENGTH`` equal to 0.
+It does not include the number of bytes that ``TLV-TYPE`` and ``TLV-LENGTH`` fields themselves occupy.
+In particular, a TLV element with empty value will have ``TLV-LENGTH`` equal to 0.
This encoding offers a reasonable balance between compactness and flexibility.
-Most common, standardized TLV-TYPE numbers will be allocated from a small-integer number-space, and these common types will be able to use the compact, single-byte encoding.
+Most common, standardized ``TLV-TYPE`` numbers will be allocated from a small-integer number-space, and these common types will be able to use the compact, single-byte encoding.
+
Non-Negative Integer Encoding
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------
A number of TLV elements in the NDN packet format take a non-negative integer as their TLV-VALUE, with the following definition::
@@ -95,18 +98,19 @@
65535 => TT02FFFF
65536 => TT0400010000
+
.. _evolvability:
Considerations for Evolvability of TLV-Based Encoding
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------------------------------
-To ensure that the TLV-based protocol can evolve over time without requiring flag days, the least significant bit of TLV-TYPE number (unless overridden by the specification of a particular network/library/application TLV element) is reserved to indicate whether that TLV element is "critical" or "non-critical".
+To ensure that the TLV-based protocol can evolve over time without requiring flag days, the least significant bit of ``TLV-TYPE`` (unless overridden by the specification of a particular network/library/application TLV element) is reserved to indicate whether that TLV element is *critical* or *non-critical*.
A compliant TLV format decoder should follow the order, quantity, and presence requirements of the recognized elements defined in the corresponding specification.
At the same time, if the decoder encounters an unrecognized or out-of-order element, the behavior should be as follows:
-- if the least significant bit of the element's TLV-TYPE number is ``1``, abort decoding and report an error;
-- if the least significant bit of the element's TLV-TYPE number is ``0``, ignore the element and continue decoding;
-- TLV-TYPE numbers 0-31 (inclusive) are "grandfathered" and are all designated as "critical" for the purposes of packet processing.
+- if the least significant bit of the element's ``TLV-TYPE`` number is 1, abort decoding and report an error;
+- if the least significant bit of the element's ``TLV-TYPE`` number is 0, ignore the element and continue decoding;
+- ``TLV-TYPE`` numbers in the range [0, 31] are "grandfathered" and are all designated as *critical* for the purposes of packet processing.
.. note::
A recognized element is considered out-of-order if it appears in the element order that violates a specification. For example:
@@ -114,6 +118,7 @@
- when a specification defines a sequence {``F1`` ``F2`` ``F3``}, an element ``F3`` would be out-of-order in the sequence {``F1`` ``F3`` ``F2``};
- for {``F1`` ``F2?`` ``F3``} specification (i.e., when ``F2`` is optional, ``F2`` would be out-of-order in the same sequence {``F1`` ``F3`` ``F2``}.
+
.. rubric:: Footnotes
.. [#f1] `"Packet Fragmentation in NDN: Why NDN Uses Hop-By-Hop Fragmentation (NDN Memo)" by A. Afanasyev, J. Shi, L. Wang, B. Zhang, and L. Zhang., NDN Memo, Technical Report NDN-0032 <https://named-data.net/publications/techreports/ndn-0032-1-ndn-memo-fragmentation/>`__
diff --git a/types.rst b/types.rst
index 7c7f132..a8d4fec 100644
--- a/types.rst
+++ b/types.rst
@@ -1,10 +1,10 @@
.. _types:
TLV Type Registry
------------------
+=================
Assigned numbers
-~~~~~~~~~~~~~~~~
+----------------
+---------------------------------------------+--------------------+-----------------+
| Type | Assigned number | Assigned number |
@@ -113,8 +113,9 @@
The ABNF grammar of this specification denotes the TLV-TYPE of element ``X`` as ``X-TYPE``.
For example, ``INTEREST-TYPE`` means ``%x05``, the TLV-TYPE of ``Interest`` encoded in ``VAR-NUMBER-1`` format.
+
Reserved ranges
-~~~~~~~~~~~~~~~
+---------------
+----------------+-----------------------------------------------------------+
| Number range | Designation |