Project

General

Profile

CommandValidatorConf » History » Version 28

Yingdi Yu, 03/20/2014 10:14 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 28 Yingdi Yu
### Name Filter
100
101 27 Yingdi Yu
There are two ways to express the conditions on name. 
102 21 Yingdi Yu
The first way is to specify a relationship between the packet name and a particular name.
103 7 Yingdi Yu
In this case, two more properties are required: **name** and **relation**.
104 27 Yingdi Yu
A packet can fulfill the condition if the **name** has a **relation* to the packet name.
105
Three types of **relation** has been defined: **equal**, **isPrefixOf**, **isStrictPrefixOf**. 
106 1 Yingdi Yu
For example, a filter 
107 22 Yingdi Yu
108 21 Yingdi Yu
    filter
109 1 Yingdi Yu
    {
110
      type name
111
      name /localhost/example
112
      relation equal
113
    }
114 21 Yingdi Yu
115 27 Yingdi Yu
shall only capture a packet with the exact name "/localhost/example".
116 21 Yingdi Yu
And a filter
117 22 Yingdi Yu
118 21 Yingdi Yu
    filter
119
    {
120 1 Yingdi Yu
      type name
121 21 Yingdi Yu
      name /localhost/example
122
      relation isPrefixOf
123
    }
124 1 Yingdi Yu
125 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".
126 1 Yingdi Yu
And a filter
127 22 Yingdi Yu
128 21 Yingdi Yu
    filter
129 8 Yingdi Yu
    {
130 7 Yingdi Yu
      type name
131 21 Yingdi Yu
      name /localhost/example
132 13 Yingdi Yu
      relation isStrictPrefixOf
133 21 Yingdi Yu
    }
134 7 Yingdi Yu
135 27 Yingdi Yu
shall capture a packet with name "/localhost/example/data", but cannot catch a packet with name "/localhost/example".
136 7 Yingdi Yu
137 1 Yingdi Yu
The second way is to specify an [[Regex|NDN Regular Expression]] that can match the packet.
138
In this case, only one property **regex** is required.
139
For example, a filter 
140 22 Yingdi Yu
141 1 Yingdi Yu
    filter
142
    {
143 21 Yingdi Yu
      type name
144 1 Yingdi Yu
      regex ^[^<KEY>]*<KEY><>*<ksk-.*><ID-CERT>$
145 26 Yingdi Yu
    }
146 1 Yingdi Yu
147 27 Yingdi Yu
shall capture all the identity certificates. 
148 26 Yingdi Yu
149 27 Yingdi Yu
## Checker Property
150 14 Yingdi Yu
151 26 Yingdi Yu
The **checker** property defines the conditions that the `SignatureInfo` part of the packet must fulfill.
152 14 Yingdi Yu
Same as the **filter** property, a rule may contain more than one **checker** properties.
153
A packet, however, only needs to satisfy one of the **checker** properties.
154 26 Yingdi Yu
155 1 Yingdi Yu
A checker property requires a **sig-type** property which specifies the acceptable signature type.
156
Right now only one signature type **rsa-sha256** is defined.
157
158 26 Yingdi Yu
A checker property also requires a **key-locator** property which specifies the conditions on `KeyLocator`.
159 1 Yingdi Yu
Right now only one key-locator type **name** is defined.
160 26 Yingdi Yu
Such a type of key-locator contains the certificate name of the signing key.
161 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**.
162
For example, a checker could be:
163
164
    checker
165
    {
166 22 Yingdi Yu
      sig-type rsa-sha256
167 1 Yingdi Yu
      key-locator
168
      {
169
        type name
170
        name /ndn/edu/ucla/KEY/yingdi/ksk-1234/ID-CERT
171 26 Yingdi Yu
        relation equal
172 1 Yingdi Yu
      }
173 21 Yingdi Yu
    }
174
175
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".
176
177 1 Yingdi Yu
Besides the two ways to express conditions on key-locator name (name and regex), 
178 21 Yingdi Yu
you can further constrain the key-locator name using the information extracted from the packet name.
179
This third type of condition is expressed via a property **hyper-relation**.
180
The **hyper-relation** property consists of three parts:
181
182 26 Yingdi Yu
* an NDN regular expression that can extract information from packet name
183 21 Yingdi Yu
* an NDN regular expression that can extract information from key-locator name
184 26 Yingdi Yu
* relation between the two parts above
185 21 Yingdi Yu
186
For example, a checker:
187
188
    checker
