| Validator Configuration File Format |
| =================================== |
| |
| .. contents:: |
| |
| 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** and **trust-anchors** that will be used in |
| validation. **Rules** tell the validator how to validate a packet, while **trust-anchors** |
| tell the validator which certificates are valid immediately. Here is an example of |
| configuration file containing two rules and a trust anchor. |
| |
| :: |
| |
| rule |
| { |
| id "Simple Rule" |
| for data |
| filter |
| { |
| type name |
| name /localhost/example |
| relation is-prefix-of |
| } |
| checker |
| { |
| type customized |
| sig-type rsa-sha256 |
| key-locator |
| { |
| type name |
| name /ndn/edu/ucla/yingdi/KEY/1234 |
| relation equal |
| } |
| } |
| } |
| rule |
| { |
| id "Testbed Validation Rule" |
| for data |
| checker |
| { |
| type hierarchical |
| sig-type rsa-sha256 |
| } |
| } |
| 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 a packet is presented for validation, the validator will check the rules one-by-one |
| in the configuration file using **for** and **filter** conditions against the packet, |
| until finding a rule for which the packet qualifies. After that, the **checker** |
| conditions of the matched rule will be used to check the validity of the packet. If the |
| packet does not match any rules, it is treated as an invalid packet. Once a packet has |
| been matched by a rule, the remaining rules are not applied to the packet (i.e., the |
| matched rule "captures" the packet). Therefore, you should always put the most specific |
| rule first. |
| |
| In the example configuration, the first rule indicates that all the data packets under the |
| name prefix ``/localhost/example`` must be signed by a certificate whose name (the key |
| part) is ``/ndn/edu/ucla/yingdi/KEY/1234``. If a packet does not have a name under |
| prefix ``/localhost/example``, the validator will skip the first rule and apply the second |
| rule. The second rule indicates that all other data packets must be validated using the |
| hierarchical policy (data name should be prefix or equal to the identity part of the |
| certificate name). The example configuration defines that all certificate chains must be |
| rooted in the certificate defined in the file "testbed-trust-anchor.cert". |
| |
| Rules in general |
| ---------------- |
| |
| A rule has four properties: **id**, **for**, **filter**, and **checker**. |
| |
| The **id** property 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 must have one and only one **id** property. |
| |
| A rule is either used to validate a data packet or an interest packet. This information |
| is specified in the **for** property, which can be either **data** or **interest**. A |
| rule must have exactly one **for** property. |
| |
| The **filter** property further constrains the packets that can be checked by the |
| rule. The filter property is not required in a rule; if omitted, the rule will capture all |
| packets passed to it. A rule may contain multiple filters, in this case, a packet |
| is captured by the rule only if all filters are satisfied. |
| |
| .. attention:: **A packet that satisfies all the filters may not be valid.** |
| |
| The **checker** property defines the conditions that a matched packet must fulfill to be |
| treated as a valid packet. A rule must have at least one **checker** property. A packet is |
| treated as valid if it can pass at least one of the checkers and as invalid when it cannot |
| pass any checkers. |
| |
| Filter Property |
| --------------- |
| |
| Filter has a **type** property and type-specific properties. Although a rule can contain |
| more 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 |
| - :doc:`NDN regular expression <utils-ndn-regex>` match. |
| |
| Name and Relation |
| ^^^^^^^^^^^^^^^^^ |
| |
| In the first case, two more properties are required: **name** and **relation**. A packet |
| can fulfill the condition if the **name** has a **relation** to the packet's name. Three |
| types of **relation** has been defined: **equal**, **is-prefix-of**, |
| **is-strict-prefix-of**. For example, the filter |
| |
| :: |
| |
| filter |
| { |
| type name |
| name /localhost/example |
| relation equal |
| } |
| |
| will capture only a packet with the exact name ``/localhost/example``. |
| |
| The filter |
| |
| :: |
| |
| filter |
| { |
| type name |
| name /localhost/example |
| relation is-prefix-of |
| } |
| |
| will capture a packet with name ``/localhost/example`` or ``/localhost/example/data``, but |
| will not capture a packet with name ``/localhost/another_example``. And the filter |
| |
| :: |
| |
| filter |
| { |
| type name |
| name /localhost/example |
| relation is-strict-prefix-of |
| } |
| |
| will capture a packet with name ``/localhost/example/data``, but will not capture a packet |
| with name ``/localhost/example``. |
| |
| NDN Regular Expression Match |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| The second way is to specify an :doc:`utils-ndn-regex` that can match the packet. In this |
| case, only one property **regex** 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 the |
| rule, and it does not necessarily imply that the packet is valid. The validity of a |
| packet is determined by the property **checker**, which defines the conditions that a |
| valid packet must fulfill. |
| |
| Same as **filter**, **checker** has a property **type**. We have defined two types of |
| checkers: |
| |
| - **customized** is a checker that allows customization of the conditions according to specific |
| requirements; |
| |
| - **hierarchical** is a checker with pre-defined hierarchical trust model. |
| |
| Customized Checker |
| ~~~~~~~~~~~~~~~~~~ |
| |
| The customized checker can include optional **sig-type** property, which specifies the acceptable signature |
| type. If not specified, the checker will only accept ECDSA signature. Possible values for **sig-type** are: |
| |
| - **ecdsa-sha256**: ECDSA signature required (default if **sig-type** not specified) |
| - **rsa-sha256**: RSA signature required |
| - **sha256** (not recommended, as it is not a real signature): SHA256 digest is required |
| |
| If sig-type is **rsa-sha256** or **ecdsa-sha256**, the customized checker requires |
| **key-locator** property. If sig-type is **sha256**, **key-locator** property can be |
| specified, but is optional. |
| |
| :: |
| |
| checker |
| { |
| type customized |
| sig-type rsa-sha256 |
| key-locator |
| { |
| ... |
| } |
| } |
| |
| checker |
| { |
| type customized |
| sig-type sha256 |
| } |
| |
| The **key-locator** property is a nested configuration property that can appear exactly once |
| and specifies conditions on ``KeyLocator``. It requires **type** property that currently |
| supports only one value: **name**. |
| |
| :: |
| |
| key-locator |
| { |
| type name |
| ... |
| } |
| |
| ``KeyLocator`` conditions can be specified in the same way as the name filter. For example, a |
| checker that requires ``SignatureSha256WithRsa`` signature type with ``KeyLocator`` to be exactly |
| ``/ndn/edu/ucla/yingdi/KEY/1234`` can be written as follows: |
| |
| :: |
| |
| checker |
| { |
| type customized |
| sig-type rsa-sha256 |
| key-locator |
| { |
| type name |
| name /ndn/edu/ucla/yingdi/KEY/1234 |
| relation equal |
| } |
| } |
| |
| Similarly, a checker that requires ``SignatureSha256WithEcdsa`` signature with ``KeyLocator`` |
| that follows a regular expression pattern ``<ndn><>*<KEY><>{1,3}`` can be written as follows: |
| |
| :: |
| |
| checker |
| { |
| type customized |
| sig-type ecdsa-sha256 |
| key-locator |
| { |
| type name |
| regex <ndn><>*<KEY><>{1,3} |
| relation equal |
| } |
| } |
| |
| |
| In addition, ``KeyLocator`` can be further constrained using information extracted from the |
| packet name using the **hyper-relation** property. |
| The **hyper-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 ``KeyLocator`` name |
| - relation from the part extracted from the ``KeyLocator`` name to the one extracted from |
| the packet name |
| |
| For example, a checker: |
| |
| :: |
| |
| checker |
| { |
| type customized |
| sig-type rsa-sha256 |
| key-locator |
| { |
| type name |
| hyper-relation |
| { |
| k-regex ^(<>*)<KEY><>{1,3}$ |
| 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 the |
| ``KeyLocator`` name. |
| |
| Hierarchical Checker |
| ~~~~~~~~~~~~~~~~~~~~ |
| |
| As implied by its name, hierarchical checker requires that the packet name must be under |
| the namespace of the packet signer. A hierarchical checker: |
| |
| :: |
| |
| checker |
| { |
| type hierarchical |
| sig-type rsa-sha256 |
| } |
| |
| is equivalent to a customized checker: |
| |
| :: |
| |
| checker |
| { |
| type customized |
| sig-type rsa-sha256 |
| key-locator |
| { |
| type name |
| hyper-relation |
| { |
| k-regex ^(<>*)<KEY><>{1,3}$ |
| k-expand \\1 |
| h-relation is-prefix-of |
| p-regex ^(<>*)$ |
| p-expand \\1 |
| } |
| } |
| } |
| |
| .. _validator-conf-trust-anchors: |
| |
| Trust Anchors |
| ------------- |
| |
| **trust-anchor** is a necessary option in order to properly validate packets. A |
| configuration file may contain more than one trust anchors and the order of trust anchors |
| does not matter. The structure of trust-anchor is as follows: |
| |
| :: |
| |
| trust-anchor |
| { |
| type file |
| file-name "trusted-signer.cert" |
| } |
| trust-anchor |
| { |
| type base64 |
| base64-string "Bv0DGwdG...amHFvHIMDw==" |
| } |
| |
| You may also specify a trust-anchor directory. All certificates under this directory are |
| taken as static trust anchors. For example, if all trust anchors are put into |
| ``/usr/local/etc/ndn/keys``. |
| |
| :: |
| |
| trust-anchor |
| { |
| type dir |
| dir /usr/local/etc/ndn/keys |
| } |
| |
| If certificates under the directory might be changed during runtime, you can set a refresh |
| period, such as |
| |
| :: |
| |
| trust-anchor |
| { |
| type dir |
| dir /usr/local/etc/ndn/keys |
| refresh 1h ; refresh certificates every hour, other units include m (for minutes) and s (for seconds) |
| } |
| |
| There is also a special trust anchor **any**. As long as such a trust-anchor is defined |
| in config file, packet validation will be turned off. |
| |
| .. danger:: |
| This type of trust anchor is dangerous. You should used it only when you |
| want to disable packet validation temporarily (e.g., debugging code, building a demo). |
| |
| :: |
| |
| trust-anchor |
| { |
| type any |
| } |
| |
| |
| 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 and examples | |
| +============+=====================================================================================+ |
| | root | ``/<network>`` | |
| | | | |
| | | Identity example: ``/ndn`` | |
| | | | |
| | | Certificate name example: ``/ndn/KEY/1/%00/%01`` | |
| +------------+-------------------------------------------------------------------------------------+ |
| | site | ``/<network>/<site>`` | |
| | | | |
| | | Identity example: ``/ndn/edu/ucla`` | |
| | | | |
| | | Certificate name example: ``/ndn/edu/ucla/KEY/2/%00/%01`` | |
| +------------+-------------------------------------------------------------------------------------+ |
| | operator | ``/<network>/<site>/%C1.O.N./<operator-id>`` | |
| | | | |
| | | Identity example: ``/ndn/edu/ucla/%C1.O.N./op1`` | |
| | | | |
| | | Certificate name example: ``/ndn/edu/ucla/%C1.O.N./op1/KEY/3/%00/%01`` | |
| +------------+-------------------------------------------------------------------------------------+ |
| | router | ``/<network>/<site>/%C1.O.R./<router-id>`` | |
| | | | |
| | | Identity example: ``/ndn/edu/ucla/%C1.O.R./rt1`` | |
| | | | |
| | | Certificate name example: ``/ndn/edu/ucla/%C1.O.R./rt1/KEY/4/%00/%01`` | |
| +------------+-------------------------------------------------------------------------------------+ |
| | NLSR | ``/<network>/<site>/%C1.O.R./<router-id>/NLSR`` | |
| | | | |
| | | Identity example: ``/ndn/edu/ucla/%C1.O.R./rt1/NLSR`` | |
| | | | |
| | | Certificate name example: ``/ndn/edu/ucla/%C1.O.R./rt1/NLSR/KEY/5/%00/%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 |
| 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 |
| -------------------------------------------- |
| |
| Assume `NFD RIB Management <https://redmine.named-data.net/projects/nfd/wiki/RibMgmt>`_ |
| allows any valid testbed certificate to register prefix, the configuration file could be |
| written 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 |
| } |