Add ParametersSha256DigestComponent
Change-Id: I4ee53136adc6a0fc0af9abbb9fb8fdec265ba749
Refs: #4658, #4690
diff --git a/changelog.rst b/changelog.rst
index 49bb1c9..078b694 100644
--- a/changelog.rst
+++ b/changelog.rst
@@ -23,6 +23,7 @@
+ 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 ``~``.
+ + Add ``ParametersSha256DigestComponent``
Version 0.2.1
-------------
diff --git a/interest.rst b/interest.rst
index caa6ba3..bd8bb11 100644
--- a/interest.rst
+++ b/interest.rst
@@ -133,5 +133,4 @@
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.
+The Interest's name MUST include a Interest parameters digest component to ensure uniqueness and integrity of the parametrized Interest (see :ref:`Interest Parameters Digest Component` section for additional details).
diff --git a/name.rst b/name.rst
index 8fad777..424ff50 100644
--- a/name.rst
+++ b/name.rst
@@ -9,7 +9,7 @@
~~~~~~~~~~~~~~~
We use a 2-level nested TLV to represent a name.
-The Type in the outer TLV indicates this is 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:
::
@@ -18,6 +18,7 @@
NameComponent ::= GenericNameComponent |
ImplicitSha256DigestComponent |
+ ParametersSha256DigestComponent |
OtherTypeComponent
GenericNameComponent ::= NAME-COMPONENT-TYPE TLV-LENGTH
@@ -26,16 +27,21 @@
ImplicitSha256DigestComponent ::= IMPLICIT-SHA256-DIGEST-COMPONENT-TYPE TLV-LENGTH(=32)
BYTE{32}
+ ParametersSha256DigestComponent ::= PARAMETERS-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
+ OTHER-TYPE-COMPONENT-TYPE ::= number in the range 3-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.
+- ``ImplicitSha256DigestComponent`` is an implicit SHA-256 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>`__.
+- ``ParametersSha256DigestComponent`` is a component carrying the SHA-256 digest of Interest parameters and it is required to contain a value of 32 octets.
+
+In addition to the above 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.
@@ -49,30 +55,45 @@
For textual representation, it is often convenient to use URI to represent NDN names.
Please refer to RFC 3986 (URI Generic Syntax) for background.
-- The scheme identifier is ``ndn``.
+The scheme identifier is ``ndn``.
-- The authority component (the part after the initial ``//`` in the familiar http and ftp URI schemes) is not relevant to NDN.
- It should not be present, and it is ignored if it is present.
+The authority component (the part after the initial ``//`` in the familiar http and ftp URI schemes) is irrelevant to NDN.
+It should not be present, and it is ignored if it is present.
-- Component types have the following URI representations:
+Each name component is represented as ``<type-number>=<escaped-value>``, where:
- * ``GenericNameComponent``
+- ``<type-number>`` is the component's TLV-TYPE in decimal format without leading zeros.
- + 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 HYPHEN (-), PERIOD (.), UNDERSCORE (\_), and TILDE (~).
- All other characters are escaped using the percent-encoding method of the URI Generic Syntax.
+- ``<escaped-value>`` is the component's TLV-VALUE escaped according to the following rules:
- + 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.
+ * 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 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``
+For example, ``42=Hello%20world`` represents a name component of TLV-TYPE 42 and TLV-VALUE "Hello world".
- + Implicit SHA256 digest component starts with ``sha256digest=`` prefix (case sensitive), followed by the digest represented as a sequence of 64 hexadecimal numbers.
+Name components of the following types have alternate URI representations for better readability:
- For example, ``sha256digest=893259d98aca58c451453f29ec7dc38688e690dd0b59ef4f3b9d33738bff0b8d``
+- ``GenericNameComponent`` can have its ``<type-number>=`` prefix omitted.
- * Other component types
+ For example, ``Hello%20world`` is equivalent to ``8=Hello%20world``.
- + Start with ``<number>=`` prefix (e.g., ``42=...``), followed by the value encoded in the same way as for ``GenericNameComponent``
+- ``ImplicitSha256DigestComponent`` can be represented as ``sha256digest=<hex-value>``.
+ ``ParametersSha256DigestComponent`` can be represented as ``params-sha256=<hex-value>``.
+
+ * The ``sha256digest=`` and ``params-sha256=`` prefixes are case sensitive.
+ * ``<hex-value>`` is the TLV-VALUE represented as a sequence of 64 hexadecimal digits.
+ Both lower-case and upper-case letters are acceptable, but lower-case is preferred.
+
+ For example, ``sha256digest=893259d98aca58c451453f29ec7dc38688e690dd0b59ef4f3b9d33738bff0b8d``, ``params-sha256=893259d98aca58c451453f29ec7dc38688e690dd0b59ef4f3b9d33738bff0b8d``
+
+- Other component types may define alternate URI representations in the form of ``<prefix>=<value>``, where:
+
+ * ``<prefix>`` is a non-empty string that starts with an upper or lower case letter and consists solely of generic URI unreserved characters.
+ * ``<value>`` is a string whose interpretation differs according to the prefix.
+
+ Such alternate representations should be defined in `Name Component Assignment policy <https://redmine.named-data.net/projects/ndn-tlv/wiki/NameComponentType>`__.
.. _Implicit Digest Component:
@@ -85,20 +106,31 @@
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:
+
+Parameters Digest Component
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The parameters digest component consists of the SHA-256 digest computed over the type, length, and value of the ``Parameters`` element of an Interest.
+This component MUST appear in an Interest name if the Interest contains a ``Parameters`` element.
+The position of the component is determined by the application protocol, generally, it should be at the end of the name but before version/segment numbers.
+
+The parameters digest (``ParametersSha256DigestComponent``) provides uniqueness of the Interest name for a given set of parameters and ensures securely that the retrieved Data packet is a response generated against the correct set of parameters.
+Producers should recalculate the digest based on the actual ``Parameters`` element in the received Interest and verify that it matches the parameters digest component in the Interest name.
+
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 ``component1`` and ``component2``, then
+- If components ``component1`` and ``component2`` have different types, then
- + ``component1`` is less than ``component2`` if numerical value of ``TLV-CODE(component1)`` is less than numerical value of ``TLV-CODE(component2)``
+ + ``component1`` is less than ``component2`` if numerical value of ``TLV-TYPE(component1)`` is less than numerical value of ``TLV-TYPE(component2)``
.. note::
- Type code ``ImplicitSha256DigestComponent`` is guaranteed to be less than type code of any other valid name component.
+ Type number of ``ImplicitSha256DigestComponent`` is guaranteed to be less than type number of any other valid name component.
- If components have the same type, then
@@ -114,7 +146,7 @@
int
canonicalOrder(Name lhs, Name rhs) {
- int result = memcmp(lhs.value(), rhs.value(), min(lhs.value_size(), rhs.value_size());
+ int result = memcmp(lhs.value(), rhs.value(), min(lhs.value_size(), rhs.value_size()));
if (result == 0) {
result = lhs.value_size() - rhs.value_size();
}
diff --git a/types.rst b/types.rst
index eb944ec..104e836 100644
--- a/types.rst
+++ b/types.rst
@@ -21,6 +21,8 @@
+---------------------------------------------+------------------+-----------------+
| ImplicitSha256DigestComponent | 1 | 0x01 |
+---------------------------------------------+------------------+-----------------+
+| ParametersSha256DigestComponent | 2 | 0x02 |
++---------------------------------------------+------------------+-----------------+
| **Interest packet** |
+---------------------------------------------+------------------+-----------------+
| CanBePrefix | 33 | 0x21 |
@@ -78,7 +80,7 @@
+----------------+-----------------------------------------------------------+
| Number range | Designation |
+================+===========================================================+
-| 0, 2-4, | |
+| 0, 3-4, | |
| 36-79 | Reserved for future assignments (1-byte encoding) |
+----------------+-----------------------------------------------------------+
| 9 | Reserved, formerly `Selectors` |