NFD » ndn-cxx

# 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

      type customized

      filter

      {

        type name

        name "/localhost/example"

        relation isPrefixOf

      }

      signer

      {

        type name

        name "/ndn/edu/ucla/KEY/yingdi/ksk-1234/ID-CERT"

        relation equal

      }

    }

    rule

    {

      id "Testbed Validation Rule"

      for data

      type hierarchical

      trust-anchor

      {

        type file

        file-name "testbed-trust-anchor.cert"

      }

    }

<font color='red'>**ATTENTION: The order of rules MATTERS!**</font>

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 decide whether further validation process is necessary.

When receiving a packet, the validator will check it against rules in the configuration file one-by-one,

until reaching a rule that the packet qualifies for.

And the second part of the matching rule will be used to check the validity of the packet.

If the packet cannot qualify any rules, it is treated as an invalid packet.

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 check the second rule.

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

Each rule has a unique name (which should be unique in the configuration file), e.g., "Simple Rule", "Testbed Validation Rule".

The rule name is specified in the property **name**. 

Each rule must be specified with a usage which is specified in the property **for**. 

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**.

The property **type** indicates how to apply the rule to packets.

Some rule types (such as **hierarchical**) has been pre-defined. 

One can also customize its own rules by setting the type property to be **customized**.

Some other properties are required depending on the rule type. 

Next, we will introduce the other properties for the each rule type.

## Customized Rule

Two properties are required by **customized rule**: **filter** and **signer**.

And some optional properties may be configured if necessary.

### Filter Property

The **filter** property specifies which packets to which the rule can be applied.

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.

A packet will be checked against the **filter** properties of rules in the configuration file,

one-by-one until the first rule whose **target** property can be satisfied by the packet.

Once the packet is caught by a rule, no other rules will be applied to the packet.

Therefore, <font color='red'>**the order of rules in configuration file MATTERS!**</font>

If the packet cannot satisfy any rules, it will be treated as **invalid** packet.

The **target** has its own property **type** which indicates the type of condition.

Although a rule may contain more than one **target** properties, there is at most one **target** property for each type.

So far, only one target type is supported: **name**.

In other word, only one **target** property can be specified for now.

There are two ways to express the restriction 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 satisfy the condition if the **name** and the packet name can establish the **relation**.

The value of **relation** could be either **isPrefixOf** or **equal**. 

For example, a target:

    target

    {

      type name

      name "/localhost/example"

      relation isPrefixOf

    }

can catch a packet with name "/localhost/example/data" but cannot catch a packet with name "/localhost/another_example".

And a target 

    target

    {

      type name

      name "/localhost/example"

      relation equal

    }

can only catch a packet with the exact name "/localhost/example".

The second way is to specify an NDN regular expression that the packet name must match.

In this case, only one property **regex** is required.

The value of **regex** is an NDN regular expression.

A packet can satisfy the **target** only if the regex can match the packet name.

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.

For example, a target 

    target

    {

      type name

      regex "^([^<KEY>]*)<KEY>(<>*)<ksk-.*><ID-CERT>$"

      expand "\\1\\2"

    }

can catch all the identity certificates and extract the corresponding namespace of the certificate.

### Signer Property

The **signer** property defines the conditions that the signer (or `KeyLocator`) must fulfill.

The structure of the **signer** property is the same as the **target** property.

And same as **target** property, a rule may contain more than one **signer** properties.

However, as long as one of the **signer** properties is satisfied, the packet validation can proceed without treating the packet as invalid.

### Relation Property

The **relation** property is optional.

If the **relation** property is set, then 

## Hierarchical Rule

As implied by its name, hierarchical rule requires the name of the target packet to be under the namespace of the packet signer.

Assume that the usage of the rule is for data, then it is equivalent to a customized rule:

    rule

    {

      for data

      name "Expanded Hierarchical Rule"

      type customized

      target

      {

        type regex

        expr "^(<>*)$"

        expand "\\1"

      }

      signer

      {

        type regex

        expr "^([^<KEY>]*)<KEY>(<>*)<ksk-.*><ID-CERT>$"

        expand "\\1\\2"

      }

      relation isPrefixOf

      anchor

      {

        type file

        file-name "trust-anchor.cert"

      }

    }

## The Order Of Rules