CommandValidatorConf » History » Version 15
Yingdi Yu, 03/18/2014 05:47 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 | trust-anchor |
||
37 | { |
||
38 | type file |
||
39 | file-name "testbed-trust-anchor.cert" |
||
40 | } |
||
41 | } |
||
42 | |||
43 | 9 | Yingdi Yu | |
44 | <font color='red'>**ATTENTION: The order of rules MATTERS!**</font> |
||
45 | |||
46 | 10 | Yingdi Yu | A rule can be broken into two parts: |
47 | 9 | Yingdi Yu | |
48 | * The first part is to qualify packets to which the rule can be applied; |
||
49 | * The second part is to decide whether further validation process is necessary. |
||
50 | 1 | Yingdi Yu | |
51 | 10 | Yingdi Yu | When receiving a packet, the validator will check it against rules in the configuration file one-by-one, |
52 | until reaching a rule that the packet qualifies for. |
||
53 | And the second part of the matching rule will be used to check the validity of the packet. |
||
54 | If the packet cannot qualify any rules, it is treated as an invalid packet. |
||
55 | 1 | Yingdi Yu | |
56 | 10 | Yingdi Yu | |
57 | In the example configuration, |
||
58 | 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". |
||
59 | If a packet does not have a name under prefix "/localhost/example", validator will skip the first rule and check the second rule. |
||
60 | 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". |
||
61 | |||
62 | 11 | Yingdi Yu | ## Rules in general |
63 | 1 | Yingdi Yu | |
64 | 11 | Yingdi Yu | Before we go into the details of specific rules, we need to introduce several general properties of a rule. |
65 | |||
66 | A rule must have a **id** property which uniquely identify the rule in the configuration file, e.g., "Simple Rule", "Testbed Validation Rule". |
||
67 | |||
68 | A rule is either used to validate an interest packet or a data packet. |
||
69 | This information is specified in the property **for**. |
||
70 | Only two value can be specified: **data** and **interest**. |
||
71 | |||
72 | The property **type** indicates the type of rules. |
||
73 | There are some pre-defined rule types, such as **hierarchical**. |
||
74 | People can also customize their own rules by setting the type property to be **customized**. |
||
75 | |||
76 | 1 | Yingdi Yu | A rule may have some other properties depending on the rule type. |
77 | Next, we will introduce the other properties for the each rule type. |
||
78 | |||
79 | 7 | Yingdi Yu | ## Customized Rule |
80 | 12 | Yingdi Yu | |
81 | 1 | Yingdi Yu | Two properties are required by customized rule: **filter** and **signer**. |
82 | 14 | Yingdi Yu | And some optional properties may be needed, such as **relation** and etc.. |
83 | 7 | Yingdi Yu | |
84 | 1 | Yingdi Yu | ### Filter Property |
85 | |||
86 | 14 | Yingdi Yu | The **filter** property specifies the condition that a packet must fulfill. |
87 | 12 | Yingdi Yu | A rule may contain more than one filters. |
88 | A packet can be captured by a rule only if the packet satisfies all the filters. |
||
89 | |||
90 | Filter has its own property **type**. |
||
91 | Although a rule may contain more than one filters, there is at most one filter of each type. |
||
92 | 1 | Yingdi Yu | So far, we defined only one filter type: **name**. |
93 | 12 | Yingdi Yu | In other word, only one filter can be specified for now. |
94 | 8 | Yingdi Yu | |
95 | 13 | Yingdi Yu | There are two ways to express the restrictions on name. |
96 | 8 | Yingdi Yu | The first way is to specify a relationship between the packet name and a particular name. |
97 | 7 | Yingdi Yu | In this case, two more properties are required: **name** and **relation**. |
98 | 14 | Yingdi Yu | A packet can fulfill the condition if the **name** and the packet name can establish the **relation**. |
99 | 13 | Yingdi Yu | The value of **relation** property could be either **isPrefixOf** or **equal**. |
100 | For example, a filter: |
||
101 | 7 | Yingdi Yu | |
102 | 13 | Yingdi Yu | filter |
103 | 7 | Yingdi Yu | { |
104 | type name |
||
105 | name "/localhost/example" |
||
106 | relation isPrefixOf |
||
107 | 1 | Yingdi Yu | } |
108 | 7 | Yingdi Yu | |
109 | 13 | Yingdi Yu | can capture a packet with name "/localhost/example/data" but cannot catch a packet with name "/localhost/another_example". |
110 | 7 | Yingdi Yu | |
111 | 13 | Yingdi Yu | And a filter |
112 | 7 | Yingdi Yu | |
113 | 13 | Yingdi Yu | filter |
114 | 1 | Yingdi Yu | { |
115 | type name |
||
116 | name "/localhost/example" |
||
117 | 7 | Yingdi Yu | relation equal |
118 | } |
||
119 | 1 | Yingdi Yu | |
120 | can only catch a packet with the exact name "/localhost/example". |
||
121 | 8 | Yingdi Yu | |
122 | The second way is to specify an NDN regular expression that the packet name must match. |
||
123 | In this case, only one property **regex** is required. |
||
124 | 7 | Yingdi Yu | The value of **regex** is an NDN regular expression. |
125 | 13 | Yingdi Yu | A packet can satisfy the filter only if the regex can match the packet name. |
126 | 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. |
||
127 | For example, a filter |
||
128 | 7 | Yingdi Yu | |
129 | 13 | Yingdi Yu | filter |
130 | 7 | Yingdi Yu | { |
131 | 1 | Yingdi Yu | type name |
132 | regex "^([^<KEY>]*)<KEY>(<>*)<ksk-.*><ID-CERT>$" |
||
133 | expand "\\1\\2" |
||
134 | } |
||
135 | |||
136 | can catch all the identity certificates and extract the corresponding namespace of the certificate. |
||
137 | 14 | Yingdi Yu | Note that, if expand property is not used or name property is used, the whole packet name is extracted. |
138 | 1 | Yingdi Yu | |
139 | ### Signer Property |
||
140 | |||
141 | 14 | Yingdi Yu | The **signer** property defines the conditions that the `SignatureInfo` part of the packet must fulfill. |
142 | Same as the **filter** property, a rule may contain more than one **signer** properties. |
||
143 | A packet, however, only needs to satisfy one of the **signer** properties. |
||
144 | |||
145 | A signer property requires a **sig-type** property which specifies the acceptable signature type. |
||
146 | Right now only one signature type **rsa-sha256** is defined. |
||
147 | |||
148 | A signer property also requires a **key-locator** property which specifies the conditions on `KeyLocator`. |
||
149 | Right now only one key-locator type **name** is defined. |
||
150 | Such a type of key-locator contains the certificate name of the signing key. |
||
151 | Since the key-locator is a name, you can specify the conditions on it in the same way as the **filter** with type **name**. |
||
152 | 15 | Yingdi Yu | For example, a signer could be: |
153 | 1 | Yingdi Yu | |
154 | 15 | Yingdi Yu | signer |
155 | { |
||
156 | sig-type rsa-sha256 |
||
157 | key-locator |
||
158 | { |
||
159 | type name |
||
160 | name "/ndn/edu/ucla/KEY/yingdi/ksk-1234/ID-CERT" |
||
161 | relation equal |
||
162 | } |
||
163 | } |
||
164 | 1 | Yingdi Yu | |
165 | 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". |
166 | 8 | Yingdi Yu | |
167 | 15 | Yingdi Yu | In some cases, the signer property may contain a **trust-anchor** property which specifies the pre-trusted certificate. |
168 | For example, a signer with a trust-anchor property could be: |
||
169 | 1 | Yingdi Yu | |
170 | 15 | Yingdi Yu | signer |
171 | { |
||
172 | sig-type rsa-sha256 |
||
173 | key-locator |
||
174 | { |
||
175 | type name |
||
176 | regex "^([^<KEY>]*)<KEY>(<>*)<ksk-.*><ID-CERT>$" |
||
177 | expand "\\1\\2" |
||
178 | } |
||
179 | trust-anchor |
||
180 | { |
||
181 | type file |
||
182 | file-name "testbed-trust-anchor.cert" |
||
183 | } |
||
184 | } |
||
185 | 1 | Yingdi Yu | |
186 | 15 | Yingdi Yu | Note that the **trust-anchor** must fulfill the conditions specified in **sig-type** and **key-locator**. |
187 | |||
188 | ### Relation Property |
||
189 | |||
190 | The **relation** property is optional. |
||
191 | It is used only when we need to specify an additional condition between packet name and key-locator name. |
||
192 | |||
193 | 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. |
||
194 | Otherwise, the rule is treated as invalid. |
||
195 | |||
196 | The **relation** property describes the relationship between the name extracted by the filter and the name extracted by the signer. |
||
197 | Three relationships can be specified: **equal** (=), **isPrefixOf** (>=), and **isStrictPrefixOf** (>). |
||
198 | 6 | Yingdi Yu | |
199 | ## Hierarchical Rule |
||
200 | |||
201 | As implied by its name, hierarchical rule requires the name of the target packet to be under the namespace of the packet signer. |
||
202 | Assume that the usage of the rule is for data, then it is equivalent to a customized rule: |
||
203 | |||
204 | rule |
||
205 | { |
||
206 | for data |
||
207 | name "Expanded Hierarchical Rule" |
||
208 | 1 | Yingdi Yu | type customized |
209 | target |
||
210 | { |
||
211 | type regex |
||
212 | expr "^(<>*)$" |
||
213 | 6 | Yingdi Yu | expand "\\1" |
214 | 1 | Yingdi Yu | } |
215 | signer |
||
216 | 6 | Yingdi Yu | { |
217 | 1 | Yingdi Yu | type regex |
218 | 6 | Yingdi Yu | expr "^([^<KEY>]*)<KEY>(<>*)<ksk-.*><ID-CERT>$" |
219 | 8 | Yingdi Yu | expand "\\1\\2" |
220 | } |
||
221 | relation isPrefixOf |
||
222 | anchor |
||
223 | { |
||
224 | 6 | Yingdi Yu | type file |
225 | 8 | Yingdi Yu | file-name "trust-anchor.cert" |
226 | } |
||
227 | 1 | Yingdi Yu | } |
228 | |||
229 | ## The Order Of Rules |