New specification of the Signature and other related changes
git-svn-id: svn+ssh://dyadis.cs.arizona.edu/NDN-spec/spec-sphinx@94 c5937c81-b952-4fd9-96ba-3036b240b622
diff --git a/data.rst b/data.rst
index e6d6591..d67d575 100644
--- a/data.rst
+++ b/data.rst
@@ -16,14 +16,16 @@
Name
~~~~
-See :ref:`Name section<name>` for details.
+See :ref:`Name section <Name>` for details.
+
+.. _MetaInfo:
MetaInfo
~~~~~~~~
.. [#f1] If both ``ContentType`` and ``FreshnessPeriod`` are optional, one may consider ``Metainfo`` itself should be optional. But would have all 4 parts of Data packet help simplify implementation? We leave this question to people who are more familiar with high speed implementations.
-.. code-block:: none
+::
MetaInfo ::= META-INFO-TYPE TLV-LENGTH
ContentType?
@@ -33,7 +35,7 @@
- PublisherPublicKeyDigest is supposed to be used in selecting data packets signed by a particular key.
- We replace PublisherPublicKeyDigest with KeyLocator, which is part of the Signature block (see :ref:`Signature Section<signature>`), due to the following consideration.
+ We replace PublisherPublicKeyDigest with KeyLocator, which is part of the Signature block (see :ref:`Signature Section <Signature>`), due to the following consideration.
First, it requires data consumer to acquire a *valid* public key, as opposed to the key locator, before sending Interest out.
Second, if a router is to verify the content objects, it must have other means to locate the keys first.
Further, it may require publishers to maintain their public keys and certificates by their public key digests instead of names.
@@ -47,7 +49,7 @@
ContentType
+++++++++++
-.. code-block:: none
+::
ContentType ::= CONTENT-TYPE-TYPE TLV-LENGTH nonNegativeInteger
@@ -62,7 +64,7 @@
FreshnessPeriod
+++++++++++++++
-.. code-block:: none
+::
FreshnessPeriod ::= FRESHNESS-PERIOD-TLV TYPE-TLV nonNegativeInteger
@@ -75,11 +77,12 @@
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).
If an exact duplicate of a stale Data arrives, the effect is the same as if the stale Data had not been present. In particular, the Data in the store is no longer stale. As a practical matter, a stale Data should be ranked high on the list of things to discard from the store when a storage quota has been reached.
+.. _Content:
Content
~~~~~~~
-.. code-block:: none
+::
Content ::= CONTENT-TYPE TLV-LENGTH BYTE*
diff --git a/index.rst b/index.rst
index bf56411..62a99f2 100644
--- a/index.rst
+++ b/index.rst
@@ -11,7 +11,7 @@
interest
data
signature
- :maxdepth: 2
+ :maxdepth: 3
.. Indices and tables
diff --git a/interest.rst b/interest.rst
index 87faf10..7b5a263 100644
--- a/interest.rst
+++ b/interest.rst
@@ -1,9 +1,11 @@
-.. _interest:
+.. _Interest:
Interest Packet
---------------
-NDN Interest packet is TLV defined as follows::
+NDN Interest packet is TLV defined as follows:
+
+::
Interest ::= INTEREST-TYPE TLV-LENGTH
Name
@@ -12,16 +14,6 @@
Scope?
InterestLifetime?
-Selectors::
-
- Selectors ::= SELECTORS-TYPE TLV-LENGTH
- MinSuffixComponents?
- MaxSuffixComponents?
- PublisherPublicKeyLocator?
- Exclude?
- ChildSelector?
- MustBeFresh?
-
``Name`` and ``Nonce`` are the only two 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.
@@ -34,24 +26,43 @@
Name
~~~~
-The Name element in an Interest is synonymous with the term *prefix*. See :ref:`Name section<name>` for details.
-
+The Name element in an Interest is synonymous with the term *prefix*.
+See :ref:`Name section <Name>` for details.
+
+.. _Nonce:
+
Nonce
~~~~~
-Nonce defined as follows::
+Nonce defined as follows:
- Nonce ::= NONCE-TYPE TLV-LENGTH BYTE+
+::
-The Nonce carries a randomly-genenerated byte-string. The combination of Name and Nonce should uniquely identify an Interest packet. This is used to detect looping Interests\footnote{We plan to select a recommended length for Nonce in next revision.}.
+ Nonce ::= NONCE-TYPE TLV-LENGTH(=4) BYTE{4}
+
+The Nonce carries a randomly-genenerated 4-octet long byte-string.
+The combination of Name and Nonce should uniquely identify an Interest packet.
+This is used to detect looping Interests.
+
+.. _Selectors:
Selectors
~~~~~~~~~
-
+
+::
+
+ Selectors ::= SELECTORS-TYPE TLV-LENGTH
+ MinSuffixComponents?
+ MaxSuffixComponents?
+ PublisherPublicKeyLocator?
+ Exclude?
+ ChildSelector?
+ MustBeFresh?
+
MinSuffixComponents, MaxSuffixComponents
++++++++++++++++++++++++++++++++++++++++
-.. code-block:: none
+::
MinSuffixComponents ::= MIN-SUFFIX-COMPONENTS-TYPE TLV-LENGTH
nonNegativeInteger
@@ -67,7 +78,7 @@
PublisherPublicKeyLocator
+++++++++++++++++++++++++
-.. code-block:: none
+::
PublisherPublicKeyLocator ::= PUBLISHER-PUBLIC-KEY-TYPE TLV-LENGTH Name
@@ -77,7 +88,7 @@
Exclude
+++++++
-.. code-block:: none
+::
Exclude ::= EXCLUDE-TYPE TLV-LENGTH Any? (NameComponent (Any)?)+
Any ::= ANY-TYPE TLV-LENGTH(=0)
@@ -98,13 +109,13 @@
- 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.
+Exclude filter MUST not consist of a single ``Any`` component or one NameComponent with leading and trailing ``Any`` components.
ChildSelector
+++++++++++++
-.. code-block:: none
+::
ChildSelector ::= CHILD-SELECTOR-TYPE TLV-LENGTH
nonNegativeInteger
@@ -122,7 +133,7 @@
MustBeFresh
+++++++++++
-.. code-block:: none
+::
MustBeFresh ::= MUST-BE-FRESH-TYPE TLV-LENGTH(=0)
@@ -135,7 +146,7 @@
Scope
+++++
-.. code-block:: none
+::
Scope ::= SCOPE-TYPE TLV-LENGTH nonNegativeInteger
@@ -149,7 +160,7 @@
InterestLifetime
++++++++++++++++
-.. code-block:: none
+::
InterestLifetime ::= INTEREST-LIFETIME-TYPE TLV-LENGTH nonNegativeInteger
diff --git a/name.rst b/name.rst
index db2599b..5658653 100644
--- a/name.rst
+++ b/name.rst
@@ -1,4 +1,4 @@
-.. _name:
+.. _Name:
Name
----
@@ -11,7 +11,9 @@
We use a 2-level nested TLV to represent a name.
The Type in the outer TLV indicates this is a Name.
All inner TLVs have the same Type indicating that they each contain a name component.
-There is no restriction on the Value field in a name component and it may not contain any bytes::
+There is no restriction on the Value field in a name component and it may not contain any bytes:
+
+::
Name ::= NAME-TYPE TLV-LENGTH NameComponent*
NameComponent ::= NAME-COMPONENT-TYPE TLV-LENGTH BYTE+
diff --git a/signature.rst b/signature.rst
index bc411cb..c91c47d 100644
--- a/signature.rst
+++ b/signature.rst
@@ -1,73 +1,157 @@
-.. _signature:
+.. _Signature:
Signature
---------
-.. code-block:: none
+NDN 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:
- Signature ::= SIGNATURE-TYPE TLV-LENGTH
- ( DigestSha256 |
- SignatureSha256WithRsa |
- SignatureSha256WithRsaAndMerkle |
- ...
- )
+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`
-Signature TLV is a general container of signature, which contains an inner signature TLV.
-The type field of the inner signature TLV indicates the signing method of the signature, for example,
+2. ``SignatureValue`` is **excluded** from signature calculation and represent actual bits of the signature and any other supporting signature material.
-- ``DigestSha256`` indicates that the integrity of Data is protected by a SHA-256 digest in ``DigestSha256``;
+::
-- ``SignatureSha256WithRsa`` indicates that the integrity and provenacne of Data is protected by a RSA signature over a SHA-256 digest;
+ Signature ::= SignatureInfo
+ SignatureBits
-- ``SignatureSha256WithRsaAndMerkle`` indicates that the integrity and provenance of Data is protected by a RSA signature over SHA-256-Merkle-Hash digest.
+ SignatureInfo ::= SIGNATURE-INFO-TYPE TLV-LENGTH
+ SignatureType
+ ... (SignatureType-specific TLVs)
-If some other types of signatures are required, a new inner signature TLV will be defined.
+ SignatureValue ::= SIGNATURE-BITS-TYPE TLV-LENGTH
+ ... (SignatureType-specific TLVs and
+ BYTE+
+SignatureType
+~~~~~~~~~~~~~
-For each inner signature TLV, the last embedded TLV must be a SignatureBits TLV, for example:
+::
-.. code-block:: none
-
- DigestSha256 ::= DIGEST-SHA256-TYPE TLV-LENGTH(=32) SignatureBits(=BYTE[32])
+ SignatureType ::= SIGNATURE-TYPE-TYPE TLV-LENGTH
+ nonNegativeInteger
- SignatureSha256WithRsa ::= SIGNATURE-SHA256-WITH-RSA-TYPE TLV-LENGTH
- KeyLocator
- SignatureBits(=BYTE[32])
-
- SignatureSha256WithRsaAndMerkle ::= SIGNATURE-SHA256-WITH-RSA-AND-MERKLE-TYPE
- TLV-LENGTH
- KeyLocator
- Witness
- SignatureBits(=BYTE[32])
-Which fields are covered by the ``SignatureBits`` TLV is up to the signing mechanism.
-A valid signing mechanism, however, must cover following TLVs: Name, MetaInfo (if present), and Content.
-Some signing mechansims may also require the SignatureBits TLV to cover more TLVs.
-For example, ``SignatureSha256WithRsa`` requires the KeyLocator TLV to be signed,
-and ``SignatureSha256WithRsaAndMerkle`` requires both KeyLocator TLV and Witness TLV to be signed.
+This specification defines the following SignatureType values:
-For inner signature TLVs that use public key cryptography, the first embedded TLV must be a KeyLocator TLV, e.g., as shown in ``SignatureSha256WithRsa`` and ``SignatureSha256WithRsaAndMerkle`` above.
++-------+----------------------------------------+-------------------------------------------------+
+| Value | Reference | Description |
++=======+========================================+=================================================+
+| 0 | :ref:`DigestSha256` | Integrity protection using SHA-256 digest |
++-------+----------------------------------------+-------------------------------------------------+
+| 1 | :ref:`SignatureSha256WithRsa` | Integrity and provenance protection using |
+| | | RSA signature over a SHA-256 digest |
++-------+----------------------------------------+-------------------------------------------------+
+| 2-200 | | reserved for future assignments |
++-------+----------------------------------------+-------------------------------------------------+
+| >200 | | unassigned |
++-------+----------------------------------------+-------------------------------------------------+
-.. code-block:: none
+.. +-------+----------------------------------------+-------------------------------------------------+
+.. | 2 | :ref:`SignatureSha256WithRsaAndMerkle` | Integrity and provenance protection using |
+.. | | | RSA signature over SHA-256-Merkle-Hash digest. |
+.. | | | |
+.. | | | This signature type defines an aggregated |
+.. | | | signing algorithm that reduces cost of signing |
+.. | | | of a large segmented content (e.g., video file).|
- KeyLocator ::= KEY-LOCATOR-TYPE TLV-LENGTH CertificateName |
- (other types of KeyLocators)
- CertificateName ::= CERTIFICATE-NAME-TYPE TLV-LENGTH Name
+.. _DigestSha256:
-A KeyLocator tells where to find the public key to verify this Data packet.
-For example, one can specify the name of the certificate of the public key (by CertificateName).
-Name conventions can be used to find the name of the key for a piece of content from the name of the Data packet.
+DigestSha256
+^^^^^^^^^^^^
-All the other embedded TLVs in an inner signature TLV (such as Witness) are the signature-specific meta information and may vary from a signature type to another.
+``DigestSha256`` provides no provenance of a Data packet or any kind of guarantee that packet is from the original source.
+This signature type is indended only for debug purposes and limited circumstances when it is necessary to protect only against unexpected modification during the transmition.
+
+``DigestSha256`` is defined as a SHA256 hash of the :ref:`Name`, :ref:`MetaInfo`, :ref:`Content`, and :ref:`SignatureInfo <Signature>` TLVs:
+
+::
+
+ SignatureInfo ::= SIGNATURE-INFO-TYPE TLV-LENGTH(=3)
+ SIGNATURE-TYPE-TYPE TLV-LENGTH(=1) 0
+
+ SignatureValue ::= BYTE{32}(=SHA256{Name, MetaInfo, Content, SignatureInfo})
+
+
+.. _SignatureSha256WithRsa:
+
+SignatureSha256WithRsa
+^^^^^^^^^^^^^^^^^^^^^^
+
+``SignatureSha256WithRsa`` is the basic signature algorithm that MUST be supported by any NDN-compliant software.
+As suggested by the name, it defines an RSA public key signature that is calculated over SHA256 hash of the :ref:`Name`, :ref:`MetaInfo`, :ref:`Content`, and :ref:`SignatureInfo <Signature>` TLVs.
+
+
+::
+
+ SignatureInfo ::= SIGNATURE-INFO-TYPE TLV-LENGTH
+ SIGNATURE-TYPE-TYPE TLV-LENGTH(=1) 1
+ KeyLocator
+
+ SignatureValue ::= BYTE{32}(=RSA over SHA256{Name, MetaInfo, Content, SignatureInfo})
+
+
+This type of signature ensures strict provenance of a Data packet, provided that the signature verifies and signature issuer is authorized to sign the Data packet.
+The signature issuer is idenfified using :ref:`KeyLocator` block in :ref:`SignatureInfo <Signature>` block of ``SignatureSha256WithRsa``.
+See :ref:`KeyLocator section <KeyLocator>` for more detail.
+
+.. note::
+
+ It is application's responsibility to define rules (trust model) of when a specific issuer (KeyLocator) is authorized to sign a specific Data packet.
+ While trust model is outside the scope of the current specification, generally, trust model needs to specify authorization rules between KeyName and Data packet Name, as well as clearly define trust anchor(s).
+ For example, an application can elect to use hierarchical trust model :cite:`testbed-key-management` to ensure Data integrity and provenance.
+
+ .. bibliography:: ndnspec-refs.bib
+
+.. .. _SignatureSha256WithRsaAndMerkle:
+
+.. SignatureSha256WithRsaAndMerkle
+.. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. ::
+
+.. SignatureInfo ::= SIGNATURE-INFO-TYPE TLV-LENGTH
+.. SIGNATURE-TYPE-TYPE TLV-LENGTH(=1) 2
+.. KeyLocator
+
+.. SignatureValue ::= BYTE{32}(=RSA over SHA256{Name, MetaInfo, Content, SignatureInfo})
+.. Witness
+
+.. Witness ::= WITNESS-TYPE TLV-LENGTH BYTE+
+
+.. _KeyLocator:
+
+KeyLocator
+~~~~~~~~~~
+
+A ``KeyLocator`` specifies a name that points to another Data packet containing certificate or public key, or can be used by the specific trust model in another way to verify the the content.
+
+::
+
+ KeyLocator ::= KEY-LOCATOR-TYPE TLV-LENGTH Name
+
+
+.. note::
+
+ KeyLocator has meaning only for specific trust model and the current specification does not imply or suggest use of any specific trust model.
+ Generally, KeyLocator should point to another Data packet which is interpreted by the trust model, but trust model can allow alternative interpretations of the KeyLocator.
+
+ For example, one can define a trust model that does not interpret KeyLocator at all (KeyLocator MUST be present, but TLV-LENGTH could be 0) and uses naming conventions to infer proper public key or public key certificate for the name of the Data packet itself.
+ Another possibility for the trust model is to define a naming convention for the KeyLocator, where Name ``/keyid/<sha256>`` identifies RSA public key using SHA256 digest, assuming that the trust model has some other means to obtain the public key.
+
Changes from CCNx
~~~~~~~~~~~~~~~~~
- ``Signature`` is moved to the end of Data packet.
-- ``KeyLocator`` is moved to be an inner signature block, making the inner signature block self-contained and self-sufficient.
+- ``KeyLocator`` is moved to be a part of the ``SignatureInfo`` block, 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.
-- Signature type (or signing method information) is expressed by the type of inner signature TLV, rather than OID.
+- ``KeyLocator`` is expressed as a trust model-interpreted name, removing nested blocks and alternative packet-format specified representations (``KeyName``, ``Key``, and ``Certificate``)
+
+- Signature type (or signing method information) is expressed as an assigned integer value (with no assumed default), rather than OID.
- Added support for cheaper signatures
+- The current specification does not define Merkle Hash Tree Aggregated Signatures, but it is expected that such (or similar) signatures will be defined in future version of this specification.