CommandValidatorConf » History » Version 27
Yingdi Yu, 03/20/2014 10:13 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 | 27 | Yingdi Yu | There are two ways to express the conditions on name. |
100 | 21 | Yingdi Yu | The first way is to specify a relationship between the packet name and a particular name. |
101 | 7 | Yingdi Yu | In this case, two more properties are required: **name** and **relation**. |
102 | 27 | Yingdi Yu | A packet can fulfill the condition if the **name** has a **relation* to the packet name. |
103 | Three types of **relation** has been defined: **equal**, **isPrefixOf**, **isStrictPrefixOf**. |
||
104 | 1 | Yingdi Yu | For example, a filter |
105 | 22 | Yingdi Yu | |
106 | 21 | Yingdi Yu | filter |
107 | 1 | Yingdi Yu | { |
108 | type name |
||
109 | name /localhost/example |
||
110 | relation equal |
||
111 | } |
||
112 | 21 | Yingdi Yu | |
113 | 27 | Yingdi Yu | shall only capture a packet with the exact name "/localhost/example". |
114 | 21 | Yingdi Yu | And a filter |
115 | 22 | Yingdi Yu | |
116 | 21 | Yingdi Yu | filter |
117 | { |
||
118 | 1 | Yingdi Yu | type name |
119 | 21 | Yingdi Yu | name /localhost/example |
120 | relation isPrefixOf |
||
121 | } |
||
122 | 1 | Yingdi Yu | |
123 | 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". |
124 | 1 | Yingdi Yu | And a filter |
125 | 22 | Yingdi Yu | |
126 | 21 | Yingdi Yu | filter |
127 | 8 | Yingdi Yu | { |
128 | 7 | Yingdi Yu | type name |
129 | 21 | Yingdi Yu | name /localhost/example |
130 | 13 | Yingdi Yu | relation isStrictPrefixOf |
131 | 21 | Yingdi Yu | } |
132 | 7 | Yingdi Yu | |
133 | 27 | Yingdi Yu | shall capture a packet with name "/localhost/example/data", but cannot catch a packet with name "/localhost/example". |
134 | 7 | Yingdi Yu | |
135 | 1 | Yingdi Yu | The second way is to specify an [[Regex|NDN Regular Expression]] that can match the packet. |
136 | In this case, only one property **regex** is required. |
||
137 | For example, a filter |
||
138 | 22 | Yingdi Yu | |
139 | 1 | Yingdi Yu | filter |
140 | { |
||
141 | 21 | Yingdi Yu | type name |
142 | 1 | Yingdi Yu | regex ^[^<KEY>]*<KEY><>*<ksk-.*><ID-CERT>$ |
143 | 26 | Yingdi Yu | } |
144 | 1 | Yingdi Yu | |
145 | 27 | Yingdi Yu | shall capture all the identity certificates. |
146 | 26 | Yingdi Yu | |
147 | 27 | Yingdi Yu | ## Checker Property |
148 | 14 | Yingdi Yu | |
149 | 26 | Yingdi Yu | The **checker** property defines the conditions that the `SignatureInfo` part of the packet must fulfill. |
150 | 14 | Yingdi Yu | Same as the **filter** property, a rule may contain more than one **checker** properties. |
151 | A packet, however, only needs to satisfy one of the **checker** properties. |
||
152 | 26 | Yingdi Yu | |
153 | 1 | Yingdi Yu | A checker property requires a **sig-type** property which specifies the acceptable signature type. |
154 | Right now only one signature type **rsa-sha256** is defined. |
||
155 | |||
156 | 26 | Yingdi Yu | A checker property also requires a **key-locator** property which specifies the conditions on `KeyLocator`. |
157 | 1 | Yingdi Yu | Right now only one key-locator type **name** is defined. |
158 | 26 | Yingdi Yu | Such a type of key-locator contains the certificate name of the signing key. |
159 | 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**. |
160 | For example, a checker could be: |
||
161 | |||
162 | checker |
||
163 | { |
||
164 | 22 | Yingdi Yu | sig-type rsa-sha256 |
165 | 1 | Yingdi Yu | key-locator |
166 | { |
||
167 | type name |
||
168 | name /ndn/edu/ucla/KEY/yingdi/ksk-1234/ID-CERT |
||
169 | 26 | Yingdi Yu | relation equal |
170 | 1 | Yingdi Yu | } |
171 | 21 | Yingdi Yu | } |
172 | |||
173 | 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". |
||
174 | |||
175 | 1 | Yingdi Yu | Besides the two ways to express conditions on key-locator name (name and regex), |
176 | 21 | Yingdi Yu | you can further constrain the key-locator name using the information extracted from the packet name. |
177 | This third type of condition is expressed via a property **hyper-relation**. |
||
178 | The **hyper-relation** property consists of three parts: |
||
179 | |||
180 | 26 | Yingdi Yu | * an NDN regular expression that can extract information from packet name |
181 | 21 | Yingdi Yu | * an NDN regular expression that can extract information from key-locator name |
182 | 26 | Yingdi Yu | * relation between the two parts above |
183 | 21 | Yingdi Yu | |
184 | For example, a checker: |
||
185 | |||
186 | checker |
||
187 | { |
||
188 | sig-type rsa-sha256 |
||
189 | key-locator |
||
190 | 22 | Yingdi Yu | { |
191 | type name |
||
192 | hyper-relation |
||
193 | { |
||
194 | 21 | Yingdi Yu | p-regex ^(<>*)$ |
195 | p-expand \1 |
||
196 | k-regex ^([^<KEY>]*)<KEY>(<>*)<ksk-.*><ID-CERT>$ |
||
197 | k-expand \1\2 |
||
198 | relation isPrefixOf |
||
199 | } |
||
200 | } |
||
201 | 26 | Yingdi Yu | } |
202 | |||
203 | 15 | Yingdi Yu | requires the packet name must be under the corresponding namespace of the key-locator name. |
204 | 26 | Yingdi Yu | |
205 | 15 | Yingdi Yu | In some cases, the checker property may contain a **trust-anchor** property which specifies the pre-trusted certificate. |
206 | For example, a checker with a trust-anchor property could be: |
||
207 | |||
208 | checker |
||
209 | { |
||
210 | 21 | Yingdi Yu | sig-type rsa-sha256 |
211 | key-locator |
||
212 | 22 | Yingdi Yu | { |
213 | type name |
||
214 | hyper-relation |
||
215 | { |
||
216 | 21 | Yingdi Yu | p-regex ^(<>*)$ |
217 | p-expand \1 |
||
218 | 15 | Yingdi Yu | k-regex ^([^<KEY>]*)<KEY>(<>*)<ksk-.*><ID-CERT>$ |
219 | 6 | Yingdi Yu | k-expand \1\2 |
220 | 1 | Yingdi Yu | relation isPrefixOf |
221 | } |
||
222 | } |
||
223 | trust-anchor |
||
224 | { |
||
225 | type file |
||
226 | file-name "testbed-trust-anchor.cert" |
||
227 | } |
||
228 | 6 | Yingdi Yu | } |
229 | |||
230 | 26 | Yingdi Yu | Note that the **trust-anchor** must fulfill the conditions specified in **sig-type** and **key-locator**. |
231 | 1 | Yingdi Yu | |
232 | 16 | Yingdi Yu | ## Hierarchical Rule |
233 | |||
234 | 1 | Yingdi Yu | As implied by its name, hierarchical rule requires that the packet name must be under the namespace of the packet checker. |
235 | 16 | Yingdi Yu | Therefore, you only need to specify two properties in hierarchical rule: |
236 | |||
237 | * a filter of type name which restrict the scope of packets |
||
238 | 1 | Yingdi Yu | * trust-anchors of the hierarchy |
239 | |||
240 | For the hierarchical rule in the example configuration, it is equivalent to a customized rule: |
||
241 | |||
242 | rule |
||
243 | { |
||
244 | id "Testbed Validation Rule" |
||
245 | for data |
||
246 | 22 | Yingdi Yu | type customized |
247 | filter |
||
248 | 1 | Yingdi Yu | { |
249 | 26 | Yingdi Yu | type name |
250 | 1 | Yingdi Yu | regex ^(<>*)$ |
251 | expand \1 |
||
252 | } |
||
253 | checker |
||
254 | { |
||
255 | 21 | Yingdi Yu | sig-type rsa-sha256 |
256 | key-locator |
||
257 | 22 | Yingdi Yu | { |
258 | type name |
||
259 | hyper-relation |
||
260 | { |
||
261 | 21 | Yingdi Yu | p-regex ^(<>*)$ |
262 | p-expand \1 |
||
263 | 1 | Yingdi Yu | k-regex ^([^<KEY>]*)<KEY>(<>*)<ksk-.*><ID-CERT>$ |
264 | k-expand \1\2 |
||
265 | relation isPrefixOf |
||
266 | 16 | Yingdi Yu | } |
267 | } |
||
268 | 1 | Yingdi Yu | trust-anchor |
269 | { |
||
270 | 17 | Yingdi Yu | type file |
271 | 1 | Yingdi Yu | file-name "testbed-trust-anchor.cert" |
272 | 6 | Yingdi Yu | } |
273 | 21 | Yingdi Yu | } |
274 | } |
||
275 | |||
276 | ## Example Configuration For NLSR |
||
277 | |||
278 | 1 | Yingdi Yu | The trust model of NLSR is semi-hierarchical. |
279 | 21 | Yingdi Yu | An example certificate signing hierarchy is: |
280 | |||
281 | root |
||
282 | | |
||
283 | +--------------+---------------+ |
||
284 | 1 | Yingdi Yu | site1 site2 |
285 | 21 | Yingdi Yu | | | |
286 | +---------+---------+ + |
||
287 | operator1 operator2 operator3 |
||
288 | | | | |
||
289 | +-----+-----+ +----+-----+ +-----+-----+--------+ |
||
290 | 1 | Yingdi Yu | router1 router2 router3 router4 router5 router6 router7 |
291 | | | | | | | | |
||
292 | + + + + + + + |
||
293 | 22 | Yingdi Yu | NLSR NSLR NSLR NSLR NSLR NSLR NSLR |
294 | |||
295 | However, entities name may not follow the signing hierarchy, for example: |
||
296 | |||
297 | Entity | Identity Name | Example | Certificate Name Example |
||
298 | -------- | ------------------------------------------------- | ------------------------------- | ------------------------------------------------ |
||
299 | root | /\<network\> | /ndn | /ndn/KEY/ksk-1/ID-CERT/%01 |
||
300 | 21 | Yingdi Yu | site | /\<network\>/\<site\> | /ndn/edu/ucla | /ndn/edu/ucla/KEY/ksk-2/ID-CERT/%01 |
301 | 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 |
||
302 | 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 |
303 | 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 |
304 | 17 | Yingdi Yu | |
305 | 1 | Yingdi Yu | |
306 | 17 | Yingdi Yu | Assume that a typical NLSR data name is "/ndn/edu/ucla/%C1.O.R./rt1/NLSR/LSA/LSType.1/%01". |
307 | Then, the exception of naming hierarchy is "operator-router". |
||
308 | So we can write a configuration file with three rules. |
||
309 | The first one is a customized rule that capture the normal NLSR data. |
||
310 | The second one is a customized rule that handles the exception case of the hierarchy (operator->router). |
||
311 | 1 | Yingdi Yu | And the last one is a hierarchical rule that handles the normal cases of the hierarchy. |
312 | |||
313 | We put the NLSR data rule to the first place, because NLSR data packets are the most frequently checked. |
||
314 | The hierarchical exception rule is put to the second, because it is more specific than the last one. |
||
315 | |||
316 | 22 | Yingdi Yu | And here is the configuration file: |
317 | 17 | Yingdi Yu | |
318 | rule |
||
319 | { |
||
320 | id "NSLR LSA Rule" |
||
321 | for data |
||
322 | 22 | Yingdi Yu | type customized |
323 | 17 | Yingdi Yu | filter |
324 | 26 | Yingdi Yu | { |
325 | 17 | Yingdi Yu | type name |
326 | 1 | Yingdi Yu | regex ^[^<NLSR><LSA>]*<NLSR><LSA> |
327 | 17 | Yingdi Yu | } |
328 | 1 | Yingdi Yu | checker |
329 | 17 | Yingdi Yu | { |
330 | 22 | Yingdi Yu | sig-type rsa-sha256 |
331 | key-locator |
||
332 | { |
||
333 | type name |
||
334 | hyper-relation |
||
335 | { |
||
336 | p-regex ^([^<NLSR><LSA>]*)<NLSR><LSA><LSType\.\d><>$ |
||
337 | p-expand \1 |
||
338 | 17 | Yingdi Yu | k-regex ^([^<KEY>]*)<KEY><ksk-.*><ID-CERT>$ |
339 | k-expand \1 |
||
340 | relation equal |
||
341 | } |
||
342 | } |
||
343 | } |
||
344 | } |
||
345 | rule |
||
346 | { |
||
347 | id "NSLR Hierarchy Exception Rule" |
||
348 | for data |
||
349 | 23 | Yingdi Yu | type customized |
350 | 17 | Yingdi Yu | filter |
351 | 26 | Yingdi Yu | { |
352 | 17 | Yingdi Yu | type name |
353 | 1 | Yingdi Yu | regex ^[^<KEY><%C1.O.R.>]*<%C1.O.R.><><KEY><ksk-.*><ID-CERT><>$ |
354 | 17 | Yingdi Yu | } |
355 | checker |
||
356 | { |
||
357 | 22 | Yingdi Yu | sig-type rsa-sha256 |
358 | key-locator |
||
359 | { |
||
360 | type name |
||
361 | hyper-relation |
||
362 | { |
||
363 | p-regex ^([^<KEY><%C1.O.R.>]*)<%C1.O.R.><><KEY><ksk-.*><ID-CERT><>$ |
||
364 | p-expand \1 |
||
365 | 17 | Yingdi Yu | k-regex ^([^<KEY><%C1.O.N.>]*)<%C1.O.N.><><KEY><ksk-.*><ID-CERT>$ |
366 | k-expand \1 |
||
367 | relation equal |
||
368 | } |
||
369 | } |
||
370 | } |
||
371 | } |
||
372 | rule |
||
373 | { |
||
374 | id "NSLR Hierarchical Rule" |
||
375 | 19 | Yingdi Yu | for data |
376 | 22 | Yingdi Yu | type hierarchical |
377 | 18 | Yingdi Yu | target |
378 | 16 | Yingdi Yu | { |
379 | 18 | Yingdi Yu | type name |
380 | regex ^([^<KEY>]*)<KEY><ksk-.*><ID-CERT><>$ |
||
381 | 16 | Yingdi Yu | } |
382 | 1 | Yingdi Yu | trust-anchor |
383 | { |
||
384 | type file |
||
385 | file-name "testbed-trust-anchor.cert" |
||
386 | } |
||
387 | } |