blob: 9df00200203a984558872d677cb9d3365edda2ba [file] [log] [blame]
Alexander Afanasyev7c6aeb02014-04-10 19:59:19 -07001Validator Configuration File Format
2===================================
3
Yingdi Yu4e99f532014-08-25 19:40:57 -07004.. contents::
Alexander Afanasyev7c6aeb02014-04-10 19:59:19 -07005
Yingdi Yu4e99f532014-08-25 19:40:57 -07006You can set up a ``Validator`` via a configuration file. Next, we will show you how to
7write a configuration file.
8
9The configuration file consists of **rules** and **trust-anchors** that will be used in
10validation. **Rules** tell the validator how to validate a packet, while **trust-anchors**
11tell the validator which certificates are valid immediately. Here is an example of
12configuration file containing two rules.
Alexander Afanasyev7c6aeb02014-04-10 19:59:19 -070013
14::
15
16 rule
17 {
18 id "Simple Rule"
19 for data
20 filter
21 {
22 type name
23 name /localhost/example
24 relation is-prefix-of
25 }
26 checker
27 {
28 type customized
29 sig-type rsa-sha256
30 key-locator
31 {
32 type name
33 name /ndn/edu/ucla/KEY/yingdi/ksk-1234/ID-CERT
34 relation equal
35 }
36 }
37 }
38 rule
39 {
40 id "Testbed Validation Rule"
41 for data
42 checker
43 {
44 type hierarchical
45 sig-type rsa-sha256
46 }
47 }
48 trust-anchor
49 {
50 type file
51 file-name "testbed-trust-anchor.cert"
52 }
53
Yingdi Yu4e99f532014-08-25 19:40:57 -070054.. note::
55 **ATTENTION: The order of rules MATTERS!**
Alexander Afanasyev7c6aeb02014-04-10 19:59:19 -070056
57A rule can be broken into two parts:
58
59- The first part is to qualify packets to which the rule can be
60 applied;
61- The second part is to check whether further validation process is
62 necessary.
63
Yingdi Yu4e99f532014-08-25 19:40:57 -070064When receiving a packet, the validator will apply rules in the configuration file
65one-by-one against the packet, until finding a rule that the packet qualifies for. And the
66second part of the matched rule will be used to check the validity of the packet. If the
67packet cannot qualify for any rules, it is treated as an invalid packet. Once a packet has
68been matched by a rule, the rest rules will not be applied against the packet. Therefore,
69you should always put the most specific rule to the top, otherwise it will become useless.
Alexander Afanasyev7c6aeb02014-04-10 19:59:19 -070070
Yingdi Yu4e99f532014-08-25 19:40:57 -070071In the example configuration, the first rule indicates that all the data packets under the
72name prefix ``/localhost/example`` must be signed by a key whose certificate name is
73``/ndn/edu/ucla/KEY/yingdi/ksk-1234/ID-CERT``. If a packet does not have a name under prefix
74``/localhost/example``, validator will skip the first rule and apply the second rule. The
75second rule indicates that any data packets must be validated along a hierarchy. And a
76certificate stored in a file "testbed-trust-anchor.cert" is valid.
Alexander Afanasyev7c6aeb02014-04-10 19:59:19 -070077
78Rules in general
79----------------
80
Yingdi Yu4e99f532014-08-25 19:40:57 -070081A rule has four types of properties: **id**, **for**, **filter**, and **checker**.
Alexander Afanasyev7c6aeb02014-04-10 19:59:19 -070082
Yingdi Yu4e99f532014-08-25 19:40:57 -070083The property **id** uniquely identifies the rule in the configuration file. As long as
84being unique, any name can be given to a rule, e.g., "Simple Rule", "Testbed Validation
85Rule". A rule must have one and only one **id** property.
Alexander Afanasyev7c6aeb02014-04-10 19:59:19 -070086
Yingdi Yu4e99f532014-08-25 19:40:57 -070087A rule is either used to validate an interest packet or a data packet. This information
88is specified in the property **for**. Only two value can be specified: **data** and
89**interest**. A rule must have one and only one **for** property.
Alexander Afanasyev7c6aeb02014-04-10 19:59:19 -070090
Yingdi Yu4e99f532014-08-25 19:40:57 -070091The property **filter** further constrains the packets that can be checked by the
92rule. Filter property is not required in a rule, in this case, the rule will capture all
93the packets passed to it. A rule may contain more than one filters, in this case, a packet
94can be checked by a rule only if the packet satisfies all the filters.
Alexander Afanasyev7c6aeb02014-04-10 19:59:19 -070095
Yingdi Yu4e99f532014-08-25 19:40:57 -070096.. note::
97 **ATTENTION: A packet that satisfies all the filters may not be valid**.
Alexander Afanasyev7c6aeb02014-04-10 19:59:19 -070098
Yingdi Yu4e99f532014-08-25 19:40:57 -070099The property **checker** defines the conditions that a matched packet must fulfill to be
Zhiyi Zhang044bb7e2016-06-10 00:02:37 -0700100treated as a valid packet. A rule must have at least one **checker** property. A packet is
101treated as valid if it can pass at least one of the checkers and as invalid when it cannot
102pass any checkers.
Alexander Afanasyev7c6aeb02014-04-10 19:59:19 -0700103
Yingdi Yu4e99f532014-08-25 19:40:57 -0700104**filter** and **checker** have their own properties. Next, we will introduce them
105separately.
Alexander Afanasyev7c6aeb02014-04-10 19:59:19 -0700106
107Filter Property
108---------------
109
Yingdi Yu4e99f532014-08-25 19:40:57 -0700110Filter has its own **type** property. Although a rule may contain more than one filters,
111there is at most one filter of each type. So far, only one type of filter is defined:
112**name**. In other word, only one filter can be specified in a rule for now.
Alexander Afanasyev7c6aeb02014-04-10 19:59:19 -0700113
114Name Filter
115~~~~~~~~~~~
116
Yingdi Yu4e99f532014-08-25 19:40:57 -0700117There are two ways to express the conditions on name. The first way is to specify a
118relationship between the packet name and a particular name. In this case, two more
119properties are required: **name** and **relation**. A packet can fulfill the condition if
120the **name** has a **relation\* to the packet name. Three types of **\ relation\*\* has
121been defined: **equal**, **is-prefix-of**, **is-strict-prefix-of**. For example, a filter
Alexander Afanasyev7c6aeb02014-04-10 19:59:19 -0700122
123::
124
125 filter
126 {
127 type name
128 name /localhost/example
129 relation equal
130 }
131
Yingdi Yu4e99f532014-08-25 19:40:57 -0700132shall only capture a packet with the exact name ``/localhost/example``.
Alexander Afanasyev7c6aeb02014-04-10 19:59:19 -0700133And a filter
134
135::
136
137 filter
138 {
139 type name
140 name /localhost/example
141 relation is-prefix-of
142 }
143
Yingdi Yu4e99f532014-08-25 19:40:57 -0700144shall capture a packet with name ``/localhost/example`` or ``/localhost/example/data``, but
145cannot catch a packet with name ``/localhost/another_example``. And a filter
Alexander Afanasyev7c6aeb02014-04-10 19:59:19 -0700146
147::
148
149 filter
150 {
151 type name
152 name /localhost/example
153 relation is-strict-prefix-of
154 }
155
Yingdi Yu4e99f532014-08-25 19:40:57 -0700156shall capture a packet with name ``/localhost/example/data``, but cannot catch a packet
157with name ``/localhost/example``.
Alexander Afanasyev7c6aeb02014-04-10 19:59:19 -0700158
Yingdi Yu4e99f532014-08-25 19:40:57 -0700159The second way is to specify an :doc:`utils-ndn-regex` that can match the packet. In this
160case, only one property **regex** is required. For example, a filter
Alexander Afanasyev7c6aeb02014-04-10 19:59:19 -0700161
162::
163
164 filter
165 {
166 type name
167 regex ^[^<KEY>]*<KEY><>*<ksk-.*><ID-CERT>$
168 }
169
170shall capture all the identity certificates.
171
172Checker Property
173----------------
174
Yingdi Yu4e99f532014-08-25 19:40:57 -0700175Passing all the filters in a rule only indicates that a packet can be checked using the
176rule, and it does not necessarily implies that the packet is valid. The validity of a
177packet is determined by the property **checker**, which defines the conditions that a
178valid packet must fulfill.
Alexander Afanasyev7c6aeb02014-04-10 19:59:19 -0700179
Yingdi Yu4e99f532014-08-25 19:40:57 -0700180Same as **filter**, **checker** has a property **type**. We have defined three types of
181checkers: **customized**, and **hierarchical**, and **fixed-signer**. As suggested by its
182name, **customized** checker allows you to customize the conditions according to specific
183requirements. **hierarchical** checker and **fixed-signer** checker are pre-defined
184shortcuts, which specify specific trust models separately.
Alexander Afanasyev7c6aeb02014-04-10 19:59:19 -0700185
186Customized Checker
187~~~~~~~~~~~~~~~~~~
188
189So far, we only allow three customized properties in a customized
190checker: **sig-type**, **key-locator**. All of them are related to the
191``SignatureInfo`` of a packet.
192
193::
194
195 checker
196 {
197 type customized
198 sig-type ...
199 key-locator
200 {
201 ...
202 }
203 }
204
Yingdi Yu4e99f532014-08-25 19:40:57 -0700205The property **sig-type** specifies the acceptable signature type. Right now three
206signature types have been defined: **rsa-sha256** and **ecdsa-sha256** (which are strong
207signature types) and **sha256** (which is a weak signature type). If sig-type is sha256,
208then **key-locator** will be ignored. Validator will simply calculate the digest of a
209packet and compare it with the one in ``SignatureValue``. If sig-type is rsa-sha256 or
210ecdsa-sha256, you have to further customize the checker with **key-locator**.
Alexander Afanasyev7c6aeb02014-04-10 19:59:19 -0700211
Yingdi Yu4e99f532014-08-25 19:40:57 -0700212The property **key-locator** which specifies the conditions on ``KeyLocator``. If the
213**key-locator** property is specified, it requires the existence of the ``KeyLocator``
214field in ``SignatureInfo``. Although there are more than one types of ``KeyLocator``
215defined in the `Packet Format <http://named-data.net/doc/ndn-tlv/signature.html>`__,
Alexander Afanasyev7c6aeb02014-04-10 19:59:19 -0700216**key-locator** property only supports one type: **name**:
217
218::
219
220 key-locator
221 {
222 type name
223 ...
224 }
225
Yingdi Yu4e99f532014-08-25 19:40:57 -0700226Such a key-locator property specifies the conditions on the certificate name of the
227signing key. Since the conditions are about name, they can be specified in the same way as
228the name filter. For example, a checker could be:
Alexander Afanasyev7c6aeb02014-04-10 19:59:19 -0700229
230::
231
232 checker
233 {
234 type customized
235 sig-type rsa-sha256
236 key-locator
237 {
238 type name
239 name /ndn/edu/ucla/KEY/yingdi/ksk-1234/ID-CERT
240 relation equal
241 }
242 }
243
Yingdi Yu4e99f532014-08-25 19:40:57 -0700244This checker property requires that the packet must have a ``rsa-sha256`` signature generated
245by a key whose certificate name is ``/ndn/edu/ucla/KEY/yingdi/ksk-1234/ID-CERT``.
Alexander Afanasyev7c6aeb02014-04-10 19:59:19 -0700246
Yingdi Yu4e99f532014-08-25 19:40:57 -0700247Besides the two ways to express conditions on the ``KeyLocator`` name (name and regex),
248you can further constrain the ``KeyLocator`` name using the information extracted from the
249packet name. This third type of condition is expressed via a property
250**hyper-relation**. The **hyper-relation** property consists of three parts:
Alexander Afanasyev7c6aeb02014-04-10 19:59:19 -0700251
Yingdi Yu4e99f532014-08-25 19:40:57 -0700252- an NDN regular expression that can extract information from packet name
253- an NDN regular expression that can extract information from ``KeyLocator`` name
254- relation from the part extracted from ``KeyLocator`` name to the one extracted from the
255 packet name
Alexander Afanasyev7c6aeb02014-04-10 19:59:19 -0700256
257For example, a checker:
258
259::
260
261 checker
262 {
263 type customized
264 sig-type rsa-sha256
265 key-locator
266 {
267 type name
268 hyper-relation
269 {
270 k-regex ^([^<KEY>]*)<KEY>(<>*)<ksk-.*><ID-CERT>$
271 k-expand \\1\\2
272 h-relation is-prefix-of
273 p-regex ^(<>*)$
274 p-expand \\1
275
276 }
277 }
278 }
279
Yingdi Yu4e99f532014-08-25 19:40:57 -0700280requires the packet name must be under the corresponding namespace of the ``KeyLocator``
281name.
Alexander Afanasyev7c6aeb02014-04-10 19:59:19 -0700282
Yingdi Yu4e99f532014-08-25 19:40:57 -0700283In some cases, you can even customize checker with another property For example:
Alexander Afanasyev7c6aeb02014-04-10 19:59:19 -0700284
285::
286
287 checker
288 {
289 type customized
290 sig-type rsa-sha256
291 key-locator
292 {
293 type name
294 hyper-relation
295 {
296 k-regex ^([^<KEY>]*)<KEY>(<>*)<ksk-.*><ID-CERT>$
297 k-expand \\1\\2
298 h-relation is-prefix-of
299 p-regex ^(<>*)$
300 p-expand \\1
301 }
302 }
303 }
304
305Hierarchical Checker
306~~~~~~~~~~~~~~~~~~~~
307
Yingdi Yu4e99f532014-08-25 19:40:57 -0700308As implied by its name, hierarchical checker requires that the packet name must be under
309the namespace of the packet signer. A hierarchical checker:
Alexander Afanasyev7c6aeb02014-04-10 19:59:19 -0700310
311::
312
313 checker
314 {
315 type hierarchical
316 sig-type rsa-sha256
317 }
318
319is equivalent to a customized checker:
320
321::
322
323 checker
324 {
325 type customized
326 sig-type rsa-sha256
327 key-locator
328 {
329 type name
330 hyper-relation
331 {
332 k-regex ^([^<KEY>]*)<KEY>(<>*)<ksk-.*><ID-CERT>$
333 k-expand \\1\\2
334 h-relation is-prefix-of
335 p-regex ^(<>*)$
336 p-expand \\1
337 }
338 }
339 }
340
341Fixed-Signer Checker
342~~~~~~~~~~~~~~~~~~~~
343
Yingdi Yu4e99f532014-08-25 19:40:57 -0700344In some cases, you only accept packets signed with pre-trusted certificates,
345i.e. "one-step validation". Such a trust model can be expressed with **fixed-signer**
346checker. And you only need to specify the trusted certificate via property **signer**. The
347definition of **signer** is the same as **trust-anchor**. For example:
Alexander Afanasyev7c6aeb02014-04-10 19:59:19 -0700348
349::
350
351 checker
352 {
353 type fixed-signer
354 sig-type rsa-sha256
355 signer
356 {
357 type file
358 file-name "trusted-signer.cert"
359 }
360 signer
361 {
362 type base64
363 base64-string "Bv0DGwdG...amHFvHIMDw=="
364 }
365 }
366
Alexander Afanasyevd36dd552014-06-30 12:42:46 -0700367.. _validator-conf-trust-anchors:
368
Alexander Afanasyev7c6aeb02014-04-10 19:59:19 -0700369Trust Anchors
370-------------
371
Yingdi Yu4e99f532014-08-25 19:40:57 -0700372Although **trust-anchor** is always not required in the configuration file (for example,
373if fixed-signer checker is used), it is very common to have a few trust-anchors in the
374configuration file, otherwise most packets cannot be validated. A configuration file may
375contain more than one trust anchors, but the order of trust anchors does not matter. The
376structure of trust-anchor is same as the **signer** in fixed-signer checker, for example:
Alexander Afanasyev7c6aeb02014-04-10 19:59:19 -0700377
378::
379
380 trust-anchor
381 {
382 type file
383 file-name "trusted-signer.cert"
384 }
385 trust-anchor
386 {
387 type base64
388 base64-string "Bv0DGwdG...amHFvHIMDw=="
389 }
390
Yingdi Yu4e99f532014-08-25 19:40:57 -0700391You may also specify a trust-anchor directory. All certificates under this directory are
392taken as trust anchors. For example, if all trust anchors are put into
393``/usr/local/etc/ndn/keys``.
Yingdi Yub4650652014-04-17 10:19:59 -0700394
395::
396
397 trust-anchor
398 {
399 type dir
400 file-name /usr/local/etc/ndn/keys
401 }
402
Yingdi Yu4e99f532014-08-25 19:40:57 -0700403If certificates under the directory might be changed during runtime, you can set a refresh
404period, such as
Yingdi Yub4650652014-04-17 10:19:59 -0700405
406::
407
408 trust-anchor
409 {
410 type dir
411 file-name /usr/local/etc/ndn/keys
412 refresh 1h ; refresh certificates every hour, other units include m (for minutes) and s (for seconds)
413 }
414
Yingdi Yu4e99f532014-08-25 19:40:57 -0700415There is another special trust anchor **any**. As long as such a trust-anchor is defined
416in config file, packet validation will be turned off.
Yingdi Yu44d190c2014-04-16 17:05:46 -0700417
Yingdi Yu4e99f532014-08-25 19:40:57 -0700418.. note::
419 **ATTENTION: This type of trust anchor is dangerous. You should used it only when you
420 want to disable packet validation temporarily (e.g, debugging code, building a demo).**
Yingdi Yu44d190c2014-04-16 17:05:46 -0700421
422::
423
424 trust-anchor
425 {
426 type any
427 }
428
Yingdi Yub4650652014-04-17 10:19:59 -0700429
Alexander Afanasyev7c6aeb02014-04-10 19:59:19 -0700430Example Configuration For NLSR
431------------------------------
432
Yingdi Yu4e99f532014-08-25 19:40:57 -0700433The trust model of NLSR is semi-hierarchical. An example certificate signing hierarchy is:
Alexander Afanasyev7c6aeb02014-04-10 19:59:19 -0700434
435::
436
437 root
438 |
439 +--------------+---------------+
440 site1 site2
441 | |
442 +---------+---------+ +
443 operator1 operator2 operator3
444 | | |
445 +-----+-----+ +----+-----+ +-----+-----+--------+
446 router1 router2 router3 router4 router5 router6 router7
447 | | | | | | |
448 + + + + + + +
449 NLSR NSLR NSLR NSLR NSLR NSLR NSLR
450
451However, entities name may not follow the signing hierarchy, for
452example:
453
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700454+------------+-------------------------------------------------------------------------------------+
455| Entity | Identity name and examples |
456+============+=====================================================================================+
457| root | ``/<network>`` |
458| | |
459| | Identity example: ``/ndn`` |
460| | |
461| | Certificate name example: ``/ndn/KEY/ksk-1/ID-CERT/%01`` |
462+------------+-------------------------------------------------------------------------------------+
463| site | ``/<network>/<site>`` |
464| | |
465| | Identity example: ``/ndn/edu/ucla`` |
466| | |
467| | Certificate name example: ``/ndn/edu/ucla/KEY/ksk-2/ID-CERT/%01`` |
468+------------+-------------------------------------------------------------------------------------+
469| operator | ``/<network>/<site>/%C1.O.N./<operator-id>`` |
470| | |
471| | Identity example: ``/ndn/edu/ucla/%C1.O.N./op1`` |
472| | |
473| | Certificate name example: ``/ndn/edu/ucla/%C1.O.N./op1/KEY/ksk-3/ID-CERT/%01`` |
474+------------+-------------------------------------------------------------------------------------+
475| router | ``/<network>/<site>/%C1.O.R./<router-id>`` |
476| | |
477| | Identity example: ``/ndn/edu/ucla/%C1.O.R./rt1`` |
478| | |
479| | Certificate name example: ``/ndn/edu/ucla/%C1.O.R./rt1/KEY/ksk-4/ID-CERT/%01`` |
480+------------+-------------------------------------------------------------------------------------+
481| NLSR | ``/<network>/<site>/%C1.O.R./<router-id>/NLSR`` |
482| | |
483| | Identity example: ``/ndn/edu/ucla/%C1.O.R./rt1/NLSR`` |
484| | |
485| | Certificate name example: ``/ndn/edu/ucla/%C1.O.R./rt1/NLSR/KEY/ksk-5/ID-CERT/%01`` |
486+------------+-------------------------------------------------------------------------------------+
Alexander Afanasyev7c6aeb02014-04-10 19:59:19 -0700487
488Assume that a typical NLSR data name is
Yingdi Yu4e99f532014-08-25 19:40:57 -0700489``/ndn/edu/ucla/%C1.O.R./rt1/NLSR/LSA/LSType.1/%01``. Then, the exception of naming
490hierarchy is "operator-router". So we can write a configuration file with three rules. The
491first one is a customized rule that capture the normal NLSR data. The second one is a
492customized rule that handles the exception case of the hierarchy (operator->router). And
493the last one is a hierarchical rule that handles the normal cases of the hierarchy.
Alexander Afanasyev7c6aeb02014-04-10 19:59:19 -0700494
Yingdi Yu4e99f532014-08-25 19:40:57 -0700495We put the NLSR data rule to the first place, because NLSR data packets are the most
496frequently checked. The hierarchical exception rule is put to the second, because it is
497more specific than the last one.
Alexander Afanasyev7c6aeb02014-04-10 19:59:19 -0700498
499And here is the configuration file:
500
501::
502
503 rule
504 {
505 id "NSLR LSA Rule"
506 for data
507 filter
508 {
509 type name
510 regex ^[^<NLSR><LSA>]*<NLSR><LSA>
511 }
512 checker
513 {
514 type customized
515 sig-type rsa-sha256
516 key-locator
517 {
518 type name
519 hyper-relation
520 {
521 k-regex ^([^<KEY>]*)<KEY><ksk-.*><ID-CERT>$
522 k-expand \\1
523 h-relation equal
524 p-regex ^([^<NLSR><LSA>]*)<NLSR><LSA><LSType\.\d><>$
525 p-expand \\1
526 }
527 }
528 }
529 }
530 rule
531 {
532 id "NSLR Hierarchy Exception Rule"
533 for data
534 filter
535 {
536 type name
537 regex ^[^<KEY><%C1.O.R.>]*<%C1.O.R.><><KEY><ksk-.*><ID-CERT><>$
538 }
539 checker
540 {
541 type customized
542 sig-type rsa-sha256
543 key-locator
544 {
545 type name
546 hyper-relation
547 {
548 k-regex ^([^<KEY><%C1.O.N.>]*)<%C1.O.N.><><KEY><ksk-.*><ID-CERT>$
549 k-expand \\1
550 h-relation equal
551 p-regex ^([^<KEY><%C1.O.R.>]*)<%C1.O.R.><><KEY><ksk-.*><ID-CERT><>$
552 p-expand \\1
553 }
554 }
555 }
556 }
557 rule
558 {
559 id "NSLR Hierarchical Rule"
560 for data
561 filter
562 {
563 type name
564 regex ^[^<KEY>]*<KEY><ksk-.*><ID-CERT><>$
565 }
566 checker
567 {
568 type hierarchical
569 sig-type rsa-sha256
570 }
571 }
572 trust-anchor
573 {
574 type file
575 file-name "testbed-trust-anchor.cert"
576 }
577
Yingdi Yu4e99f532014-08-25 19:40:57 -0700578Example Configuration For NFD RIB Management
579--------------------------------------------
Alexander Afanasyev7c6aeb02014-04-10 19:59:19 -0700580
Davide Pesavento0530b5b2016-11-07 03:23:58 +0100581Assume `NFD RIB Management <https://redmine.named-data.net/projects/nfd/wiki/RibMgmt>`_
Yingdi Yu4e99f532014-08-25 19:40:57 -0700582allows any valid testbed certificate to register prefix, the configuration file could be
583written as:
Alexander Afanasyev7c6aeb02014-04-10 19:59:19 -0700584
585::
586
587 rule
588 {
589 id "NRD Prefix Registration Command Rule"
590 for interest
591 filter
592 {
593 type name
594 regex ^<localhost><nrd>[<register><unregister><advertise><withdraw>]
595 }
596 checker
597 {
598 type customized
599 sig-type rsa-sha256
600 key-locator
601 {
602 type name
603 regex ^[^<KEY>]*<KEY><>*<ksk-.*><ID-CERT>$
604 }
605 }
606 }
607 rule
608 {
609 id "Testbed Hierarchy Rule"
610 for data
611 filter
612 {
613 type name
614 regex ^[^<KEY>]*<KEY><>*<ksk-.*><ID-CERT><>$
615 }
616 checker
617 {
618 type hierarchical
619 sig-type rsa-sha256
620 }
621 }
622 trust-anchor
623 {
624 type file
625 file-name "testbed-trust-anchor.cert"
626 }