Project

General

Profile

CommandValidatorConf » History » Version 17

Yingdi Yu, 03/18/2014 10:53 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
A rule must have a **id** property which uniquely identify the rule in the configuration file, e.g., "Simple Rule", "Testbed Validation Rule".
73
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
People can also customize their own rules by setting the type property to be **customized**.
81
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 14 Yingdi Yu
And some optional properties may be needed, such as **relation** and etc..
89 7 Yingdi Yu
90 1 Yingdi Yu
### Filter Property
91
92 14 Yingdi Yu
The **filter** property specifies the condition that a packet must fulfill.
93 12 Yingdi Yu
A rule may contain more than one filters.
94
A packet can be captured by a rule only if the packet satisfies all the filters.
95
96
Filter has its own property **type**.
97
Although a rule may contain more than one filters, there is at most one filter of each type.
98 1 Yingdi Yu
So far, we defined only one filter type: **name**.
99 12 Yingdi Yu
In other word, only one filter can be specified for now.
100 8 Yingdi Yu
101 13 Yingdi Yu
There are two ways to express the restrictions on name. 
102 8 Yingdi Yu
The first way is to specify a relationship between the packet name and a particular name.
103 7 Yingdi Yu
In this case, two more properties are required: **name** and **relation**.
104 14 Yingdi Yu
A packet can fulfill the condition if the **name** and the packet name can establish the **relation**.
105 13 Yingdi Yu
The value of **relation** property could be either **isPrefixOf** or **equal**. 
106
For example, a filter:
107 7 Yingdi Yu
108 13 Yingdi Yu
    filter
109 7 Yingdi Yu
    {
110
      type name
111
      name "/localhost/example"
112
      relation isPrefixOf
113 1 Yingdi Yu
    }
114 7 Yingdi Yu
115 13 Yingdi Yu
can capture a packet with name "/localhost/example/data" but cannot catch a packet with name "/localhost/another_example".
116 7 Yingdi Yu
117 13 Yingdi Yu
And a filter 
118 7 Yingdi Yu
119 13 Yingdi Yu
    filter
120 1 Yingdi Yu
    {
121
      type name
122
      name "/localhost/example"
123 7 Yingdi Yu
      relation equal
124
    }
125 1 Yingdi Yu
126
can only catch a packet with the exact name "/localhost/example".
127 8 Yingdi Yu
128
The second way is to specify an NDN regular expression that the packet name must match.
129
In this case, only one property **regex** is required.
130 7 Yingdi Yu
The value of **regex** is an NDN regular expression.
131 13 Yingdi Yu
A packet can satisfy the filter only if the regex can match the packet name.
132
If regex is used, an optional property **expand** may be specified if back reference is need to extract certain pattern out of the packet name.
133
For example, a filter 
134 7 Yingdi Yu
135 13 Yingdi Yu
    filter
136 7 Yingdi Yu
    {
137 1 Yingdi Yu
      type name
138
      regex "^([^<KEY>]*)<KEY>(<>*)<ksk-.*><ID-CERT>$"
139
      expand "\\1\\2"
140
    }
141
142
can catch all the identity certificates and extract the corresponding namespace of the certificate.
143 14 Yingdi Yu
Note that, if expand property is not used or name property is used, the whole packet name is extracted. 
144 1 Yingdi Yu
145
### Signer Property
146
147 14 Yingdi Yu
The **signer** property defines the conditions that the `SignatureInfo` part of the packet must fulfill.
148
Same as the **filter** property, a rule may contain more than one **signer** properties.
149
A packet, however, only needs to satisfy one of the **signer** properties.
150
151
A signer property requires a **sig-type** property which specifies the acceptable signature type.
152
Right now only one signature type **rsa-sha256** is defined.
153
154
A signer property also requires a **key-locator** property which specifies the conditions on `KeyLocator`.
155
Right now only one key-locator type **name** is defined.
156
Such a type of key-locator contains the certificate name of the signing key.
157
Since the key-locator is a name, you can specify the conditions on it in the same way as the **filter** with type **name**.
158 15 Yingdi Yu
For example, a signer could be:
159 1 Yingdi Yu
160 15 Yingdi Yu
    signer
161
    {
162
      sig-type rsa-sha256
163
      key-locator
164
      {
165
        type name
166
        name "/ndn/edu/ucla/KEY/yingdi/ksk-1234/ID-CERT"
167
        relation equal
168
      }
169
    }
170 1 Yingdi Yu
171 15 Yingdi Yu
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".
172 8 Yingdi Yu
173 15 Yingdi Yu
In some cases, the signer property may contain a **trust-anchor** property which specifies the pre-trusted certificate.
174
For example, a signer with a trust-anchor property could be:
175 1 Yingdi Yu
176 15 Yingdi Yu
    signer
177
    {
178
      sig-type rsa-sha256
179
      key-locator
180
      {
181
        type name
182
        regex "^([^<KEY>]*)<KEY>(<>*)<ksk-.*><ID-CERT>$"
183
        expand "\\1\\2"
184
      }
185
      trust-anchor
186
      {
187
        type file
188
        file-name "testbed-trust-anchor.cert"
189
      }
190
    }
