Project

General

Profile

CommandValidatorConf » History » Version 8

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