Signed Interest Format
Change-Id: Ic52835977cadb34479508c7817f842bd3330961b
Refs: #4599
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.