This commit also addresses some old issues, such as "using namespace std". Change-Id: I62b8ff97fb2b6f6cfe04b0ad5866bc0797e6e43b Refs: #1660
654 lines
20 KiB
ReStructuredText
654 lines
20 KiB
ReStructuredText
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** 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.
|
|
|
|
::
|
|
|
|
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/KEY/yingdi/ksk-1234/ID-CERT
|
|
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 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. And a certificate stored in
|
|
a file "testbed-trust-anchor.cert" is valid.
|
|
|
|
Rules in general
|
|
----------------
|
|
|
|
A rule has four types of properties: **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 must have one and only
|
|
one **id** property.
|
|
|
|
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**. A rule must have one and
|
|
only one **for** property.
|
|
|
|
The property **filter** further constrains the packets that can be
|
|
checked by the rule. Filter property is not required in a rule, in this
|
|
case, the rule will capture all the packets passed to it. A rule may
|
|
contain more than one filters, in this case, a packet can be checked by
|
|
a rule only if the packet satisfies all the filters.
|
|
|
|
- \ **ATTENTION: A packet that satisfies all the filters may not be
|
|
valid**\ .
|
|
|
|
The property **checker** 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 invalid if it cannot
|
|
pass none of the checkers.
|
|
|
|
**filter** and **checker** have their own properties. Next, we will
|
|
introduce them separately.
|
|
|
|
Filter Property
|
|
---------------
|
|
|
|
Filter has its own **type** property. Although a rule may contain more
|
|
than one filters, there is at most one filter of each type. So far, only
|
|
one type of filter is defined: **name**. In other word, only one filter
|
|
can be specified in a rule for now.
|
|
|
|
Name Filter
|
|
~~~~~~~~~~~
|
|
|
|
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**, **is-prefix-of**, **is-strict-prefix-of**. 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 is-prefix-of
|
|
}
|
|
|
|
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 is-strict-prefix-of
|
|
}
|
|
|
|
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 [[Regex\|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
|
|
----------------
|
|
|
|
Passing all the filters in a rule only indicates that a packet can be
|
|
checked using the rule, and it does not necessarily implies 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
|
|
three types of checkers: **customized**, and **hierarchical**, and
|
|
**fixed-signer**. As suggested by its name, **customized** checker
|
|
allows you to customize the conditions according to specific
|
|
requirements. **hierarchical** checker and **fixed-signer** checker are
|
|
pre-defined shortcuts, which specify specific trust models separately.
|
|
|
|
Customized Checker
|
|
~~~~~~~~~~~~~~~~~~
|
|
|
|
So far, we only allow three customized properties in a customized
|
|
checker: **sig-type**, **key-locator**. All of them are related to the
|
|
``SignatureInfo`` of a packet.
|
|
|
|
::
|
|
|
|
checker
|
|
{
|
|
type customized
|
|
sig-type ...
|
|
key-locator
|
|
{
|
|
...
|
|
}
|
|
}
|
|
|
|
The property **sig-type** specifies the acceptable signature type.
|
|
Right now three signature types have been defined: **rsa-sha256** and
|
|
**ecdsa-sha256** (which are strong signature types) and **sha256**
|
|
(which is a weak signature type).
|
|
If sig-type is sha256, then **key-locator** will be ignored. Validator
|
|
will simply calculate the digest of a packet and compare it with the one
|
|
in ``SignatureValue``. If sig-type is rsa-sha256 or ecdsa-sha256, you
|
|
have to further customize the checker with **key-locator**.
|
|
|
|
The property **key-locator** which specifies the conditions on
|
|
``KeyLocator``. If the **key-locator** property is specified, it
|
|
requires the existence of the ``KeyLocator`` field in ``SignatureInfo``.
|
|
Although there are more than one types of ``KeyLocator`` defined in the
|
|
`Packet Format <http://named-data.net/doc/ndn-tlv/signature.html>`__,
|
|
**key-locator** property only supports one type: **name**:
|
|
|
|
::
|
|
|
|
key-locator
|
|
{
|
|
type name
|
|
...
|
|
}
|
|
|
|
Such a key-locator property specifies the conditions on the certificate
|
|
name of the signing key. Since the conditions are about name, they can
|
|
be specified in the same way as the name filter. For example, a checker
|
|
could be:
|
|
|
|
::
|
|
|
|
checker
|
|
{
|
|
type customized
|
|
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 the ``KeyLocator`` name
|
|
(name and regex), you can further constrain the ``KeyLocator`` 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
|
|
``KeyLocator`` name
|
|
- relation from the part extracted from ``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>]*)<KEY>(<>*)<ksk-.*><ID-CERT>$
|
|
k-expand \\1\\2
|
|
h-relation is-prefix-of
|
|
p-regex ^(<>*)$
|
|
p-expand \\1
|
|
|
|
}
|
|
}
|
|
}
|
|
|
|
requires the packet name must be under the corresponding namespace of
|
|
the ``KeyLocator`` name.
|
|
|
|
In some cases, you can even customize checker with another property For
|
|
example:
|
|
|
|
::
|
|
|
|
checker
|
|
{
|
|
type customized
|
|
sig-type rsa-sha256
|
|
key-locator
|
|
{
|
|
type name
|
|
hyper-relation
|
|
{
|
|
k-regex ^([^<KEY>]*)<KEY>(<>*)<ksk-.*><ID-CERT>$
|
|
k-expand \\1\\2
|
|
h-relation is-prefix-of
|
|
p-regex ^(<>*)$
|
|
p-expand \\1
|
|
}
|
|
}
|
|
}
|
|
|
|
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>]*)<KEY>(<>*)<ksk-.*><ID-CERT>$
|
|
k-expand \\1\\2
|
|
h-relation is-prefix-of
|
|
p-regex ^(<>*)$
|
|
p-expand \\1
|
|
}
|
|
}
|
|
}
|
|
|
|
Fixed-Signer Checker
|
|
~~~~~~~~~~~~~~~~~~~~
|
|
|
|
In some cases, you only accept packets signed with pre-trusted
|
|
certificates, i.e. "one-step validation". Such a trust model can be
|
|
expressed with **fixed-signer** checker. And you only need to specify
|
|
the trusted certificate via property **signer**. The definition of
|
|
**signer** is the same as **trust-anchor**. For example:
|
|
|
|
::
|
|
|
|
checker
|
|
{
|
|
type fixed-signer
|
|
sig-type rsa-sha256
|
|
signer
|
|
{
|
|
type file
|
|
file-name "trusted-signer.cert"
|
|
}
|
|
signer
|
|
{
|
|
type base64
|
|
base64-string "Bv0DGwdG...amHFvHIMDw=="
|
|
}
|
|
}
|
|
|
|
Trust Anchors
|
|
-------------
|
|
|
|
Although **trust-anchor** is always not required in the configuration
|
|
file (for example, if fixed-signer checker is used), it is very common
|
|
to have a few trust-anchors in the configuration file, otherwise most
|
|
packets cannot be validated. A configuration file may contain more than
|
|
one trust anchors, but the order of trust anchors does not matter. The
|
|
structure of trust-anchor is same as the **signer** in fixed-signer
|
|
checker, for example:
|
|
|
|
::
|
|
|
|
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 trust anchors. For example, if all trust anchors are
|
|
put into ``/usr/local/etc/ndn/keys``.
|
|
|
|
::
|
|
|
|
trust-anchor
|
|
{
|
|
type dir
|
|
file-name /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
|
|
file-name /usr/local/etc/ndn/keys
|
|
refresh 1h ; refresh certificates every hour, other units include m (for minutes) and s (for seconds)
|
|
}
|
|
|
|
There is another special trust anchor **any**.
|
|
As long as such a trust-anchor is defined in config file,
|
|
packet validation will be turned off.
|
|
|
|
- **ATTENTION: 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/ksk-1/ID-CERT/%01`` |
|
|
+------------+-------------------------------------------------------------------------------------+
|
|
| site | ``/<network>/<site>`` |
|
|
| | |
|
|
| | Identity example: ``/ndn/edu/ucla`` |
|
|
| | |
|
|
| | Certificate name example: ``/ndn/edu/ucla/KEY/ksk-2/ID-CERT/%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/ksk-3/ID-CERT/%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/ksk-4/ID-CERT/%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/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
|
|
filter
|
|
{
|
|
type name
|
|
regex ^[^<NLSR><LSA>]*<NLSR><LSA>
|
|
}
|
|
checker
|
|
{
|
|
type customized
|
|
sig-type rsa-sha256
|
|
key-locator
|
|
{
|
|
type name
|
|
hyper-relation
|
|
{
|
|
k-regex ^([^<KEY>]*)<KEY><ksk-.*><ID-CERT>$
|
|
k-expand \\1
|
|
h-relation equal
|
|
p-regex ^([^<NLSR><LSA>]*)<NLSR><LSA><LSType\.\d><>$
|
|
p-expand \\1
|
|
}
|
|
}
|
|
}
|
|
}
|
|
rule
|
|
{
|
|
id "NSLR Hierarchy Exception Rule"
|
|
for data
|
|
filter
|
|
{
|
|
type name
|
|
regex ^[^<KEY><%C1.O.R.>]*<%C1.O.R.><><KEY><ksk-.*><ID-CERT><>$
|
|
}
|
|
checker
|
|
{
|
|
type customized
|
|
sig-type rsa-sha256
|
|
key-locator
|
|
{
|
|
type name
|
|
hyper-relation
|
|
{
|
|
k-regex ^([^<KEY><%C1.O.N.>]*)<%C1.O.N.><><KEY><ksk-.*><ID-CERT>$
|
|
k-expand \\1
|
|
h-relation equal
|
|
p-regex ^([^<KEY><%C1.O.R.>]*)<%C1.O.R.><><KEY><ksk-.*><ID-CERT><>$
|
|
p-expand \\1
|
|
}
|
|
}
|
|
}
|
|
}
|
|
rule
|
|
{
|
|
id "NSLR Hierarchical Rule"
|
|
for data
|
|
filter
|
|
{
|
|
type name
|
|
regex ^[^<KEY>]*<KEY><ksk-.*><ID-CERT><>$
|
|
}
|
|
checker
|
|
{
|
|
type hierarchical
|
|
sig-type rsa-sha256
|
|
}
|
|
}
|
|
trust-anchor
|
|
{
|
|
type file
|
|
file-name "testbed-trust-anchor.cert"
|
|
}
|
|
|
|
Example Configuration For NRD
|
|
-----------------------------
|
|
|
|
Assume NRD allows any valid testbed certificate to register prefix, the
|
|
configuration file could be written as:
|
|
|
|
::
|
|
|
|
rule
|
|
{
|
|
id "NRD Prefix Registration Command Rule"
|
|
for interest
|
|
filter
|
|
{
|
|
type name
|
|
regex ^<localhost><nrd>[<register><unregister><advertise><withdraw>]
|
|
}
|
|
checker
|
|
{
|
|
type customized
|
|
sig-type rsa-sha256
|
|
key-locator
|
|
{
|
|
type name
|
|
regex ^[^<KEY>]*<KEY><>*<ksk-.*><ID-CERT>$
|
|
}
|
|
}
|
|
}
|
|
rule
|
|
{
|
|
id "Testbed Hierarchy Rule"
|
|
for data
|
|
filter
|
|
{
|
|
type name
|
|
regex ^[^<KEY>]*<KEY><>*<ksk-.*><ID-CERT><>$
|
|
}
|
|
checker
|
|
{
|
|
type hierarchical
|
|
sig-type rsa-sha256
|
|
}
|
|
}
|
|
trust-anchor
|
|
{
|
|
type file
|
|
file-name "testbed-trust-anchor.cert"
|
|
}
|