189
    {
190
      sig-type rsa-sha256
191
      key-locator
192 22 Yingdi Yu
      {
193
        type name
194
        hyper-relation
195
        {
196 21 Yingdi Yu
          p-regex ^(<>*)$
197
          p-expand \1
198
          k-regex ^([^<KEY>]*)<KEY>(<>*)<ksk-.*><ID-CERT>$
199
          k-expand \1\2
200
          relation isPrefixOf
201
        }
202
      }
203 26 Yingdi Yu
    }
204
205 15 Yingdi Yu
requires the packet name must be under the corresponding namespace of the key-locator name.
206 26 Yingdi Yu
207 15 Yingdi Yu
In some cases, the checker property may contain a **trust-anchor** property which specifies the pre-trusted certificate.
208
For example, a checker with a trust-anchor property could be:
209
210
    checker
211
    {
212 21 Yingdi Yu
      sig-type rsa-sha256
213
      key-locator
214 22 Yingdi Yu
      {
215
        type name
216
        hyper-relation
217
        {
218 21 Yingdi Yu
          p-regex ^(<>*)$
219
          p-expand \1
220 15 Yingdi Yu
          k-regex ^([^<KEY>]*)<KEY>(<>*)<ksk-.*><ID-CERT>$
221 6 Yingdi Yu
          k-expand \1\2
222 1 Yingdi Yu
          relation isPrefixOf
223
        }
224
      }
225
      trust-anchor
226
      {
227
        type file
228
        file-name "testbed-trust-anchor.cert"
229
      }
230 6 Yingdi Yu
    }
231
232 26 Yingdi Yu
Note that the **trust-anchor** must fulfill the conditions specified in **sig-type** and **key-locator**.
233 1 Yingdi Yu
234 16 Yingdi Yu
## Hierarchical Rule
235
236 1 Yingdi Yu
As implied by its name, hierarchical rule requires that the packet name must be under the namespace of the packet checker.
237 16 Yingdi Yu
Therefore, you only need to specify two properties in hierarchical rule: 
238
239
* a filter of type name which restrict the scope of packets
240 1 Yingdi Yu
* trust-anchors of the hierarchy
241
242
For the hierarchical rule in the example configuration, it is equivalent to a customized rule:
243
244
    rule
245
    {
246
      id "Testbed Validation Rule"
247
      for data
248 22 Yingdi Yu
      type customized
249
      filter
250 1 Yingdi Yu
      {
251 26 Yingdi Yu
        type name
252 1 Yingdi Yu
        regex ^(<>*)$
253
        expand \1
254
      }
255
      checker
256
      {
257 21 Yingdi Yu
        sig-type rsa-sha256
258
        key-locator
259 22 Yingdi Yu
        {
260
          type name
261
          hyper-relation
262
          {
263 21 Yingdi Yu
            p-regex ^(<>*)$
264
            p-expand \1
265 1 Yingdi Yu
            k-regex ^([^<KEY>]*)<KEY>(<>*)<ksk-.*><ID-CERT>$
266
            k-expand \1\2
267
            relation isPrefixOf
268 16 Yingdi Yu
          }
269
        }
270 1 Yingdi Yu
        trust-anchor
271
        {
272 17 Yingdi Yu
          type file
273 1 Yingdi Yu
          file-name "testbed-trust-anchor.cert"
274 6 Yingdi Yu
        }
275 21 Yingdi Yu
      }
276
    }
277
278
## Example Configuration For NLSR
279
280 1 Yingdi Yu
The trust model of NLSR is semi-hierarchical.
281 21 Yingdi Yu
An example certificate signing hierarchy is:
282
    
283
                                            root 
284
                                             |  	    
285
                              +--------------+---------------+
286 1 Yingdi Yu
                            site1                          site2
287 21 Yingdi Yu
                              |                              |		   
288
                    +---------+---------+                    +
289
                 operator1           operator2            operator3
290
                    |                   |                    | 
291
              +-----+-----+        +----+-----+        +-----+-----+--------+
292 1 Yingdi Yu
           router1     router2  router3    router4  router5     router6  router7
293
              |           |        |          |        |           |        |
