docs: Update of tutorials and other minor fixes
Change-Id: I87d8679d38b3f17f8d4d8dbad3d5f01b3cc4ce7b
diff --git a/docs/tutorials/security-validator-config.rst b/docs/tutorials/security-validator-config.rst
index 905c087..a9ec70e 100644
--- a/docs/tutorials/security-validator-config.rst
+++ b/docs/tutorials/security-validator-config.rst
@@ -1,14 +1,15 @@
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.
+.. contents::
-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.
+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.
::
@@ -50,7 +51,8 @@
file-name "testbed-trust-anchor.cert"
}
-- \ **ATTENTION: The order of rules MATTERS!**\
+.. note::
+ **ATTENTION: The order of rules MATTERS!**
A rule can be broken into two parts:
@@ -59,75 +61,63 @@
- 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.
+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.
+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**.
+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.
+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.
+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.
+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**\ .
+.. note::
+ **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.
+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** 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.
+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
+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
::
@@ -138,7 +128,7 @@
relation equal
}
-shall only capture a packet with the exact name "/localhost/example".
+shall only capture a packet with the exact name ``/localhost/example``.
And a filter
::
@@ -150,9 +140,8 @@
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
+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
::
@@ -163,12 +152,11 @@
relation is-strict-prefix-of
}
-shall capture a packet with name "/localhost/example/data", but cannot
-catch a packet with name "/localhost/example".
+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
+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, a filter
::
@@ -183,18 +171,16 @@
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.
+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.
+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
~~~~~~~~~~~~~~~~~~
@@ -215,20 +201,17 @@
}
}
-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 **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>`__,
+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**:
::
@@ -239,10 +222,9 @@
...
}
-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:
+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:
::
@@ -258,22 +240,18 @@
}
}
-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".
+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:
+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
+- 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:
@@ -298,11 +276,10 @@
}
}
-requires the packet name must be under the corresponding namespace of
-the ``KeyLocator`` name.
+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:
+In some cases, you can even customize checker with another property For example:
::
@@ -327,9 +304,8 @@
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:
+As implied by its name, hierarchical checker requires that the packet name must be under
+the namespace of the packet signer. A hierarchical checker:
::
@@ -364,11 +340,10 @@
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:
+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:
::
@@ -393,13 +368,11 @@
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:
+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:
::
@@ -414,9 +387,9 @@
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``.
+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``.
::
@@ -426,8 +399,8 @@
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
+If certificates under the directory might be changed during runtime, you can set a refresh
+period, such as
::
@@ -438,13 +411,12 @@
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.
+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).**
+.. note::
+ **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).**
::
@@ -457,8 +429,7 @@
Example Configuration For NLSR
------------------------------
-The trust model of NLSR is semi-hierarchical. An example certificate
-signing hierarchy is:
+The trust model of NLSR is semi-hierarchical. An example certificate signing hierarchy is:
::
@@ -514,17 +485,15 @@
+------------+-------------------------------------------------------------------------------------+
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.
+``/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.
+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:
@@ -605,11 +574,12 @@
file-name "testbed-trust-anchor.cert"
}
-Example Configuration For NRD
------------------------------
+Example Configuration For NFD RIB Management
+--------------------------------------------
-Assume NRD allows any valid testbed certificate to register prefix, the
-configuration file could be written as:
+Assume `NFD RIB Management <http://redmine.named-data.net/projects/nfd/wiki/RibMgmt>`_
+allows any valid testbed certificate to register prefix, the configuration file could be
+written as:
::