docs: fix syntax highlighting of code blocks
And various other cleanups
Change-Id: If945f5407036e73db980cafd2185359a488a0ff1
diff --git a/docs/specs/certificate-format.rst b/docs/specs/certificate-format.rst
index f1ec424..9e811b9 100644
--- a/docs/specs/certificate-format.rst
+++ b/docs/specs/certificate-format.rst
@@ -3,8 +3,6 @@
NDN Certificate Format Version 2.0
==================================
-.. contents::
-
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
@@ -46,27 +44,26 @@
| SignatureValue |
+--------------------------+
+.. code-block:: abnf
- CertificateV2 = DATA-TYPE TLV-LENGTH
- Name ; /<NameSpace>/KEY/[KeyId]/[IssuerId]/[Version]
- MetaInfo ; ContentType = KEY, FreshnessPeriod required
- Content ; X509PublicKey
- CertificateV2SignatureInfo
- SignatureValue
+ 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
+ CertificateV2SignatureInfo = SIGNATURE-INFO-TYPE TLV-LENGTH
+ SignatureType
+ KeyLocator
+ ValidityPeriod
+ *CertificateV2Extension
Name
----
-The name of a certificate consists of five parts as shown below:
-
-::
+The name of a certificate consists of five parts as shown below::
/<SubjectName>/KEY/[KeyId]/[IssuerId]/[Version]
@@ -82,17 +79,13 @@
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,
-
-::
+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
--------
@@ -120,7 +113,7 @@
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
@@ -180,7 +173,7 @@
``("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
diff --git a/docs/specs/safe-bag.rst b/docs/specs/safe-bag.rst
index fcb6211..23e93cb 100644
--- a/docs/specs/safe-bag.rst
+++ b/docs/specs/safe-bag.rst
@@ -1,24 +1,24 @@
-Export/Import Credentials
-=========================
+SafeBag Format for Exported Credentials
+=======================================
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>`_.
+key, which is encrypted in `PKCS #8 format <https://tools.ietf.org/html/rfc5208>`_.
The format of **SafeBag** is defined as:
-::
+.. code-block:: abnf
SafeBag = SAFE-BAG-TYPE TLV-LENGTH
- CertificateV2 ; a data packet following certificate format spec
+ CertificateV2
EncryptedKeyBag
EncryptedKeyBag = ENCRYPTED-KEY-BAG-TYPE TLV-LENGTH
- *OCTET ; private key encrypted in PKCS#8 format
+ *OCTET ; private key encrypted in PKCS #8 format
-All TLV-TYPE codes are application specific:
+All TLV-TYPE numbers are application specific:
+---------------------------------------------+-------------------+----------------+
| TLV-TYPE | Assigned number | Assigned number|
diff --git a/docs/specs/signed-interest.rst b/docs/specs/signed-interest.rst
index f283b7f..b854c13 100644
--- a/docs/specs/signed-interest.rst
+++ b/docs/specs/signed-interest.rst
@@ -18,7 +18,7 @@
+-------------+----------+-----------------------------------------------------------------------------------+
| Interest | Interest | +------+--------+--------------------------------------------------+ +----------+ |
- | Type (0x01) | length | | Name | Name | +---------+-- --+---------+---------+---------+| | Other | |
+ | Type (0x05) | length | | Name | Name | +---------+-- --+---------+---------+---------+| | Other | |
| | | | Type | Length | |Component| ... |Component|Component|Component|| | TLVs ... | |
| | | | | | | TLV 1 | | TLV n-2 | TLV n-1 | TLV n || | in | |
| | | | | | +---------+-- --+---------+---------+---------+| | Interest | |
@@ -32,14 +32,12 @@
More specifically, the SignedInterest is defined to have four additional components:
-- ``<timestamp>``
-- ``<nonce>``
-- ``<SignatureInfo>``
-- ``<SignatureValue>``
+- ``timestamp``
+- ``nonce``
+- ``SignatureInfo``
+- ``SignatureValue``
-For example, for ``/signed/interest/name`` name, CommandInterest will be defined as:
-
-::
+For example, for ``/signed/interest/name`` name, CommandInterest will be defined as::
/signed/interest/name/<timestamp>/<random-value>/<SignatureInfo>/<SignatureValue>