191 1 Yingdi Yu
192 15 Yingdi Yu
Note that the **trust-anchor** must fulfill the conditions specified in **sig-type** and **key-locator**.
193
194
### Relation Property
195
196
The **relation** property is optional.
197
It is used only when we need to specify an additional condition between packet name and key-locator name.
198
 
199
If the **relation** property is specified, then the rule must contain: 1) a **filter** of type name, and 2) a **signer** with a key-locator of type name.
200
Otherwise, the rule is treated as invalid.
201
202 6 Yingdi Yu
The **relation** property describes the relationship between the name extracted by the filter and the name extracted by the signer.
203
Three relationships can be specified: **equal** (=), **isPrefixOf** (>=), and **isStrictPrefixOf** (>).
204
205 1 Yingdi Yu
## Hierarchical Rule
206
207 16 Yingdi Yu
As implied by its name, hierarchical rule requires that the packet name must be under the namespace of the packet signer.
208
Therefore, you only need to specify two properties in hierarchical rule: 
209 1 Yingdi Yu
210 16 Yingdi Yu
* a filter of type name which restrict the scope of packets
211
* trust-anchors of the hierarchy
212
213
For the hierarchical rule in the example configuration, it is equivalent to a customized rule:
214
215 1 Yingdi Yu
    rule
216
    {
217 17 Yingdi Yu
      id "Testbed Validation Rule"
218 1 Yingdi Yu
      for data
219 6 Yingdi Yu
      type customized
220 17 Yingdi Yu
      filter
221 1 Yingdi Yu
      {
222 16 Yingdi Yu
        type name
223
        regex "^(<>*)$"
224 1 Yingdi Yu
        expand "\\1"
225
      }
226
      signer
227
      {
228 17 Yingdi Yu
        sig-type rsa-sha256
229
        key-locator
230
        {
231
          type name
232
          regex "^([^<KEY>]*)<KEY>(<>*)<ksk-.*><ID-CERT>$"
233
          expand "\\1\\2"
234
        }
235
        trust-anchor
236
        {
237
          type file
238
          file-name "testbed-trust-anchor.cert"
239
        }
240
      }
241
      relation isStrictPrefixOf
242
    }
243
244
## Example Configuration For NLSR
245
246
The trust model of NLSR is semi-hierarchical.
247
The signing hierarchy is root->site->operator->router->NLSR->NLSR data
248
249
The root could be the self-signed testbed root key, and an example certificate name could be "/ndn/KEY/ksk-12345/ID-CERT/%01%02%03".
250
A 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".
251
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".
252
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".
253
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".
254
A typical NLSR data name could be "/ndn/edu/ucla/router/router-1/NLSR/LSA/LSType.1/%02%04%06".
255
256
The only place where hierarchy is broken is "operator->router".
257
So we can write a configuration file with three rules.
258
The first one is a customized rule that capture the normal NLSR data.
259
The second one is a customized rule that handles the exception case of the hierarchy (operator->router).
260
And the last one is a hierarchical rule that handles the normal cases of the hierarchy.
261
262
We put the NLSR data rule to the first place, because NLSR data packets are the most frequently checked.
263
The hierarchical exception rule is put to the second, because it is more specific than the last one.
264
265
And here is the configuration file:
266
267
    rule
268
    {
269
      id "NSLR Data Rule"
270
      for data
271
      type customized
272
      filter
273
      {
274 1 Yingdi Yu
        type name
275 17 Yingdi Yu
        regex "^([^<NLSR><KEY>]*<NLSR>)[^<KEY>]*$"
276
        expand "\\1"
277
      }
278
      signer
279
      {
280
        sig-type rsa-sha256
281
        key-locator
282
        {
283
          type name
284
          regex "^([^<KEY>]*)<KEY>(<>*<NLSR>)<ksk-.*><ID-CERT>$"
285
          expand "\\1\\2"
286
        }
287
      }
288
      relation equal
289
    }
290
    rule
291
    {
292
      id "NSLR Hierarchy Exception Rule"
293
      for data
294
      type customized
295
      filter
296
      {
297
        type name
298
        regex "^([^<KEY>]*)<KEY>([^<router>]*)<router><><ksk-.*><ID-CERT><>$"
299 1 Yingdi Yu
        expand "\\1\\2"
300 17 Yingdi Yu
      }
301
      signer
302
      {
303
        sig-type rsa-sha256
304
        key-locator
305
        {
306
          type name
307
          regex "^([^<KEY>]*)<KEY>([^<operator>]*)<operator><><ksk-.*><ID-CERT>$"
308
          expand "\\1\\2"
309
        }
310
      }
311
      relation equal
312
    }
313
    rule
314
    {
315
      id "NSLR Hierarchical Rule"
316
      for data
317
      type hierarchical
318
      target
319
      {
320
        type name
321
        regex "^(<>*)$"
322
        expand "\\1"
323
      }
324
      signer
325
      {
326
        sig-type rsa-sha256
327
        key-locator
328
        {
329
          type name
330
          regex "^([^<KEY>]*)<KEY>(<>*)<ksk-.*><ID-CERT>$"
331
          expand "\\1\\2"
332
        }
333 16 Yingdi Yu
        trust-anchor
334
        {
335
          type file
336
          file-name "testbed-trust-anchor.cert"
337
        }
338 1 Yingdi Yu
      }
339 16 Yingdi Yu
      relation isStrictPrefixOf
340 1 Yingdi Yu
    }