Use :rfc: and :abbr: sphinx roles
Change-Id: I34e0ddbd644944d98a26f9c0c93ad787b4d93679
diff --git a/changelog.rst b/changelog.rst
index e65718a..c6b611a 100644
--- a/changelog.rst
+++ b/changelog.rst
@@ -4,7 +4,7 @@
Version 0.3
-----------
-- Rewrite TLV syntax specifications using `IETF Augmented BNF (RFC 5234) <https://tools.ietf.org/html/rfc5234>`__
+- Rewrite TLV syntax specifications using IETF Augmented BNF (:rfc:`5234`)
- Require shortest encoding for TLV-TYPE and TLV-LENGTH numbers
diff --git a/name.rst b/name.rst
index 0db53cd..d018701 100644
--- a/name.rst
+++ b/name.rst
@@ -51,7 +51,7 @@
~~~~~~~~~~~~~~
For textual representation, it is often convenient to use URI to represent NDN names.
-Please refer to RFC 3986 (URI Generic Syntax) for background.
+Please refer to :rfc:`3986` (URI Generic Syntax) for background.
The scheme identifier is ``ndn``.
diff --git a/requirements.txt b/requirements.txt
index 8a90dbc..4bc87db 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -1,2 +1,2 @@
-furo == 2022.3.4
-sphinx ~= 4.0
+furo == 2022.6.4.1
+sphinx ~= 5.0
diff --git a/signature.rst b/signature.rst
index 10bcc42..d9f5367 100644
--- a/signature.rst
+++ b/signature.rst
@@ -181,7 +181,7 @@
^^^^^^^^^^^^^^^^^^^^^^
``SignatureSha256WithRsa`` defines an RSA public key signature that is calculated over the SHA-256 hash of the "signed portion" of an Interest or Data packet.
-It uses the RSASSA-PKCS1-v1_5 signature scheme, as defined in `RFC 8017, Section 8.2 <https://tools.ietf.org/html/rfc8017#section-8.2>`__.
+It uses the RSASSA-PKCS1-v1_5 signature scheme, as defined in :rfc:`RFC 8017, Section 8.2 <8017#section-8.2>`.
* The TLV-VALUE of ``SignatureType`` is 1
* ``KeyLocator`` is required
@@ -200,7 +200,7 @@
The TLV-LENGTH of these elements varies depending on the length of the private key used for signing (e.g., 256 bytes for a 2048-bit key).
This type of signature, if verified, provides very strong assurances that a packet was created by the claimed producer (authentication/provenance) and was not tampered with while in transit (integrity).
-The ``KeyDigest`` option in :ref:`KeyLocator` is defined as the SHA-256 digest over the DER encoding of the ``SubjectPublicKeyInfo`` for an RSA key as defined by `RFC 3279 <https://tools.ietf.org/html/rfc3279>`__."
+The ``KeyDigest`` option in :ref:`KeyLocator` is defined as the SHA-256 digest over the DER encoding of the ``SubjectPublicKeyInfo`` for an RSA key as defined by :rfc:`3279`.
.. note::
It is the application's responsibility to define rules (a trust model) concerning when a specific issuer (``KeyLocator``) is authorized to sign a specific packet.
@@ -213,7 +213,7 @@
^^^^^^^^^^^^^^^^^^^^^^^^
``SignatureSha256WithEcdsa`` defines an ECDSA public key signature that is calculated over the SHA-256 hash of the "signed portion" of an Interest or Data packet.
-This signature algorithm is defined in `RFC 5753, Section 2.1 <https://tools.ietf.org/html/rfc5753#section-2.1>`__.
+This signature algorithm is defined in :rfc:`RFC 5753, Section 2.1 <5753#section-2.1>`.
All NDN implementations MUST support this signature type with the NIST P-256 curve.
* The TLV-VALUE of ``SignatureType`` is 3
@@ -233,9 +233,9 @@
The TLV-LENGTH of these elements depends on the specific elliptic curve used for signing (e.g., up to 72 bytes for the NIST P-256 curve).
This type of signature, if verified, provides very strong assurances that a packet was created by the claimed producer (authentication/provenance) and was not tampered with while in transit (integrity).
-The ``KeyDigest`` option in :ref:`KeyLocator` is defined as the SHA-256 digest of the DER encoding of the ``SubjectPublicKeyInfo`` for an EC key as defined by `RFC 5480 <https://tools.ietf.org/html/rfc5480>`__.
+The ``KeyDigest`` option in :ref:`KeyLocator` is defined as the SHA-256 digest of the DER encoding of the ``SubjectPublicKeyInfo`` for an EC key as defined by :rfc:`5480`.
-The value of ``SignatureValue`` of ``SignatureSha256WithEcdsa`` is a DER-encoded ``Ecdsa-Sig-Value`` structure as defined in `RFC 3279, Section 2.2.3 <https://tools.ietf.org/html/rfc3279#section-2.2.3>`__.
+The value of ``SignatureValue`` of ``SignatureSha256WithEcdsa`` is a DER-encoded ``Ecdsa-Sig-Value`` structure as defined in :rfc:`RFC 3279, Section 2.2.3 <3279#section-2.2.3>`.
.. _SignatureHmacWithSha256:
@@ -243,10 +243,10 @@
^^^^^^^^^^^^^^^^^^^^^^^
``SignatureHmacWithSha256`` defines a hash-based message authentication code (HMAC) that is calculated over the "signed portion" of an Interest or Data packet, using SHA-256 as the hash function, salted with a shared secret key.
-This signature algorithm is defined in `RFC 2104, Section 2 <https://tools.ietf.org/html/rfc2104#section-2>`__.
+This signature algorithm is defined in :rfc:`RFC 2104, Section 2 <2104#section-2>`.
.. warning::
- As stated in `RFC 2104, Section 3 <https://tools.ietf.org/html/rfc2104#section-3>`__, shared keys shorter than the SHA-256 output length (32 bytes) are strongly discouraged.
+ As stated in :rfc:`RFC 2104, Section 3 <2104#section-3>`, shared keys shorter than the SHA-256 output length (32 bytes) are strongly discouraged.
* The TLV-VALUE of ``SignatureType`` is 4
* ``KeyLocator`` is required
@@ -274,7 +274,7 @@
^^^^^^^^^^^^^^^^
``SignatureEd25519`` defines an Ed25519 public key signature that is calculated over the "signed portion" of an Interest or Data packet.
-This signature algorithm is defined in `RFC 8032, Section 5.1 <https://datatracker.ietf.org/doc/html/rfc8032#section-5.1>`__.
+This signature algorithm is defined in :rfc:`RFC 8032, Section 5.1 <8032#section-5.1>`.
* The TLV-VALUE of ``SignatureType`` is 5
* ``KeyLocator`` is required
@@ -290,6 +290,6 @@
64OCTET ; == Ed25519{Interest signed portion}
This type of signature, if verified, provides very strong assurances that a packet was created by the claimed producer (authentication/provenance) and was not tampered with while in transit (integrity).
-The ``KeyDigest`` option in :ref:`KeyLocator` is defined as the SHA-256 digest over the DER encoding of the ``SubjectPublicKeyInfo`` for an Ed25519 key as defined by `RFC 8410, Section 4 <https://datatracker.ietf.org/doc/html/rfc8410#section-4>`__."
+The ``KeyDigest`` option in :ref:`KeyLocator` is defined as the SHA-256 digest over the DER encoding of the ``SubjectPublicKeyInfo`` for an Ed25519 key as defined by :rfc:`RFC 8410, Section 4 <8410#section-4>`.
.. _hierarchical trust model: https://named-data.net/publications/techreports/trpublishkey-rev2/
diff --git a/tlv.rst b/tlv.rst
index 01da1eb..240af02 100644
--- a/tlv.rst
+++ b/tlv.rst
@@ -1,15 +1,14 @@
Type-Length-Value (TLV) Encoding
--------------------------------
-Each NDN packet is encoded in a Type-Length-Value (TLV) format. NDN Interest and Data packets are distinguished by the type number in the first and outmost TLV\ :sub:`0`\ .
+Each NDN packet is encoded in :abbr:`TLV (Type-Length-Value)` format.
+NDN Interest and Data packets are distinguished by the type number in the first and outermost TLV\ :sub:`0`\ .
An NDN packet is mainly a collection of TLVs inside TLV\ :sub:`0`\ . Some TLVs may contain sub-TLVs, and each sub-TLV may also be further nested. A guiding design principle is to keep the order of TLV\ :sub:`i`\ s deterministic, and keep the level of nesting as small as possible to minimize both processing overhead and chances for errors.
Note that NDN packet format does not have a fixed packet header nor does it encode a protocol version number. Instead the design uses the TLV format to provide the flexibility of adding new types and phasing out old types as the protocol evolves over time. The absence of a fixed header makes it possible to support packets of very small sizes efficiently, without the header overhead.
There is also no packet fragmentation support at network level.
-Whenever needed, NDN packets may be fragmented and reassembled hop-by-hop. [#f1]_
-
-.. [#f1] `"Packet Fragmentation in NDN: Why NDN Uses Hop-By-Hop Fragmentation (NDN Memo)" by A. Afanasyev, J. Shi, L. Wang, B. Zhang, and L. Zhang., NDN Memo, Technical Report NDN-0032 <https://named-data.net/publications/techreports/ndn-0032-1-ndn-memo-fragmentation/>`__
+Whenever needed, NDN packets may be fragmented and reassembled hop-by-hop\ [#f1]_.
Variable-Size Encoding for Type and Length
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -28,23 +27,23 @@
VAR-NUMBER-9 = %xFF 8OCTET
.. note::
- The formal grammar of NDN packet format in this specification is given using :rfc:`Augmented BNF for Syntax Specifications <5234>`.
+ The formal grammar of the NDN packet format in this specification is given using :rfc:`Augmented BNF for Syntax Specifications <5234>`.
The first octet of the number either carries the actual number, or signals that a multi-octet encoding is present, as defined below:
-- If the first octet is less than or equal to 252 (0xFC), the number is encoded in that octet.
+- If the first octet is less than or equal to 252 (``0xFC``), the number is encoded in that octet.
-- If the first octet is 253 (0xFD), the number is encoded in the following 2 octets, in network byte-order.
- This number must be greater than 252 (0xFC).
+- If the first octet is 253 (``0xFD``), the number is encoded in the following 2 octets, in network byte-order.
+ This number must be greater than 252 (``0xFC``).
-- If the first octet is 254 (0xFE), the number is encoded in the following 4 octets, in network byte-order.
- This number must be greater than 65535 (0xFFFF).
+- If the first octet is 254 (``0xFE``), the number is encoded in the following 4 octets, in network byte-order.
+ This number must be greater than 65535 (``0xFFFF``).
-- If the first octet is 255 (0xFF), the number is encoded in the following 8 octets, in network byte-order.
- This number must be greater than 4294967295 (0xFFFFFFFF).
+- If the first octet is 255 (``0xFF``), the number is encoded in the following 8 octets, in network byte-order.
+ This number must be greater than 4294967295 (``0xFFFFFFFF``).
A number MUST be encoded in the shortest format.
-For example, the number 1024 is encoded as %xFD0400 in VAR-NUMBER-3 format, not %xFE00000400 in VAR-NUMBER-5 format.
+For example, the number 1024 is encoded as ``%xFD0400`` in ``VAR-NUMBER-3`` format, not ``%xFE00000400`` in ``VAR-NUMBER-5`` format.
.. _TLV:
@@ -114,3 +113,7 @@
- when a specification defines a sequence {``F1`` ``F2`` ``F3``}, an element ``F3`` would be out-of-order in the sequence {``F1`` ``F3`` ``F2``};
- for {``F1`` ``F2?`` ``F3``} specification (i.e., when ``F2`` is optional, ``F2`` would be out-of-order in the same sequence {``F1`` ``F3`` ``F2``}.
+
+.. rubric:: Footnotes
+
+.. [#f1] `"Packet Fragmentation in NDN: Why NDN Uses Hop-By-Hop Fragmentation (NDN Memo)" by A. Afanasyev, J. Shi, L. Wang, B. Zhang, and L. Zhang., NDN Memo, Technical Report NDN-0032 <https://named-data.net/publications/techreports/ndn-0032-1-ndn-memo-fragmentation/>`__