294
              +           +        +          +        +           +        +  	      
295 22 Yingdi Yu
            NLSR        NSLR     NSLR       NSLR     NSLR        NSLR     NSLR
296
297
However, entities name may not follow the signing hierarchy, for example:
298
299
Entity   | Identity Name                                     | Example                         | Certificate Name Example
300
-------- | ------------------------------------------------- | ------------------------------- | ------------------------------------------------
301
root     | /\<network\>                                      | /ndn                            | /ndn/KEY/ksk-1/ID-CERT/%01
302 21 Yingdi Yu
site     | /\<network\>/\<site\>                             | /ndn/edu/ucla                   | /ndn/edu/ucla/KEY/ksk-2/ID-CERT/%01
303
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
304 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
305 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
306 17 Yingdi Yu
307 1 Yingdi Yu
308 17 Yingdi Yu
Assume that a typical NLSR data name is "/ndn/edu/ucla/%C1.O.R./rt1/NLSR/LSA/LSType.1/%01".
309
Then, the exception of naming hierarchy is "operator-router".
310
So we can write a configuration file with three rules.
311
The first one is a customized rule that capture the normal NLSR data.
312
The second one is a customized rule that handles the exception case of the hierarchy (operator->router).
313 1 Yingdi Yu
And the last one is a hierarchical rule that handles the normal cases of the hierarchy.
314
315
We put the NLSR data rule to the first place, because NLSR data packets are the most frequently checked.
316
The hierarchical exception rule is put to the second, because it is more specific than the last one.
317
318 22 Yingdi Yu
And here is the configuration file:
319 17 Yingdi Yu
320
    rule
321
    {
322
      id "NSLR LSA Rule"
323
      for data
324 22 Yingdi Yu
      type customized
325 17 Yingdi Yu
      filter
326 26 Yingdi Yu
      {
327 17 Yingdi Yu
        type name
328 1 Yingdi Yu
        regex ^[^<NLSR><LSA>]*<NLSR><LSA>
329 17 Yingdi Yu
      }
330 1 Yingdi Yu
      checker
331 17 Yingdi Yu
      {
332 22 Yingdi Yu
        sig-type rsa-sha256
333
        key-locator
334
        {
335
          type name
336
          hyper-relation
337
          {
338
            p-regex ^([^<NLSR><LSA>]*)<NLSR><LSA><LSType\.\d><>$
339
            p-expand \1
340 17 Yingdi Yu
            k-regex ^([^<KEY>]*)<KEY><ksk-.*><ID-CERT>$
341
            k-expand \1
342
            relation equal
343
          }
344
        }
345
      }
346
    }
347
    rule
348
    {
349
      id "NSLR Hierarchy Exception Rule"
350
      for data
351 23 Yingdi Yu
      type customized
352 17 Yingdi Yu
      filter
353 26 Yingdi Yu
      {
354 17 Yingdi Yu
        type name
355 1 Yingdi Yu
        regex ^[^<KEY><%C1.O.R.>]*<%C1.O.R.><><KEY><ksk-.*><ID-CERT><>$
356 17 Yingdi Yu
      }
357
      checker
358
      {
359 22 Yingdi Yu
        sig-type rsa-sha256
360
        key-locator
361
        {
362
          type name
363
          hyper-relation
364
          {
365
            p-regex ^([^<KEY><%C1.O.R.>]*)<%C1.O.R.><><KEY><ksk-.*><ID-CERT><>$
366
            p-expand \1
367 17 Yingdi Yu
            k-regex ^([^<KEY><%C1.O.N.>]*)<%C1.O.N.><><KEY><ksk-.*><ID-CERT>$
368
            k-expand \1
369
            relation equal
370
          }
371
        }
372
      }
373
    }
374
    rule
375
    {
376
      id "NSLR Hierarchical Rule"
377 19 Yingdi Yu
      for data
378 22 Yingdi Yu
      type hierarchical
379 18 Yingdi Yu
      target
380 16 Yingdi Yu
      {
381 18 Yingdi Yu
        type name
382
        regex ^([^<KEY>]*)<KEY><ksk-.*><ID-CERT><>$
383 16 Yingdi Yu
      }
384 1 Yingdi Yu
      trust-anchor
385
      {
386
        type file
387
        file-name "testbed-trust-anchor.cert"
388
      }
389
    }