Validator Configuration File Format¶

You can set up a Validator via a configuration file.
Next, we will show you how to write a configuration file.

The configuration file consists of rules that will be used in validation.
Here is an example of configuration file containing two rules.

rule
{
  id "Simple Rule"
  for data
  filter
  {
    type name
    name /localhost/example
    relation isPrefixOf
  }
  checker
  {
    type customized
    sig-type rsa-sha256
    key-locator
    {
      type name
      name /ndn/edu/ucla/KEY/yingdi/ksk-1234/ID-CERT
      relation equal
    }
  }
}
rule
{
  id "Testbed Validation Rule"
  for data
  filter
  {
    type name
    regex ^<>*$
  }
  checker
  {
    type hierarchical
    trust-anchor
    {
      type file
      file-name "testbed-trust-anchor.cert"
    }
  }
}

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 be applied;
• The second part is to check whether further validation process is necessary.

When receiving a packet, the validator will apply rules in the configuration file one-by-one against the packet,
until finding a rule that the packet qualifies for.
And the second part of the matched rule will be used to check the validity of the packet.
If the packet cannot qualify for any rules, it is treated as an invalid packet.
Once a packet has been matched by a rule, the rest rules will not be applied against the packet.
Therefore, you should always put the most specific rule to the top, otherwise it will become useless.

In the example configuration,
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".
If a packet does not have a name under prefix "/localhost/example", validator will skip the first rule and apply the second rule.
The second rule indicates that any data packets must be validated along a hierarchy with a trust anchor stored in a file called "testbed-trust-anchor.cert".

Rules in general¶

A rule is defined via several properties.
For properties are required: id, for, filter, and checker.

The property id uniquely identifies the rule in the configuration file.
As long as being unique, any name can be given to a rule, e.g., "Simple Rule", "Testbed Validation Rule".

A rule is either used to validate an interest packet or a data packet.
This information is specified in the property for.
Only two value can be specified: data and interest.

The property filter further constrains the packets that can be checked by the rule.
A rule may contain more than one filters.
A packet can be checked by a rule only if the packet satisfies all the filters.

The property checker defines the conditions that a qualified packet must fulfill to be treated as a valid packet.
Unlike the filter property, one and only one checker property must be specified in a rule.

filter and checker have their own properties.
Next we will introduce them separately.

Filter Property¶

Filter has its own property type.
Although a rule may contain more than one filters, there is at most one filter of each type.
So far, only one filter type is defined: name.
In other word, only one filter can be specified in a rule for now.

There are two ways to express the conditions on name.
The first way is to specify a relationship between the packet name and a particular name.
In this case, two more properties are required: name and relation.
A packet can fulfill the condition if the name has a relation* to the packet name.
Three types of **relation has been defined: equal, isPrefixOf, isStrictPrefixOf.
For example, a filter

filter
{
  type name
  name /localhost/example
  relation equal
}

shall only capture a packet with the exact name "/localhost/example".
And a filter

filter
{
  type name
  name /localhost/example
  relation isPrefixOf
}

shall capture a packet with name "/localhost/example" or "/localhost/example/data", but cannot catch a packet with name "/localhost/another_example".
And a filter

filter
{
  type name
  name /localhost/example
  relation isStrictPrefixOf
}

shall capture a packet with name "/localhost/example/data", but cannot catch a packet with name "/localhost/example".

The second way is to specify an NDN Regular Expression that can match the packet.
In this case, only one property regex is required.
For example, a filter

filter
{
  type name
  regex ^[^<KEY>]*<KEY><>*<ksk-.*><ID-CERT>$
}

shall capture all the identity certificates.

Checker Property¶

The checker property defines the conditions that the SignatureInfo part of the packet must fulfill.
Same as the filter property, a rule may contain more than one checker properties.
A packet, however, only needs to satisfy one of the checker properties.

A checker property requires a sig-type property which specifies the acceptable signature type.
Right now only one signature type rsa-sha256 is defined.

A checker property also requires a key-locator property which specifies the conditions on KeyLocator.
Right now only one key-locator type name is defined.
Such a type of key-locator contains the certificate name of the signing key.
Since the key-locator is a name, you can specify the conditions on it in the same way as the filter with type name.
For example, a checker could be:

checker
{
  sig-type rsa-sha256
  key-locator
  {
    type name
    name /ndn/edu/ucla/KEY/yingdi/ksk-1234/ID-CERT
    relation equal
  }
}

This checker 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".

Besides the two ways to express conditions on key-locator name (name and regex),
you can further constrain the key-locator name using the information extracted from the packet name.
This third type of condition is expressed via a property hyper-relation.
The hyper-relation property consists of three parts:

• an NDN regular expression that can extract information from packet name
• an NDN regular expression that can extract information from key-locator name
• relation between the two parts above

For example, a checker:

checker
{
  sig-type rsa-sha256
  key-locator
  {
    type name
    hyper-relation
    {
      p-regex ^(<>*)$
      p-expand \1
      k-regex ^([^<KEY>]*)<KEY>(<>*)<ksk-.*><ID-CERT>$
      k-expand \1\2
      relation isPrefixOf
    }
  }
}

requires the packet name must be under the corresponding namespace of the key-locator name.

In some cases, the checker property may contain a trust-anchor property which specifies the pre-trusted certificate.
For example, a checker with a trust-anchor property could be:

