Project

General

Profile

CommandValidatorConf » History » Version 27

Yingdi Yu, 03/20/2014 10:13 AM

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