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