blob: 6cd482988c9f363038d1b2b6888a0b846009eebe [file] [log] [blame]
Alexander Afanasyev7c6aeb02014-04-10 19:59:19 -07001Validator Configuration File Format
2===================================
3
4You can set up a ``Validator`` via a configuration file. Next, we will
5show you how to write a configuration file.
6
7The configuration file consists of **rules** and **trust-anchors** that
8will be used in validation. **Rules** tell the validator how to validate
9a packet, while **trust-anchors** tell the validator which certificates
10are valid immediately. Here is an example of configuration file
11containing two rules.
12
13::
14
15 rule
16 {
17 id "Simple Rule"
18 for data
19 filter
20 {
21 type name
22 name /localhost/example
23 relation is-prefix-of
24 }
25 checker
26 {
27 type customized
28 sig-type rsa-sha256
29 key-locator
30 {
31 type name
32 name /ndn/edu/ucla/KEY/yingdi/ksk-1234/ID-CERT
33 relation equal
34 }
35 }
36 }
37 rule
38 {
39 id "Testbed Validation Rule"
40 for data
41 checker
42 {
43 type hierarchical
44 sig-type rsa-sha256
45 }
46 }
47 trust-anchor
48 {
49 type file
50 file-name "testbed-trust-anchor.cert"
51 }
52
53- \ **ATTENTION: The order of rules MATTERS!**\
54
55A rule can be broken into two parts:
56
57- The first part is to qualify packets to which the rule can be
58 applied;
59- The second part is to check whether further validation process is
60 necessary.
61
62When receiving a packet, the validator will apply rules in the
63configuration file one-by-one against the packet, until finding a rule
64that the packet qualifies for. And the second part of the matched rule
65will be used to check the validity of the packet. If the packet cannot
66qualify for any rules, it is treated as an invalid packet. Once a packet
67has been matched by a rule, the rest rules will not be applied against
68the packet. Therefore, you should always put the most specific rule to
69the top, otherwise it will become useless.
70
71In the example configuration, the first rule indicates that all the data
72packets under the name prefix "/localhost/example" must be signed by a
73key whose certificate name is
74"/ndn/edu/ucla/KEY/yingdi/ksk-1234/ID-CERT". If a packet does not have a
75name under prefix "/localhost/example", validator will skip the first
76rule and apply the second rule. The second rule indicates that any data
77packets must be validated along a hierarchy. And a certificate stored in
78a file "testbed-trust-anchor.cert" is valid.
79
80Rules in general
81----------------
82
83A rule has four types of properties: **id**, **for**, **filter**, and
84**checker**.
85
86The property **id** uniquely identifies the rule in the configuration
87file. As long as being unique, any name can be given to a rule, e.g.,
88"Simple Rule", "Testbed Validation Rule". A rule must have one and only
89one **id** property.
90
91A rule is either used to validate an interest packet or a data packet.
92This information is specified in the property **for**. Only two value
93can be specified: **data** and **interest**. A rule must have one and
94only one **for** property.
95
96The property **filter** further constrains the packets that can be
97checked by the rule. Filter property is not required in a rule, in this
98case, the rule will capture all the packets passed to it. A rule may
99contain more than one filters, in this case, a packet can be checked by
100a rule only if the packet satisfies all the filters.
101
102- \ **ATTENTION: A packet that satisfies all the filters may not be
103 valid**\ .
104
105The property **checker** defines the conditions that a matched packet
106must fulfill to be treated as a valid packet. A rule must have at least
107one **checker** property, a packet is treated as invalid if it cannot
108pass none of the checkers.
109
110**filter** and **checker** have their own properties. Next, we will
111introduce them separately.
112
113Filter Property
114---------------
115
116Filter has its own **type** property. Although a rule may contain more
117than one filters, there is at most one filter of each type. So far, only
118one type of filter is defined: **name**. In other word, only one filter
119can be specified in a rule for now.
120
121Name Filter
122~~~~~~~~~~~
123
124There are two ways to express the conditions on name. The first way is
125to specify a relationship between the packet name and a particular name.
126In this case, two more properties are required: **name** and
127**relation**. A packet can fulfill the condition if the **name** has a
128**relation\* to the packet name. Three types of **\ relation\*\* has
129been defined: **equal**, **is-prefix-of**, **is-strict-prefix-of**. For
130example, a filter
131
132::
133
134 filter
135 {
136 type name
137 name /localhost/example
138 relation equal
139 }
140
141shall only capture a packet with the exact name "/localhost/example".
142And a filter
143
144::
145
146 filter
147 {
148 type name
149 name /localhost/example
150 relation is-prefix-of
151 }
152
153shall capture a packet with name "/localhost/example" or
154"/localhost/example/data", but cannot catch a packet with name
155"/localhost/another\_example". And a filter
156
157::
158
159 filter
160 {
161 type name
162 name /localhost/example
163 relation is-strict-prefix-of
164 }
165
166shall capture a packet with name "/localhost/example/data", but cannot
167catch a packet with name "/localhost/example".
168
169The second way is to specify an [[Regex\|NDN Regular Expression]] that
170can match the packet. In this case, only one property **regex** is
171required. For example, a filter
172
173::
174
175 filter
176 {
177 type name
178 regex ^[^<KEY>]*<KEY><>*<ksk-.*><ID-CERT>$
179 }
180
181shall capture all the identity certificates.
182
183Checker Property
184----------------
185
186Passing all the filters in a rule only indicates that a packet can be
187checked using the rule, and it does not necessarily implies that the
188packet is valid. The validity of a packet is determined by the property
189**checker**, which defines the conditions that a valid packet must
190fulfill.
191
192Same as **filter**, **checker** has a property **type**. We have defined
193three types of checkers: **customized**, and **hierarchical**, and
194**fixed-signer**. As suggested by its name, **customized** checker
195allows you to customize the conditions according to specific
196requirements. **hierarchical** checker and **fixed-signer** checker are
197pre-defined shortcuts, which specify specific trust models separately.
198
199Customized Checker
200~~~~~~~~~~~~~~~~~~
201
202So far, we only allow three customized properties in a customized
203checker: **sig-type**, **key-locator**. All of them are related to the
204``SignatureInfo`` of a packet.
205
206::
207
208 checker
209 {
210 type customized
211 sig-type ...
212 key-locator
213 {
214 ...
215 }
216 }
217
218The property **sig-type** specifies the acceptable signature type. Right
219now two signature types have been defined: **rsa-sha256** (which is a
220strong signature type) and **sha256** (which is a weak signature type).
221If sig-type is sha256, then **key-locator** will be ignored. Validator
222will simply calculate the digest of a packet and compare it with the one
223in ``SignatureValue``. If sig-type is rsa-sha256, you have to further
224customize the checker with **key-locator**.
225
226The property **key-locator** which specifies the conditions on
227``KeyLocator``. If the **key-locator** property is specified, it
228requires the existence of the ``KeyLocator`` field in ``SignatureInfo``.
229Although there are more than one types of ``KeyLocator`` defined in the
230`Packet Format <http://named-data.net/doc/ndn-tlv/signature.html>`__,
231**key-locator** property only supports one type: **name**:
232
233::
234
235 key-locator
236 {
237 type name
238 ...
239 }
240
241Such a key-locator property specifies the conditions on the certificate
242name of the signing key. Since the conditions are about name, they can
243be specified in the same way as the name filter. For example, a checker
244could be:
245
246::
247
248 checker
249 {
250 type customized
251 sig-type rsa-sha256
252 key-locator
253 {
254 type name
255 name /ndn/edu/ucla/KEY/yingdi/ksk-1234/ID-CERT
256 relation equal
257 }
258 }
259
260This checker property requires that the packet must have a rsa-sha256
261signature generated by a key whose certificate name is
262"/ndn/edu/ucla/KEY/yingdi/ksk-1234/ID-CERT".
263
264Besides the two ways to express conditions on the ``KeyLocator`` name
265(name and regex), you can further constrain the ``KeyLocator`` name
266using the information extracted from the packet name. This third type of
267condition is expressed via a property **hyper-relation**. The
268**hyper-relation** property consists of three parts:
269
270- an NDN regular expression that can extract information from packet
271 name
272- an NDN regular expression that can extract information from
273 ``KeyLocator`` name
274- relation from the part extracted from ``KeyLocator`` name to the one
275 extracted from the packet name
276
277For example, a checker:
278
279::
280
281 checker
282 {
283 type customized
284 sig-type rsa-sha256
285 key-locator
286 {
287 type name
288 hyper-relation
289 {
290 k-regex ^([^<KEY>]*)<KEY>(<>*)<ksk-.*><ID-CERT>$
291 k-expand \\1\\2
292 h-relation is-prefix-of
293 p-regex ^(<>*)$
294 p-expand \\1
295
296 }
297 }
298 }
299
300requires the packet name must be under the corresponding namespace of
301the ``KeyLocator`` name.
302
303In some cases, you can even customize checker with another property For
304example:
305
306::
307
308 checker
309 {
310 type customized
311 sig-type rsa-sha256
312 key-locator
313 {
314 type name
315 hyper-relation
316 {
317 k-regex ^([^<KEY>]*)<KEY>(<>*)<ksk-.*><ID-CERT>$
318 k-expand \\1\\2
319 h-relation is-prefix-of
320 p-regex ^(<>*)$
321 p-expand \\1
322 }
323 }
324 }
325
326Hierarchical Checker
327~~~~~~~~~~~~~~~~~~~~
328
329As implied by its name, hierarchical checker requires that the packet
330name must be under the namespace of the packet signer. A hierarchical
331checker:
332
333::
334
335 checker
336 {
337 type hierarchical
338 sig-type rsa-sha256
339 }
340
341is equivalent to a customized checker:
342
343::
344
345 checker
346 {
347 type customized
348 sig-type rsa-sha256
349 key-locator
350 {
351 type name
352 hyper-relation
353 {
354 k-regex ^([^<KEY>]*)<KEY>(<>*)<ksk-.*><ID-CERT>$
355 k-expand \\1\\2
356 h-relation is-prefix-of
357 p-regex ^(<>*)$
358 p-expand \\1
359 }
360 }
361 }
362
363Fixed-Signer Checker
364~~~~~~~~~~~~~~~~~~~~
365
366In some cases, you only accept packets signed with pre-trusted
367certificates, i.e. "one-step validation". Such a trust model can be
368expressed with **fixed-signer** checker. And you only need to specify
369the trusted certificate via property **signer**. The definition of
370**signer** is the same as **trust-anchor**. For example:
371
372::
373
374 checker
375 {
376 type fixed-signer
377 sig-type rsa-sha256
378 signer
379 {
380 type file
381 file-name "trusted-signer.cert"
382 }
383 signer
384 {
385 type base64
386 base64-string "Bv0DGwdG...amHFvHIMDw=="
387 }
388 }
389
390Trust Anchors
391-------------
392
393Although **trust-anchor** is always not required in the configuration
394file (for example, if fixed-signer checker is used), it is very common
395to have a few trust-anchors in the configuration file, otherwise most
396packets cannot be validated. A configuration file may contain more than
397one trust anchors, but the order of trust anchors does not matter. The
398structure of trust-anchor is same as the **signer** in fixed-signer
399checker, for example:
400
401::
402
403 trust-anchor
404 {
405 type file
406 file-name "trusted-signer.cert"
407 }
408 trust-anchor
409 {
410 type base64
411 base64-string "Bv0DGwdG...amHFvHIMDw=="
412 }
413
414Example Configuration For NLSR
415------------------------------
416
417The trust model of NLSR is semi-hierarchical. An example certificate
418signing hierarchy is:
419
420::
421
422 root
423 |
424 +--------------+---------------+
425 site1 site2
426 | |
427 +---------+---------+ +
428 operator1 operator2 operator3
429 | | |
430 +-----+-----+ +----+-----+ +-----+-----+--------+
431 router1 router2 router3 router4 router5 router6 router7
432 | | | | | | |
433 + + + + + + +
434 NLSR NSLR NSLR NSLR NSLR NSLR NSLR
435
436However, entities name may not follow the signing hierarchy, for
437example:
438
439+------------+-----------------------------------------------+-----------------------------------+---------------------------------------------------------+
440| Entity | Identity Name | Example | Certificate Name Example |
441+============+===============================================+===================================+=========================================================+
442| root | /<network> | /ndn | /ndn/KEY/ksk-1/ID-CERT/%01 |
443+------------+-----------------------------------------------+-----------------------------------+---------------------------------------------------------+
444| site | /<network>/<site> | /ndn/edu/ucla | /ndn/edu/ucla/KEY/ksk-2/ID-CERT/%01 |
445+------------+-----------------------------------------------+-----------------------------------+---------------------------------------------------------+
446| operator | /<network>/<site>/%C1.O.N./<operator-id> | /ndn/edu/ucla/%C1.O.N./op1 | /ndn/edu/ucla/%C1.O.N./op1/KEY/ksk-3/ID-CERT/%01 |
447+------------+-----------------------------------------------+-----------------------------------+---------------------------------------------------------+
448| router | /<network>/<site>/%C1.O.R./<router-id> | /ndn/edu/ucla/%C1.O.R./rt1 | /ndn/edu/ucla/%C1.O.R./rt1/KEY/ksk-4/ID-CERT/%01 |
449+------------+-----------------------------------------------+-----------------------------------+---------------------------------------------------------+
450| NLSR | /<network>/<site>/%C1.O.R./<router-id>/NLSR | /ndn/edu/ucla/%C1.O.R./rt1/NLSR | /ndn/edu/ucla/%C1.O.R./rt1/NLSR/KEY/ksk-5/ID-CERT/%01 |
451+------------+-----------------------------------------------+-----------------------------------+---------------------------------------------------------+
452
453Assume that a typical NLSR data name is
454``/ndn/edu/ucla/%C1.O.R./rt1/NLSR/LSA/LSType.1/%01``. Then, the exception
455of naming hierarchy is "operator-router". So we can write a
456configuration file with three rules. The first one is a customized rule
457that capture the normal NLSR data. The second one is a customized rule
458that handles the exception case of the hierarchy (operator->router). And
459the last one is a hierarchical rule that handles the normal cases of the
460hierarchy.
461
462We put the NLSR data rule to the first place, because NLSR data packets
463are the most frequently checked. The hierarchical exception rule is put
464to the second, because it is more specific than the last one.
465
466And here is the configuration file:
467
468::
469
470 rule
471 {
472 id "NSLR LSA Rule"
473 for data
474 filter
475 {
476 type name
477 regex ^[^<NLSR><LSA>]*<NLSR><LSA>
478 }
479 checker
480 {
481 type customized
482 sig-type rsa-sha256
483 key-locator
484 {
485 type name
486 hyper-relation
487 {
488 k-regex ^([^<KEY>]*)<KEY><ksk-.*><ID-CERT>$
489 k-expand \\1
490 h-relation equal
491 p-regex ^([^<NLSR><LSA>]*)<NLSR><LSA><LSType\.\d><>$
492 p-expand \\1
493 }
494 }
495 }
496 }
497 rule
498 {
499 id "NSLR Hierarchy Exception Rule"
500 for data
501 filter
502 {
503 type name
504 regex ^[^<KEY><%C1.O.R.>]*<%C1.O.R.><><KEY><ksk-.*><ID-CERT><>$
505 }
506 checker
507 {
508 type customized
509 sig-type rsa-sha256
510 key-locator
511 {
512 type name
513 hyper-relation
514 {
515 k-regex ^([^<KEY><%C1.O.N.>]*)<%C1.O.N.><><KEY><ksk-.*><ID-CERT>$
516 k-expand \\1
517 h-relation equal
518 p-regex ^([^<KEY><%C1.O.R.>]*)<%C1.O.R.><><KEY><ksk-.*><ID-CERT><>$
519 p-expand \\1
520 }
521 }
522 }
523 }
524 rule
525 {
526 id "NSLR Hierarchical Rule"
527 for data
528 filter
529 {
530 type name
531 regex ^[^<KEY>]*<KEY><ksk-.*><ID-CERT><>$
532 }
533 checker
534 {
535 type hierarchical
536 sig-type rsa-sha256
537 }
538 }
539 trust-anchor
540 {
541 type file
542 file-name "testbed-trust-anchor.cert"
543 }
544
545Example Configuration For NRD
546-----------------------------
547
548Assume NRD allows any valid testbed certificate to register prefix, the
549configuration file could be written as:
550
551::
552
553 rule
554 {
555 id "NRD Prefix Registration Command Rule"
556 for interest
557 filter
558 {
559 type name
560 regex ^<localhost><nrd>[<register><unregister><advertise><withdraw>]
561 }
562 checker
563 {
564 type customized
565 sig-type rsa-sha256
566 key-locator
567 {
568 type name
569 regex ^[^<KEY>]*<KEY><>*<ksk-.*><ID-CERT>$
570 }
571 }
572 }
573 rule
574 {
575 id "Testbed Hierarchy Rule"
576 for data
577 filter
578 {
579 type name
580 regex ^[^<KEY>]*<KEY><>*<ksk-.*><ID-CERT><>$
581 }
582 checker
583 {
584 type hierarchical
585 sig-type rsa-sha256
586 }
587 }
588 trust-anchor
589 {
590 type file
591 file-name "testbed-trust-anchor.cert"
592 }