CommandValidatorConf » History » Version 19
Yingdi Yu, 03/18/2014 10:55 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 | 19 | Yingdi Yu | regex "^<>*$" |
322 | 17 | Yingdi Yu | } |
323 | 18 | Yingdi Yu | trust-anchor |
324 | 16 | Yingdi Yu | { |
325 | 18 | Yingdi Yu | type file |
326 | file-name "testbed-trust-anchor.cert" |
||
327 | 16 | Yingdi Yu | } |
328 | 1 | Yingdi Yu | } |