Project

General

Profile

CommandValidatorConf » History » Version 12

Yingdi Yu, 03/18/2014 03:43 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
There are two ways to express the restriction on name. 
92
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
The value of **relation** could be either **isPrefixOf** or **equal**. 
96 6 Yingdi Yu
For example, a target:
97 7 Yingdi Yu
98
    target
99
    {
100
      type name
101
      name "/localhost/example"
102
      relation isPrefixOf
103 1 Yingdi Yu
    }
104 7 Yingdi Yu
105 1 Yingdi Yu
can catch a packet with name "/localhost/example/data" but cannot catch a packet with name "/localhost/another_example".
106 7 Yingdi Yu
107
And a target 
108
109 1 Yingdi Yu
    target
110
    {
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 8 Yingdi Yu
A packet can satisfy the **target** only if the regex can match the packet name.
122 7 Yingdi Yu
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 1 Yingdi Yu
For example, a target 
124 7 Yingdi Yu
125 1 Yingdi Yu
    target
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