CommandValidatorConf » History » Version 16
Yingdi Yu, 03/18/2014 05:57 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 | 1 | Yingdi Yu | |
61 | 10 | Yingdi Yu | |
62 | In the example configuration, |
||
63 | 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". |
||
64 | If a packet does not have a name under prefix "/localhost/example", validator will skip the first rule and check the second rule. |
||
65 | 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". |
||
66 | |||
67 | 11 | Yingdi Yu | ## Rules in general |
68 | 1 | Yingdi Yu | |
69 | 11 | Yingdi Yu | Before we go into the details of specific rules, we need to introduce several general properties of a rule. |
70 | |||
71 | A rule must have a **id** property which uniquely identify the rule in the configuration file, e.g., "Simple Rule", "Testbed Validation Rule". |
||
72 | |||
73 | A rule is either used to validate an interest packet or a data packet. |
||
74 | This information is specified in the property **for**. |
||
75 | Only two value can be specified: **data** and **interest**. |
||
76 | |||
77 | The property **type** indicates the type of rules. |
||
78 | There are some pre-defined rule types, such as **hierarchical**. |
||
79 | People can also customize their own rules by setting the type property to be **customized**. |
||
80 | |||
81 | 1 | Yingdi Yu | A rule may have some other properties depending on the rule type. |
82 | Next, we will introduce the other properties for the each rule type. |
||
83 | |||
84 | 7 | Yingdi Yu | ## Customized Rule |
85 | 12 | Yingdi Yu | |
86 | 1 | Yingdi Yu | Two properties are required by customized rule: **filter** and **signer**. |
87 | 14 | Yingdi Yu | And some optional properties may be needed, such as **relation** and etc.. |
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 | 14 | Yingdi Yu | A packet can fulfill the condition if the **name** and the packet name can establish the **relation**. |
104 | 13 | Yingdi Yu | The value of **relation** property could be either **isPrefixOf** or **equal**. |
105 | 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 | 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". |
171 | 8 | Yingdi Yu | |
172 | 15 | Yingdi Yu | In some cases, the signer property may contain a **trust-anchor** property which specifies the pre-trusted certificate. |
173 | For example, a signer with a trust-anchor property could be: |
||
174 | 1 | Yingdi Yu | |
175 | 15 | Yingdi Yu | signer |
176 | { |
||
177 | sig-type rsa-sha256 |
||
178 | key-locator |
||
179 | { |
||
180 | type name |
||
181 | regex "^([^<KEY>]*)<KEY>(<>*)<ksk-.*><ID-CERT>$" |
||
182 | expand "\\1\\2" |
||
183 | } |
||
184 | trust-anchor |
||
185 | { |
||
186 | type file |
||
187 | file-name "testbed-trust-anchor.cert" |
||
188 | } |
||
189 | } |
||
190 | 1 | Yingdi Yu | |
191 | 15 | Yingdi Yu | Note that the **trust-anchor** must fulfill the conditions specified in **sig-type** and **key-locator**. |
192 | |||
193 | ### Relation Property |
||
194 | |||
195 | The **relation** property is optional. |
||
196 | It is used only when we need to specify an additional condition between packet name and key-locator name. |
||
197 | |||
198 | 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. |
||
199 | Otherwise, the rule is treated as invalid. |
||
200 | |||
201 | 6 | Yingdi Yu | The **relation** property describes the relationship between the name extracted by the filter and the name extracted by the signer. |
202 | Three relationships can be specified: **equal** (=), **isPrefixOf** (>=), and **isStrictPrefixOf** (>). |
||
203 | |||
204 | 1 | Yingdi Yu | ## Hierarchical Rule |
205 | |||
206 | 16 | Yingdi Yu | As implied by its name, hierarchical rule requires that the packet name must be under the namespace of the packet signer. |
207 | Therefore, you only need to specify two properties in hierarchical rule: |
||
208 | 1 | Yingdi Yu | |
209 | 16 | Yingdi Yu | * a filter of type name which restrict the scope of packets |
210 | * trust-anchors of the hierarchy |
||
211 | |||
212 | For the hierarchical rule in the example configuration, it is equivalent to a customized rule: |
||
213 | |||
214 | 1 | Yingdi Yu | rule |
215 | { |
||
216 | 16 | Yingdi Yu | name "Testbed Validation Rule" |
217 | 1 | Yingdi Yu | for data |
218 | 6 | Yingdi Yu | type customized |
219 | 8 | Yingdi Yu | target |
220 | 1 | Yingdi Yu | { |
221 | 16 | Yingdi Yu | type name |
222 | regex "^(<>*)$" |
||
223 | 1 | Yingdi Yu | expand "\\1" |
224 | } |
||
225 | signer |
||
226 | { |
||
227 | 16 | Yingdi Yu | type name |
228 | regex "^([^<KEY>]*)<KEY>(<>*)<ksk-.*><ID-CERT>$" |
||
229 | 8 | Yingdi Yu | expand "\\1\\2" |
230 | 16 | Yingdi Yu | trust-anchor |
231 | { |
||
232 | type file |
||
233 | file-name "testbed-trust-anchor.cert" |
||
234 | } |
||
235 | 1 | Yingdi Yu | } |
236 | 16 | Yingdi Yu | relation isStrictPrefixOf |
237 | 1 | Yingdi Yu | } |