Project

General

Profile

CommandValidatorConf » History » Version 39

Yingdi Yu, 03/24/2014 01: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 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
A rule must have one and only one **checker** property.
89
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
          k-expand \1\2
233 35 Yingdi Yu
          h-relation isPrefixOf
234 29 Yingdi Yu
          p-regex ^(<>*)$
235
          p-expand \1
236
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
          k-expand \1\2
257 35 Yingdi Yu
          h-relation isPrefixOf
258 1 Yingdi Yu
          p-regex ^(<>*)$
259 29 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 1 Yingdi Yu
          k-expand \1\2
288 35 Yingdi Yu
          h-relation isPrefixOf
289 29 Yingdi Yu
          p-regex ^(<>*)$
290
          p-expand \1
291
        }
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
        type hex
315
        hex-string "Bv0DGwdG...amHFvHIMDw=="
316
      }
317 29 Yingdi Yu
    }
318
319 32 Yingdi Yu
## Trust Anchors
320
321
A configuration file must contain <font color='red'>**AT LEAST ONE**</font> trust anchors.
322
A configuration file may contain more than one trust anchors, but the order of trust anchors does not matter.
323
324 29 Yingdi Yu
325 21 Yingdi Yu
## Example Configuration For NLSR
326 25 Yingdi Yu
327 24 Yingdi Yu
The trust model of NLSR is semi-hierarchical.
328 17 Yingdi Yu
An example certificate signing hierarchy is:
329 1 Yingdi Yu
    
330 17 Yingdi Yu
                                            root 
331
                                             |  	    
332
                              +--------------+---------------+
333
                            site1                          site2
334
                              |                              |		   
335 1 Yingdi Yu
                    +---------+---------+                    +
336
                 operator1           operator2            operator3
337
                    |                   |                    | 
338
              +-----+-----+        +----+-----+        +-----+-----+--------+
339
           router1     router2  router3    router4  router5     router6  router7
340
              |           |        |          |        |           |        |
341 22 Yingdi Yu
              +           +        +          +        +           +        +  	      
342 17 Yingdi Yu
            NLSR        NSLR     NSLR       NSLR     NSLR        NSLR     NSLR
343 1 Yingdi Yu
344
However, entities name may not follow the signing hierarchy, for example:
345 17 Yingdi Yu
346
Entity   | Identity Name                                     | Example                         | Certificate Name Example
347
-------- | ------------------------------------------------- | ------------------------------- | ------------------------------------------------
348
root     | /\<network\>                                      | /ndn                            | /ndn/KEY/ksk-1/ID-CERT/%01
349 22 Yingdi Yu
site     | /\<network\>/\<site\>                             | /ndn/edu/ucla                   | /ndn/edu/ucla/KEY/ksk-2/ID-CERT/%01
350 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
351 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
352 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
353 1 Yingdi Yu
354 17 Yingdi Yu
355 1 Yingdi Yu
Assume that a typical NLSR data name is "/ndn/edu/ucla/%C1.O.R./rt1/NLSR/LSA/LSType.1/%01".
356
Then, the exception of naming hierarchy is "operator-router".
357
So we can write a configuration file with three rules.
358
The first one is a customized rule that capture the normal NLSR data.
359
The second one is a customized rule that handles the exception case of the hierarchy (operator->router).
360
And the last one is a hierarchical rule that handles the normal cases of the hierarchy.
361
362
We put the NLSR data rule to the first place, because NLSR data packets are the most frequently checked.
363 17 Yingdi Yu
The hierarchical exception rule is put to the second, because it is more specific than the last one.
364 22 Yingdi Yu
365
And here is the configuration file:
366
367
    rule
368
    {
369
      id "NSLR LSA Rule"
370
      for data
371
      filter
372 17 Yingdi Yu
      {
373
        type name
374
        regex ^[^<NLSR><LSA>]*<NLSR><LSA>
375
      }
376
      checker
377
      {
378 29 Yingdi Yu
        type customized
379 17 Yingdi Yu
        sig-type rsa-sha256
380
        key-locator
381
        {
382
          type name
383 23 Yingdi Yu
          hyper-relation
384 17 Yingdi Yu
          {
385 26 Yingdi Yu
            k-regex ^([^<KEY>]*)<KEY><ksk-.*><ID-CERT>$
386 17 Yingdi Yu
            k-expand \1
387 35 Yingdi Yu
            h-relation equal
388 29 Yingdi Yu
            p-regex ^([^<NLSR><LSA>]*)<NLSR><LSA><LSType\.\d><>$
389
            p-expand \1
390 17 Yingdi Yu
          }
391 22 Yingdi Yu
        }
392
      }
393
    }
394
    rule
395
    {
396
      id "NSLR Hierarchy Exception Rule"
397
      for data
398
      filter
399 17 Yingdi Yu
      {
400
        type name
401
        regex ^[^<KEY><%C1.O.R.>]*<%C1.O.R.><><KEY><ksk-.*><ID-CERT><>$
402
      }
403
      checker
404
      {
405 29 Yingdi Yu
        type customized
406 17 Yingdi Yu
        sig-type rsa-sha256
407
        key-locator
408
        {
409 19 Yingdi Yu
          type name
410 22 Yingdi Yu
          hyper-relation
411 18 Yingdi Yu
          {
412 16 Yingdi Yu
            k-regex ^([^<KEY><%C1.O.N.>]*)<%C1.O.N.><><KEY><ksk-.*><ID-CERT>$
413 18 Yingdi Yu
            k-expand \1
414 35 Yingdi Yu
            h-relation equal
415 29 Yingdi Yu
            p-regex ^([^<KEY><%C1.O.R.>]*)<%C1.O.R.><><KEY><ksk-.*><ID-CERT><>$
416
            p-expand \1
417 1 Yingdi Yu
          }
418
        }
419
      }
420
    }
421
    rule
422
    {
423
      id "NSLR Hierarchical Rule"
424
      for data
425 30 Yingdi Yu
      filter
426 1 Yingdi Yu
      {
427
        type name
428
        regex ^([^<KEY>]*)<KEY><ksk-.*><ID-CERT><>$
429
      }
430 29 Yingdi Yu
      checker
431 1 Yingdi Yu
      {
432 29 Yingdi Yu
        type hierarchical
433 1 Yingdi Yu
        sig-type rsa-sha256
434
      }
435 33 Yingdi Yu
    }
436
    trust-anchor
437
    {
438
      type file
439
      file-name "testbed-trust-anchor.cert"
440 1 Yingdi Yu
    }