CommandValidatorConf » History » Version 13
Yingdi Yu, 03/18/2014 03:49 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 | type name |
||
23 | 7 | Yingdi Yu | name "/ndn/edu/ucla/KEY/yingdi/ksk-1234/ID-CERT" |
24 | relation equal |
||
25 | 6 | Yingdi Yu | } |
26 | 1 | Yingdi Yu | } |
27 | rule |
||
28 | { |
||
29 | 9 | Yingdi Yu | id "Testbed Validation Rule" |
30 | 1 | Yingdi Yu | for data |
31 | type hierarchical |
||
32 | trust-anchor |
||
33 | { |
||
34 | type file |
||
35 | file-name "testbed-trust-anchor.cert" |
||
36 | } |
||
37 | } |
||
38 | |||
39 | 9 | Yingdi Yu | |
40 | <font color='red'>**ATTENTION: The order of rules MATTERS!**</font> |
||
41 | |||
42 | 10 | Yingdi Yu | A rule can be broken into two parts: |
43 | 9 | Yingdi Yu | |
44 | * The first part is to qualify packets to which the rule can be applied; |
||
45 | * The second part is to decide whether further validation process is necessary. |
||
46 | 1 | Yingdi Yu | |
47 | 10 | Yingdi Yu | When receiving a packet, the validator will check it against rules in the configuration file one-by-one, |
48 | until reaching a rule that the packet qualifies for. |
||
49 | And the second part of the matching rule will be used to check the validity of the packet. |
||
50 | If the packet cannot qualify any rules, it is treated as an invalid packet. |
||
51 | 1 | Yingdi Yu | |
52 | 10 | Yingdi Yu | |
53 | In the example configuration, |
||
54 | 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". |
||
55 | If a packet does not have a name under prefix "/localhost/example", validator will skip the first rule and check the second rule. |
||
56 | 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". |
||
57 | |||
58 | 11 | Yingdi Yu | ## Rules in general |
59 | 1 | Yingdi Yu | |
60 | 11 | Yingdi Yu | Before we go into the details of specific rules, we need to introduce several general properties of a rule. |
61 | |||
62 | A rule must have a **id** property which uniquely identify the rule in the configuration file, e.g., "Simple Rule", "Testbed Validation Rule". |
||
63 | |||
64 | A rule is either used to validate an interest packet or a data packet. |
||
65 | This information is specified in the property **for**. |
||
66 | Only two value can be specified: **data** and **interest**. |
||
67 | |||
68 | The property **type** indicates the type of rules. |
||
69 | There are some pre-defined rule types, such as **hierarchical**. |
||
70 | People can also customize their own rules by setting the type property to be **customized**. |
||
71 | |||
72 | A rule may have some other properties depending on the rule type. |
||
73 | 1 | Yingdi Yu | Next, we will introduce the other properties for the each rule type. |
74 | |||
75 | ## Customized Rule |
||
76 | 7 | Yingdi Yu | |
77 | 12 | Yingdi Yu | Two properties are required by customized rule: **filter** and **signer**. |
78 | And some optional properties may be needed, such as **relation**, **trust-anchor**, etc.. |
||
79 | 7 | Yingdi Yu | |
80 | 1 | Yingdi Yu | ### Filter Property |
81 | |||
82 | 12 | Yingdi Yu | The **filter** property specifies the condition that a packet must satisfy. |
83 | A rule may contain more than one filters. |
||
84 | A packet can be captured by a rule only if the packet satisfies all the filters. |
||
85 | 8 | Yingdi Yu | |
86 | 12 | Yingdi Yu | Filter has its own property **type**. |
87 | Although a rule may contain more than one filters, there is at most one filter of each type. |
||
88 | So far, we defined only one filter type: **name**. |
||
89 | In other word, only one filter can be specified for now. |
||
90 | 8 | Yingdi Yu | |
91 | 13 | Yingdi Yu | There are two ways to express the restrictions on name. |
92 | 8 | Yingdi Yu | The first way is to specify a relationship between the packet name and a particular name. |
93 | 7 | Yingdi Yu | In this case, two more properties are required: **name** and **relation**. |
94 | A packet can satisfy the condition if the **name** and the packet name can establish the **relation**. |
||
95 | 13 | Yingdi Yu | The value of **relation** property could be either **isPrefixOf** or **equal**. |
96 | For example, a filter: |
||
97 | 7 | Yingdi Yu | |
98 | 13 | Yingdi Yu | filter |
99 | 7 | Yingdi Yu | { |
100 | type name |
||
101 | name "/localhost/example" |
||
102 | relation isPrefixOf |
||
103 | 1 | Yingdi Yu | } |
104 | 7 | Yingdi Yu | |
105 | 13 | Yingdi Yu | can capture a packet with name "/localhost/example/data" but cannot catch a packet with name "/localhost/another_example". |
106 | 7 | Yingdi Yu | |
107 | 13 | Yingdi Yu | And a filter |
108 | 7 | Yingdi Yu | |
109 | 13 | Yingdi Yu | filter |
110 | 1 | Yingdi Yu | { |
111 | type name |
||
112 | name "/localhost/example" |
||
113 | 7 | Yingdi Yu | relation equal |
114 | } |
||
115 | 1 | Yingdi Yu | |
116 | can only catch a packet with the exact name "/localhost/example". |
||
117 | 8 | Yingdi Yu | |
118 | The second way is to specify an NDN regular expression that the packet name must match. |
||
119 | In this case, only one property **regex** is required. |
||
120 | 7 | Yingdi Yu | The value of **regex** is an NDN regular expression. |
121 | 13 | Yingdi Yu | A packet can satisfy the filter only if the regex can match the packet name. |
122 | 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. |
||
123 | For example, a filter |
||
124 | 7 | Yingdi Yu | |
125 | 13 | Yingdi Yu | filter |
126 | 8 | Yingdi Yu | { |
127 | type name |
||
128 | 7 | Yingdi Yu | regex "^([^<KEY>]*)<KEY>(<>*)<ksk-.*><ID-CERT>$" |
129 | 1 | Yingdi Yu | expand "\\1\\2" |
130 | 7 | Yingdi Yu | } |
131 | 1 | Yingdi Yu | |
132 | can catch all the identity certificates and extract the corresponding namespace of the certificate. |
||
133 | 7 | Yingdi Yu | |
134 | 8 | Yingdi Yu | ### Signer Property |
135 | 1 | Yingdi Yu | |
136 | 8 | Yingdi Yu | The **signer** property defines the conditions that the signer (or `KeyLocator`) must fulfill. |
137 | The structure of the **signer** property is the same as the **target** property. |
||
138 | And same as **target** property, a rule may contain more than one **signer** properties. |
||
139 | 7 | Yingdi Yu | However, as long as one of the **signer** properties is satisfied, the packet validation can proceed without treating the packet as invalid. |
140 | 8 | Yingdi Yu | |
141 | 7 | Yingdi Yu | ### Relation Property |
142 | 8 | Yingdi Yu | |
143 | The **relation** property is optional. |
||
144 | 7 | Yingdi Yu | If the **relation** property is set, then |
145 | 8 | Yingdi Yu | |
146 | |||
147 | |||
148 | 6 | Yingdi Yu | |
149 | ## Hierarchical Rule |
||
150 | |||
151 | As implied by its name, hierarchical rule requires the name of the target packet to be under the namespace of the packet signer. |
||
152 | Assume that the usage of the rule is for data, then it is equivalent to a customized rule: |
||
153 | |||
154 | rule |
||
155 | { |
||
156 | for data |
||
157 | name "Expanded Hierarchical Rule" |
||
158 | type customized |
||
159 | target |
||
160 | 1 | Yingdi Yu | { |
161 | type regex |
||
162 | expr "^(<>*)$" |
||
163 | expand "\\1" |
||
164 | } |
||
165 | 6 | Yingdi Yu | signer |
166 | 1 | Yingdi Yu | { |
167 | type regex |
||
168 | 6 | Yingdi Yu | expr "^([^<KEY>]*)<KEY>(<>*)<ksk-.*><ID-CERT>$" |
169 | 1 | Yingdi Yu | expand "\\1\\2" |
170 | 6 | Yingdi Yu | } |
171 | 8 | Yingdi Yu | relation isPrefixOf |
172 | anchor |
||
173 | { |
||
174 | type file |
||
175 | file-name "trust-anchor.cert" |
||
176 | 6 | Yingdi Yu | } |
177 | 8 | Yingdi Yu | } |
178 | |||
179 | 1 | Yingdi Yu | ## The Order Of Rules |