Prepare 0.6.0 release
Change-Id: I4cea28b09b20f5359f0e2ddaf188b234b2b102f9
Refs: #4275
diff --git a/docs/INSTALL.rst b/docs/INSTALL.rst
index 5e0eb01..fcf1865 100644
--- a/docs/INSTALL.rst
+++ b/docs/INSTALL.rst
@@ -11,7 +11,7 @@
- Ubuntu 14.04 (64-bit and 32-bit)
- Ubuntu 16.04 (64-bit and 32-bit)
-- OS X 10.9
+- Ubuntu 17.04 (64-bit and 32-bit)
- OS X 10.10
- OS X 10.11
- macOS 10.12
diff --git a/docs/index.rst b/docs/index.rst
index fae38ab..f9c7351 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -37,7 +37,6 @@
- :doc:`tutorials`
- + :doc:`tutorials/security-library`
+ :doc:`tutorials/utils-ndn-regex`
+ :doc:`tutorials/security-validator-config`
diff --git a/docs/release-notes-latest.rst b/docs/release-notes-latest.rst
index e77ea53..cbbc128 120000
--- a/docs/release-notes-latest.rst
+++ b/docs/release-notes-latest.rst
@@ -1 +1 @@
-release-notes/release-notes-0.5.1.rst
\ No newline at end of file
+release-notes/release-notes-0.6.0.rst
\ No newline at end of file
diff --git a/docs/release-notes/release-notes-0.6.0.rst b/docs/release-notes/release-notes-0.6.0.rst
new file mode 100644
index 0000000..8510ad2
--- /dev/null
+++ b/docs/release-notes/release-notes-0.6.0.rst
@@ -0,0 +1,153 @@
+ndn-cxx version 0.5.1
+---------------------
+
+Release date: October 16, 2017
+
+Changes since version 0.5.1:
+
+New features:
+^^^^^^^^^^^^^
+
+- **breaking change** Security framework version 2 (:issue:`3098`, :issue:`3920`,
+ :issue:`3644`, :issue:`4085`, :issue:`4323`, :issue:`4339`)
+
+ The released version of the library only supports the new version of the security (v2
+ certificate format) and features a number of updates of KeyChain and Validator
+ interfaces. At the same time, management APIs for :ndn-cxx:`ValidatorConfig` remained
+ intact; transition to the new framework would require only adjusting
+ :ndn-cxx:`Validator::validate` calls and updating configuration files to follow the new
+ naming conventions of :ref:`NDN Certificate Format Version 2.0`.
+
+- Integration of fetching certificates using Certificate Bundle as part of specialized
+ ``CertificateFetcher`` (:issue:`3891`)
+
+- ``ForwardingHint``, ``Delegation``, and ``DelegationList``; refactoring of Interest encoding
+ to include ``ForwardingHint`` instead of ``LinkObject``, following the latest NDN
+ specification updates (:issue:`4054`, :issue:`4055`)
+
+- Fine-grained signals on interface/address changes in NetworkMonitor
+ for all supported platforms (:issue:`3353`, :issue:`4025`, :issue:`3817`, :issue:`4024`)
+
+- Addition of ``TxSequence`` field and ``Ack``, the first repeatable field in
+ NDNLPv2 (:issue:`3931`)
+
+- Optional ``LocalUri`` as part of ``ControlParameters`` and adjusting face creation command
+ and responses to handle the new optional field (:issue:`4014`, :issue:`4015`, :issue:`3956`)
+
+- ``LpReliability`` flag in Face management data structures (:issue:`4003`)
+
+- Backported implementation of C++17 classes ``ostream_joiner`` and ``optional``
+ (:issue:`3962`, :issue:`3753`)
+
+Improvements and bug fixes
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- Removed dependency on CryptoPP library. All cryptographic operations are now realized using
+ OpenSSL library routines and/or with the help of ``security::transform`` framework
+ (:issue:`3006`, :issue:`3946`, :issue:`3924`, :issue:`3886`).
+
+- Improved APIs for NFD management data structures, including equality comparators, formatted
+ output, etc. (:issue:`3932`, :issue:`3903`, :issue:`3864`)
+
+- FaceUri now accepts link-local IPv6 addresses (:issue:`1428`)
+
+- Rename variables in ``FaceStatus`` and ``ForwarderStatus`` ('datas' => 'data')
+ (:issue:`3955`)
+
+- Improve logging framework and its uses
+
+ * Add API to enumerate Logger modules (:issue:`4013`)
+
+ * Advanced filtering of the logging modules (:issue:`3918`)
+
+ * Add logging capabilities to ``Face``, ``UnixTransport``, ``TcpTransport``, and the new
+ security framework (:issue:`3563`)
+
+ To enable logging, set environment variable ``NDN_LOG`` to enable specific, subset, or all
+ logging module at appropriate levels. Examples:
+
+ ::
+
+ export NDN_LOG=*=ALL
+ export NDN_LOG=ndn.*=ALL
+ export NDN_LOG=ndn.security=DEBUG:ndn.TcpTransport=ALL
+
+- Ensure that ``Face`` sends ``Nack`` only after every ``InterestCallback`` has responded
+ (:issue:`4228`)
+
+- Fix potential overflow in ``time::toIsoString`` (:issue:`3915`)
+
+- Fix potentially misaligned memory accesses (:issue:`4172`, :issue:`4097`, :issue:`4175`,
+ :issue:`4190`, :issue:`4191`)
+
+- Fix potential memory access error in ``Face/PendingInterest`` (:issue:`4228`)
+
+- Improvements and streamlining of the ``security::transform`` framework
+
+- Source/header reorganization (:issue:`3940`)
+
+ * Move network-related files to ``src/net``
+
+ .. note::
+ Namespace changes
+
+ * ndn::util::FaceUri is now ndn::FaceUri
+ * ndn::util::ethernet is now ndn::ethernet
+ * ndn::util::NetworkMonitor and related classes are now in ndn::net
+
+ * Move signal-related files into ``src/util/signal/`` directory, except for
+ the main include ``signal.hpp``
+
+ * Move InMemoryStorage to ``src/ims``
+
+ * Rename ``digest.hpp`` to ``sha256.hpp`` to match the ``Sha256`` class declared within
+
+Removed
+^^^^^^^
+
+- Old security framework.
+
+ * ``v1::KeyChain``, use :ndn-cxx:`v2::KeyChain` instead
+
+ * ``v1::Validator`` interface and ``ValidatorRegex`` implementation of this
+ interface. ``ValidatorConfig``, ``ValidatorNull`` implementation refactored to be based on
+ the new validation framework.
+
+ * ``v1::SecPublicInfo`` and its implementation (``SecPublicInfoSqlite``), ``SecTpm`` and its
+ implementations (``SecTpmFile``, ``SecTpmOsx``). These classes are internal implementation
+ and not intended to be used without ``v1::KeyChain``. :ndn-cxx:`v2::KeyChain` internally
+ uses the newly introduced :ndn-cxx:`Pib` and :ndn-cxx:`Tpm` interfaces with their
+ corresponding implementations.
+
+ * ``v1::Certificate``, ``v1::IdentityCertificate``, ``v1::CertificateExtension``,
+ ``v1::CertificateSubjectDescription``, use :ndn-cxx:`v2::Certificate` and
+ :ndn-cxx:`AdditionalDescription`
+
+ * ``v1::SecuredBag``, use ``v2::SafeBag`` instead
+
+- Constant ``io::BASE_64``, use ``io::BASE64`` instead (:issue:`3741`)
+
+- Headers ``management/nfd-*``, use ``mgmt/nfd/*`` instead (:issue:`3760`)
+
+- ``security/cryptopp.hpp`` header
+
+- ``security/identity-certificate.hpp`` header
+
+- ``ndn::PublicKey``, ``ndn::Certificate``, ``ndn::IdentityCertificate``,
+ ``ndn::CertificateExtension``, ``ndn::CertificateSubjectDescription``.
+
+- ``Link`` and ``SelectedDelegation`` fields in ``Interest``, replaced by
+ ``ForwardingHint`` following the latest version of NDN specification (:issue:`4055`)
+
+- ``LocalControlHeader`` constants (:issue:`3755`)
+
+- ``NInDatas`` and ``NOutDatas`` (:issue:`3955`)
+
+- Overload of ``Block::Block`` that parses a ``Block`` from a ``void*`` buffer
+
+- Duplicate ``buf()`` and ``get()`` methods from ``Buffer`` class in favor of ``data()``
+
+- ``util/crypto.hpp``, ``crypto::sha256()``, and ``crypto::computeSha256Digest()`` in favor of
+ ``Sha256::computeDigest()``
+
+- Previously deprecated functions (:issue:`4055`)
diff --git a/docs/releases.rst b/docs/releases.rst
index 9b93c63..1f674f6 100644
--- a/docs/releases.rst
+++ b/docs/releases.rst
@@ -5,6 +5,7 @@
:hidden:
:maxdepth: 1
+ release-notes/release-notes-0.6.0
release-notes/release-notes-0.5.1
release-notes/release-notes-0.5.0
release-notes/release-notes-0.4.1
@@ -17,6 +18,12 @@
release-notes/release-notes-0.2.0
release-notes/release-notes-0.1.0
+* **ndn-cxx version 0.6.0**
+ (:doc:`Release Notes <release-notes/release-notes-0.6.0>`, `Documentation <https://named-data.net/doc/ndn-cxx/0.6.0/>`__)
+
+ `src (git) <https://github.com/named-data/ndn-cxx/releases/tag/ndn-cxx-0.6.0>`__,
+ `src (tarball) <https://named-data.net/downloads/nfd-0.6.0.tar.bz2>`__ (`checksum <http://named-data.net/downloads/nfd-0.6.0.tar.bz2.sha256>`__)
+
* **ndn-cxx version 0.5.1**
(:doc:`Release Notes <release-notes/release-notes-0.5.1>`, `Documentation <http://named-data.net/doc/ndn-cxx/0.5.1/>`__)
diff --git a/docs/tutorials.rst b/docs/tutorials.rst
index c3c1ca1..0edb3c2 100644
--- a/docs/tutorials.rst
+++ b/docs/tutorials.rst
@@ -4,6 +4,5 @@
.. toctree::
:maxdepth: 2
- tutorials/security-library
tutorials/utils-ndn-regex
tutorials/security-validator-config
diff --git a/docs/tutorials/security-library.rst b/docs/tutorials/security-library.rst
deleted file mode 100644
index 392bbf6..0000000
--- a/docs/tutorials/security-library.rst
+++ /dev/null
@@ -1,361 +0,0 @@
-.. _Security Library Tutorial:
-
-Security Library Tutorial
-=========================
-
-.. contents::
-
-Identity, Key and Certificates
-------------------------------
-
-All keys, certificates and their corresponding identities are managed by :ndn-cxx:`KeyChain`.
-
-An real world **identity** can be expressed by a namespace. (e.g.,
-``/ndn/edu/ucla/alice``, or ``/ndn/edu/ucla/BoelterHall/4805``).
-
-**Keys** belonging to an identity are named under the identity's namespace, with a unique
-**KeyId**::
-
- /<identity_name>/[KeyId]
-
-For now, only two types of KeyId are specified: ``ksk-[timestamp]`` and
-``dsk-[timestamp]``. The first type of KeyId is used to denote Key-Signing-Key (KSK)
-which is supposed to have a long lifetime. The second type of KeyId is used to denote
-Data-Signing-Key (DSK) which is supposed to have a short lifetime. Both types of KeyId
-use timestamps (number of milliseconds since unix epoch) to provide relative uniqueness of
-key names. Replacing timestamp with key hash can bring stronger uniqueness but on the
-cost of longer name. Therefore, key hash is not used for now. For example,
-``/ndn/edu/ucla/alice/ksk-1234567890`` or
-``/ndn/edu/ucla/BoelterHall/4805/dsk-1357924680``.
-
-An identity may have more than one keys associated with it. For example, one may have a
-KSK to sign other keys and a DSK to sign data packets, or one may periodically replace its
-expired DSK/KSK with a new key.
-
-The private part of a key ("private key"), is stored in a :ndn-cxx:`Trusted Platform
-Module (TPM) <SecTpm>`. The public part ("public key"), is managed in a
-:ndn-cxx:`Public-key Information Base (PIB) <SecPublicInfo>`. The most important
-information managed by PIB is **certificates** of public keys. A certificate binds a
-public key to its key name or the corresponding identity. The signer (or issuer) of a
-certificate vouches for the binding through its own signature. With different signers
-vouching for the binding, a public key may have more than one certificates.
-
-The certificate name follows the naming convention of `NDNS (NDN Domain Name Service) <http://lasr.cs.ucla.edu/afanasyev/data/files/Afanasyev/afanasyev-phd-thesis.pdf>`_. The
-public key name will be broken into two parts:
-
-- The first part ("authoritative namespace") will be put before a name component ``KEY``
- which serves as an application tag
-- The second part ("label") will be put between ``KEY`` and ``ID-CERT`` which serves as an
- indicator of certificate.
-
-A version number of the certificate is appended after ``ID-CERT``. For example,
-``/ndn/edu/ucla/KEY/alice/ksk-1234567890/ID-CERT/%FD%01`` or
-``/ndn/edu/ucla/BoelterHall/4805/KEY/dsk-1357924680/ID-CERT/%FD%44``.
-
-The :ndn-cxx:`NDN certificate <IdentityCertificate>` is just an ordinary `NDN-TLV Data
-packet <http://named-data.net/doc/ndn-tlv/data.html>`_, with the content part in DER
-encoding that resembles X.509 certificate:
-
-.. code-block:: cpp
-
- // NDN-TLV Encoding
- Certificate ::= DATA-TLV TLV-LENGTH
- Name
- MetaInfo (= CertificateMetaInfo)
- Content (= CertificateContent)
- Signature
-
- CertificateMetaInfo ::= META-INFO-TYPE TLV-LENGTH
- ContentType (= KEY)
- FreshnessPeriod (= ?)
-
-
- CertificateContent ::= CONTENT-TYPE TLV-LENGTH
- CertificateDerPayload
-
-
- // DER Encoding
- CertificateDerPayload ::= SEQUENCE {
- validity Validity,
- subject Name,
- subjectPubKeyInfo SubjectPublicKeyInfo,
- extension Extensions OPTIONAL }
-
- Validity ::= SEQUENCE {
- notBefore Time,
- notAfter Time }
-
- Time ::= CHOICE {
- GeneralizedTime }
-
- Name ::= CHOICE {
- RDNSequence }
-
- RDNSequence ::= SEQUENCE OF RelativeDistinguishedName
-
- RelativeDistinguishedName ::=
- SET OF AttributeTypeAndValue
-
- SubjectPublicKeyInfo ::= SEQUENCE {
- algorithm AlgorithmIdentifier
- keybits BIT STRING }
-
- Extensions ::= SEQUENCE SIZE (1..MAX) OF Extension
-
-See `RFC 3280 <http://www.ietf.org/rfc/rfc3280.txt>`_ for more details about DER field
-definitions.
-
-Signing
--------
-
-Key Management
-%%%%%%%%%%%%%%
-
-Create Identity/Keys/Certificate
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The simplest way to initialize an identity and its key and certificate is to call
-:ndn-cxx:`KeyChain::createIdentity`
-
-.. code-block:: cpp
-
- KeyChain keyChain;
- Name defaultCertName = keyChain.createIdentity(identity);
-
-This method guarantees that the default key and certificate of the supplied identity
-always exist in the KeyChain. This method checks if the supplied identity has already had
-a default key and a default certificate and returns the default certificate name if
-exists. If the default certificate is missing, KeyChain will automatically create a
-self-signed certificate of the default key. If the default key is missing, KeyChain will
-automatically create a new key and set it as the default key and create a self-signed
-certificate as well.
-
-Create Keys Manually
-~~~~~~~~~~~~~~~~~~~~
-
-One can call :ndn-cxx:`KeyChain::generateRsaKeyPair` to generate an RSA key pair or
-:ndn-cxx:`KeyChain::generateEcKeyPair` to generate an EC key. Note that generated
-key pair is not set as the default key of the identity, so you need to set it manually by
-calling :ndn-cxx:`KeyChain::setDefaultKeyNameForIdentity`. There is also a helper method
-:ndn-cxx:`KeyChain::generateRsaKeyPairAsDefault`, which combines the two steps into one.
-
-.. code-block:: cpp
-
- KeyChain keyChain;
- Name alice("/ndn/test/alice");
-
- Name aliceKeyName = keyChain.generateRsaKeyPair(alice);
- keyChain.setDefaultKeyNameForIdentity(aliceKeyName);
-
- // Now the key with the name aliceKeyName2 becomes alice's default key
- Name aliceKeyName2 = keyChain.generateRsaKeyPairAsDefault(alice);
-
-Create Identity Certificate Manually
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If you have created a key pair, you can generate a self-signed certificate for the key by
-calling :ndn-cxx:`KeyChain::selfSign`.
-
-.. code-block:: cpp
-
- KeyChain keyChain;
- Name aliceKeyName("/ndn/test/alice/ksk-1394129695025");
-
- shared_ptr<IdentityCertificate> aliceCert = keyChain.selfSign(aliceKeyName);
-
-You can sign a public key using a different key:
-
-.. code-block:: cpp
-
- KeyChain keyChain;
-
- shared_ptr<IdentityCertificate> certificate =
- keyChain.prepareUnsignedIdentityCertificate(publicKeyName, publicKey,
- signingIdentity,
- notBefore, notAfter,
- subjectDescription, prefix
-
- keyChain.signByIdentity(*certificate, signingIdentity);
-
-Signing Data
-%%%%%%%%%%%%
-
-Although the security library does not have the intelligence to automatically determine
-the signing key for each data packet, it still provides a mechanism, called **Default
-Signing Settings**, to facilitate signing process.
-
-The basic signing process in the security library would be like this: create :ndn-cxx:`KeyChain`
-instance and supply the data packet and signing certificate name to :ndn-cxx:`KeyChain::sign`
-method.
-
-.. code-block:: cpp
-
- KeyChain keyChain;
- keyChain.sign(dataPacket, signingCertificateName);
-
-The :ndn-cxx:`KeyChain` instance will
-
-- construct ``SignatureInfo`` using the signing certificate name;
-- look up the corresponding private key in :ndn-cxx:`TPM <SecTpm>`;
-- sign the data packet if the private key exists.
-
-The basic process, however, requires application developers to supply the exact
-certificate name. Such a process has two shortages: first, it might be difficult to
-remember the certificate name; second, application developers have to be aware of
-certificate update and key roll-over. Therefore, the security library provides another
-signing process in which application developers only need to supply the signing identity:
-
-.. code-block:: cpp
-
- KeyChain keyChain;
- keyChain.signByIdentity(dataPacket, signingIdentity);
-
-The :ndn-cxx:`KeyChain` instance will
-
-- determine the default key of the signing identity;
-- determine the default certificate of the key;
-- construct ``SignatureInfo`` using the default certificate name;
-- look up the corresponding private key in :ndn-cxx:`TPM <SecTpm>`;
-- sign the data packet if the private key exists.
-
-The process above requires that each identity has a default key and that each key has a
-default certificate. All these default settings is managed in :ndn-cxx:`PIB
-<SecPublicInfo>`, one can get/set these default settings through :ndn-cxx:`KeyChain`
-directly:
-
-.. code-block:: cpp
-
- KeyChain keyChain;
- Name defaultKeyName = keyChain.getDefaultKeyNameForIdentity(identity);
- Name defaultCertName = keyChain.getDefaultCertificateNameForKey(keyName);
-
- keyChain.setDefaultKeyNameForIdentity(keyName);
- keyChain.setDefaultCertificateNameForKey(certificateName);
-
-There is even a default identity which will be used when no identity information is
-supplied in signing method:
-
-.. code-block:: cpp
-
- KeyChain keyChain;
- keyChain.sign(dataPacket);
-
-And default identity can be got/set through :ndn-cxx:`KeyChain` as well:
-
-.. code-block:: cpp
-
- KeyChain keyChain;
- Name defaultIdentity = keyChain.getDefaultIdentity();
- keyChain.setDefaultIdentity(identity);
-
-
-Signing Interests
-%%%%%%%%%%%%%%%%%
-
-The process of signing Interests according to the :doc:`Signed Interest specification
-<../specs/signed-interest>` is exactly the same as the process of signing Data packets:
-
-.. code-block:: cpp
-
- KeyChain keyChain;
-
- keyChain.sign(interest, signingCertName);
- keyChain.signByIdentity(interest, signingIdentity);
- keyChain.sign(interest);
-
-Validation
-----------
-
-Interest and Data validation is done through a **Validator**. :ndn-cxx:`Validator` is a virtual
-class, two pure virtual methods must be implemented in order to construct a working
-validator:
-
-.. code-block:: cpp
-
- class Validator
- {
- ...
- protected:
- virtual void
- checkPolicy(const Data& data,
- int nSteps,
- const OnDataValidated& onValidated,
- const OnDataValidationFailed& onValidationFailed,
- std::vector<shared_ptr<ValidationRequest> >& nextSteps) = 0;
-
- virtual void
- checkPolicy(const Interest& interest,
- int nSteps,
- const OnInterestValidated& onValidated,
- const OnInterestValidationFailed& onValidationFailed,
- std::vector<shared_ptr<ValidationRequest> >& nextSteps) = 0;
- ...
- };
-
-What should be implemented in these two methods is to check:
-
-- whether the packet and signer comply with trust policies;
-- whether their signature can be verified.
-
-If the packet can be validated, the ``onValidated`` callback should be invoked, otherwise
-the ``onValidationFailed`` callback should be invoked. If more information (e.g., other
-certificates) is needed, express the request for missing information in one or more
-``ValidationRequest`` and push them into ``nextSteps``.
-
-.. code-block:: cpp
-
- class ValidationRequest
- {
- public:
- Interest m_interest; // The Interest for the requested data/certificate.
- OnDataValidated m_onValidated; // Callback when the retrieved certificate is authenticated.
- OnDataValidationFailed m_onDataValidated; // Callback when the retrieved certificate cannot be authenticated.
- int m_nRetries; // The number of retries when the interest times out.
- int m_nStep; // The number of validation steps that have been performed.
- };
-
-Besides the two ``Validator::checkPolicy`` methods, the ``Validator`` also provides three
-hooks to control packet validation in a finer granularity.
-
-.. code-block:: cpp
-
- class Validator
- {
- ...
- protected:
- virtual shared_ptr<const Data>
- preCertificateValidation(const Data& data);
-
- virtual void
- onTimeout(const Interest& interest,
- int nRemainingRetries,
- const OnFailure& onFailure,
- const shared_ptr<ValidationRequest>& validationRequest);
-
- virtual void
- afterCheckPolicy(const std::vector<shared_ptr<ValidationRequest> >& nextSteps,
- const OnFailure& onFailure);
- ...
- };
-
-``Validator::preCertificateValidation`` is triggered before validating requested
-certificate. The Data supplied matches the interest in the ``ValidationRequest``. It may
-be certificate or a data encapsulating certificate. This hook returns a data (actually
-certificate) that is will be passed as Data into ``Validator::validate``;
-
-``Validator::onTimeout`` is triggered when interest for certificate times out. The logic
-to handle the timeout can be implemented in this hook. One could invoke onFailure or
-re-express the interest.
-
-``Validator::afterCheckPolicy`` is invoked after ``Validator::checkPolicy`` is done. One
-can implement the logic of how to process the set of ValidationRequests according to its
-trust model.
-
-Configuration-based Validator
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-In most cases, the trust model of applications are simple. However, it is not trivial to
-implement the two ``Validator::checkPolicy`` methods. Therefore, we provide a more
-developer-friendly configuration-based validator, ``ValidatorConfig``. With
-``ValidatorConfig``, one can express the trust model using a policy language in a
-configuration file. See :doc:`security-validator-config` for more details.
diff --git a/docs/tutorials/security-validator-config.rst b/docs/tutorials/security-validator-config.rst
index 044161d..fcd49dc 100644
--- a/docs/tutorials/security-validator-config.rst
+++ b/docs/tutorials/security-validator-config.rst
@@ -30,7 +30,7 @@
key-locator
{
type name
- name /ndn/edu/ucla/yingdi/KEY/ksk-1234
+ name /ndn/edu/ucla/yingdi/KEY/1234
relation equal
}
}
@@ -72,7 +72,7 @@
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/ksk-1234``. If a packet does not have a name under
+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
@@ -248,13 +248,13 @@
key-locator
{
type name
- name /ndn/edu/ucla/yingdi/KEY/ksk-1234
+ name /ndn/edu/ucla/yingdi/KEY/1234
relation equal
}
}
This checker property requires that the packet must have a ``rsa-sha256`` signature that
-can be verified with ``/ndn/edu/ucla/yingdi/KEY/ksk-1234`` key.
+can be verified with ``/ndn/edu/ucla/yingdi/KEY/1234`` key.
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
@@ -392,10 +392,6 @@
Example Configuration For NLSR
------------------------------
-.. note::
- **These example assumes the v1 certificate naming convention that is no longer in
- use. The example will be updated later.**
-
The trust model of NLSR is semi-hierarchical. An example certificate signing hierarchy is:
::
@@ -424,31 +420,31 @@
| | |
| | Identity example: ``/ndn`` |
| | |
-| | Certificate name example: ``/ndn/KEY/ksk-1/ID-CERT/%01`` |
+| | Certificate name example: ``/ndn/KEY/1/%00/%01`` |
+------------+-------------------------------------------------------------------------------------+
| site | ``/<network>/<site>`` |
| | |
| | Identity example: ``/ndn/edu/ucla`` |
| | |
-| | Certificate name example: ``/ndn/edu/ucla/KEY/ksk-2/ID-CERT/%01`` |
+| | 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/ksk-3/ID-CERT/%01`` |
+| | 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/ksk-4/ID-CERT/%01`` |
+| | 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/ksk-5/ID-CERT/%01`` |
+| | Certificate name example: ``/ndn/edu/ucla/%C1.O.R./rt1/NLSR/KEY/5/%00/%01`` |
+------------+-------------------------------------------------------------------------------------+
Assume that a typical NLSR data name is
@@ -473,7 +469,7 @@
filter
{
type name
- regex ^[^<NLSR><LSA>]*<NLSR><LSA>
+ regex ^<>*<NLSR><LSA><><>$
}
checker
{
@@ -484,10 +480,10 @@
type name
hyper-relation
{
- k-regex ^([^<KEY>]*)<KEY><ksk-.*><ID-CERT>$
+ k-regex ^(<>*)<KEY><>$
k-expand \\1
h-relation equal
- p-regex ^([^<NLSR><LSA>]*)<NLSR><LSA><LSType\.\d><>$
+ p-regex ^(<>*)<NLSR><LSA><><>$
p-expand \\1
}
}
@@ -500,7 +496,7 @@
filter
{
type name
- regex ^[^<KEY><%C1.O.R.>]*<%C1.O.R.><><KEY><ksk-.*><ID-CERT><>$
+ regex ^<>*<%C1.O.R.><><KEY><><><>$
}
checker
{
@@ -511,10 +507,10 @@
type name
hyper-relation
{
- k-regex ^([^<KEY><%C1.O.N.>]*)<%C1.O.N.><><KEY><ksk-.*><ID-CERT>$
+ k-regex ^(<>*)<%C1.O.N.><><KEY><>$
k-expand \\1
h-relation equal
- p-regex ^([^<KEY><%C1.O.R.>]*)<%C1.O.R.><><KEY><ksk-.*><ID-CERT><>$
+ p-regex ^(<>*)<%C1.O.R.><><KEY><><><>$
p-expand \\1
}
}
@@ -527,7 +523,7 @@
filter
{
type name
- regex ^[^<KEY>]*<KEY><ksk-.*><ID-CERT><>$
+ regex ^<>*<KEY><><><>$
}
checker
{
diff --git a/docs/tutorials/utils-ndn-regex.rst b/docs/tutorials/utils-ndn-regex.rst
index 88934b6..6492a96 100644
--- a/docs/tutorials/utils-ndn-regex.rst
+++ b/docs/tutorials/utils-ndn-regex.rst
@@ -1,23 +1,20 @@
NDN Regular Expression
======================
-NDN regular expression matching is done at two levels: one at the name
-level and one at the name component level.
+NDN regular expression is a kind of regular expression that can match NDN names. Matching is
+performed at two levels: the name level and the name component level.
-We use ``<`` and ``>`` to enclose a name component matcher which
-specifies the pattern of a name component. The component pattern is
-expressed using the `Perl Regular Expression
-Syntax <http://www.boost.org/doc/libs/1_55_0/libs/regex/doc/html/boost_regex/syntax/perl_syntax.html>`__.
-For example, ``<ab*c>`` can match the 1st, 3rd, and 4th components of
-``/ac/dc/abc/abbc``, but it cannot match the 2nd component. A special
-case is that ``<>`` is a wildcard matcher that can match **ANY**
-component.
+A name component matcher, enclosed in ``<`` and ``>``, specifies the pattern of a name component. The
+component pattern is expressed with the `Perl Regular Expression Syntax
+<http://www.boost.org/doc/libs/1_55_0/libs/regex/doc/html/boost_regex/syntax/perl_syntax.html>`__.
+For example, ``<ab*c>`` matches the 1st, 3rd, and 4th components of ``/ac/dc/abc/abbc``, but does
+not match the 2nd component. A special case is that ``<>`` denotes a wildcard matcher that can match
+**ANY** name component.
-Note that a component match can match only one name component. In order
-to match a name, you need to specify the pattern of a name based on the
-name component matchers. For example, ``<ndn><edu><ucla>`` can match the
-name ``/ndn/edu/ucla``. In order to describe a more complicated name
-pattern, we borrow some syntaxes from the standard regular expressions.
+A component matcher can match only one name component. To match a name, you need to compose an NDN
+regular expression with zero or more name component matchers. For example, ``<ndn><edu><ucla>``
+matches the name ``/ndn/edu/ucla``. To describe a more complicated name pattern, we borrow some
+syntaxes from the standard regular expressions.
NDN Regex Syntax
----------------
@@ -25,79 +22,70 @@
Anchors
~~~~~~~
-A ``'^'`` character shall match the start of a name. For example,
-``^<ndn>`` shall match any names starting with a component ``ndn``, and
-it will exclude a name like ``/local/broadcast``.
+The ``^`` character matches the start of a name. For example, ``^<ndn>`` matches any name starting
+with the component ``ndn``, but does not match a name like ``/local/broadcast``.
-A ``'$'`` character shall match the end of a name. For example,
-``^<ndn><edu>$`` shall match only one name: ``/ndn/edu``.
+The ``$`` character matches the end of a name. For example, ``^<ndn><edu>$`` matches only one
+name: ``/ndn/edu``.
-Repeats
-~~~~~~~
+Repetition
+~~~~~~~~~~
-A component matcher can be followed by a repeat syntax to indicate how
-many times the preceding component can be matched.
+A component matcher can be followed by a repeat quantifier to indicate how many times the preceding
+component may appear.
-Syntax ``*`` for zero or more times. For example,
-``^<ndn><KEY><>*<ID-CERT>`` shall match ``/ndn/KEY/ID-CERT/``, or
-``/ndn/KEY/edu/ID-CERT``, or ``/ndn/KEY/edu/ksk-12345/ID-CERT`` and so
-on.
+The ``*`` quantifier denotes "zero or more times". For example, ``^<A><B>*<C>$`` matches ``/A/C``,
+``/A/B/C``, ``/A/B/B/C``, and so on.
-Syntax ``+`` for one or more times. For example,
-``^<ndn><KEY><>+<ID-CERT>`` shall match ``/ndn/KEY/edu/ID-CERT``, or
-``/ndn/KEY/edu/ksk-12345/ID-CERT`` and so on, but it cannot match
-``/ndn/KEY/ID-CERT/``.
+The ``+`` quantifier denotes "one or more times". For example, ``^<A><B>+<C>$`` matches ``/A/B/C``,
+``/A/B/B/C``, and so on, but does not match ``/A/C``.
-Syntax ``?`` for zero or one times. For example,
-``^<ndn><KEY><>?<ID-CERT>`` shall match ``/ndn/KEY/ID-CERT/``, or
-``/ndn/KEY/edu/ID-CERT``, but it cannot match
-``/ndn/KEY/edu/ksk-12345/ID-CERT``.
+The ``?`` quantifier denotes "zero or one time". For example, ``^<A><B>?<C>`` matches ``/A/C`` and
+``/A/B/C``, but does not match ``/A/B/B/C``.
-Repetition can also be bounded:
+A bounded quantifier specifies a minimum and maximum number of permitted matches: ``{n}`` denotes
+"exactly ``n`` times"; ``{n,}`` denotes "at least ``n`` times"; ``{,n}`` denotes "at most ``n``
+times"; ``{n, m}`` denotes "between ``n`` and ``m`` times (inclusive)". For example,
+``^<A><B>{2, 4}<C>$`` matches ``/A/B/B/C`` and ``/A/B/B/B/B/C``.
-``{n}`` for exactly ``n`` times. ``{n,}`` for at least ``n`` times.
-``{,n}`` for at most ``n`` times. And ``{n, m}`` for ``n`` to ``m``
-times.
-
-Note that the repeat matching is **greedy**, that is it will consume as
-many matched components as possible. We do not support non-greedy repeat
-matching and possessive repeat matching for now.
+Note that the quantifiers are **greedy**, which means it will consume as many matched components as
+possible. NDN regular expressions currently do not support non-greedy repeat matching and possessive
+repeat matching. For example, for the name ``/A/B/C/C/C``, ``^<A><B><C>+$`` will match the entire
+name instead of only ``/A/B/C``.
Sets
~~~~
-Name component set is a bracket-expression starting with ``'['`` and
-ending with ``']'``, it defines a set of name components, and matches
-any single name component that is a member of that set.
+A name component set, denoted by a bracket expression starting with ``[`` and ending with ``]``,
+defines a set of name components. It matches any single name component that is a member of that set.
-Unlike the standard regular expression, NDN regular expression only
-supports **Single Components Set**, that is, you have to list all the
-set members one by one between the bracket. For example,
-``^[<ndn><localhost>]`` shall match any names starting with either a
-component ``ndn"`` or ``localhost``.
+Unlike standard regular expressions, NDN regular expression only supports **Single Components Set**,
+that is, you have to list all the set members one by one between the brackets. For example,
+``^[<ndn><localhost>]`` matches any names starting with either ``ndn"`` or ``localhost`` component.
-When a name component set starts with a ``'^'``, the set becomes a
-**Negation Set**, that is, it matches the complement of the name
-components it contains. For example, ``^[^<ndn>]`` shall match any names
-that does not start with a component ``ndn``.
+When a name component set starts with a ``'^'``, the set becomes a **Negation Set**. It matches the
+complement of the contained name components. For example, ``^[^<ndn>]`` matches any non-empty name
+that does not start with ``ndn`` component.
Some other types of sets, such as Range Set, will be supported later.
-Note that component set can be repeated as well.
+Note that component sets may be repeated in the same way as component matchers.
Sub-pattern and Back Reference
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-A section beginning ``(`` and ending ``)`` acts as a marked sub-pattern.
-Whatever matched the sub-pattern is split out in a separate field by the
-matching algorithms. For example ``^([^<DNS>])<DNS>(<>*)<NS>`` shall
-match a data name of NDN DNS NS record, and the first sub-pattern
-captures the zone name while the second sub-pattern captures the
-relative record name.
+A section beginning ``(`` and ending ``)`` acts as a marked sub-pattern. Whatever matched the
+sub-pattern is split out in a separate field by the matching algorithm. For example
+``^<A>(<>{2})<B>(<>)`` matches the name ``/A/C/D/B/E``, and the first sub-pattern captures ``C/D``.
-Marked sub-patterns can be referred to by a back-reference ``\n``. The
-same example above shall match a name
-``/ndn/edu/ucla/DNS/irl/NS/123456``, and a back reference ``\1\2`` shall
-extract ``/ndn/edu/ucla/irl`` out of the name.
+Marked sub-patterns can be referred to by a back-reference ``\N``, which references one or more
+capturing groups. In the example above, a back reference ``\1\2`` extracts ``/C/D/E`` out of the
+name.
-Note that marked sub-patterns can be also repeated.
+Marked sub-patterns can also be repeated. The regex engine does not permanently substitute
+back-references in a regular expression, but will use the last match saved into the back-reference.
+If a new match is found by capturing parentheses, the previous match is overwritten. For example,
+both ``^([<A><B><C>]+)$`` and ``^([<A><B><C>])+$`` match ``/C/A/B``. However, the former regex
+stores ``C/A/B`` as the first back-reference, while the latter one stores ``B``. That is because the
+``+`` quantifier in the latter NDN regular expression causes the marked sub-pattern to be matched
+three times, and ``B`` is the last saved match.