docs: clarify and cleanup the certificate format spec
Also, cleanup references to the legacy signed interest spec
Change-Id: Ib761399b6e44cefea6331e4e128bb2976c2fc11d
diff --git a/docs/INSTALL.rst b/docs/INSTALL.rst
index 4ad0fba..dda1924 100644
--- a/docs/INSTALL.rst
+++ b/docs/INSTALL.rst
@@ -57,9 +57,12 @@
* Install either Xcode (from the App Store) or the Command Line Tools
(with ``xcode-select --install``)
- * If using Homebrew (recommended), enter the following in a terminal::
+ * If using Homebrew (recommended), enter the following in a terminal:
+
+ .. code-block:: sh
brew install boost openssl pkg-config
+ brew install python # only on macOS 10.14 and earlier
.. warning::
@@ -96,7 +99,7 @@
.. code-block:: sh
- sudo dnf config-manager --enable PowerTools # on CentOS only
+ sudo dnf config-manager --enable powertools # on CentOS only
sudo dnf install doxygen graphviz python3-pip
pip3 install --user sphinx sphinxcontrib-doxylink
diff --git a/docs/conf.py b/docs/conf.py
index a2df0fc..22f4bc1 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -18,7 +18,7 @@
# -- Project information -----------------------------------------------------
project = u'ndn-cxx: NDN C++ library with eXperimental eXtensions'
-copyright = u'Copyright © 2013-2020 Regents of the University of California.'
+copyright = u'Copyright © 2013-2021 Regents of the University of California.'
author = u'Named Data Networking Project'
# The short X.Y version.
diff --git a/docs/index.rst b/docs/index.rst
index ea459fb..5d7364c 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -49,10 +49,10 @@
- :doc:`specs`
- + :doc:`specs/signed-interest`
- + :doc:`specs/certificate-format`
+ + :doc:`specs/certificate`
+ :doc:`specs/safe-bag`
+ :doc:`specs/validation-error-code`
+ + :doc:`specs/signed-interest`
- :doc:`manpages`
diff --git a/docs/release-notes/release-notes-0.5.0.rst b/docs/release-notes/release-notes-0.5.0.rst
index b81f209..914c5de 100644
--- a/docs/release-notes/release-notes-0.5.0.rst
+++ b/docs/release-notes/release-notes-0.5.0.rst
@@ -112,8 +112,7 @@
``ndn::CertificateExtension``, ``ndn::CertificateSubjectDescription``. When necessary, use
``security::v1::PublicKey``, ``security::v1::Certificate``, ``security::v1::IdentityCertificate``,
``security::v1::CertificateExtension``, ``security::v1::CertificateSubjectDescription`` instead.
- The next release will feature :doc:`a new version of NDN Certificate format
- <../specs/certificate-format>`.
+ The next release will feature :doc:`a new version of the NDN Certificate format </specs/certificate>`.
Removed
^^^^^^^
diff --git a/docs/release-notes/release-notes-0.5.1.rst b/docs/release-notes/release-notes-0.5.1.rst
index 8e1acc9..63c831f 100644
--- a/docs/release-notes/release-notes-0.5.1.rst
+++ b/docs/release-notes/release-notes-0.5.1.rst
@@ -15,8 +15,7 @@
- Add version 2 of the security framework (introduced in ``security::v2`` namespace)
- * :ref:`NDN Certificate Format Version 2.0 <NDN Certificate Format Version 2.0>`
- (:issue:`3103`)
+ * :doc:`/specs/certificate` (:issue:`3103`)
* New Public Information Base (PIB) and Trusted Program Module (TPM) framework to manage
public/private keys and NDN Certificate version 2.0 (:issue:`2948`, :issue:`3202`)
* New KeyChain implementation (:issue:`2926`)
@@ -24,8 +23,8 @@
* New security-supporting utilities: trust anchor container and certificate cache
* Creation of `Command Interests
<https://redmine.named-data.net/projects/ndn-cxx/wiki/CommandInterest>`__ delegated to
- :ndn-cxx:`CommandInterestSigner` class, while the new KeyChain only :ref:`signs Interests
- <Signed Interest>` (:issue:`3912`)
+ :ndn-cxx:`CommandInterestSigner` class, while the new KeyChain only :doc:`signs Interests
+ </specs/signed-interest>` (:issue:`3912`)
- Enable validator to fetch certificates directly from the signed/command interest sender
(:issue:`3921`)
@@ -100,5 +99,3 @@
``ndn::CertificateExtension``, ``ndn::CertificateSubjectDescription``. When necessary, use
``security::v1::PublicKey``, ``security::v1::Certificate``, ``security::v1::IdentityCertificate``,
``security::v1::CertificateExtension``, ``security::v1::CertificateSubjectDescription`` instead.
- The next release will feature :ref:`a new version of NDN Certificate format
- <NDN Certificate Format Version 2.0>`.
diff --git a/docs/release-notes/release-notes-0.6.0.rst b/docs/release-notes/release-notes-0.6.0.rst
index 4beb3ef..c2e045f 100644
--- a/docs/release-notes/release-notes-0.6.0.rst
+++ b/docs/release-notes/release-notes-0.6.0.rst
@@ -16,7 +16,7 @@
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`.
+ naming conventions of :doc:`/specs/certificate`.
- Integration of fetching certificates using Certificate Bundle as part of specialized
``CertificateFetcher`` (:issue:`3891`)
diff --git a/docs/specs.rst b/docs/specs.rst
index 65803db..2d4a5ab 100644
--- a/docs/specs.rst
+++ b/docs/specs.rst
@@ -4,7 +4,7 @@
.. toctree::
:maxdepth: 2
- specs/signed-interest
- specs/certificate-format
+ specs/certificate
specs/safe-bag
specs/validation-error-code
+ specs/signed-interest
diff --git a/docs/specs/certificate-format.rst b/docs/specs/certificate-format.rst
deleted file mode 100644
index 9e811b9..0000000
--- a/docs/specs/certificate-format.rst
+++ /dev/null
@@ -1,200 +0,0 @@
-.. _NDN Certificate Format Version 2.0:
-
-NDN Certificate Format Version 2.0
-==================================
-
-Since signature verification is a common operation in NDN applications, it is
-important to define a common certificate format to standardize the public key
-authentication procedure. As every NDN data packet is signed, a data packet
-that carries a public key as content is conceptually a certificate. However,
-the specification of a data packet is not sufficient to be the specification of
-a common certificate format, as it requires additional components. For example,
-a certificate may follow a specific naming convention and may need to include
-validity period, revocation information, etc. This specification defines
-naming and structure of the NDN certificates and is complementary to NDN packet
-specification.
-
-::
-
- Overview of NDN certificate format
- +--------------------------+
- | Name |
- +--------------------------+
- | MetaInfo |
- |+------------------------+|
- || ContentType: KEY(2) ||
- |+------------------------+|
- |+------------------------+|
- || FreshnessPeriod: >~ 1h ||
- |+------------------------+|
- +--------------------------+
- | Content |
- |+------------------------+|
- || Public Key ||
- |+------------------------+|
- +--------------------------+
- | SignatureInfo |
- |+------------------------+|
- || SignatureType: ... ||
- || KeyLocator: ... ||
- || ValidityPeriod: ... ||
- || ... ||
- |+------------------------+|
- +--------------------------+
- | SignatureValue |
- +--------------------------+
-
-.. code-block:: abnf
-
- CertificateV2 = DATA-TYPE TLV-LENGTH
- Name ; /<NameSpace>/KEY/[KeyId]/[IssuerId]/[Version]
- MetaInfo ; ContentType == KEY, FreshnessPeriod required
- Content ; X509PublicKey
- CertificateV2SignatureInfo
- SignatureValue
-
- CertificateV2SignatureInfo = SIGNATURE-INFO-TYPE TLV-LENGTH
- SignatureType
- KeyLocator
- ValidityPeriod
- *CertificateV2Extension
-
-
-Name
-----
-
-The name of a certificate consists of five parts as shown below::
-
- /<SubjectName>/KEY/[KeyId]/[IssuerId]/[Version]
-
-A certificate name starts with the subject to which a public key is bound. The following parts
-include the keyword ``KEY`` component, KeyId, IssuerId, and version components.
-
-``KeyId`` is an opaque name component to identify an instance of the public key for the
-certificate namespace. The value of `Key ID` is controlled by the namespace owner and can be
-an 8-byte random number, SHA-256 digest of the public key, timestamp, or a simple numerical
-identifier.
-
-``Issuer Id`` is an opaque name component to identify issuer of the certificate. The value is
-controlled by the certificate issuer and, similar to KeyId, can be an 8-byte random number,
-SHA-256 digest of the issuer's public key, or a simple numerical identifier.
-
-For example::
-
- /edu/ucla/cs/yingdi/KEY/%03%CD...%F1/%9F%D3...%B7/%FD%d2...%8E
- \_________________/ \___________/ \___________/\___________/
- Certificate Namespace Key Id Issuer Id Version
- (Identity)
-
-MetaInfo
---------
-
-The ``ContentType`` of certificate is set to ``KEY`` (2).
-
-The ``FreshnessPeriod`` of certificate must be explicitly specified. The
-recommended value is 1 hour (3,600,000 milliseconds).
-
-Content
--------
-
-By default, the content of a certificate is the public key encoded in
-`X509PublicKey <https://tools.ietf.org/html/rfc5280#section-4.1.2.7>`__ format.
-
-SignatureInfo
--------------
-
-The SignatureInfo block of a certificate is required to include the ``ValidityPeriod`` field.
-``ValidityPeriod`` includes two sub TLV fields: ``NotBefore`` and ``NotAfter``, which carry two
-UTC timestamps in ISO 8601 compact format (``yyyymmddTHHMMSS``, e.g., "20020131T235959").
-``NotBefore`` indicates when the certificate takes effect while ``NotAfter`` indicates when the
-certificate expires.
-
-.. note::
- Using ISO style string is the convention of specifying the validity period of certificate,
- which has been adopted by many certificate systems, such as X.509, PGP, and DNSSEC.
-
-.. code-block:: abnf
-
- ValidityPeriod = VALIDITY-PERIOD-TYPE TLV-LENGTH
- NotBefore
- NotAfter
-
- NotBefore = NOT-BEFORE-TYPE TLV-LENGTH 8DIGIT "T" 6DIGIT
-
- NotAfter = NOT-AFTER-TYPE TLV-LENGTH 8DIGIT "T" 6DIGIT
-
-For each TLV, the TLV-TYPE codes are assigned as below:
-
-+---------------------------------------------+-------------------+----------------+
-| TLV-TYPE | Assigned code | Assigned code |
-| | (decimal) | (hexadecimal) |
-+=============================================+===================+================+
-| ValidityPeriod | 253 | 0xFD |
-+---------------------------------------------+-------------------+----------------+
-| NotBefore | 254 | 0xFE |
-+---------------------------------------------+-------------------+----------------+
-| NotAfter | 255 | 0xFF |
-+---------------------------------------------+-------------------+----------------+
-
-Extensions
-~~~~~~~~~~
-
-A certificate may optionally carry some extensions in SignatureInfo. An extension
-could be either critical or non-critical depends on the TLV-TYPE code convention. A
-critical extension implies that if a validator cannot recognize or parse the
-extension, the validator must reject the certificate. A non-critical extension
-implies that if a validator cannot recognize or cannot parse the extension, the
-validator may ignore the extension.
-
-The TLV-TYPE code range [256, 512) is reserved for extensions. The last bit of a
-TLV-TYPE code indicates whether the extension is critical or not: ``1`` for critical
-while ``0`` for non-critical. If an extension could be either critical or
-non-critical, the extension should be allocated with two TLV-TYPE codes which only
-differ at the last bit.
-
-Extensions
-----------
-
-We list currently defined extensions:
-
-+---------------------------------------------+-------------------+----------------+
-| TLV-TYPE | Assigned number | Assigned number|
-| | (decimal) | (hexadecimal) |
-+=============================================+===================+================+
-| AdditionalDescription (non-critical) | 258 | 0x0102 |
-+---------------------------------------------+-------------------+----------------+
-
-AdditionalDescription
-~~~~~~~~~~~~~~~~~~~~~
-
-``AdditionalDescription`` is a non-critical extension that provides additional
-information about the certificate. The information is expressed as a set of
-key-value pairs. Both key and value are UTF-8 strings, e.g.,
-``("Organization", "UCLA")``. The issuer of a certificate can specify arbitrary
-key-value pair to provide additional description about the certificate.
-
-.. code-block:: abnf
-
- CertificateV2Extension = AdditionalDescription
-
- AdditionalDescription = ADDITIONAL-DESCRIPTION-TYPE TLV-LENGTH
- 1*DescriptionEntry
-
- DescriptionEntry = DESCRIPTION-ENTRY-TYPE TLV-LENGTH
- DescriptionKey
- DescriptionValue
-
- DescriptionKey = DESCRIPTION-KEY-TYPE TLV-LENGTH 1*OCTET
-
- DescriptionValue = DESCRIPTION-VALUE-TYPE TLV-LENGTH 1*OCTET
-
-+---------------------------------------------+-------------------+----------------+
-| TLV-TYPE | Assigned number | Assigned number|
-| | (decimal) | (hexadecimal) |
-+=============================================+===================+================+
-| DescriptionEntry | 512 | 0x0200 |
-+---------------------------------------------+-------------------+----------------+
-| DescriptionKey | 513 | 0x0201 |
-+---------------------------------------------+-------------------+----------------+
-| DescriptionValue | 514 | 0x0202 |
-+---------------------------------------------+-------------------+----------------+
diff --git a/docs/specs/certificate.rst b/docs/specs/certificate.rst
new file mode 100644
index 0000000..9233b75
--- /dev/null
+++ b/docs/specs/certificate.rst
@@ -0,0 +1,201 @@
+NDN Certificate Format Version 2.0
+==================================
+
+Since signature verification is a common operation in NDN applications, it is
+important to define a common certificate format to standardize the public key
+authentication procedure. As every NDN data packet is signed, a data packet
+that carries a public key as content is conceptually a certificate. However,
+the specification of a data packet alone is not sufficient to serve as the
+specification of a common NDN certificate format, because additional provisions
+are required for the latter. For example, a certificate follows a specific
+naming scheme and may need to include validity period, revocation information,
+etc. This specification defines the naming and structure of NDN certificates
+and is complementary to the `NDN packet specification
+<https://named-data.net/doc/NDN-packet-spec/current/>`__.
+
+::
+
+ Structure of an NDN certificate
+ +--------------------------+
+ | Name |
+ +--------------------------+
+ | MetaInfo |
+ |+------------------------+|
+ || ContentType: KEY(2) ||
+ |+------------------------+|
+ |+------------------------+|
+ || FreshnessPeriod: ~1h ||
+ |+------------------------+|
+ +--------------------------+
+ | Content |
+ |+------------------------+|
+ || Public Key ||
+ |+------------------------+|
+ +--------------------------+
+ | SignatureInfo |
+ |+------------------------+|
+ || SignatureType: ... ||
+ || KeyLocator: ... ||
+ || ValidityPeriod: ... ||
+ || ... ||
+ |+------------------------+|
+ +--------------------------+
+ | SignatureValue |
+ +--------------------------+
+
+.. code-block:: abnf
+
+ CertificateV2 = DATA-TYPE TLV-LENGTH
+ Name ; /<IdentityName>/KEY/<KeyId>/<IssuerId>/<Version>
+ MetaInfo ; ContentType == KEY, FreshnessPeriod required
+ CertificateV2Content
+ CertificateV2SignatureInfo
+ SignatureValue
+
+ CertificateV2Content = CONTENT-TYPE TLV-LENGTH SubjectPublicKeyInfo
+
+ CertificateV2SignatureInfo = SIGNATURE-INFO-TYPE TLV-LENGTH
+ SignatureType
+ KeyLocator
+ ValidityPeriod
+ *CertificateV2Extension
+
+
+Name
+----
+
+The name of a certificate consists of five parts as shown below::
+
+ /<IdentityName>/KEY/<KeyId>/<IssuerId>/<Version>
+
+A certificate name starts with the name of the identity to which the public key is
+bound. The identity is followed by a literal ``KEY`` GenericNameComponent and by
+the *KeyId*, *IssuerId*, and *Version* components.
+
+*KeyId* is an opaque name component that identifies an instance of the public key in
+the certificate namespace. The value of *KeyId* is controlled by the namespace owner
+and can be an 8-byte random number, the SHA-256 digest of the certificate's public
+key, a timestamp, or any other unique numerical identifier.
+
+*IssuerId* is an opaque name component that identifies the issuer of the certificate.
+The value is controlled by the certificate issuer and, similar to *KeyId*, can be an
+8-byte random number, the SHA-256 digest of the issuer's public key, or any other
+free-form identifier.
+
+*Version* represents the version number of the certificate. This component is encoded
+as a VersionNameComponent, following either revision 1 (marker-based) or revision 2
+(type-based) of the `NDN naming conventions
+<https://named-data.net/publications/techreports/ndn-tr-22-2-ndn-memo-naming-conventions/>`__.
+
+For example::
+
+ /edu/ucla/cs/yingdi/KEY/%03%CD...%F1/%9F%D3...%B7/v=1617592200702
+ \_________________/ \___________/\___________/\______________/
+ Identity Name KeyId IssuerId Version
+
+MetaInfo
+--------
+
+The ``ContentType`` must be set to ``KEY`` (2).
+
+The ``FreshnessPeriod`` must be explicitly specified. The recommended value is 3,600,000 (1 hour).
+
+Content
+-------
+
+The ``Content`` element of a certificate contains the actual bits of the public key, formatted
+as a DER-encoded `SubjectPublicKeyInfo <https://tools.ietf.org/html/rfc5280#section-4.1.2.7>`__
+structure.
+
+SignatureInfo
+-------------
+
+The ``SignatureInfo`` element of a certificate is required to include a ``ValidityPeriod``
+element.
+
+``ValidityPeriod`` contains two TLV sub-elements: ``NotBefore`` and ``NotAfter``, each
+carrying a UTC timestamp in *ISO 8601-1:2019* compact format without the final "Z" character
+("YYYYMMDDThhmmss", e.g., "20201231T235959"). ``NotBefore`` indicates when the certificate
+takes effect while ``NotAfter`` indicates when the certificate expires.
+
+.. code-block:: abnf
+
+ ValidityPeriod = VALIDITY-PERIOD-TYPE TLV-LENGTH
+ NotBefore
+ NotAfter
+
+ NotBefore = NOT-BEFORE-TYPE TLV-LENGTH IsoDate "T" IsoTime
+
+ NotAfter = NOT-AFTER-TYPE TLV-LENGTH IsoDate "T" IsoTime
+
+ IsoDate = 8DIGIT ; YYYYMMDD (UTC)
+
+ IsoTime = 6DIGIT ; hhmmss (UTC)
+
++---------------------------------------------+------------------+-----------------+
+| Type | Assigned number | Assigned number |
+| | (decimal) | (hexadecimal) |
++=============================================+==================+=================+
+| ValidityPeriod | 253 | 0xFD |
++---------------------------------------------+------------------+-----------------+
+| NotBefore | 254 | 0xFE |
++---------------------------------------------+------------------+-----------------+
+| NotAfter | 255 | 0xFF |
++---------------------------------------------+------------------+-----------------+
+
+Extensions
+----------
+
+A certificate may carry zero or more extension fields in its ``SignatureInfo`` element.
+An extension can be either critical or non-critical depending on its TLV-TYPE number.
+A critical TLV-TYPE means that if a validator cannot recognize or parse the extension,
+the validator must reject the whole certificate. Conversely, an extension with a
+non-critical TLV-TYPE may be ignored by the validator if it is not recognized. Refer to
+the general `evolvability rules
+<https://named-data.net/doc/NDN-packet-spec/current/tlv.html#considerations-for-evolvability-of-tlv-based-encoding>`__
+of the NDN packet format to determine whether a TLV-TYPE is critical or not.
+
+The TLV-TYPE number range [256, 511] is reserved for extensions. The currently defined
+extensions are listed in the table below.
+
++---------------------------------------------+------------------+-----------------+
+| Type | Assigned number | Assigned number |
+| | (decimal) | (hexadecimal) |
++=============================================+==================+=================+
+| AdditionalDescription (non-critical) | 258 | 0x102 |
++---------------------------------------------+------------------+-----------------+
+
+AdditionalDescription
+~~~~~~~~~~~~~~~~~~~~~
+
+``AdditionalDescription`` is a non-critical extension that provides additional
+information about the certificate. The information is expressed as a set of
+key-value pairs. Both key and value are UTF-8 strings, e.g.,
+``("Organization", "UCLA")``. The issuer of a certificate can specify arbitrary
+key-value pairs to provide further details about the certificate.
+
+.. code-block:: abnf
+
+ CertificateV2Extension = AdditionalDescription
+
+ AdditionalDescription = ADDITIONAL-DESCRIPTION-TYPE TLV-LENGTH
+ 1*DescriptionEntry
+
+ DescriptionEntry = DESCRIPTION-ENTRY-TYPE TLV-LENGTH
+ DescriptionKey
+ DescriptionValue
+
+ DescriptionKey = DESCRIPTION-KEY-TYPE TLV-LENGTH 1*OCTET
+
+ DescriptionValue = DESCRIPTION-VALUE-TYPE TLV-LENGTH 1*OCTET
+
++---------------------------------------------+------------------+-----------------+
+| Type | Assigned number | Assigned number |
+| | (decimal) | (hexadecimal) |
++=============================================+==================+=================+
+| DescriptionEntry | 512 | 0x200 |
++---------------------------------------------+------------------+-----------------+
+| DescriptionKey | 513 | 0x201 |
++---------------------------------------------+------------------+-----------------+
+| DescriptionValue | 514 | 0x202 |
++---------------------------------------------+------------------+-----------------+
diff --git a/docs/specs/safe-bag.rst b/docs/specs/safe-bag.rst
index 23e93cb..6cc6773 100644
--- a/docs/specs/safe-bag.rst
+++ b/docs/specs/safe-bag.rst
@@ -4,8 +4,8 @@
Sometimes, one may need to export credentials (e.g., certificate and private key) from
one machine, and import them into another machine. This requires a secured container for
sensitive information. We define **SafeBag**, which contains both an NDN certificate
-(:doc:`version 2.0 <certificate-format>`) and the corresponding private
-key, which is encrypted in `PKCS #8 format <https://tools.ietf.org/html/rfc5208>`_.
+(:doc:`version 2.0 <certificate>`) and the corresponding private key, which is encrypted
+in `PKCS #8 format <https://tools.ietf.org/html/rfc5208>`_.
The format of **SafeBag** is defined as:
@@ -20,11 +20,11 @@
All TLV-TYPE numbers are application specific:
-+---------------------------------------------+-------------------+----------------+
-| TLV-TYPE | Assigned number | Assigned number|
-| | (decimal) | (hexadecimal) |
-+=============================================+===================+================+
-| SafeBag | 128 | 0x80 |
-+---------------------------------------------+-------------------+----------------+
-| EncryptedKeyBag | 129 | 0x81 |
-+---------------------------------------------+-------------------+----------------+
++---------------------------------------------+------------------+-----------------+
+| Type | Assigned number | Assigned number |
+| | (decimal) | (hexadecimal) |
++=============================================+==================+=================+
+| SafeBag | 128 | 0x80 |
++---------------------------------------------+------------------+-----------------+
+| EncryptedKeyBag | 129 | 0x81 |
++---------------------------------------------+------------------+-----------------+
diff --git a/docs/specs/signed-interest.rst b/docs/specs/signed-interest.rst
index b854c13..56b9323 100644
--- a/docs/specs/signed-interest.rst
+++ b/docs/specs/signed-interest.rst
@@ -1,5 +1,3 @@
-.. _Signed Interest:
-
Signed Interest Version 0.2 (DEPRECATED)
========================================