-
Notifications
You must be signed in to change notification settings - Fork 4
/
signature.rst
295 lines (195 loc) · 14.6 KB
/
signature.rst
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
Signature
=========
.. _DataSignature:
Data Signature
--------------
The NDN Data packet signature is defined as two consecutive TLV elements: ``SignatureInfo`` and ``SignatureValue``.
::
DataSignature = SignatureInfo SignatureValue
SignatureInfo = SIGNATURE-INFO-TYPE TLV-LENGTH
SignatureType
[KeyLocator]
SignatureValue = SIGNATURE-VALUE-TYPE TLV-LENGTH *OCTET
The ``SignatureInfo`` element fully describes the digital signature algorithm utilized and any other relevant information to locate its parent certificate(s), such as :ref:`KeyLocator`.
The ``SignatureValue`` element holds the actual bits of the signature. The exact encoding of the TLV-VALUE of this element depends on the specific signature type. See :ref:`SignatureTypes` for details.
The cryptographic signature contained in ``SignatureValue`` covers all TLV elements inside ``Data``, starting from ``Name`` and up to, but not including, ``SignatureValue``.
These TLV elements are hereby referred to as the "*signed portion*" of a Data packet.
.. _InterestSignature:
Interest Signature
------------------
The NDN Interest packet signature is defined as two consecutive TLV elements: ``InterestSignatureInfo`` and ``InterestSignatureValue``.
::
InterestSignature = InterestSignatureInfo InterestSignatureValue
InterestSignatureInfo = INTEREST-SIGNATURE-INFO-TYPE TLV-LENGTH
SignatureType
[KeyLocator]
[SignatureNonce]
[SignatureTime]
[SignatureSeqNum]
InterestSignatureValue = INTEREST-SIGNATURE-VALUE-TYPE TLV-LENGTH *OCTET
The ``InterestSignatureInfo`` element fully describes the digital signature algorithm utilized and any other relevant information to locate its parent certificate(s), such as :ref:`KeyLocator`.
To ensure the uniqueness of a signed Interest and to mitigate potential replay attacks, the ``InterestSignatureInfo`` element SHOULD include at least one of the following elements (described below): ``SignatureNonce``, ``SignatureTime``, ``SignatureSeqNum``.
The ``InterestSignatureValue`` element holds the actual bits of the signature. The exact encoding of the TLV-VALUE of this element depends on the specific signature type. See :ref:`SignatureTypes` for details.
The cryptographic signature contained in ``InterestSignatureValue`` covers all the ``NameComponent`` elements in the Interest's ``Name`` up to, but not including, ``ParametersSha256DigestComponent``, and the complete TLV elements starting from ``ApplicationParameters`` up to, but not including, ``InterestSignatureValue``.
These TLV elements are hereby referred to as the "*signed portion*" of an Interest packet.
Signature Elements
------------------
SignatureType
^^^^^^^^^^^^^
::
SignatureType = SIGNATURE-TYPE-TYPE TLV-LENGTH NonNegativeInteger
This specification defines the following values for ``SignatureType``:
+---------+----------------------------------------+-------------------------------------------------+
| Value | Reference | Description |
+=========+========================================+=================================================+
| 0 | :ref:`DigestSha256` | Integrity protection using a SHA-256 digest |
+---------+----------------------------------------+-------------------------------------------------+
| 1 | :ref:`SignatureSha256WithRsa` | Integrity and provenance protection using |
| | | an RSA signature over a SHA-256 digest |
+---------+----------------------------------------+-------------------------------------------------+
| 3 | :ref:`SignatureSha256WithEcdsa` | Integrity and provenance protection using |
| | | an ECDSA signature over a SHA-256 digest |
+---------+----------------------------------------+-------------------------------------------------+
| 4 | :ref:`SignatureHmacWithSha256` | Integrity and provenance protection using |
| | | a SHA-256 hash-based message authentication code|
+---------+----------------------------------------+-------------------------------------------------+
| 5 | :ref:`SignatureEd25519` | Integrity and provenance protection using |
| | | an Ed25519 signature |
+---------+----------------------------------------+-------------------------------------------------+
| 2,6-200 | | Reserved for future assignments |
+---------+----------------------------------------+-------------------------------------------------+
| >200 | | Unassigned |
+---------+----------------------------------------+-------------------------------------------------+
.. _KeyLocator:
KeyLocator
^^^^^^^^^^
A ``KeyLocator`` specifies either a ``Name`` that points to another Data packet containing a certificate or public key, or a ``KeyDigest`` that identifies the public key within a specific trust model (definition of the trust model is outside the scope of this specification).
Note that although ``KeyLocator`` is defined as an optional field in ``SignatureInfo`` and ``InterestSignatureInfo``, specific signature types may require its presence or absence.
::
KeyLocator = KEY-LOCATOR-TYPE TLV-LENGTH (Name / KeyDigest)
KeyDigest = KEY-DIGEST-TYPE TLV-LENGTH *OCTET
See :ref:`Name` for the definition of the ``Name`` element.
The specific definition of the proper usage of the ``Name`` and ``KeyDigest`` options in the ``KeyLocator`` field is outside the scope of this specification.
Generally, ``Name`` names the Data packet containing the corresponding :ref:`certificate <Certificate>`.
However, it is up to the specific trust model to define whether this name is the full name of the Data packet or a prefix that can match multiple Data packets.
For example, the `hierarchical trust model`_ uses the latter approach, requiring clients to fetch the latest version of the Data packet pointed to by ``KeyLocator`` (the latest version of the public key certificate) in order to ensure that the public key was not yet revoked.
SignatureNonce
^^^^^^^^^^^^^^
::
SignatureNonce = SIGNATURE-NONCE-TYPE TLV-LENGTH 1*OCTET
The ``SignatureNonce`` element adds additional assurances that a signature will be unique.
The recommended minimum length for a ``SignatureNonce`` element is 8 octets.
SignatureTime
^^^^^^^^^^^^^
::
SignatureTime = SIGNATURE-TIME-TYPE TLV-LENGTH NonNegativeInteger
The value of the ``SignatureTime`` element is the timestamp of the signature, represented as the number of milliseconds since 1970-01-01T00:00:00Z (Unix epoch).
This element can be used to indicate that the packet was signed at a particular point in time.
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.
.. _SignatureTypes:
Different Types of Signatures
-----------------------------
Each signature type has different requirements on the format of its ``SignatureInfo`` and ``InterestSignatureInfo`` elements.
In the following sections, these requirements are specified along 2 dimensions:
* The TLV-VALUE of ``SignatureType``
* Whether ``KeyLocator`` is required/forbidden
.. _DigestSha256:
DigestSha256
^^^^^^^^^^^^
``DigestSha256`` provides no information about the provenance of a packet or any guarantee that the packet is from the original source.
This signature type is intended only for debug purposes and in the limited circumstances when it is necessary to protect only against unexpected modification during transmission.
``DigestSha256`` is defined as the SHA-256 hash of the "signed portion" of an Interest or Data packet:
* The TLV-VALUE of ``SignatureType`` is 0
* ``KeyLocator`` is forbidden; if present, it must be ignored
::
SignatureValue = SIGNATURE-VALUE-TYPE
TLV-LENGTH ; == 32
32OCTET ; == SHA-256{Data signed portion}
InterestSignatureValue = INTEREST-SIGNATURE-VALUE-TYPE
TLV-LENGTH ; == 32
32OCTET ; == SHA-256{Interest signed portion}
.. _SignatureSha256WithRsa:
SignatureSha256WithRsa
^^^^^^^^^^^^^^^^^^^^^^
``SignatureSha256WithRsa`` defines an RSA public key signature that is calculated over the SHA-256 hash of the "signed portion" of an Interest or Data packet.
It uses the RSASSA-PKCS1-v1_5 signature scheme, as defined in :rfc:`RFC 8017, Section 8.2 <8017#section-8.2>`.
* The TLV-VALUE of ``SignatureType`` is 1
* ``KeyLocator`` is required
::
SignatureValue = SIGNATURE-VALUE-TYPE
TLV-LENGTH
1*OCTET ; == RSA over SHA-256{Data signed portion}
InterestSignatureValue = INTEREST-SIGNATURE-VALUE-TYPE
TLV-LENGTH
1*OCTET ; == RSA over SHA-256{Interest signed portion}
.. note::
The TLV-LENGTH of these elements varies depending on the length of the private key used for signing (e.g., 256 bytes for a 2048-bit key).
This type of signature, if verified, provides very strong assurances that a packet was created by the claimed producer (authentication/provenance) and was not tampered with while in transit (integrity).
The ``KeyDigest`` option in :ref:`KeyLocator` is defined as the SHA-256 digest over the DER encoding of the ``SubjectPublicKeyInfo`` for an RSA key as defined by :rfc:`3279`.
.. note::
It is the application's responsibility to define rules (a trust model) concerning when a specific issuer (``KeyLocator``) is authorized to sign a specific packet.
While trust models are outside the scope of this specification, generally, trust models need to specify authorization rules between key names and Data packet names, as well as clearly define trust anchor(s).
For example, an application can elect to use a `hierarchical trust model`_ to ensure Data integrity and provenance.
.. _SignatureSha256WithEcdsa:
SignatureSha256WithEcdsa
^^^^^^^^^^^^^^^^^^^^^^^^
``SignatureSha256WithEcdsa`` defines an ECDSA public key signature that is calculated over the SHA-256 hash of the "signed portion" of an Interest or Data packet.
This signature algorithm is defined in :rfc:`RFC 5753, Section 2.1 <5753#section-2.1>`.
All NDN implementations MUST support this signature type with the NIST P-256 curve.
* The TLV-VALUE of ``SignatureType`` is 3
* ``KeyLocator`` is required
::
SignatureValue = SIGNATURE-VALUE-TYPE
TLV-LENGTH
1*OCTET ; == ECDSA over SHA-256{Data signed portion}
InterestSignatureValue = INTEREST-SIGNATURE-VALUE-TYPE
TLV-LENGTH
1*OCTET ; == ECDSA over SHA-256{Interest signed portion}
.. note::
The TLV-LENGTH of these elements depends on the specific elliptic curve used for signing (e.g., up to 72 bytes for the NIST P-256 curve).
This type of signature, if verified, provides very strong assurances that a packet was created by the claimed producer (authentication/provenance) and was not tampered with while in transit (integrity).
The ``KeyDigest`` option in :ref:`KeyLocator` is defined as the SHA-256 digest of the DER encoding of the ``SubjectPublicKeyInfo`` for an EC key as defined by :rfc:`5480`.
The value of ``SignatureValue`` of ``SignatureSha256WithEcdsa`` is a DER-encoded ``Ecdsa-Sig-Value`` structure as defined in :rfc:`RFC 3279, Section 2.2.3 <3279#section-2.2.3>`.
.. _SignatureHmacWithSha256:
SignatureHmacWithSha256
^^^^^^^^^^^^^^^^^^^^^^^
``SignatureHmacWithSha256`` defines a hash-based message authentication code (HMAC) that is calculated over the "signed portion" of an Interest or Data packet, using SHA-256 as the hash function, salted with a shared secret key.
This signature algorithm is defined in :rfc:`RFC 2104, Section 2 <2104#section-2>`.
.. warning::
As stated in :rfc:`RFC 2104, Section 3 <2104#section-3>`, shared keys shorter than the SHA-256 output length (32 bytes) are strongly discouraged.
* The TLV-VALUE of ``SignatureType`` is 4
* ``KeyLocator`` is required
::
SignatureValue = SIGNATURE-VALUE-TYPE
TLV-LENGTH ; == 32
32OCTET ; == HMAC-SHA-256{Data signed portion}
InterestSignatureValue = INTEREST-SIGNATURE-VALUE-TYPE
TLV-LENGTH ; == 32
32OCTET ; == HMAC-SHA-256{Interest signed portion}
Provided that the signature verifies, this type of signature ensures the authenticity of the packet, namely, that it was signed by a party possessing the shared key, and that it was not altered in transit (integrity).
The shared key used to generate the HMAC signature can be identified by the :ref:`KeyLocator` element, e.g., by using the ``Name`` according to the application's naming conventions.
It is the application's responsibility to associate the shared key with the identities of the parties who hold the shared key.
.. danger::
The shared secret key is not included in the signature and must not be included anywhere in the packet, as this would invalidate the security properties of HMAC.
.. _SignatureEd25519:
SignatureEd25519
^^^^^^^^^^^^^^^^
``SignatureEd25519`` defines an Ed25519 public key signature that is calculated over the "signed portion" of an Interest or Data packet.
This signature algorithm is defined in :rfc:`RFC 8032, Section 5.1 <8032#section-5.1>`.
* The TLV-VALUE of ``SignatureType`` is 5
* ``KeyLocator`` is required
::
SignatureValue = SIGNATURE-VALUE-TYPE
TLV-LENGTH
64OCTET ; == Ed25519{Data signed portion}
InterestSignatureValue = INTEREST-SIGNATURE-VALUE-TYPE
TLV-LENGTH
64OCTET ; == Ed25519{Interest signed portion}
This type of signature, if verified, provides very strong assurances that a packet was created by the claimed producer (authentication/provenance) and was not tampered with while in transit (integrity).
The ``KeyDigest`` option in :ref:`KeyLocator` is defined as the SHA-256 digest over the DER encoding of the ``SubjectPublicKeyInfo`` for an Ed25519 key as defined by :rfc:`RFC 8410, Section 4 <8410#section-4>`.
.. _hierarchical trust model: https://named-data.net/publications/techreports/trpublishkey-rev2/