Project

General

Profile

CommandValidatorConf » History » Version 37

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