Signed Interest Format
Change-Id: Ic52835977cadb34479508c7817f842bd3330961b
Refs: #4599
diff --git a/changelog.rst b/changelog.rst
index 1793192..ddc616c 100644
--- a/changelog.rst
+++ b/changelog.rst
@@ -11,14 +11,14 @@
+ Move optional ``MustBeFresh`` element after ``CanBePrefix``
+ Move optional ``ForwardingHint`` element after ``MustBeFresh`` (before ``Nonce``)
+ Add optional ``HopLimit`` element
- + Add optional ``Parameters`` element
+ + Add optional ``ApplicationParameters`` element
+ + Define a new specification for Signed Interest using new optional 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``
- + Add optional ``SignatureNonce`` and ``Timestamp`` elements to ``SignatureInfo``
- **Name**
diff --git a/index.rst b/index.rst
index b6b4df2..e3346ab 100644
--- a/index.rst
+++ b/index.rst
@@ -11,6 +11,7 @@
data
signature
link
+ signed-interest
types
changelog
:maxdepth: 3
diff --git a/interest.rst b/interest.rst
index f93185e..0206e6d 100644
--- a/interest.rst
+++ b/interest.rst
@@ -15,13 +15,17 @@
Nonce?
InterestLifetime?
HopLimit?
- ApplicationParameters?
+ (ApplicationParameters |
+ ApplicationParameters InterestSignatureInfo InterestSignatureValue)?
``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 ``ApplicationParameters`` element.
+If an Interest contains ``InterestSignatureInfo`` and ``InterestSignatureValue``, it is considered a Signed Interest.
+See :doc:`Signed Interest section <signed-interest>` for details.
+
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.
@@ -133,4 +137,4 @@
BYTE*
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:`Interest Parameters Digest Component` section for additional details).
\ No newline at end of file
diff --git a/signature.rst b/signature.rst
index 21c9df1..9a0d713 100644
--- a/signature.rst
+++ b/signature.rst
@@ -1,9 +1,12 @@
+Signature
+=========
+
.. _Signature:
-Signature
----------
+Data Signature
+--------------
-NDN Signature is defined as two consecutive TLV blocks: ``SignatureInfo`` and ``SignatureValue``.
+NDN Data Signature is defined as two consecutive TLV blocks: ``SignatureInfo`` and ``SignatureValue``.
The following general considerations about SignatureInfo and SignatureValue blocks that apply for all signature types:
1. ``SignatureInfo`` is **included** in signature calculation and fully describes the signature, signature algorithm, and any other relevant information to obtain parent certificate(s), such as :ref:`KeyLocator`.
@@ -20,13 +23,36 @@
SignatureInfo ::= SIGNATURE-INFO-TYPE TLV-LENGTH
SignatureType
KeyLocator?
- SignatureNonce?
- Timestamp?
- ... (SignatureType-specific TLVs)
SignatureValue ::= SIGNATURE-VALUE-TYPE TLV-LENGTH
BYTE+
+.. _InterestSignature:
+
+Interest Signature
+------------------
+
+NDN Interest Signature is defined as two consecutive TLV blocks: ``InterestSignatureInfo`` and ``InterestSignatureValue``.
+
+To ensure uniqueness of the signed Interest name and to mitigate potential replay attacks, the ``InterestSignatureInfo`` element can include a ``SignatureNonce`` element, ``SignatureTime`` element, and/or ``SignatureSeqNum`` element.
+
+The cryptographic signature in the ``InterestSignatureValue`` element covers all the ``NameComponent`` elements inside ``Name`` up to but not including ``ParametersSha256DigestComponent`` component, and the complete TLVs starting from ``ApplicationParameters`` up until but not including ``InterestSignatureValue``.
+
+
+::
+
+ InterestSignatureInfo ::= INTEREST-SIGNATURE-INFO-TYPE TLV-LENGTH
+ SignatureType
+ KeyLocator?
+ SignatureNonce?
+ SignatureTime?
+ SignatureSeqNum?
+
+ InterestSignatureValue ::= INTEREST-SIGNATURE-VALUE-TYPE TLV-LENGTH
+ BYTE+
+
+Signature Elements
+------------------
SignatureType
~~~~~~~~~~~~~
@@ -92,29 +118,43 @@
The ``SignatureNonce`` element adds additional assurances that a signature will be unique.
-.. _Timestamp:
+.. _SignatureTime:
-Timestamp
-~~~~~~~~~
+SignatureTime
+~~~~~~~~~~~~~
::
- Timestamp ::= TIMESTAMP-TYPE TLV-LENGTH
+ SignatureTime ::= SIGNATURE-TIME-TYPE TLV-LENGTH
nonNegativeInteger
-The value of the ``Timestamp`` element is the signature's timestamp (in terms of milliseconds since 1970-01-01 00:00:00 UTC) encoded as nonNegativeInteger.
-The timestamp may be used to protect against replay attacks.
+The value of the ``SignatureTime`` element is the signature's timestamp (in terms of milliseconds since 1970-01-01 00:00:00 UTC) encoded as nonNegativeInteger.
+The ``SignatureTime`` element may be used to protect against replay attacks.
+
+.. _SignatureSeqNum:
+
+SignatureSeqNum
+~~~~~~~~~~~~~~~
+
+::
+
+ SignatureSeqNum ::= SIGNATURE-SEQ-NUM-TYPE TLV-LENGTH
+ nonNegativeInteger
+
+
+The ``SignatureSeqNum`` element adds additional assurances that a signature will be unique.
+The ``SignatureSeqNum`` may be used to protect against replay attacks.
+
Different Types of Signature
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Each signature type has different requirements on the format of its ``SignatureInfo`` element.
-In the following sections, these requirements are specified along 3 dimensions:
+Each signature type has different requirements on the format of its ``SignatureInfo`` or ``InterestSignatureInfo`` element.
+In the following sections, these requirements are specified along 2 dimensions:
* The TLV-VALUE of ``SignatureType``
* ``KeyLocator`` is required/forbidden
-* If ``SignatureType``-specific elements are needed, express so using a ``SignatureInfoByType`` rule
.. _DigestSha256:
@@ -134,6 +174,11 @@
SignatureValue ::= SIGNATURE-VALUE-TYPE TLV-LENGTH(=32)
BYTE+(=SHA256{Name, MetaInfo, Content, SignatureInfo})
+ InterestSignatureValue ::= INTEREST-SIGNATURE-VALUE-TYPE TLV-LENGTH(=32)
+ BYTE+(=SHA256{Name(without T, L, and ParametersSha256DigestComponent),
+ ApplicationParameters,
+ InterestSignatureInfo})
+
.. _SignatureSha256WithRsa:
SignatureSha256WithRsa
@@ -150,6 +195,11 @@
SignatureValue ::= SIGNATURE-VALUE-TYPE TLV-LENGTH
BYTE+(=RSA over SHA256{Name, MetaInfo, Content, SignatureInfo})
+ InterestSignatureValue ::= INTEREST-SIGNATURE-VALUE-TYPE TLV-LENGTH(=32)
+ BYTE+(=RSA over SHA256{Name(without T, L, and ParametersSha256DigestComponent),
+ ApplicationParameters,
+ InterestSignatureInfo})
+
.. note::
SignatureValue size varies (typically 128 or 256 bytes) depending on the private key length used during the signing process.
@@ -181,6 +231,11 @@
SignatureValue ::= SIGNATURE-VALUE-TYPE TLV-LENGTH
BYTE+(=ECDSA over SHA256{Name, MetaInfo, Content, SignatureInfo})
+ InterestSignatureValue ::= INTEREST-SIGNATURE-VALUE-TYPE TLV-LENGTH(=32)
+ BYTE+(=ECDSA over SHA256{Name(without T, L, and ParametersSha256DigestComponent),
+ ApplicationParameters,
+ InterestSignatureInfo})
+
.. note::
The SignatureValue size depends on the private key length used during the signing process (about 63 bytes for a 224 bit key).
@@ -214,6 +269,11 @@
SignatureValue ::= SIGNATURE-VALUE-TYPE TLV-LENGTH(=32)
BYTE+(=HMAC{Name, MetaInfo, Content, SignatureInfo})
+ InterestSignatureValue ::= INTEREST-SIGNATURE-VALUE-TYPE TLV-LENGTH(=32)
+ BYTE+(=HMAC{Name(without T, L, and ParametersSha256DigestComponent),
+ ApplicationParameters,
+ InterestSignatureInfo})
+
.. note::
The shared secret key is not included in the signature and must not be included anywhere in the data packet, as it would invalidate security properties of HMAC.
diff --git a/signed-interest.rst b/signed-interest.rst
new file mode 100644
index 0000000..63ad44b
--- /dev/null
+++ b/signed-interest.rst
@@ -0,0 +1,87 @@
+.. _Signed Interest:
+
+Signed Interest
+===============
+
+**Signed Interest** is a mechanism to issue an authenticated Interest.
+
+::
+
+ SignedInterest ::= INTEREST-TYPE TLV-LENGTH
+ Name (must end with ParametersSha256DigestComponent)
+ CanBePrefix?
+ MustBeFresh?
+ ForwardingHint?
+ Nonce?
+ InterestLifetime?
+ HopLimit?
+ ApplicationParameters
+ InterestSignatureInfo
+ InterestSignatureValue
+
+
+See :ref:`Interest Signature section <InterestSignature>` for details of ``InterestSignatureInfo`` and ``InterestSignatureValue``.
+
+Construction of Signed Interest
+-------------------------------
+
+The following procedure describes the signing of an Interest:
+
+1. 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.
+
+3. 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>`.
+
+5. 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``.
+
+Signed Interest processing
+--------------------------
+
+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 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.
+
+2. The ``InterestSignatureInfo`` element is missing or any mandatory sub-element is missing from the ``InterestSignatureInfo`` element.
+
+3. The ``InterestSignatureValue`` element is missing.
+
+4. The signature cannot be cryptographically verified.
+
+5. The key used to create the signature is not trusted for signing the Interest.
+
+6. 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.
+
+ .. 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:
+
+ 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.
+ If it is a repetition, treat the Interest as invalid.
+ Add the newly received ``SignatureNonce`` into the ``SignatureNonce`` list if the signed Interest has been validated according to this and all other rules.
+
+ .. 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:
+
+ 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.
+
+ .. 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.
\ No newline at end of file
diff --git a/types.rst b/types.rst
index 1023cc7..4f6c314 100644
--- a/types.rst
+++ b/types.rst
@@ -39,6 +39,10 @@
+---------------------------------------------+------------------+-----------------+
| ApplicationParameters | 36 (non-critical)| 0x24 |
+---------------------------------------------+------------------+-----------------+
+| InterestSignatureInfo | 44 (non-critical)| 0x2c |
++---------------------------------------------+------------------+-----------------+
+| InterestSignatureValue | 46 (non-critical)| 0x2e |
++---------------------------------------------+------------------+-----------------+
| **Data packet** |
+---------------------------------------------+------------------+-----------------+
| MetaInfo | 20 | 0x14 |
@@ -57,7 +61,7 @@
+---------------------------------------------+------------------+-----------------+
| FinalBlockId | 26 | 0x1a |
+---------------------------------------------+------------------+-----------------+
-| **Data/Signature** |
+| **Signature** |
+---------------------------------------------+------------------+-----------------+
| SignatureType | 27 | 0x1b |
+---------------------------------------------+------------------+-----------------+
@@ -67,7 +71,9 @@
+---------------------------------------------+------------------+-----------------+
| SignatureNonce | 38 (non-critical)| 0x26 |
+---------------------------------------------+------------------+-----------------+
-| Timestamp | 40 (non-critical)| 0x28 |
+| SignatureTime | 40 (non-critical)| 0x28 |
++---------------------------------------------+------------------+-----------------+
+| SignatureSeqNum | 42 (non-critical)| 0x2a |
+---------------------------------------------+------------------+-----------------+
| **Link Object** |
+---------------------------------------------+------------------+-----------------+