docs: clarify and cleanup the certificate format spec
Also, cleanup references to the legacy signed interest spec
Change-Id: Ib761399b6e44cefea6331e4e128bb2976c2fc11d
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 |
++---------------------------------------------+------------------+-----------------+