Project

General

Profile

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