Project

General

Profile

CommandValidatorConf » History » Version 21

Yingdi Yu, 03/19/2014 06:06 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 6 Yingdi Yu
      type customized
14 9 Yingdi Yu
      filter
15 3 Yingdi Yu
      {
16 6 Yingdi Yu
        type name
17
        name "/localhost/example"
18 7 Yingdi Yu
        relation isPrefixOf
19 3 Yingdi Yu
      }
20 6 Yingdi Yu
      signer
21
      {
22 14 Yingdi Yu
        sig-type rsa-sha256
23
        key-locator
24
        {
25
          type name
26
          name "/ndn/edu/ucla/KEY/yingdi/ksk-1234/ID-CERT"
27
          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
        regex "^<>*$"
40
      }
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 1 Yingdi Yu
Two properties are required by customized rule: **filter** and **signer**.
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
      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
      name "/localhost/example"
121
      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 8 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 21 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
### Signer Property
149
150 14 Yingdi Yu
The **signer** 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 **signer** properties.
152
A packet, however, only needs to satisfy one of the **signer** properties.
153
154
A signer property requires a **sig-type** property which specifies the acceptable signature type.
155
Right now only one signature type **rsa-sha256** is defined.
156
157 1 Yingdi Yu
A signer property also requires a **key-locator** property which specifies the conditions on `KeyLocator`.
158
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 14 Yingdi Yu
For example, a signer could be:
162 1 Yingdi Yu
163
    signer
164
    {
165
      sig-type rsa-sha256
166
      key-locator
167
      {
168
        type name
169
        name "/ndn/edu/ucla/KEY/yingdi/ksk-1234/ID-CERT"
170
        relation equal
171
      }
172
    }
173
174
This signer 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
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
For example, a signer:
186
187
    signer
188
    {
189
      sig-type rsa-sha256
190
      key-locator
191
      {
192
        type name
193
        hyper-relation
194
        {
195
          p-regex "^(<>*)$"
196
          p-expand "\1"
197
          k-regex "^([^<KEY>]*)<KEY>(<>*)<ksk-.*><ID-CERT>$"
198
          k-expand "\1\2"
199
          relation isPrefixOf
200
        }
201
      }
202
    }
203
204
requires the packet name must be under the corresponding namespace of the key-locator name.
205
206 15 Yingdi Yu
In some cases, the signer property may contain a **trust-anchor** property which specifies the pre-trusted certificate.
207
For example, a signer with a trust-anchor property could be:
208
209
    signer
210
    {
211
      sig-type rsa-sha256
212
      key-locator
213
      {
214
        type name
215 21 Yingdi Yu
        hyper-relation
216
        {
217
          p-regex "^(<>*)$"
218
          p-expand "\1"
219
          k-regex "^([^<KEY>]*)<KEY>(<>*)<ksk-.*><ID-CERT>$"
220
          k-expand "\1\2"
221
          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 1 Yingdi Yu
As implied by its name, hierarchical rule requires that the packet name must be under the namespace of the packet signer.
236
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
        regex "^(<>*)$"
252 21 Yingdi Yu
        expand "\1"
253 1 Yingdi Yu
      }
254
      signer
255
      {
256
        sig-type rsa-sha256
257
        key-locator
258
        {
259
          type name
260 21 Yingdi Yu
          hyper-relation
261
          {
262
            p-regex "^(<>*)$"
263
            p-expand "\1"
264
            k-regex "^([^<KEY>]*)<KEY>(<>*)<ksk-.*><ID-CERT>$"
265
            k-expand "\1\2"
266
            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 17 Yingdi Yu
279 1 Yingdi Yu
The trust model of NLSR is semi-hierarchical.
280 21 Yingdi Yu
An example certificate signing hierarchy is:
281
    
282
                                            root 
283
                                             |  	    
284
                              +--------------+---------------+
285
                            site1                          site2
286
                              |                              |		   
287
                    +---------+---------+                    +
288
                 operator1           operator2            operator3
289
                    |                   |                    | 
290
              +-----+-----+        +----+-----+        +-----+-----+--------+
291
           router1     router2  router3    router4  router5     router6  router7
292
              |           |        |          |        |           |        |
293
              +           +        +          +        +           +        +  	      
294
            NLSR        NSLR     NSLR       NSLR     NSLR        NSLR     NSLR
295 17 Yingdi Yu
296 21 Yingdi Yu
However, entities name may not follow the signing hierarchy, for example:
297
298
Entity   | Identity Name                                     | Example                             | Certificate Name Example
299
-------- | ------------------------------------------------- | ----------------------------------- | ------------------------------------
300
root     | /\<network\>                                      | /ndn                                | /ndn/KEY/ksk-12345/ID-CERT/%01%02%03
301
site     | /\<network\>/\<site\>                             | /ndn/edu/ucla                       |
302
operator | /\<network\>/\<site\>/%C1.O.N./\<operator-id\>    | /ndn/edu/ucla/%C1.O.N./operator1    |
303
router   | /\<network\>/\<site\>/%C1.O.R./\<router-id\>      | /ndn/edu/ucla/%C1.O.R./router1      |
304
NLSR     | /\<network\>/\<site\>/%C1.O.R./\<router-id\>/NLSR | /ndn/edu/ucla/%C1.O.R./router1/NLSR |
305
306
307
308
    root   -->    /ndn/KEY/ksk-12345/ID-CERT/%01%02%03
309
    site certificate is signed using the root key, and an example certificate name could be "/ndn/edu/ucla/KEY/ksk-13579/ID-CERT/%03%04%05".
310 17 Yingdi Yu
A operator certificate is signed using the site key, and an example certificate name could be "/ndn/edu/ucla/KEY/operator/operator-1/ksk-24680/ID-CERT/%05%06%07".
311
A router certificate is signed using the operator key, and an example certificate name could be "/ndn/edu/ucla/KEY/router/router-1/ksk-67890/ID-CERT/%07%08%09".
312
A NLSR certificate is signed using the router key, and an example certificate name could be "/ndn/edu/ucla/router/router-1/KEY/NLSR/ksk-54321/ID-CERT/%01%03%05".
313
A typical NLSR data name could be "/ndn/edu/ucla/router/router-1/NLSR/LSA/LSType.1/%02%04%06".
314
315
The only place where hierarchy is broken is "operator->router".
316
So we can write a configuration file with three rules.
317
The first one is a customized rule that capture the normal NLSR data.
318
The second one is a customized rule that handles the exception case of the hierarchy (operator->router).
319
And the last one is a hierarchical rule that handles the normal cases of the hierarchy.
320
321
We put the NLSR data rule to the first place, because NLSR data packets are the most frequently checked.
322
The hierarchical exception rule is put to the second, because it is more specific than the last one.
323
324
And here is the configuration file:
325
326
    rule
327
    {
328
      id "NSLR Data Rule"
329
      for data
330
      type customized
331
      filter
332 1 Yingdi Yu
      {
333 17 Yingdi Yu
        type name
334
        regex "^([^<NLSR><KEY>]*<NLSR>)[^<KEY>]*$"
335
        expand "\\1"
336
      }
337
      signer
338
      {
339
        sig-type rsa-sha256
340
        key-locator
341
        {
342
          type name
343
          regex "^([^<KEY>]*)<KEY>(<>*<NLSR>)<ksk-.*><ID-CERT>$"
344
          expand "\\1\\2"
345
        }
346
      }
347
      relation equal
348
    }
349
    rule
350
    {
351
      id "NSLR Hierarchy Exception Rule"
352
      for data
353
      type customized
354
      filter
355
      {
356
        type name
357 1 Yingdi Yu
        regex "^([^<KEY>]*)<KEY>([^<router>]*)<router><><ksk-.*><ID-CERT><>$"
358 17 Yingdi Yu
        expand "\\1\\2"
359
      }
360
      signer
361
      {
362
        sig-type rsa-sha256
363
        key-locator
364
        {
365
          type name
366
          regex "^([^<KEY>]*)<KEY>([^<operator>]*)<operator><><ksk-.*><ID-CERT>$"
367
          expand "\\1\\2"
368
        }
369
      }
370
      relation equal
371
    }
372
    rule
373
    {
374
      id "NSLR Hierarchical Rule"
375
      for data
376
      type hierarchical
377
      target
378
      {
379 19 Yingdi Yu
        type name
380 17 Yingdi Yu
        regex "^<>*$"
381 18 Yingdi Yu
      }
382 16 Yingdi Yu
      trust-anchor
383 18 Yingdi Yu
      {
384
        type file
385 16 Yingdi Yu
        file-name "testbed-trust-anchor.cert"
386 1 Yingdi Yu
      }
387
    }