blob: b854c130be3f374afe265f7e4629e91db9d09270 [file] [log] [blame]
Alexander Afanasyevaa8b3782017-01-19 20:04:31 -08001.. _Signed Interest:
2
Eric Newberry6b2cb792020-06-28 13:05:24 -07003Signed Interest Version 0.2 (DEPRECATED)
4========================================
5
6.. warning::
7 This document describes a deprecated format for signed Interest packets. The current format can
8 be found in the
9 `NDN Packet Specification <https://named-data.net/doc/NDN-packet-spec/current/signed-interest.html>`__.
Yingdi Yu4e99f532014-08-25 19:40:57 -070010
11**Signed Interest** is a mechanism to issue an authenticated interest.
12
13The signature of a signed Interest packet is embedded into the last component of the Interest
14name. The signature covers a continuous block starting from the first name component TLV to the
15penultimate name component TLV:
16
17::
18
19 +-------------+----------+-----------------------------------------------------------------------------------+
20 | Interest | Interest | +------+--------+--------------------------------------------------+ +----------+ |
Davide Pesavento933a5672020-07-03 22:32:43 -040021 | Type (0x05) | length | | Name | Name | +---------+-- --+---------+---------+---------+| | Other | |
Yingdi Yu4e99f532014-08-25 19:40:57 -070022 | | | | Type | Length | |Component| ... |Component|Component|Component|| | TLVs ... | |
23 | | | | | | | TLV 1 | | TLV n-2 | TLV n-1 | TLV n || | in | |
24 | | | | | | +---------+-- --+---------+---------+---------+| | Interest | |
25 | | | +------+--------+--------------------------------------------------+ +----------+ |
26 +-------------+----------+-----------------------------------------------------------------------------------+
27
28 \ /\ /
29 ---------------- ------------------ --- ---
30 \/ \/
31 Signed portion of Interest Signature
32
33More specifically, the SignedInterest is defined to have four additional components:
34
Davide Pesavento933a5672020-07-03 22:32:43 -040035- ``timestamp``
36- ``nonce``
37- ``SignatureInfo``
38- ``SignatureValue``
Yingdi Yu4e99f532014-08-25 19:40:57 -070039
Davide Pesavento933a5672020-07-03 22:32:43 -040040For example, for ``/signed/interest/name`` name, CommandInterest will be defined as::
Yingdi Yu4e99f532014-08-25 19:40:57 -070041
42 /signed/interest/name/<timestamp>/<random-value>/<SignatureInfo>/<SignatureValue>
43
44 \ /
45 ----------------------------- --------------------------
46 \/
47 Additional components of Signed Interest
48
49Signed Interest specific Name components
50----------------------------------------
51
52Timestamp component (n-3 *th*)
53~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
54
55The value of the n-3 *th* component is the interest's timestamp (in terms of millisecond offset
56from UTC 1970-01-01 00:00:00) encoded as
Eric Newberry6b2cb792020-06-28 13:05:24 -070057`NonNegativeInteger <https://named-data.net/doc/NDN-packet-spec/0.2.1/tlv.html#non-negative-integer-encoding>`__.
Yingdi Yu4e99f532014-08-25 19:40:57 -070058The timestamp may be used to protect against replay attack.
59
60Nonce component (n-2 *th*)
61~~~~~~~~~~~~~~~~~~~~~~~~~~
62
63The value of the n-2 *th* component is random value (encoded as
Eric Newberry6b2cb792020-06-28 13:05:24 -070064`NonNegativeInteger <https://named-data.net/doc/NDN-packet-spec/0.2.1/tlv.html#non-negative-integer-encoding>`__)
Yingdi Yu4e99f532014-08-25 19:40:57 -070065that adds additional assurances that the interest will be unique.
66
67SignatureInfo component (n-1 *th*)
68~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
69
70The value of the n-1 *th* component is actually a
Eric Newberry6b2cb792020-06-28 13:05:24 -070071`SignatureInfo <https://named-data.net/doc/NDN-packet-spec/0.2.1/signature.html>`__ TLV.
Yingdi Yu4e99f532014-08-25 19:40:57 -070072
73::
74
75 +---------+---------+-------------------+
76 |Component|Component| +---------------+ |
77 | Type | Length | | SignatureInfo | |
78 | | | | TLV | |
79 | | | +---------------+ |
80 +---------+---------+-------------------+
81
82 | |
83 |<---------The n-1 th Component-------->|
84
85SignatureValue component (n *th*)
86~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
87
88The value of the n *th* component is actually a
Eric Newberry6b2cb792020-06-28 13:05:24 -070089`SignatureValue <https://named-data.net/doc/NDN-packet-spec/0.2.1/signature.html>`__ TLV.
Yingdi Yu4e99f532014-08-25 19:40:57 -070090
91::
92
93 +---------+---------+--------------------+
94 |Component|Component| +----------------+ |
95 | Type | Length | | SignatureValue | |
96 | | | | TLV | |
97 | | | +----------------+ |
98 +---------+---------+--------------------+
99
100 | |
101 |<----------The n th Component---------->|
102
103Signed Interest processing
104--------------------------
105
106On receiving an Interest, the producer, according to the Interest name prefix, should be able
107to tell whether the Interest is required to be signed. If the received Interest is supposed to
108be signed, it will be treated as invalid in the following three cases:
109
110- one of the four components above (Timestamp, Nonce, SignatureValue, and SignatureInfo) is
111 missing or cannot be parsed correctly;
112- the key is not trusted for signing the Interest;
113- the signature cannot be verified with the public key pointed by the
Eric Newberry6b2cb792020-06-28 13:05:24 -0700114 `KeyLocator <https://named-data.net/doc/NDN-packet-spec/0.2.1/signature.html#keylocator>`__ in
Yingdi Yu4e99f532014-08-25 19:40:57 -0700115 SignatureInfo.
116
117Recipients of a signed interest may further check the timestamp and the uniqueness of the
118signed interest (e.g., when the signed interest carries a command). In this case, a signed
119interest may be treated as invalid if :
120
121- a valid signed Interest whose timestamp is **equal or later** than the timestamp of the
122 received one has been received before.
123
124Note that in order to detect this situation, the recipient needs to maintain a *latest
125timestamp* state for each trusted public key (**Since public key cryptography is used, sharing
126private keys is not recommended. If private key sharing is inevitable, it is the key owner's
127responsibility to keep clock synchronized**). For each trusted public key, the state is
128initialized as the timestamp of the first valid Interest signed by the key. Since then, the
129state will be updated every time when the recipient receives a valid signed Interest.
130
131Note that for the first Interest, the state is not available. To handle this special situation,
132the recipient should check the Interest's timestamp against a grace interval (e.g., 120
133seconds) [current\_timestamp - interval/2, current\_timestamp + interval/2]. The first interest
134is invalid if its timestamp is outside of the interval.