Project

General

Profile

CommandValidatorConf » History » Version 9

Yingdi Yu, 03/18/2014 02:05 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
Each rule can be broken into two parts: 
43
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
47
When receiving a packet, the validator will check rules in the configuration file one-by-one, 
48
49
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".
50
51 1 Yingdi Yu
Each rule has a unique name (which should be unique in the configuration file), e.g., "Simple Rule", "Testbed Validation Rule".
52
The rule name is specified in the property **name**. 
53 6 Yingdi Yu
Each rule must be specified with a usage which is specified in the property **for**. 
54
The usage indicates the type of packets to which the rule should be applied, therefore, only two usages can be specified so far: **data** and **interest**.
55 1 Yingdi Yu
The property **type** indicates how to apply the rule to packets.
56 9 Yingdi Yu
Some rule types (such as **hierarchical**) has been pre-defined. 
57
One can also customize its own rules by setting the type property to be **customized**.
58
Some other properties are required depending on the rule type. 
59 1 Yingdi Yu
Next, we will introduce the other properties for the each rule type.
60
61
## Customized Rule
62 7 Yingdi Yu
63 9 Yingdi Yu
Two properties are required by **customized rule**: **filter** and **signer**.
64 7 Yingdi Yu
And some optional properties may be configured if necessary.
65
66 9 Yingdi Yu
### Filter Property
67 1 Yingdi Yu
68 9 Yingdi Yu
The **filter** property specifies which packets to which the rule can be applied.
69
A rule may contain more than one **filter** properties, a packet can be caught by a rule only if the packet satisfy all the **filter** properties.
70 8 Yingdi Yu
71 9 Yingdi Yu
A packet will be checked against the **filter** properties of rules in the configuration file,
72 1 Yingdi Yu
one-by-one until the first rule whose **target** property can be satisfied by the packet.
73
Once the packet is caught by a rule, no other rules will be applied to the packet.
74 8 Yingdi Yu
Therefore, <font color='red'>**the order of rules in configuration file MATTERS!**</font>
75 1 Yingdi Yu
If the packet cannot satisfy any rules, it will be treated as **invalid** packet.
76 8 Yingdi Yu
77
The **target** has its own property **type** which indicates the type of condition.
78
Although a rule may contain more than one **target** properties, there is at most one **target** property for each type.
79
So far, only one target type is supported: **name**.
80 7 Yingdi Yu
In other word, only one **target** property can be specified for now.
81 8 Yingdi Yu
82
There are two ways to express the restriction on name. 
83
The first way is to specify a relationship between the packet name and a particular name.
84 7 Yingdi Yu
In this case, two more properties are required: **name** and **relation**.
85
A packet can satisfy the condition if the **name** and the packet name can establish the **relation**.
86
The value of **relation** could be either **isPrefixOf** or **equal**. 
87 6 Yingdi Yu
For example, a target:
88 7 Yingdi Yu
89
    target
90
    {
91
      type name
92
      name "/localhost/example"
93
      relation isPrefixOf
94 1 Yingdi Yu
    }
95 7 Yingdi Yu
96 1 Yingdi Yu
can catch a packet with name "/localhost/example/data" but cannot catch a packet with name "/localhost/another_example".
97 7 Yingdi Yu
98
And a target 
99
100 1 Yingdi Yu
    target
101
    {
102
      type name
103
      name "/localhost/example"
104 7 Yingdi Yu
      relation equal
105
    }
106 1 Yingdi Yu
107
can only catch a packet with the exact name "/localhost/example".
108 8 Yingdi Yu
109
The second way is to specify an NDN regular expression that the packet name must match.
110
In this case, only one property **regex** is required.
111 7 Yingdi Yu
The value of **regex** is an NDN regular expression.
112 8 Yingdi Yu
A packet can satisfy the **target** only if the regex can match the packet name.
113 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.
114 1 Yingdi Yu
For example, a target 
115 7 Yingdi Yu
116 1 Yingdi Yu
    target
117 8 Yingdi Yu
    {
118
      type name
119 7 Yingdi Yu
      regex "^([^<KEY>]*)<KEY>(<>*)<ksk-.*><ID-CERT>$"
120 1 Yingdi Yu
      expand "\\1\\2"
121 7 Yingdi Yu
    }
122 1 Yingdi Yu
123
can catch all the identity certificates and extract the corresponding namespace of the certificate.
124 7 Yingdi Yu
125 8 Yingdi Yu
### Signer Property
126 1 Yingdi Yu
127 8 Yingdi Yu
The **signer** property defines the conditions that the signer (or `KeyLocator`) must fulfill.
128
The structure of the **signer** property is the same as the **target** property.
129
And same as **target** property, a rule may contain more than one **signer** properties.
130 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.
131 8 Yingdi Yu
132 7 Yingdi Yu
### Relation Property
133 8 Yingdi Yu
134
The **relation** property is optional.
135 7 Yingdi Yu
If the **relation** property is set, then 
136 8 Yingdi Yu
137
138
139 6 Yingdi Yu
140
## Hierarchical Rule
141
142
As implied by its name, hierarchical rule requires the name of the target packet to be under the namespace of the packet signer.
143
Assume that the usage of the rule is for data, then it is equivalent to a customized rule:
144
145
    rule
146
    {
147
      for data
148
      name "Expanded Hierarchical Rule"
149
      type customized
150
      target
151 1 Yingdi Yu
      {
152
        type regex
153
        expr "^(<>*)$"
154
        expand "\\1"
155
      }
156 6 Yingdi Yu
      signer
157 1 Yingdi Yu
      {
158
        type regex
159 6 Yingdi Yu
        expr "^([^<KEY>]*)<KEY>(<>*)<ksk-.*><ID-CERT>$"
160 1 Yingdi Yu
        expand "\\1\\2"
161 6 Yingdi Yu
      }
162 8 Yingdi Yu
      relation isPrefixOf
163
      anchor
164
      {
165
        type file
166
        file-name "trust-anchor.cert"
167 6 Yingdi Yu
      }
168 8 Yingdi Yu
    }
169
170 1 Yingdi Yu
## The Order Of Rules