Project

General

Profile

CommandValidatorConf » History » Version 26

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