checker
{
  sig-type rsa-sha256
  key-locator
  {
    type name
    hyper-relation
    {
      p-regex ^(<>*)$
      p-expand \1
      k-regex ^([^<KEY>]*)<KEY>(<>*)<ksk-.*><ID-CERT>$
      k-expand \1\2
      relation isPrefixOf
    }
  }
  trust-anchor
  {
    type file
    file-name "testbed-trust-anchor.cert"
  }
}

Note that the trust-anchor must fulfill the conditions specified in sig-type and key-locator.

Hierarchical Rule¶

As implied by its name, hierarchical rule requires that the packet name must be under the namespace of the packet checker.
Therefore, you only need to specify two properties in hierarchical rule:

• a filter of type name which restrict the scope of packets
• trust-anchors of the hierarchy

For the hierarchical rule in the example configuration, it is equivalent to a customized rule:

rule
{
  id "Testbed Validation Rule"
  for data
  type customized
  filter
  {
    type name
    regex ^(<>*)$
    expand \1
  }
  checker
  {
    sig-type rsa-sha256
    key-locator
    {
      type name
      hyper-relation
      {
        p-regex ^(<>*)$
        p-expand \1
        k-regex ^([^<KEY>]*)<KEY>(<>*)<ksk-.*><ID-CERT>$
        k-expand \1\2
        relation isPrefixOf
      }
    }
    trust-anchor
    {
      type file
      file-name "testbed-trust-anchor.cert"
    }
  }
}

Example Configuration For NLSR¶

The trust model of NLSR is semi-hierarchical.
An example certificate signing hierarchy is:

                                        root 
                                         |          
                          +--------------+---------------+
                        site1                          site2
                          |                              |         
                +---------+---------+                    +
             operator1           operator2            operator3
                |                   |                    | 
          +-----+-----+        +----+-----+        +-----+-----+--------+
       router1     router2  router3    router4  router5     router6  router7
          |           |        |          |        |           |        |
          +           +        +          +        +           +        +         
        NLSR        NSLR     NSLR       NSLR     NSLR        NSLR     NSLR

However, entities name may not follow the signing hierarchy, for example:

Entity	Identity Name	Example	Certificate Name Example
root	/<network>	/ndn	/ndn/KEY/ksk-1/ID-CERT/%01
site	/<network>/<site>	/ndn/edu/ucla	/ndn/edu/ucla/KEY/ksk-2/ID-CERT/%01
operator	/<network>/<site>/%C1.O.N./<operator-id>	/ndn/edu/ucla/%C1.O.N./op1	/ndn/edu/ucla/%C1.O.N./op1/KEY/ksk-3/ID-CERT/%01
router	/<network>/<site>/%C1.O.R./<router-id>	/ndn/edu/ucla/%C1.O.R./rt1	/ndn/edu/ucla/%C1.O.R./rt1/KEY/ksk-4/ID-CERT/%01
NLSR	/<network>/<site>/%C1.O.R./<router-id>/NLSR	/ndn/edu/ucla/%C1.O.R./rt1/NLSR	/ndn/edu/ucla/%C1.O.R./rt1/NLSR/KEY/ksk-5/ID-CERT/%01

Assume that a typical NLSR data name is "/ndn/edu/ucla/%C1.O.R./rt1/NLSR/LSA/LSType.1/%01".
Then, the exception of naming hierarchy is "operator-router".
So we can write a configuration file with three rules.
The first one is a customized rule that capture the normal NLSR data.
The second one is a customized rule that handles the exception case of the hierarchy (operator->router).
And the 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 most frequently checked.
The hierarchical exception rule is put to the second, because it is more specific than the last one.

And here is the configuration file:

rule
{
  id "NSLR LSA Rule"
  for data
  type customized
  filter
  {
    type name
    regex ^[^<NLSR><LSA>]*<NLSR><LSA>
  }
  checker
  {
    sig-type rsa-sha256
    key-locator
    {
      type name
      hyper-relation
      {
        p-regex ^([^<NLSR><LSA>]*)<NLSR><LSA><LSType\.\d><>$
        p-expand \1
        k-regex ^([^<KEY>]*)<KEY><ksk-.*><ID-CERT>$
        k-expand \1
        relation equal
      }
    }
  }
}
rule
{
  id "NSLR Hierarchy Exception Rule"
  for data
  type customized
  filter
  {
    type name
    regex ^[^<KEY><%C1.O.R.>]*<%C1.O.R.><><KEY><ksk-.*><ID-CERT><>$
  }
  checker
  {
    sig-type rsa-sha256
    key-locator
    {
      type name
      hyper-relation
      {
        p-regex ^([^<KEY><%C1.O.R.>]*)<%C1.O.R.><><KEY><ksk-.*><ID-CERT><>$
        p-expand \1
        k-regex ^([^<KEY><%C1.O.N.>]*)<%C1.O.N.><><KEY><ksk-.*><ID-CERT>$
        k-expand \1
        relation equal
      }
    }
  }
}
rule
{
  id "NSLR Hierarchical Rule"
  for data
  type hierarchical
  target
  {
    type name
    regex ^([^<KEY>]*)<KEY><ksk-.*><ID-CERT><>$
  }
  trust-anchor
  {
    type file
    file-name "testbed-trust-anchor.cert"
  }
}