Updates for version 0.3
Change-Id: I1e5307e5c04323046549c001fcf638c17e08f0ab
Refs: #4445, #4444, #4443, #4442, #4441, #4440, #4485
diff --git a/changelog.rst b/changelog.rst
index 0184781..49bb1c9 100644
--- a/changelog.rst
+++ b/changelog.rst
@@ -1,6 +1,29 @@
Changes
=======
+Version 0.3
+-----------
+
+- **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 ``Parameters`` element
+
+- **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``
+
+- **Name**
+
+ + Lift restriction on name component types, allowing types in the range ``1`` - ``32767``.
+ + Correct definition of name URI encoding: disallow unescaped encoding of PLUS ``+`` and allow TILDE ``~``.
+
Version 0.2.1
-------------
@@ -8,8 +31,8 @@
- **Interest**
- + Add default of leftmost child if ChildSelector field not present
- + Add specification of ForwardingHint field
+ + Add default of leftmost child if ChildSelector element not present
+ + Add specification of ForwardingHint element
- **Data**
@@ -17,7 +40,7 @@
************************************************************
-Version 2.0
+Version 0.2
-----------
- **Name**
@@ -51,7 +74,7 @@
+ New ``SignatureSha256WithEcdsa`` signature type for Elliptic Curve Digital Signature Algorithm (ECDSA).
+ ``KeyLocatorDigest`` renamed to ``KeyDigest``. The specification now explicitly allows KeyDigest to be a SHA256 of any type of the key.
- + ``KeyLocator`` field is now defined to be optionally present in generic ``SignatureInfo`` block.
+ + ``KeyLocator`` element is now defined to be optionally present in generic ``SignatureInfo`` element.
``SignatureSha256WithRsa`` and ``SignatureSha256WithEcdsa`` still require ``KeyLocator`` to be always present.
************************************************************
@@ -93,14 +116,14 @@
+ ``SignedInfo`` is renamed to ``MetaInfo`` and its content is changed
+ ``PublisherPublicKeyDigest`` and ``ExtOpt`` are removed.
+ ``Timestamp`` is removed
- + ``KeyLocator`` is moved to be inside the ``Signature`` (``SignatureInfo``) block
+ + ``KeyLocator`` is moved to be inside the ``Signature`` (``SignatureInfo``) element
+ Three content types, ENCR, GONE, and NACK are removed
+ ``FreshnessSeconds`` is renamed to ``FreshnessPeriod`` and is expressed in units of milliseconds
- **Signature**
+ ``Signature`` is moved to the end of Data packet.
- + ``KeyLocator`` is moved to be a part of the ``SignatureInfo`` block, if it is applicable for the specific signature type.
+ + ``KeyLocator`` is moved to be a part of the ``SignatureInfo`` element, if it is applicable for the specific signature type.
The rationale for the move is to make Signature (sequence of ``SignatureInfo`` and ``SignatureValue`` TLVs) self-contained and self-sufficient.
diff --git a/conf.py b/conf.py
index 123685b..97805c4 100644
--- a/conf.py
+++ b/conf.py
@@ -41,16 +41,16 @@
# General information about the project.
project = u'NDN Packet Format Specification'
-copyright = u'2013-2017, NDN Project Team'
+copyright = u'2013-2018, NDN Project Team'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
-version = '0.2.1'
+version = '0.3'
# The full version, including alpha/beta/rc tags.
-release = '0.2.1'
+release = '0.3'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
diff --git a/data.rst b/data.rst
index 7b1e5b8..eba092c 100644
--- a/data.rst
+++ b/data.rst
@@ -7,11 +7,11 @@
Data ::= DATA-TLV TLV-LENGTH
Name
- MetaInfo
- Content
+ MetaInfo?
+ Content?
Signature
-The Data packet represents some arbitrary binary data (held in the Content element) together with its Name, some additional bits of information (MetaInfo), and a digital Signature of the other three elements. The Name is the first element since all NDN packet processing starts with the name. Signature is put at the end of the packet to ease the implementation because signature computation covers all the elements before Signature.
+The Data packet represents some arbitrary binary data (held in the optional ``Content`` element) together with its ``Name``, some additional bits of optional information (``MetaInfo``), and a digital ``Signature`` of the other element(s). The Name is the first element since all NDN packet processing starts with the name. Signature is put at the end of the packet to ease the implementation because signature computation covers all the elements before Signature.
Name
~~~~
@@ -23,8 +23,6 @@
MetaInfo
~~~~~~~~
-.. [#f1] If ``ContentType``, ``FreshnessPeriod`` and ``FinalBlockId`` are optional, one may consider ``Metainfo`` itself should be optional. But would having all 4 parts of Data packet help simplify implementation? We leave this question to people who are more familiar with high speed implementations.
-
::
MetaInfo ::= META-INFO-TYPE TLV-LENGTH
@@ -42,21 +40,22 @@
The following ContentTypes are currently defined:
-+-----------------+----------------+--------------------------------------------------------------+
-| ContentType | Assigned value | Description of the content |
-+=================+================+==============================================================+
-| BLOB | 0 | payload identified by the data name; this is the default |
-| | | ContentType |
-+-----------------+----------------+--------------------------------------------------------------+
-| LINK | 1 | a list of delegations (see :ref:`link`) |
-+-----------------+----------------+--------------------------------------------------------------+
-| KEY | 2 | public key |
-+-----------------+----------------+--------------------------------------------------------------+
-| NACK | 3 | application-level NACK |
-+-----------------+----------------+--------------------------------------------------------------+
++-----------------+-----------------+--------------------------------------------------------------+
+| ContentType | Assigned number | Description of the content |
++=================+=================+==============================================================+
+| BLOB | 0 | payload identified by the data name; this is the default |
+| | | ContentType |
++-----------------+-----------------+--------------------------------------------------------------+
+| LINK | 1 | a 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>`__.
+.. _FreshnessPeriod:
FreshnessPeriod
+++++++++++++++
@@ -66,33 +65,28 @@
FreshnessPeriod ::= FRESHNESS-PERIOD-TLV TLV-LENGTH
nonNegativeInteger
-The optional FreshnessPeriod indicates how long a node should wait after the arrival of this data before marking it as stale.
+The optional ``FreshnessPeriod`` indicates how long a node should wait after the arrival of this data before marking it "non-fresh".
The encoded value is number of milliseconds.
-Note that the stale data is still valid data; the expiration of FreshnessPeriod only means that the producer may have produced newer data.
+Note that the "non-fresh" data is still valid data; the expiration of ``FreshnessPeriod`` only means that the producer may have produced newer data.
-Each content store associates every piece of Data with a staleness bit.
-If the Data carries a FreshnessPeriod, it will initially be considered "fresh" and, after the Data has resided in the content store for FreshnessPeriod, it will be marked as stale.
-This is per object staleness and is local to the NDN node.
+If the Data packet carries a ``FreshnessPeriod`` greater than zero, a node should initially consider it "fresh". After the Data has resided in the node for ``FreshnessPeriod`` milliseconds, it will be marked as "non-fresh".
+If the Data does not have a ``FreshnessPeriod`` or if it has a ``FreshnessPeriod`` equal to zero, it MUST be immediately marked "non-fresh".
-If an Interest contains MustBeFresh TLV, a content store MUST NOT return Data with the staleness bit set in response to this interest.
-The effect is the same as if that stale Data did not exist (i.e., the Interest might be matched by some other Data in the store, or, failing that, get forwarded to other nodes).
-When an exact duplicate of the "stale" Data packet, carrying a positive FreshnessPeriod value, is inserted into a content store, the store SHOULD remove the "stale" bit from the cached Data.
-In particular, the Data in the store is no longer stale.
-
-When a content store receives a Data packet without a FreshnessPeriod or with a FreshnessPeriod equal to 0, then it can satisfy an Interest marked MustBeFresh.
+If an Interest contains ``MustBeFresh`` element, a node MUST NOT return "non-fresh" Data in response to this Interest.
+The effect is the same as if that "non-fresh" Data did not exist (i.e., the Interest might be matched by some other Data in the store, or, failing that, get forwarded to other nodes).
+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
++++++++++++
::
- FinalBlockId ::= FINAL-BLOCK-ID-TLV TLV-LENGTH
- NameComponent
+ FinalBlockId ::= FINAL-BLOCK-ID-TYPE TLV-LENGTH
+ NameComponent
-The optional FinalBlockId indicates the identifier of the final block
-in a sequence of fragments.
+The optional FinalBlockId identifies the final block in a sequence of fragments.
It should be present in the final block itself, and may also be present in other fragments to provide advanced warning of the end to consumers.
-The value here should be equal to the last explicit Name Component of the final block.
+The value here should be equal to the last explicit name component of the final block.
.. _Content:
@@ -103,3 +97,5 @@
::
Content ::= CONTENT-TYPE TLV-LENGTH BYTE*
+
+The ``Content`` element can carry any arbitrary sequence of bytes.
diff --git a/interest.rst b/interest.rst
index 30d9abd..8218007 100644
--- a/interest.rst
+++ b/interest.rst
@@ -9,135 +9,63 @@
Interest ::= INTEREST-TYPE TLV-LENGTH
Name
- Selectors?
- Nonce
- InterestLifetime?
+ CanBePrefix?
+ MustBeFresh?
ForwardingHint?
+ Nonce?
+ InterestLifetime?
+ HopLimit?
+ Parameters?
-``Name`` and ``Nonce`` are the only two required elements in an Interest packet.
-Selectors are optional elements that further qualify Data that may match the Interest.
-They are used for discovering and selecting the Data that matches best to what the application wants. Selectors are placed right after the Name to facilitate implementations that may use continuous memory block of Name and Selectors TLVs together as the index for PIT lookup. By using a TLV to group all the Selectors, an implementation can easily skip them to find Nonce, which is used together with Name to identify looping Interests.
-If Selectors TLV is present in the Interest, it MUST contain at least one selector.
-
-``InterestLifetime`` and ``ForwardingHint`` are optional and are referred to as *Guiders*.
-They affect Interest forwarding behavior.
-
-.. Guiders are not grouped.
-
+``Name`` is the only required element in an Interest packet.
+``Nonce`` is required when an Interest is transmitted over the network links, i.e., a compliant forwarder must augment the Interest with the ``Nonce`` element if it is missing.
+``CanBePrefix``, ``MustBeFresh``, ``InterestLifetime``, and ``ForwardingHint`` are optional elements to guide Interest matching or forwarding.
+Interest can also include an optional ``Parameters`` element.
Name
~~~~
-The Name element in an Interest is synonymous with the term *prefix*.
See :ref:`Name section <Name>` for details.
-The Name element that can be put in the Interest is further restricted to have at least one NameComponent.
-Interests that include Name TLV that has zero name components MUST BE discarded.
+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.
-.. _Selectors:
-
-Selectors
-~~~~~~~~~
+CanBePrefix
+~~~~~~~~~~~
::
- Selectors ::= SELECTORS-TYPE TLV-LENGTH
- MinSuffixComponents?
- MaxSuffixComponents?
- PublisherPublicKeyLocator?
- Exclude?
- ChildSelector?
- MustBeFresh?
+ CanBePrefix ::= CAN-BE-PREFIX-TYPE TLV-LENGTH(=0)
-MinSuffixComponents, MaxSuffixComponents
-++++++++++++++++++++++++++++++++++++++++
+When present, ``Name`` element in the Interest is a prefix, exact, or full name of the requested Data packet.
-::
+When not present, the ``Name`` element is either exact or full name of the Data packet:
- MinSuffixComponents ::= MIN-SUFFIX-COMPONENTS-TYPE TLV-LENGTH
- nonNegativeInteger
+- if the last component of the ``Name`` has type ``ImplicitSha256DigestComponent``, Interest can be matched only to a Data packet with full name that includes the implicit digest component;
- MaxSuffixComponents ::= MAX-SUFFIX-COMPONENTS-TYPE TLV-LENGTH
- nonNegativeInteger
-
-When needed, ``MinSuffixComponents`` and ``MaxSuffixComponents`` allow a data consumer to indicate whether the Name in the Interest is the full name including the digest, or the full name except for the digest, or the content it is seeking has a known range of legitimate component counts.
-These two parameters refer to the number of name components beyond those in the prefix, and counting the implicit digest, that may occur in the matching Data.
-The default for ``MinSuffixComponents`` is 0 and for ``MaxSuffixComponents`` is effectively infinite, meaning that any Data whose name starts with the prefix is a match. Often only one of these will be needed to get the desired effect.
-
-
-PublisherPublicKeyLocator
-+++++++++++++++++++++++++
-
-::
-
- PublisherPublicKeyLocator ::= KeyLocator
-
-This element specifies the name of the key which is used to sign the Data packet that the consumer is requesting.
-This is a way for the Interest to select answers from a particular publisher.
-
-See :ref:`KeyLocator` section for more detail.
-
-Exclude
-+++++++
-
-::
-
- Exclude ::= EXCLUDE-TYPE TLV-LENGTH AnyLeading? (NameComponent | AnyBetween)* AnyTrailing?
- AnyLeading ::= Any NameComponent
- AnyBetween ::= NameComponent Any NameComponent
- AnyTrailing ::= NameComponent Any
- Any ::= ANY-TYPE TLV-LENGTH(=0)
-
-The ``Exclude`` selectors allow requesters to specify list and/or ranges of name components that MUST NOT appear as a continuation of the Name prefix in the responding Data packet to the Interest.
-For example, if Interest is expressed for ``/ndn/edu`` and Exclude specifies one name component ``ucla``, then neither data producer nor conforming NDN routers are allowed to return any Data packet that has prefix ``/ndn/edu/ucla``.
-
-Exclude filter applies only to a name component of the Data packet name that is located at a position that numerically equals to the number of name components in the Interest packet, assuming 0 is the first name component.
-
-The Components in the exclusion list MUST occur in strictly increasing order according to the canonical NDN name component ordering (:ref:`Name Section<name>`), with optional leading, trailing, and interleaved ``Any`` components. The following defines processing of ``Any`` components:
-
-- If none of the ``Any`` components are specified, the filter excludes only the names specified in the Exclude list.
-
-- If a leading ``Any`` component is specified, then the filter excludes all names that are smaller or equal (in NDN name component canonical ordering) to the first NameComponent in the Exclude list.
-
-- If a trailing ``Any`` component is specified, then the filter excludes all names that are larger or equal (in NDN name component canonical ordering) to the last NameComponent in the Exclude list.
-
-- If ``Any`` component is specified between two NameComponents in the list, then the filter excludes all names from the range from the right NameComponent to the left NameComponent, including both ends.
-
-
-Exclude filter MUST not consist of a single ``Any`` component or one NameComponent with leading and trailing ``Any`` components.
-
-
-ChildSelector
-+++++++++++++
-
-::
-
- ChildSelector ::= CHILD-SELECTOR-TYPE TLV-LENGTH
- nonNegativeInteger
-
-Often a given Interest can match more than one Data within a given content store.
-The ``ChildSelector`` provides a way of expressing a preference for which of these should be returned.
-If the value is 0, the leftmost child is preferred.
-If 1, the rightmost child is preferred.
-Here leftmost and rightmost refer to the least and greatest components according to the canonical NDN name component ordering (:ref:`Name Section<name>`).
-This ordering is only done at the level of the name hierarchy one past the name prefix.
-If the ``ChildSelector`` field is not present, the leftmost child is preferred (a value of 0).
-
-For example, assuming in the name hierarchy the component immediately after the name prefix is the version number, whose next level is the segment number, then setting ChildSelector to be 1 will retrieve the rightmost version number (i.e., the latest version) and the leftmost segment number (i.e., the first segment). However, this selection is only done with respect to a single content store, not globally. Additional rounds that exclude the earlier versions may be used to explore other content stores for newer versions.
-In this case, the use of ChildSelector does not change the multi-round outcome, but it decreases the number of rounds needed to converge to an answer.
+- 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
-+++++++++++
+~~~~~~~~~~~
::
MustBeFresh ::= MUST-BE-FRESH-TYPE TLV-LENGTH(=0)
-This selector is encoded with Type and Length but no Value part.
-When it is absent from an Interest packet, the router can respond with a Data packet from its content store whose FreshnessPeriod is either still valid or expired.
-When it is present in an Interest packet, the router should not return Data packet from its content store whose FreshnessPeriod has expired.
+The presence or absense 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.
-The FreshnessPeriod carried in each Data packet (:ref:`Data Section<data>`) is set by the original producer. It starts counting down when the Data packet arrives at a node. Consequently if a node is N hops away from the original producer, it may not consider the Data stale until N *X* FreshnessPeriod after the Data is produced.
+ForwardingHint
+~~~~~~~~~~~~~~
+
+::
+
+ ForwardingHint ::= FORWARDING-HINT-TYPE TLV-LENGTH
+ Delegation+
+
+The ForwardingHint element contains a list of name delegations, as defined in :ref:`link` section.
+Each delegation implies that the requested Data packet can be retrieved by forwarding the Interest along the delegation path.
+Specifics of the forwarding logic for Interests with ``ForwardingHint`` will be defined in a separated document.
.. _Nonce:
@@ -154,13 +82,8 @@
The combination of Name and Nonce should uniquely identify an Interest packet.
This is used to detect looping Interests.
-.. _Guiders:
-
-Guiders
-~~~~~~~
-
InterestLifetime
-++++++++++++++++
+~~~~~~~~~~~~~~~~
::
@@ -175,14 +98,37 @@
If the ``InterestLifetime`` element is omitted, a default value of 4 seconds is used (4000).
The missing element may be added before forwarding.
-ForwardingHint
-++++++++++++++
+HopLimit
+~~~~~~~~
::
- ForwardingHint ::= FORWARDING-HINT-TYPE TLV-LENGTH
- Delegation+
+ HopLimit ::= HOP-LIMIT-TYPE TLV-LENGTH(=1) BYTE{1}
-The ForwardingHint field contains a list of name delegations, as defined in :ref:`link` section.
-Each delegation implies that the requested Data packet can be retrieved by forwarding the Interest along the delegation path.
-Specifics of the forwarding logic for Interests with ``ForwardingHint`` will be defined in a separated document.
+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:
+
+- if the ``HopLimit`` value is larger than or equal to 1, a node should accept the packet and decrease the encoded value by 1.
+
+ If the ``HopLimit`` value becomes 0, a node can satisfy this Interest locally (cache or applications bound to local faces), but must not forward the Interests to any non-local faces.
+
+- if ``HopLimit`` is 0, a node must drop the packet
+
+If omitted:
+
+- a node should accept the packet;
+
+- when desired, a node can augment the Interest with the ``HopLimit`` element.
+
+Parameters
+~~~~~~~~~~
+
+::
+
+ Parameters ::= PARAMETERS-TYPE TLV-LENGTH
+ BYTE*
+
+The ``Parameters`` element can carry any arbitrary data that parameterizes the request for Data.
+The Interest's name should include a component or components to ensure uniqueness of the parametrized Interest.
+For example, a SHA256 digest of the ``Parameters`` TLV can be included as one of the components of the Interest name.
diff --git a/intro.rst b/intro.rst
index ce227d6..944c340 100644
--- a/intro.rst
+++ b/intro.rst
@@ -13,8 +13,3 @@
- `"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 <http://named-data.net/publications/snamp-ndn-scalability/>`__
- `"NDN Technical Memo: Naming Conventions" by NDN Project Team. NDN, Technical Report NDN-0022 <http://named-data.net/publications/techreports/ndn-tr-22-ndn-memo-naming-conventions/>`__
-
-Acknowledgment
---------------
-
-This NDN packet format specification is evolution of the `CCNx 0.7.2 specification <https://github.com/named-data/ndnx/releases/tag/ccnx-0.7.2-ndn-1>`__ as of May 2013.
diff --git a/name.rst b/name.rst
index 8e5d3d6..afc8eed 100644
--- a/name.rst
+++ b/name.rst
@@ -17,18 +17,30 @@
Name ::= NAME-TYPE TLV-LENGTH NameComponent*
NameComponent ::= GenericNameComponent |
- ImplicitSha256DigestComponent
+ ImplicitSha256DigestComponent |
+ OtherTypeComponent
- GenericNameComponent ::= NAME-COMPONENT-TYPE TLV-LENGTH BYTE*
+ GenericNameComponent ::= NAME-COMPONENT-TYPE TLV-LENGTH
+ BYTE*
ImplicitSha256DigestComponent ::= IMPLICIT-SHA256-DIGEST-COMPONENT-TYPE TLV-LENGTH(=32)
BYTE{32}
+ OtherTypeComponent ::= OTHER-TYPE-COMPONENT-TYPE TLV-LENGTH
+ BYTE*
+
+ OTHER-TYPE-COMPONENT-TYPE ::= number in the range 2-65535 inclusive except 8
- ``GenericNameComponent`` is a generic name component, without any restrictions on the content of the value.
- ``ImplicitSha256DigestComponent`` is an implicit SHA256 digest component and it is required to contain a value of 32 octets.
+In addition to two component types, ``Name`` can include other component types governed by `Name Component Assignment policy <https://redmine.named-data.net/projects/ndn-tlv/wiki/NameComponentType>`__.
+
+TLV-TYPE of name component MUST be in the range ``1-65535`` (inclusive).
+``Name`` element containing a sub-element out of this range is invalid and the packet SHOULD be dropped.
+
+Name component with TLV-TYPE ``0`` (zero) is reserved to indicate an invalid name component.
NDN URI Scheme
~~~~~~~~~~~~~~
@@ -46,10 +58,9 @@
* ``GenericNameComponent``
+ When producing a URI from an NDN Name, only the generic URI unreserved characters are left unescaped.
- These are the US-ASCII upper and lower case letters (A-Z, a-z), digits (0-9), and the four specials PLUS (+), PERIOD (.), UNDERSCORE (\_), and HYPHEN (-).
+ These are the US-ASCII upper and lower case letters (A-Z, a-z), digits (0-9), and the four specials HYPHEN (-), PERIOD (.), UNDERSCORE (\_), and TILDE (~).
All other characters are escaped using the percent-encoding method of the URI Generic Syntax.
-
+ To unambiguously represent name components that would collide with the use of . and .. for relative URIs, any component that consists solely of zero or more periods is encoded using three additional periods.
* ``ImplicitSha256DigestComponent``
@@ -58,6 +69,9 @@
For example, ``sha256digest=893259d98aca58c451453f29ec7dc38688e690dd0b59ef4f3b9d33738bff0b8d``
+ * Other component types
+
+ + Start with ``<number>=`` prefix (e.g., ``42=...``), followed by the value encoded in the same way as for ``GenericNameComponent``
.. _Implicit Digest Component:
@@ -77,21 +91,17 @@
Canonical Order
~~~~~~~~~~~~~~~
+
In several contexts in NDN packet processing, it is necessary to have a consistent ordering of names and name components.
The order between individual name components is defined as follows:
-- If components have different type, then
+- If components have different type ``component1`` and ``component2``, then
- + Any ``ImplicitSha256DigestComponent`` is less than any ``GenericNameComponent``
-
- ::
-
- ImplicitSha256DigestComponent < GenericNameComponent
+ + ``component1`` is less than ``component2`` if numerical value of ``TLV-CODE(component1)`` is less than numerical value of ``TLV-CODE(component2)``
.. note::
- This order can be enforced by directly comparing TYPE code of the components.
- Type code ``ImplicitSha256DigestComponent`` is guaranteed to be less than type code ``GenericNameComponent``.
+ Type code ``ImplicitSha256DigestComponent`` is guaranteed to be less than type code of any other valid name component.
- If components have the same type, then
@@ -101,3 +111,15 @@
For Names, the ordering is just based on the ordering of the first component where they differ.
If one name is a proper prefix of the other, then it comes first.
+
+.. note::
+ The canonical order can be enforced by directly comparing the wire encoding of the ``Name`` field's TLV-VALUE (i.e., excluding TLV-TYPE and TLV-LEGNTH of the whole Name TLV)::
+
+ int
+ canonicalOrder(Name lhs, Name rhs) {
+ int result = memcmp(lhs.value(), rhs.value(), min(lhs.value_size(), rhs.value_size());
+ if (result == 0) {
+ result = lhs.value_size() - rhs.value_size();
+ }
+ return result;
+ }
diff --git a/tlv.rst b/tlv.rst
index 520655e..9b0233a 100644
--- a/tlv.rst
+++ b/tlv.rst
@@ -97,17 +97,17 @@
In particular, empty payload TLV will carry ``TLV-LENGTH`` equal to 0.
This encoding offers a reasonable balance between compactness and flexibility.
-Most common, standardized Type codes 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 NDN packet format take a non-negative integer as their value, with the following definition::
- nonNegativeInteger ::= BYTE+
+ nonNegativeInteger ::= BYTE{1} | BYTE{2} | BYTE{4} | BYTE{8}
TLV-LENGTH of the TLV element MUST be either 1, 2, 4, or 8.
-Depending on the length value, a nonNegativeInteger is encoded as follows:
+Depending on TLV-LENGTH, a nonNegativeInteger is encoded as follows:
- if the length is 1 (i.e. the value length is 1 octet), the nonNegativeInteger is encoded in one octet;
@@ -125,3 +125,21 @@
256 => TT020100
65535 => TT02FFFF
65536 => TT0400010000
+
+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 overriden 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 decoder encounters an unrecognized or out-of-order element, the behavior should be as follows:
+
+- if the least significant bit of element's TLV-TYPE number is ``1``, abort decoding and report an error;
+- if the least significant bit of element's TLV-TYPE number is ``0``, ignore the element and continue decoding.
+
+.. note::
+ A recognized element is considered out-of-order if it appears in the element order that violates a specification. For example,
+ - 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``}.
+
+.. note::
+ TLV-TYPE numbers 0-31 (inclusive) are "grandfathered" and all designated as "critical" for the purpose of packet processing.
diff --git a/types.rst b/types.rst
index 57e85c4..4a44288 100644
--- a/types.rst
+++ b/types.rst
@@ -23,29 +23,19 @@
+---------------------------------------------+------------------+-----------------+
| **Interest packet** |
+---------------------------------------------+------------------+-----------------+
-| Selectors | 9 | 0x09 |
+| CanBePrefix | 33 | 0x21 |
++---------------------------------------------+------------------+-----------------+
+| MustBeFresh | 18 | 0x12 |
++---------------------------------------------+------------------+-----------------+
+| ForwardingHint | 30 | 0x1e |
+---------------------------------------------+------------------+-----------------+
| Nonce | 10 | 0x0a |
+---------------------------------------------+------------------+-----------------+
| InterestLifetime | 12 | 0x0c |
+---------------------------------------------+------------------+-----------------+
-| ForwardingHint | 30 | 0x1e |
+| HopLimit | 34 (non-critical)| 0x22 |
+---------------------------------------------+------------------+-----------------+
-| **Interest/Selectors** |
-+---------------------------------------------+------------------+-----------------+
-| MinSuffixComponents | 13 | 0x0d |
-+---------------------------------------------+------------------+-----------------+
-| MaxSuffixComponents | 14 | 0x0e |
-+---------------------------------------------+------------------+-----------------+
-| PublisherPublicKeyLocator | 15 | 0x0f |
-+---------------------------------------------+------------------+-----------------+
-| Exclude | 16 | 0x10 |
-+---------------------------------------------+------------------+-----------------+
-| ChildSelector | 17 | 0x11 |
-+---------------------------------------------+------------------+-----------------+
-| MustBeFresh | 18 | 0x12 |
-+---------------------------------------------+------------------+-----------------+
-| Any | 19 | 0x13 |
+| Parameters | 35 (critical) | 0x23 |
+---------------------------------------------+------------------+-----------------+
| **Data packet** |
+---------------------------------------------+------------------+-----------------+
@@ -71,8 +61,6 @@
+---------------------------------------------+------------------+-----------------+
| KeyLocator | 28 | 0x1c |
+---------------------------------------------+------------------+-----------------+
-| KeyDigest | 29 | 0x1d |
-+---------------------------------------------+------------------+-----------------+
| **Link Object** |
+---------------------------------------------+------------------+-----------------+
| Delegation | 31 | 0x1f |
@@ -88,10 +76,27 @@
+----------------+-----------------------------------------------------------+
| Number range | Designation |
+================+===========================================================+
-| 0, 2-4, 32-79 | Reserved for future assignments (1-byte encoding) |
+| 0, 2-4, | |
+| 36-79 | Reserved for future assignments (1-byte encoding) |
++----------------+-----------------------------------------------------------+
+| 9 | Reserved, formerly `Selectors` |
+----------------+-----------------------------------------------------------+
| 11 | Reserved, formerly `Scope` |
+----------------+-----------------------------------------------------------+
+| 13 | Reserved, formerly `MinSuffixComponents` |
++----------------+-----------------------------------------------------------+
+| 14 | Reserved, formerly `MaxSuffixComponents` |
++----------------+-----------------------------------------------------------+
+| 15 | Reserved, formerly `PublisherPublicKeyLocator` |
++----------------+-----------------------------------------------------------+
+| 16 | Reserved, formerly `Exclude` |
++----------------+-----------------------------------------------------------+
+| 17 | Reserved, formerly `ChildSelector` |
++----------------+-----------------------------------------------------------+
+| 19 | Reserved, formerly `Any` |
++----------------+-----------------------------------------------------------+
+| 29 | Reserved, formerly `KeyDigest` |
++----------------+-----------------------------------------------------------+
| 32 | Reserved, formerly `SelectedDelegation` |
+----------------+-----------------------------------------------------------+
| 80-100 | Reserved for assignments related to local link data |