Validator Configuration File Format¶
Contents
You can set up aValidator via a configuration file. Next, we will show you how towrite a configuration file.
The configuration file consists ofrules andtrust-anchors that will be used invalidation.Rules tell the validator how to validate a packet, whiletrust-anchorstell the validator which certificates are valid immediately. Here is an example ofconfiguration file containing two rules and a trust anchor.
rule{id"Simple Rule"fordatafilter{typenamename/localhost/examplerelationis-prefix-of}checker{typecustomizedsig-typersa-sha256key-locator{typenamename/ndn/edu/ucla/yingdi/KEY/1234relationequal}}}rule{id"Testbed Validation Rule"fordatachecker{typehierarchicalsig-typersa-sha256}}trust-anchor{typefilefile-name"testbed-trust-anchor.cert"}
Note
ATTENTION: The order of rules MATTERS!
A rule can be broken into two parts:
- The first part is to qualify packets to which the rule can beapplied;
- The second part is to check whether further validation process isnecessary.
When a packet is presented for validation, the validator will check the rules one-by-onein the configuration file usingfor andfilter conditions against the packet,until finding a rule for which the packet qualifies. After that, thecheckerconditions of the matched rule will be used to check the validity of the packet. If thepacket does not match any rules, it is treated as an invalid packet. Once a packet hasbeen matched by a rule, the remaining rules are not applied to the packet (i.e., thematched rule “captures” the packet). Therefore, you should always put the most specificrule first.
In the example configuration, the first rule indicates that all the data packets under thename prefix/localhost/example must be signed by a certificate whose name (the keypart) is/ndn/edu/ucla/yingdi/KEY/1234. If a packet does not have a name underprefix/localhost/example, the validator will skip the first rule and apply the secondrule. The second rule indicates that all other data packets must be validated using thehierarchical policy (data name should be prefix or equal to the identity part of thecertificate name). The example configuration defines that all certificate chains must berooted in the certificate defined in the file “testbed-trust-anchor.cert”.
Rules in general¶
A rule has four properties:id,for,filter, andchecker.
Theid property uniquely identifies the rule in the configuration file. As long asbeing unique, any name can be given to a rule, e.g., “Simple Rule”, “Testbed ValidationRule”. A rule must have one and only oneid property.
A rule is either used to validate a data packet or an interest packet. This informationis specified in thefor property, which can be eitherdata orinterest. Arule must have exactly onefor property.
Thefilter property further constrains the packets that can be checked by therule. The filter property is not required in a rule; if omitted, the rule will capture allpackets passed to it. A rule may contain multiple filters, in this case, a packetis captured by the rule only if all filters are satisfied.
Note
ATTENTION: A packet that satisfies all the filters may not be valid.
Thechecker property defines the conditions that a matched packet must fulfill to betreated as a valid packet. A rule must have at least onechecker property. A packet istreated as valid if it can pass at least one of the checkers and as invalid when it cannotpass any checkers.
Filter Property¶
Filter has atype property and type-specific properties. Although a rule can containmore than one filters, there can be at most one filter of each type.
Currently, only the packet name filter is defined.
Name Filter¶
There are two ways to express the conditions on packet name:
- relationship between the packet name and the specified name
- NDN regular expression match.
Name and Relation¶
In the first case, two more properties are required:name andrelation. A packetcan fulfill the condition if thename has arelation to the packet’s name. Threetypes ofrelation has been defined:equal,is-prefix-of,is-strict-prefix-of. For example, the filter
filter{typenamename/localhost/examplerelationequal}
will capture only a packet with the exact name/localhost/example.
The filter
filter{typenamename/localhost/examplerelationis-prefix-of}
will capture a packet with name/localhost/example or/localhost/example/data, butwill not capture a packet with name/localhost/another_example. And the filter
filter{typenamename/localhost/examplerelationis-strict-prefix-of}
will capture a packet with name/localhost/example/data, but will not capture a packetwith name/localhost/example.
NDN Regular Expression Match¶
The second way is to specify anNDN Regular Expression that can match the packet. In thiscase, only one propertyregex is required. For example, the filter
filter{ type name regex ^<>*<KEY><><><>$}will capture all certificates.
Checker Property¶
Passing all the filters in a rule only indicates that a packet can be checked using therule, and it does not necessarily imply that the packet is valid. The validity of apacket is determined by the propertychecker, which defines the conditions that avalid packet must fulfill.
Same asfilter,checker has a propertytype. We have defined two types ofcheckers:
- customized is a checker that allows customization of the conditions according to specificrequirements;
- hierarchical is a checker with pre-defined hierarchical trust model.
Customized Checker¶
The customized checker requires two properties:sig-type,key-locator. Both mustappear exactly once and are related to theSignatureInfo of a packet.
checker{typecustomizedsig-type...key-locator{...}}
The propertysig-type specifies the acceptable signature type and can bersa-sha256,ecdsa-sha256 (strong signature types), orsha256 (weak signaturetype). If sig-type is sha256,key-locator is ignored, and the validator will simplycalculate the digest of a packet and compare it with the one inSignatureValue. Ifsig-type is rsa-sha256 or ecdsa-sha256, you have to further customize the checker withkey-locator.
The propertykey-locator specifies the conditions onKeyLocator. If thekey-locator property is specified, it requires the existence of theKeyLocatorfield inSignatureInfo.key-locator property only supports one type:name:
key-locator{typename...}
This key-locator property specifies the conditions on the certificate name of the signingkey. Since the conditions are about name, they can be specified in the same way as thename filter. For example, a checker can be:
checker{typecustomizedsig-typersa-sha256key-locator{typenamename/ndn/edu/ucla/yingdi/KEY/1234relationequal}}
This checker property requires that the packet must have arsa-sha256 signature thatcan be verified with/ndn/edu/ucla/yingdi/KEY/1234 key.
Besides the two ways to express conditions on theKeyLocator name (name and regex),you can further constrain theKeyLocator name using the information extracted from thepacket name. This third type of condition is expressed via a propertyhyper-relation. Thehyper-relation property consists of three parts:
- an NDN regular expression that extracts information from the packet name
- an NDN regular expression that extracts information from the
KeyLocatorname - relation from the part extracted from the
KeyLocatorname to the one extracted fromthe packet name
For example, a checker:
checker{ type customized sig-type rsa-sha256 key-locator { type name hyper-relation { k-regex ^(<>*)<KEY><>$ k-expand \\1 h-relation is-prefix-of p-regex ^(<>*)$ p-expand \\1 } }}requires the packet name must be under the corresponding namespace (identity part) of theKeyLocator name.
Hierarchical Checker¶
As implied by its name, hierarchical checker requires that the packet name must be underthe namespace of the packet signer. A hierarchical checker:
checker{typehierarchicalsig-typersa-sha256}
is equivalent to a customized checker:
checker{ type customized sig-type rsa-sha256 key-locator { type name hyper-relation { k-regex ^(<>*)<KEY><>$ k-expand \\1 h-relation is-prefix-of p-regex ^(<>*)$ p-expand \\1 } }}Trust Anchors¶
trust-anchor is a necessary option in order to properly validate packets. Aconfiguration file may contain more than one trust anchors and the order of trust anchorsdoes not matter. The structure of trust-anchor is as follows:
trust-anchor{typefilefile-name"trusted-signer.cert"}trust-anchor{typebase64base64-string"Bv0DGwdG...amHFvHIMDw=="}
You may also specify a trust-anchor directory. All certificates under this directory aretaken as static trust anchors. For example, if all trust anchors are put into/usr/local/etc/ndn/keys.
trust-anchor{typedirdir/usr/local/etc/ndn/keys}
If certificates under the directory might be changed during runtime, you can set a refreshperiod, such as
trust-anchor{typedirdir/usr/local/etc/ndn/keysrefresh1h;refreshcertificateseveryhour,otherunitsincludem(forminutes)ands(forseconds)}
There is also a special trust anchorany. As long as such a trust-anchor is definedin config file, packet validation will be turned off.
Note
ATTENTION: This type of trust anchor is dangerous. You should used it only when youwant to disable packet validation temporarily (e.g, debugging code, building a demo).
trust-anchor{typeany}
Example Configuration For NLSR¶
The trust model of NLSR is semi-hierarchical. An example certificate signing hierarchy is:
root|+--------------+---------------+site1site2||+---------+---------++operator1operator2operator3|||+-----+-----++----+-----++-----+-----+--------+router1router2router3router4router5router6router7|||||||+++++++NLSRNSLRNSLRNSLRNSLRNSLRNSLR
However, entities name may not follow the signing hierarchy, forexample:
| Entity | Identity name and examples |
|---|---|
| root |
Identity example: Certificate name example: |
| site |
Identity example: Certificate name example: |
| operator |
Identity example: Certificate name example: |
| router |
Identity example: Certificate name example: |
| NLSR |
Identity example: Certificate name example: |
Assume that a typical NLSR data name is/ndn/edu/ucla/%C1.O.R./rt1/NLSR/LSA/LSType.1/%01. Then, the exception of naminghierarchy is “operator-router”. So we can write a configuration file with three rules. Thefirst one is a customized rule that capture the normal NLSR data. The second one is acustomized rule that handles the exception case of the hierarchy (operator->router). Andthe last one is a hierarchical rule that handles the normal cases of the hierarchy.
We put the NLSR data rule to the first place, because NLSR data packets are the mostfrequently checked. The hierarchical exception rule is put to the second, because it ismore specific than the last one.
And here is the configuration file:
rule{ id "NSLR LSA Rule" for data filter { type name regex ^<>*<NLSR><LSA><><>$ } checker { type customized sig-type rsa-sha256 key-locator { type name hyper-relation { k-regex ^(<>*)<KEY><>$ k-expand \\1 h-relation equal p-regex ^(<>*)<NLSR><LSA><><>$ p-expand \\1 } } }}rule{ id "NSLR Hierarchy Exception Rule" for data filter { type name regex ^<>*<%C1.O.R.><><KEY><><><>$ } checker { type customized sig-type rsa-sha256 key-locator { type name hyper-relation { k-regex ^(<>*)<%C1.O.N.><><KEY><>$ k-expand \\1 h-relation equal p-regex ^(<>*)<%C1.O.R.><><KEY><><><>$ p-expand \\1 } } }}rule{ id "NSLR Hierarchical Rule" for data filter { type name regex ^<>*<KEY><><><>$ } checker { type hierarchical sig-type rsa-sha256 }}trust-anchor{ type file file-name "testbed-trust-anchor.cert"}Example Configuration For NFD RIB Management¶
AssumeNFD RIB Managementallows any valid testbed certificate to register prefix, the configuration file could bewritten as:
rule{ id "RIB Prefix Registration Command Rule" for interest ; rule for Interests (to validate CommandInterests) filter { type name ; condition on interest name (w/o signature) regex ^[<localhop><localhost>]<nfd><rib>[<register><unregister>]<><><>$ ; prefix before ; SigInfo & SigValue } checker { type customized sig-type rsa-sha256 ; interest must have a rsa-sha256 signature key-locator { type name ; key locator must be the certificate name of the ; signing key regex ^<>*<KEY><><><>$ } } checker { type customized sig-type ecdsa-sha256 ; interest must have a ecdsa-sha256 signature key-locator { type name ; key locator must be the certificate name of the ; signing key regex ^<>*<KEY><><><>$ } }}rule{ id "NDN Testbed Hierarchy Rule" for data ; rule for Data (to validate NDN certificates) filter { type name ; condition on data name regex ^<>*<KEY><><><>$ } checker { type hierarchical ; the certificate name of the signing key and ; the data name must follow the hierarchical model sig-type rsa-sha256 ; data must have a rsa-sha256 signature } checker { type hierarchical ; the certificate name of the signing key and ; the data name must follow the hierarchical model sig-type ecdsa-sha256 ; data must have a ecdsa-sha256 signature }}trust-anchor{ type file file-name keys/ndn-testbed-root.ndncert.base64}