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