Project

General

Profile

CommandValidatorConf » History » Version 30

Yingdi Yu, 03/20/2014 12:03 PM

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