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