Project

General

Profile

CommandValidatorConf » History » Version 45

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